Writing an Elasticsearch query

The Elasticsearch query step lets you run Query DSL queries against the internal Elasticsearch database. This guide walks through building and running a query; see the reference page for the full list of supported features and security constraints.

With access to Kibana

If you have access to the Elasticsearch database and Kibana, then you can use Kibana’s console to experiment and test custom queries, as well as explore the data schemas of Elasticsearch.
Note that Kibana’s console requires a full query, while Ember Nexus API’s POST /search endpoint only accepts the content of the query property:

curl -X POST \
  -H 'Authorization: Bearer secret-token:PIPeJGUt7c00ENn8a5uDlc' \
  -H 'Content-Type: application/json' \
  -d '{
        "debug": true,
        "steps": [
          {
            "type": "elasticsearch-query-dsl-mixin",
            "query": {
              "match": {
                "description": {
                  "query": "lily"
                }
              }
            }
          },
          {
            "type": "element-hydration"
          }
        ]
      }' \
  https://api.example.com/search

GET /_search
{
  "query": {
    "match": {
      "description": {
        "query": "lily"
      }
    }
  }
}

Without access to Kibana

If you do not have direct access, you need to build the query blindly. As small errors can break the whole query, it is recommended to slowly build your query up, and to test it frequently.

As the base of your query you can use one of the provided examples.

Generative AI like Claude and its competitors are usually experienced enough to help with Elasticsearch query generation.

Parameterized Elasticsearch queries

Elasticsearch’s Query DSL has no native concept of parameters. To still let client-provided data flow into a query, Ember Nexus lets you write {{your_expression}} anywhere inside the query object; the expression is evaluated against the step’s parameters and its result replaces the placeholder before the query reaches Elasticsearch.
See parameters and expressions for how parameters flow between search steps, the reference page for a worked example, and Expr Lang for the full expression syntax.