Search your dataedit

A search query, or query, is a request for information about data in Elasticsearch 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 one or more Elasticsearch 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 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 indicesedit

To search multiple 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 indices using an index pattern.

The following request uses the index pattern user_logs* in place of the index name. The request searches any indices in the cluster that start with user_logs.

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

To search all indices in a cluster, omit the index name from the request path. Alternatively, you can use _all or * in place of the index name.

The following requests are equivalent and search all 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. If you only need certain source fields in the search response, you can use the source filtering to restrict what parts of the source are returned.

Returning fields using only the document source has some limitations:

  • The _source field does not include multi-fields or field aliases. Likewise, a field in the source does not contain values copied using the copy_to mapping parameter.
  • Since the _source is stored as a single field in Lucene, the whole source object must be loaded and parsed, even if only a small number of fields are needed.

To avoid these limitations, you can:

  • 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:

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"
    }
  }
}

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 following fields:

  • Fields with names starting with my_ip
  • my_keyword_field
  • Fields with names ending with _date_field
GET /_search
{
  "query": {
    "match_all": {}
  },
  "docvalue_fields": [
    "my_ip*",                     
    {
      "field": "my_keyword_field" 
    },
    {
      "field": "*_date_field",
      "format": "epoch_millis"    
    }
  ]
}

Wildcard patten used to match field names, specified as a string.

Wildcard patten used to match field names, specified as an object.

With the object notation, you can use the format parameter to specify a format for the field’s returned doc values. Date fields support a date format. Numeric fields support a DecimalFormat pattern. Other field data types 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.