Query language reference

Estimated time to read: 9 minutes

EraSearch supports parts of Elasticsearch's Query Domain Specific Language (DSL) and several Elasticsearch aggregations. Use this page to see what EraSearch supports, specify queries, and learn about your data.

The content below is for all EraSearch users.

Sending queries to EraSearch¶

To learn about your data, you send queries to EraSearch's search API. The API relies on Elasticsearch's search API, and you have two options for specifying queries in requests:

• q query-string parameter

• Request-body parameters

If you include a q parameter and request-body parameter in the same request, the API uses the q parameter.

Using the q query-string parameter for queries¶

Use the q parameter to send query-string syntax queries to EraSearch. Note that the q parameter only supports that subsection of the Query DSL.

Example

The example below uses the q parameter to request all documents where dog.name contains spot. The request only targets the customers index.

$ curl 'http://localhost:9200/customers/_search?q=dog.name:spot' \
  -H 'Authorization: Bearer abcdefghi123456789' | jq

EraSearch's response shows information about the request and the one returned document. For more information about the response, visit Elasticsearch's response body documentation.

{
  "took": 13,
  "timed_out": false,
  "hits": {
    "total": {
      "value": 1,
      "relation": "eq"
    },
    "max_score": null,
    "hits": [
      {
        "_index": "customers",
        "_id": "14558162682937802752",
        "_score": 1,
        "_source": {
          "customer.firstname": "lian",
          "dog.name": "spot",
          "_line": "account pending",
          "treats": 3,
          "_ts": 1635037200000,
          "_lid": 14558162682937803000
        }
      }
    ]
  }
}

Using request-body parameters for queries¶

Use the request-body parameter to send Query DSL queries and aggregations to EraSearch.

Example: query parameter

The example below uses the query parameter to request all documents where dog.name contains spot. The request only targets the customers index.

$ curl 'http://localhost:9200/customers/_search' \
  -H 'Authorization: Bearer abcdefghi123456789' \
  -H 'Content-Type: application/json' -d'
  {
    "query": {
      "term": {
        "dog.name": "spot"
      }
    }
  }
  ' | jq

EraSearch's response shows information about the request and the one returned document. For more information about the response, visit Elasticsearch's response body documentation.

{
  "took": 13,
  "timed_out": false,
  "hits": {
    "total": {
      "value": 1,
      "relation": "eq"
    },
    "max_score": null,
    "hits": [
      {
        "_index": "customers",
        "_id": "14558162682937802752",
        "_score": 1,
        "_source": {
          "customer.firstname": "lian",
          "dog.name": "spot",
          "_line": "account pending",
          "treats": 3,
          "_ts": 1635037200000,
          "_lid": 14558162682937803000
        }
      }
    ]
  }
}

Example: aggs parameter

The example below uses the aggs parameter to calculate the average number of treats. The request only targets documents in the customers index.

$ curl 'http://localhost:9200/customers/_search' \
  -H 'Authorization: Bearer abcdefghi123456789' \
  -H 'Content-Type: application/json' -d'
  {
    "aggs": {
      "avg_treats": { "avg": { "field": "treats" } }
    }
  }
  ' | jq

EraSearch returns information about the request, the relevant documents, and the calculated average. The output below shows only part of the response. For more information about the response, visit Elasticsearch's response body documentation.

{
  [...]
  "aggregations": {
    "avg_treats": {
      "value": 3.875
    }
  }
}

Permission needs for sending queries¶

To query data, you need the read permission on all relevant indexes. Visit User and role management and Setting up RBAC for more information.

Relevance scores in EraSearch¶

One of Elasticsearch's use cases is full-text search. To support that use case, Elasticsearch calculates relevance scores and returns them in the _score and max_score fields.

EraSearch focuses on Elasticsearch's log-management use case, so EraSearch doesn't calculate relevance scores. Because of the API similarity, query results still show the _score and max_score fields. Those fields aren't relevant in EraSearch, and you can safely ignore them.

Query DSL¶

This section lists and describes EraSearch's Query DSL.

Boolean query¶

Find documents matching one or more boolean clauses. Every boolean clause has one of these occurrence types, impacting query behavior:

• must
• filter
• should
• must_not

