What does elasticsearch _search api stats tag do?

Question

I am trying to collect data while a user is using the _search API and I stumbled into a tag that can be put into the search query that might simplify everything for me but I can't find enough information on it.

Does the stats tag in a _search body affect anything; like the results returned?

The only information I could find on it was this page https://www.elastic.co/guide/en/elasticsearch/client/javascript-api/current/api-reference.html and all that it states is String, String[], Boolean — Specific tag of the request for logging and statistical purposes. Is elasticsearch actually logging it somewhere?

Example of my _search request:

Kibana

GET myindex/doc/_search
{
  "query": {
    "match_all": {}
  }, 
  "stats": ["my string of data"]
}

cURL

curl -XGET "http://localhost:9200/myindex/doc/_search" -H 'Content-Type: application/json' -d'
{
  "query": {
    "match_all": {}
  }, 
  "stats": ["my string of data"]
}'

Answer 1

The stats keyword in the _search query is meant to define some statistics group that you can later query using the _stats API. For instance, let's say you query myindex using the my-query group:

curl -XGET "http://localhost:9200/myindex/doc/_search" -H 'Content-Type: application/json' -d'
{
  "query": {
    "match_all": {}
  }, 
  "stats": ["my-query"]
}'

Then you can get the index-level search statistics for that group using the following query:

curl -XGET "http://localhost:9200/myindex/_stats/search?groups=my-stats"

And you'll get something like this:

{
  "_shards": {
    "total": 2,
    "successful": 2,
    "failed": 0
  },
  "_all": {
    "primaries": {
      "search": {
        "open_contexts": 0,
        "query_total": 5806,
        "query_time_in_millis": 73948,
        ...
        "groups": {
          "my-query": {                         <----------
            "query_total": 8,
            "query_time_in_millis": 81,
            ...
          }
        }
      }
    },
    "total": {
      "search": {
        "open_contexts": 0,
        "query_total": 5806,
        "query_time_in_millis": 73948,
        ...
        "groups": {
          "my-query": {                         <----------
            "query_total": 8,
            "query_time_in_millis": 81,
            ...
          }
        }
      }
    }
  },
  "indices": {
    "listings-master": {
      "uuid": "oUYHBiU8RVayI95uCw3Clg",
      "primaries": {
        "search": {
          "open_contexts": 0,
          "query_total": 5806,
          "query_time_in_millis": 73948,
          ...
          "groups": {
            "my-query": {                         <----------
              "query_total": 8,
              "query_time_in_millis": 81,
              ...
            }
          }
        }
      },
      "total": {
        "search": {
          "open_contexts": 0,
          "query_total": 5806,
          "query_time_in_millis": 73948,
          ...
          "groups": {
            "my-query": {                         <----------
              "query_total": 8,
              "query_time_in_millis": 81,
              ...
            }
          }
        }
      }
    }
  }
}