elasticsearch: the complete guide to query types and usage

introduction

Elasticsearch (ES) is a powerful, distributed search and analytics engine built on top of Apache Lucene; it has been widely used for full-text search, log analytics, real-time data exploration or more. Learning how to query Elticsearch effectively can be essential in order to leverage its full capabilities.

This article covers the core concepts of Elasticsearch, its architecture and provides a comprehensive overview of the various query types with practical examples and best practices.

1. what is elasticsearch?

It is an open-source RESTful search engine for horizontal scalability, reliability and real-time search engines like Elasticsearch that stores data as JSON documents to allow you to quickly index, search or analyze large volumes of data.

Key Features:

Distributed and scalable
Near real-time search and analytics
Full-text search capabilities
RESTful API
Schema-free JSON documents

2. core concepts

Cluster: A collection of one or more nodes (servers) that together hold your entire data and provide indexing and search capabilities.
Node: A single server that is part of the cluster.
Index: A collection of documents with similar characteristics (like a database in RDBMS).
Document: A JSON object containing data (like a row in RDBMS).
Shard: A subset of an index, allowing horizontal scaling.
Replica: A copy of a shard, providing redundancy and high availability.

3. elasticsearch query types

The query DSL (Domain Specific Language) is a rich query for the definition of queries provided by Elasticsearch, and Queries are divided into two main types.

Leaf Query Clauses: Search for a particular value in a particular field (e.g., match, term, range).
Compound Query Clauses: Combine multiple queries (e.g., bool, dis_max, constant_score).

3.1. full-text queries

Used for analyzing and searching text fields.

match: Analyzes the text and constructs a query.

JSON Query DSL:

1
{ "match": { "title": "Elasticsearch tutorial" } }

ES|QL Equivalent:

1
2
FROM your_index
| WHERE title MATCHES 'Elasticsearch tutorial'

match_phrase: Searches for an exact phrase.

JSON Query DSL:

1
{ "match_phrase": { "title": "Elasticsearch tutorial" } }

ES|QL Equivalent:

1
2
FROM your_index
| WHERE title == "Elasticsearch tutorial"

multi_match: Searches multiple fields.

JSON Query DSL:

1
{ "multi_match": { "query": "Elasticsearch", "fields": ["title", "content"] } }

ES|QL Equivalent:

1
2
FROM your_index
| WHERE title MATCHES 'Elasticsearch' OR content MATCHES 'Elasticsearch'

query_string: Supports advanced query syntax (AND, OR, wildcards).

JSON Query DSL:

1
{ "query_string": { "query": "Elasticsearch AND tutorial" } }

ES|QL Equivalent:

1
2
FROM your_index
| WHERE title MATCHES 'Elasticsearch' AND title MATCHES 'tutorial'

3.2. term-level queries

Used for structured data (numbers, dates, keywords).

term: Exact value match (no analysis).

JSON Query DSL:

1
{ "term": { "status": "published" } }

ES|QL Equivalent:

1
2
FROM your_index
| WHERE status == 'published'

terms: Matches any of the provided values.

JSON Query DSL:

1
{ "terms": { "status": ["published", "draft"] } }

ES|QL Equivalent:

1
2
FROM your_index
| WHERE status IN ("published", "draft")

range: Finds values within a range.

JSON Query DSL:

1
{ "range": { "date": { "gte": "2024-01-01", "lte": "2024-12-31" } } }

ES|QL Equivalent:

1
2
FROM your_index
| WHERE date >= "2024-01-01" AND date <= "2024-12-31"

exists: Checks if a field exists.

JSON Query DSL:

1
{ "exists": { "field": "author" } }

ES|QL Equivalent:

1
2
FROM your_index
| WHERE author IS NOT NULL

3.3. compound queries

Combine multiple queries for complex logic.

bool: Combines queries with must, should, must_not, and filter.

JSON Query DSL:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
{
  "bool": {
    "must": [
      { "match": { "title": "Elasticsearch" } }
    ],
    "filter": [
      { "term": { "status": "published" } }
    ]
  }
}

ES|QL Equivalent:

1
2
FROM your_index
| WHERE title MATCHES 'Elasticsearch' AND status == 'published'

dis_max: Returns documents matching any query, but scores by the best match.
constant_score: Wraps a query and assigns a constant score to all matching docs.

3.4. joining queries

nested: Query nested objects within documents.
has_child / has_parent: Query parent-child relationships.

3.5. geo queries

geo_distance: Finds documents within a certain distance of a geo point.
geo_bounding_box: Finds documents within a bounding box.

3.6. specialized queries

script: Custom queries using scripts.
percolate: Register queries and match documents to them.

4. filtering vs. querying

Query context: Calculates relevance score (used for full-text search).
Filter context: No scoring, just yes/no match (used for structured data, faster, cacheable).

Use filter for exact matches, ranges, and existence checks; use query for full-text search.

5. aggregations

Elasticsearch supports powerful aggregations for analytics:

terms aggregation: Group by field values.
date_histogram: Group by date intervals.
stats, avg, sum, min, max: Statistical calculations.

Example:

1
2
3
4
5
6
7
{
  "aggs": {
    "status_count": {
      "terms": { "field": "status" }
    }
  }
}

6. best practices

Use keyword fields for exact matches, text fields for full-text search.
Use filters for structured data to improve performance.
Paginate results with from and size.
Use mappings to control field types and analyzers.
Monitor cluster health and shard allocation.

7. example: putting it all together

json query dsl

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
POST /articles/_search
{
  "query": {
    "bool": {
      "must": [
        { "match": { "content": "Elasticsearch" } }
      ],
      "filter": [
        { "term": { "status": "published" } },
        { "range": { "date": { "gte": "2024-01-01" } } }
      ]
    }
  },
  "aggs": {
    "by_author": {
      "terms": { "field": "author.keyword" }
    }
  }
}

es|ql equivalent

1
2
3
4
FROM articles
| WHERE content MATCHES 'Elasticsearch'
| WHERE status == 'published' AND date >= "2024-01-01"
| STATS count() BY author

8. resources

conclusion

Elasticsearch is a powerful and flexible search engine: learning its query types—full-text, term-level, compound, and more—enables you to build fast, flexible (and scalable) search and analytics solutions. Test with the examples above; consult the official documentation to deepen your understanding.