Boolean queries are compound queries, so you can use them to wrap other queries. For more about boolean queries, visit Elasticsearch's boolean query documentation.

Boolean query example

The query below uses the must and must_not boolean occurrence types and wraps three other queries: exists, range, and term.

It returns documents where the name field exists, average_temperature is between 30 and 70, and _line doesn't contain experienced.

{
  "query": {
    "bool": {
      "must": [
        {"exists": { "field": "name"}},
        {"range": { "average_temperature": { "gt": 30, "lt": 70}}}
      ],
      "must_not": {
        "term": { "_line": "experienced"}
      }
    }  
  }
}

Exists query¶

Find documents with non-null values for a specific field. Non-null values include:

• Valid data types, such as strings, booleans, or numbers
• Empty strings, such as "" or "-"

In query results, EraSearch omits documents if the field doesn't appear in the document or if the field is set to null or []. For more about exists queries, visit Elasticsearch's exists query documentation.

Exists query examples

This query returns documents where the hike_name field has non-null values:

{
  "query": {
    "exists": {
      "field": "hike_name"
    }
  }
}

The query below wraps an exists query in a boolean query. It returns documents where average_temperature is missing, set to null, or set to [].

{
  "query": {
    "bool": {
      "must_not": {
        "exists": {
          "field": "average_temperature" 
        }
      }
    }
  }
}

Multi-match query¶

Find documents where one or more tokenized fields have specific terms.

Supported types¶

The type parameter determines how EraSearch defines matches. You must set the type parameter in multi-match queries.

EraSearch supports two multi-match type parameters: phrase and phrase_prefix.

phrase

Use phrase to match documents where:

• All terms are in the fields' values.
• Terms are in the same order as they are in the query.
• Terms aren't separated by other words.

The phrase type is case insensitive. For example, the query terms Green meadow match field values such as green meadow and We sawGreen MeadowPeak.

phrase_prefix

Use phrase_prefix to match documents where:

• All terms are in the fields' values.
• Terms are in the same order as they are in the query.
• Terms aren't separated by other words.
• The last term is the start of a word.

The phrase_prefix type is case insensitive. For example, the query terms great fa match field values such as Great falls and TheGreat Favorite.

Unsupported types¶

EraSearch doesn't support these Elasticsearch multi-match types:

• best_fields
• most_fields
• cross_fields
• bool_prefix

For more about multi-match queries, visit Elasticsearch's multi-match query documentation.

Multi-match query examples

The query below requests documents where _line or hike_features includes the terms full of aspens.

The query uses the phrase type. It matches values such as Full of aspens and The hike isfull of aspens. It doesn't match values where other words separate the terms, such as The hike isfull ofviews andaspens.

{
  "query": {
    "multi_match": {
      "query": "full of aspens",
      "type": "phrase",
      "fields": [ "_line", "hike_features" ]
    }
  }
}

The next query requests documents where _line or hike_features includes the terms the hike has f.

The query uses the phrase_prefix type. It matches values such as The hike has forests and valleys and Experts only, andthe hike has Fragaria. It doesn't match values missing the last term, such as The hike has rocks.

{
  "query": {
    "multi_match": {
      "query": "the hike has f",
      "type": "phrase_prefix",
      "fields": [ "_line", "hike_features" ]
    }
  }
}

Query-string query¶

Find documents using Elasticsearch's mini-language: query-string syntax.

Top-level parameters¶

EraSearch supports these top-level parameters for query-string queries:

• default_field
• fields
• lenient
• query

Query-string syntax¶

EraSearch supports the following query-string syntax. You can use the syntax in either the query request-body parameter or the q query-string parameter.

• Boolean operators
• Field names
• Fuzziness
• Ranges
• Regular expressions
• Wildcards

EraSearch doesn't support these parts of Elasticsearch's query-string-syntax:

• Boosting
• Proximity searches

For more about query-string queries, visit Elasticsearch's query-string query documentation.

Query-string query example

The query below uses the fields and query top-level parameters. It groups query terms with OR and uses the fuzziness operator (~).

The query returns documents where _line or description have the terms footpath or paved. The values can have variations of footpath, such as footpat4 and footpaths.

{
  "query": {
    "query_string": {
      "fields": ["_line","description"],
      "query": "footpath~ OR paved"
    }
  }
}