How to Write a Valid Query for ElasticSearch: A Guide with Examples

4 min readFeb 17, 2023

ElasticSearch is a powerful search engine that allows users to efficiently search and retrieve data from large datasets. To make the most of ElasticSearch, it’s important to understand how to write a valid query. In this article, we’ll cover the basics of ElasticSearch queries and how to write them.

Assuming that we have already created a mapping for our index, named “index_name”, we can start writing queries.

Basic Query

The basic query syntax is as follows:

GET /index_name/_search
{
  "query": {
    "match": {
      "field": "value"
    }
  }
}

This will search for documents in the “index_name” index where the specified field matches the specified value.

Bool Query

The bool query is a powerful query that allows us to combine multiple queries using Boolean logic. The syntax for the bool query is as follows:

GET /index_name/_search
{
  "query": {
    "bool": {
      "must": [
        { "match": { "field1": "value1" } },
        { "match": { "field2": "value2" } }
      ]
    }
  }
}

This query will search for documents in the “index_name” index where both “field1” matches “value1” and “field2” matches “value2”.

Nested Query

The nested query allows us to search for nested documents within a document. The syntax for the nested query is as follows:

GET /index_name/_search
{
  "query": {
    "nested": {
      "path": "nested_field",
      "query": {
        "bool": {
          "must": [
            { "match": { "nested_field.field1": "value1" } },
            { "match": { "nested_field.field2": "value2" } }
          ]
        }
      }
    }
  }
}

This query will search for documents in the “index_name” index where a nested field named “nested_field” contains documents where “field1” matches “value1” and “field2” matches “value2”.

Range Query

The range query allows us to search for documents where a field falls within a certain range. The syntax for the range query is as follows:

GET /index_name/_search
{
  "query": {
    "range": {
      "field": {
        "gte": 10,
        "lte": 20
      }
    }
  }
}

This query will search for documents in the “index_name” index where the value of “field” is greater than or equal to 10 and less than or equal to 20.

Path parameters

It is quite important to know the “path” parameter in ElasticSearch queries.

It’s used to specify the nested object path that should be searched. When searching within nested objects, you may encounter situations where you need to reference a nested field using dot notation (e.g., “obj1.obj2.field”). In this case, the “path” parameter is used to specify the nested object path.

GET /index_name/_search
{
  "query": {
    "nested": {
      "path": "nested_field.obj1.obj2",
      "query": {
        "match": {
          "nested_field.obj1.obj2.field": "value"
        }
      }
    }
  }
}

This query will search for documents in the “index_name” index where a nested field named "nested_field" contains documents with a nested object path of "obj1.obj2" and where the "field" field matches the value "value".

GET /index_name/_search
{
  "query": {
    "bool": {
      "must": [
        {
          "match": {
            "field1": "value1"
          }
        },
        {
          "nested": {
            "path": "nested_field.obj1.obj2",
            "query": {
              "match": {
                "nested_field.obj1.obj2.field": "value2"
              }
            }
          }
        }
      ]
    }
  }
}

This query will search for documents in the “index_name” index where "field1" matches "value1" and where a nested field named "nested_field" contains documents with a nested object path of "obj1.obj2" and where the "field" field matches the value "value2".

As you can see, the "path" parameter is used to specify the nested object path that should be searched. When using dot notation to reference nested fields, the "path" parameter should include the entire nested object path, including all intermediate nested objects separated by dots.

Mapping Doc

Furthermore, the most important thing is to know how documentation mapping works in Elastic Search.

Here’s an example of how dot notation is used in a _mapping for the _doc type:

PUT /index_name/_mapping/_doc
{
  "properties": {
    "field1": {
      "type": "text"
    },
    "nested_field": {
      "type": "nested",
      "properties": {
        "obj1": {
          "type": "nested",
          "properties": {
            "obj2": {
              "type": "object",
              "properties": {
                "field": {
                  "type": "text"
                }
              }
            }
          }
        }
      }
    }
  }
}

In this example, the _mapping for the _doc type in the “index_name” index includes a field named “nested_field” that is of the “nested” type. This field contains a nested object that includes two levels of nesting, with an intermediate level of nesting named “obj1” and a final level of nesting named “obj2”. The “field” field is located at the final level of nesting and is of the “text” type.

To reference this field in a query using dot notation, you would use the following path: “nested_field.obj1.obj2.field”. This path includes all intermediate nested objects separated by dots, allowing you to reference the “field” field using dot notation.

Conclusion

Writing valid queries in ElasticSearch is crucial for efficiently searching and retrieving data. We covered the basic query syntax, as well as more advanced queries such as the bool, nested, and range queries. Understanding these queries and their syntax will allow you to make the most of ElasticSearch and efficiently search through large datasets.

Also understanding how to use the “path” parameter with dot notation in ElasticSearch queries is essential for searching within nested objects. By following the examples above, you can write more complex queries that search within specific nested object paths and retrieve the data you need.