field-usage-stats.asciidoc

Field usage stats API

Field usage stats

experimental[]

Returns field usage information for each shard and field of an index. Field usage statistics are automatically captured when queries are running on a cluster. A shard-level search request that accesses a given field, even if multiple times during that request, is counted as a single use.

GET /my-index-000001/_field_usage_stats

{api-request-title}

GET /<index>/_field_usage_stats

{api-prereq-title}

• If the {es} {security-features} are enabled, you must have the manage index privilege for the target index or index alias.

{api-path-parms-title}

{es-repo-dir}/rest-api/common-parms.asciidoc

{api-query-parms-title}

{es-repo-dir}/rest-api/common-parms.asciidoc

{es-repo-dir}/rest-api/common-parms.asciidoc

{es-repo-dir}/rest-api/common-parms.asciidoc

{es-repo-dir}/rest-api/common-parms.asciidoc

{es-repo-dir}/rest-api/common-parms.asciidoc

fields

(Optional, string) Comma-separated list or wildcard expressions of fields to include in the statistics.

{api-examples-title}

The following request retrieves field usage information of index my-index-000001 on the currently available shards.

GET /my-index-000001/_field_usage_stats

The API returns the following response:

{
    "_shards": {
        "total": 1,
        "successful": 1,
        "failed": 0
    },
    "my-index-000001": {
        "shards": [
            {
                "tracking_id": "MpOl0QlTQ4SYYhEe6KgJoQ",
                "tracking_started_at_millis": 1625558985010,
                "routing": {
                    "state": "STARTED",
                    "primary": true,
                    "node": "gA6KeeVzQkGURFCUyV-e8Q",
                    "relocating_node": null
                },
                "stats" : {
                    "all_fields": {
                        "any": "6", (1)
                        "inverted_index": {
                            "terms" : 1,
                            "postings" : 1,
                            "proximity" : 1, (2)
                            "positions" : 0,
                            "term_frequencies" : 1,
                            "offsets" : 0,
                            "payloads" : 0
                        },
                        "stored_fields" : 2,
                        "doc_values" : 1,
                        "points" : 0,
                        "norms" : 1,
                        "term_vectors" : 0,
                        "knn_vectors" : 0
                    },
                    "fields": {
                        "_id": {
                            "any" : 1,
                            "inverted_index": {
                                "terms" : 1,
                                "postings" : 1,
                                "proximity" : 1,
                                "positions" : 0,
                                "term_frequencies" : 1,
                                "offsets" : 0,
                                "payloads" : 0
                            },
                            "stored_fields" : 1,
                            "doc_values" : 0,
                            "points" : 0,
                            "norms" : 0,
                            "term_vectors" : 0,
                            "knn_vectors" : 0
                        },
                        "_source": {...},
                        "context": {...},
                        "message.keyword": {...}
                    }
                }
            }
        ]
    }
}

1. denotes any kind of use of the field, either inverted index, or stored fields, or doc values, etc.

2. denotes any kind of use of either positions, offsets or payloads.