API version: dev

---

# Writing an Elasticsearch query

The [Elasticsearch query](/reference/search/elasticsearch-query-dsl-mixin.md) step lets you run
[Query DSL](https://www.elastic.co/docs/reference/query-languages/query-dsl) queries against the internal
Elasticsearch database. This guide walks through building and running a query; see the
[reference page](/reference/search/elasticsearch-query-dsl-mixin.md) 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](https://www.elastic.co/docs/explore-analyze/query-filter/tools/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`](/api/post-search.md)
endpoint only accepts the **content of the `query` property**:

#### Ember Nexus

```bash
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
```

#### Kibana's console

```txt
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](/reference/search/elasticsearch-query-dsl-mixin.md#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](/guide/search/parameters-and-expressions.md) for how parameters flow between search
steps, the [reference page](/reference/search/elasticsearch-query-dsl-mixin.md#parameterized-elasticsearch-queries) for a
worked example, and [Expr Lang](/reference/expr-lang.md) for the full expression syntax.

---

Home: [Ember Nexus API docs](/index.md)

Full site map: [llms.txt](/llms.txt)

Previous: [Choosing a search step](/guide/search/choosing-a-search-step.md)

Next: [Writing a Cypher query](/guide/search/writing-a-cypher-query.md)