Search your dataedit

A search query, or query, is a request for information about data in Elasticsearch data streams or indices.

You can think of a query as a question, written in a way Elasticsearch 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?
  • How many of my products have a price greater than $20?
  • 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 Elasticsearch. 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.

Run a searchedit

You can use the search API to search data stored in Elasticsearch data streams or indices.

The API can run two types of searches, depending on how you provide queries:

URI searches
Queries are provided through a query parameter. URI searches tend to be simpler and best suited for testing.
Request body searches
Queries are provided through the JSON body of the API request. These queries are written in Query DSL. We recommend using request body searches in most production use cases.

If you specify a query in both the URI and request body, the search API request runs only the URI query.

Run a URI searchedit

You can use the search API’s q query string parameter to run a search in the request’s URI. The q parameter only accepts queries written in Lucene’s query string syntax.

To get started, ingest or add some data to an Elasticsearch data stream or index.

The following bulk API request adds some example server access log data to the my-index-000001 index.

PUT /my-index-000001/_bulk?refresh
{ "index":{ } }
{ "@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" } }
{ "index":{ } }
{ "@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": "10.42.42.42" }, "user": { "id": "elkbee" } }
{ "index":{ } }
{ "@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": "10.42.42.42" }, "user": { "id": "elkbee" } }

You can now use the search API to run a URI search on this index.

The following URI search matches documents with a user.id value of kimchy. Note the query is specified using the q query string parameter.

GET /my-index-000001/_search?q=user.id:kimchy

The API returns the following response. Note the hits.hits property contains the document that matched the query.

{
  "took": 5,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 1,
      "relation": "eq"
    },
    "max_score": 0.9808291,
    "hits": [
      {
        "_index": "my-index-000001",
        "_type": "_doc",
        "_id": "kxWFcnMByiguvud1Z8vC",
        "_score": 0.9808291,
        "_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"
          }
        }
      }
    ]
  }
}

Run a request body searchedit

You can use the search API’s query request body parameter to provide a query as a JSON object, written in Query DSL.

The following request body search uses the match query to match documents with a user.id value of kimchy. Note the match query is specified as a JSON object in the query parameter.

GET /my-index-000001/_search
{
  "query": {
    "match": {
      "user.id": "kimchy"
    }
  }
}

The API returns the following response.

The hits.hits property contains matching documents. By default, the response sorts these matching documents by _score, a relevance score that measures how well each document matches the query.

{
  "took": 5,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 1,
      "relation": "eq"
    },
    "max_score": 0.9808291,
    "hits": [
      {
        "_index": "my-index-000001",
        "_type": "_doc",
        "_id": "kxWFcnMByiguvud1Z8vC",
        "_score": 0.9808291,
        "_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"
          }
        }
      }
    ]
  }
}

Search multiple data streams and indicesedit

To search multiple data streams and indices, add them as comma-separated values in the search API request path.

The following request searches the my-index-000001 and my-index-000002 indices.

GET /my-index-000001,my-index-000002/_search
{
  "query": {
    "match": {
      "user.id": "kimchy"
    }
  }
}

You can also search multiple data streams and indices using a wildcard (*) pattern.

The following request targets the wildcard pattern user_logs*. The request searches any data streams or indices in the cluster that start with user_logs.

GET /user_logs*/_search
{
  "query": {
    "match": {
      "user.id": "kimchy"
    }
  }
}

To search all data streams and indices in a cluster, omit the target from the request path. Alternatively, you can use _all or *.

The following requests are equivalent and search all data streams and indices in the cluster.

GET /_search
{
  "query": {
    "match": {
      "user.id": "kimchy"
    }
  }
}

GET /_all/_search
{
  "query": {
    "match": {
      "user.id": "kimchy"
    }
  }
}

