<commit_before>[[search-your-data]]
= Search your data

[[search-query]]
A _search query_, or _query_, is a request for information about data in
{es} data streams or indices.

You can think of a query as a question, written in a way {es} understands.
Depending on your data, you can use a query to get answers to questions like:

* What processes on my server take longer than 500 milliseconds to respond?
* What users on my network ran `regsvr32.exe` within the last week?
* What pages on my website contain a specific word or phrase?

A _search_ consists of one or more queries that are combined and sent to {es}.
Documents that match a search's queries are returned in the _hits_, or
_search results_, of the response.

A search may also contain additional information used to better process its
queries. For example, a search may be limited to a specific index or only return
a specific number of results.

[discrete]
[[run-an-es-search]]
== Run a search

You can use the <<search-search,search API>> to search and
<<search-aggregations,aggregate>> data stored in {es} data streams or indices.
The API's `query` request body parameter accepts queries written in
<<query-dsl,Query DSL>>.

The following request searches `my-index-000001` using a
<<query-dsl-match-query,`match`>> query. This query matches documents with a
`user.id` value of `kimchy`.

[source,console]
----
GET /my-index-000001/_search
{
  "query": {
    "match": {
      "user.id": "kimchy"
    }
  }
}
----
// TEST[setup:my_index]

The API response returns the top 10 documents matching the query in the
`hits.hits` property.

[source,console-result]
----
{
  "took": 5,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 1,
      "relation": "eq"
    },
    "max_score": 1.3862942,
    "hits": [
      {
        "_index": "my-index-000001",
        "_id": "kxWFcnMByiguvud1Z8vC",
        "_score": 1.3862942,
        "_source": {
          "@timestamp": "2099-11-15T14:12:12",
          "http": {
            "request": {
              "method": "get"
            },
            "response": {
              "bytes": 1070000,
              "status_code": 200
            },
            "version": "1.1"
          },
          "message": "GET /search HTTP/1.1 200 1070000",
          "source": {
            "ip": "127.0.0.1"
          },
          "user": {
            "id": "kimchy"
          }
        }
      }
    ]
  }
}
----
// TESTRESPONSE[s/"took": 5/"took": "$body.took"/]
// TESTRESPONSE[s/"_id": "kxWFcnMByiguvud1Z8vC"/"_id": "$body.hits.hits.0._id"/]

[discrete]
[[run-search-runtime-fields]]
== Define fields that exist only in a query
Instead of indexing your data and then searching it, you can define
<<runtime-search-request,runtime fields>> that only exist as part of your<commit_msg>[DOCS] Decrement 'Search your data' headings<commit_after>[[search-your-data]]
= Search your data

[[search-query]]
A _search query_, or _query_, is a request for information about data in
{es} data streams or indices.

You can think of a query as a question, written in a way {es} understands.
Depending on your data, you can use a query to get answers to questions like:

* What processes on my server take longer than 500 milliseconds to respond?
* What users on my network ran `regsvr32.exe` within the last week?
* What pages on my website contain a specific word or phrase?

A _search_ consists of one or more queries that are combined and sent to {es}.
Documents that match a search's queries are returned in the _hits_, or
_search results_, of the response.

A search may also contain additional information used to better process its
queries. For example, a search may be limited to a specific index or only return
a specific number of results.

[discrete]
[[run-an-es-search]]
=== Run a search

You can use the <<search-search,search API>> to search and
<<search-aggregations,aggregate>> data stored in {es} data streams or indices.
The API's `query` request body parameter accepts queries written in
<<query-dsl,Query DSL>>.

The following request searches `my-index-000001` using a
<<query-dsl-match-query,`match`>> query. This query matches documents with a
`user.id` value of `kimchy`.

[source,console]
----
GET /my-index-000001/_search
{
  "query": {
    "match": {
      "user.id": "kimchy"
    }
  }
}
----
// TEST[setup:my_index]

The API response returns the top 10 documents matching the query in the
`hits.hits` property.

[source,console-result]
----
{
  "took": 5,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 1,
      "relation": "eq"
    },
    "max_score": 1.3862942,
    "hits": [
      {
        "_index": "my-index-000001",
        "_id": "kxWFcnMByiguvud1Z8vC",
        "_score": 1.3862942,
        "_source": {
          "@timestamp": "2099-11-15T14:12:12",
          "http": {
            "request": {
              "method": "get"
            },
            "response": {
              "bytes": 1070000,
              "status_code": 200
            },
            "version": "1.1"
          },
          "message": "GET /search HTTP/1.1 200 1070000",
          "source": {
            "ip": "127.0.0.1"
          },
          "user": {
            "id": "kimchy"
          }
        }
      }
    ]
  }
}
----
// TESTRESPONSE[s/"took": 5/"took": "$body.took"/]
// TESTRESPONSE[s/"_id": "kxWFcnMByiguvud1Z8vC"/"_id": "$body.hits.hits.0._id"/]

[discrete]
[[run-search-runtime-fields]]
=== Define fields that exist only in a query
Instead of indexing your data and then searching it, you can define
<<runtime-search-request,runtime fields>> that only exist as part of your
{'fraction_non_alphanumeric': 0.13252804141501295, 'fraction_numerical': 0.03347713546160483, 'mean_word_length': 2.6315789473684212, 'pattern_counts': {'":': 74, '<': 23, '<?xml version=': 0, '>': 23, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 2, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6743178', 'n_tokens_mistral': 1998, 'n_tokens_neox': 1833, 'n_words': 644}