GET /*/_search
{
  "query": {
    "match": {
      "user.id": "kimchy"
    }
  }
}

Retrieve selected fieldsedit

By default, each hit in the search response includes the document _source, which is the entire JSON object that was provided when indexing the document. To retrieve specific fields in the search response, you can use the fields parameter:

POST my-index-000001/_search
{
  "query": {
    "match": {
      "message": "foo"
    }
  },
  "fields": ["user.id", "@timestamp"],
  "_source": false
}

The fields parameter consults both a document’s _source and the index mappings to load and return values. Because it makes use of the mappings, fields has some advantages over referencing the _source directly: it accepts multi-fields and field aliases, and also formats field values like dates in a consistent way.

A document’s _source is stored as a single field in Lucene. So the whole _source object must be loaded and parsed even if only a small number of fields are requested. To avoid this limitation, you can try another option for loading fields:

  • Use the docvalue_fields parameter to get values for selected fields. This can be a good choice when returning a fairly small number of fields that support doc values, such as keywords and dates.
  • Use the stored_fields parameter to get the values for specific stored fields (fields that use the store mapping option).

You can find more detailed information on each of these methods in the following sections:

Fieldsedit

The fields parameter allows for retrieving a list of document fields in the search response. It consults both the document _source and the index mappings to return each value in a standardized way that matches its mapping type. By default, date fields are formatted according to the date format parameter in their mappings.

The following search request uses the fields parameter to retrieve values for the user.id field, all fields starting with http.response., and the @timestamp field:

POST my-index-000001/_search
{
  "query": {
    "match": {
      "user.id": "kimchy"
    }
  },
  "fields": [
    "user.id",
    "http.response.*", 
    {
      "field": "@timestamp",
      "format": "epoch_millis" 
    }
  ],
  "_source": false
}

Both full field names and wildcard patterns are accepted.

Using object notation, you can pass a format parameter to apply a custom format for the field’s values. The date fields date and date_nanos accept a date format. Spatial fields accept either geojson for GeoJSON (the default) or wkt for Well Known Text. Other field types do not support the format parameter.

The values are returned as a flat list in the fields section in each hit:

{
  "took" : 2,
  "timed_out" : false,
  "_shards" : {
    "total" : 1,
    "successful" : 1,
    "skipped" : 0,
    "failed" : 0
  },
  "hits" : {
    "total" : {
      "value" : 1,
      "relation" : "eq"
    },
    "max_score" : 1.0,
    "hits" : [
      {
        "_index" : "my-index-000001",
        "_id" : "0",
        "_score" : 1.0,
        "_type" : "_doc",
        "fields" : {
          "user.id" : [
            "kimchy"
          ],
          "@timestamp" : [
            "4098435132000"
          ],
          "http.response.bytes": [
            1070000
          ],
          "http.response.status_code": [
            200
          ]
        }
      }
    ]
  }
}

Only leaf fields are returned — fields does not allow for fetching entire objects.

The fields parameter handles field types like field aliases and constant_keyword whose values aren’t always present in the _source. Other mapping options are also respected, including ignore_above, ignore_malformed and null_value.

The fields response always returns an array of values for each field, even when there is a single value in the _source. This is because Elasticsearch has no dedicated array type, and any field could contain multiple values. The fields parameter also does not guarantee that array values are returned in a specific order. See the mapping documentation on arrays for more background.

Doc value fieldsedit

You can use the docvalue_fields parameter to return doc values for one or more fields in the search response.

Doc values store the same values as the _source but in an on-disk, column-based structure that’s optimized for sorting and aggregations. Since each field is stored separately, Elasticsearch only reads the field values that were requested and can avoid loading the whole document _source.

Doc values are stored for supported fields by default. However, doc values are not supported for text or text_annotated fields.

The following search request uses the docvalue_fields parameter to retrieve doc values for the user.id field, all fields starting with http.response., and the @timestamp field:

GET my-index-000001/_search
{
  "query": {
    "match": {
      "user.id": "kimchy"
    }
  },
  "docvalue_fields": [
    "user.id",
    "http.response.*", 
    {
      "field": "date",
      "format": "epoch_millis" 
    }
  ]
}

Both full field names and wildcard patterns are accepted.

Using object notation, you can pass a format parameter to apply a custom format for the field’s doc values. Date fields support a date format. Numeric fields support a DecimalFormat pattern. Other field datatypes do not support the format parameter.

You cannot use the docvalue_fields parameter to retrieve doc values for nested objects. If you specify a nested object, the search returns an empty array ([ ]) for the field. To access nested fields, use the inner_hits parameter’s docvalue_fields property.

Stored fieldsedit

It’s also possible to store an individual field’s values by using the store mapping option. You can use the stored_fields parameter to include these stored values in the search response.

Source filteringedit

You can use the _source parameter to select what fields of the source are returned. This is called source filtering.

The following search API request sets the _source request body parameter to false. The document source is not included in the response.

GET /_search
{
  "_source": false,
  "query": {
    "match": {
      "user.id": "kimchy"
    }
  }
}

To return only a subset of source fields, specify a wildcard (*) pattern in the _source parameter. The following search API request returns the source for only the obj field and its properties.

GET /_search
{
  "_source": "obj.*",
  "query": {
    "match": {
      "user.id": "kimchy"
    }
  }
}

You can also specify an array of wildcard patterns in the _source field. The following search API request returns the source for only the obj1 and obj2 fields and their properties.

GET /_search
{
  "_source": [ "obj1.*", "obj2.*" ],
  "query": {
    "match": {
      "user.id": "kimchy"
    }
  }
}

For finer control, you can specify an object containing arrays of includes and excludes patterns in the _source parameter.

If the includes property is specified, only source fields that match one of its patterns are returned. You can exclude fields from this subset using the excludes property.

If the includes property is not specified, the entire document source is returned, excluding any fields that match a pattern in the excludes property.

The following search API request returns the source for only the obj1 and obj2 fields and their properties, excluding any child description fields.

GET /_search
{
  "_source": {
    "includes": [ "obj1.*", "obj2.*" ],
    "excludes": [ "*.description" ]
  },
  "query": {
    "term": {
      "user.id": "kimchy"
    }
  }
}