API version: dev

---

# Exact keyword matching

This example uses Elasticsearch's [`term` query](https://www.elastic.co/docs/reference/query-languages/query-dsl/query-dsl-term-query)
to retrieve all elements whose `name` has the exact same content as the provided query, "Bluebell", and are accessible
to the user.\
Results are then [hydrated](/reference/search/element-hydration.md), i.e. transformed into a collection response.

**Note**: Instead of querying the Elasticsearch property `name` directly, we use `name.keyword` for a more efficient
lookup. The `.keyword` suffix is part of Elasticsearch's automatic schema generation process. Manually managed schemas
might differ. See [their documentation](https://www.elastic.co/docs/reference/elasticsearch/mapping-reference/keyword)
for details.

```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": {
              "term": {
                "name.keyword": {
                  "value": "Bluebell"
                }
              }
            }
          },
          {
            "type": "element-hydration"
          }
        ]
      }' \
  https://api.example.com/search
```

##### Response Body

```json
{
  "type": "_SearchResultResponse",
  "results": [
    {
      "type": "Plant",
      "id": "83b35321-4a91-4e9f-a49b-66d718c32ba7",
      "data": {
        "images": [
          {
            "description": "Mertensia virginica Virginia Bluebell seen in Brooklyn Botanic Garden",
            "imageLinkFull": "https://upload.wikimedia.org/wikipedia/commons/3/31/Mertensia_virginica.bbg.jpg",
            "imageLinkThumbnail": "https://upload.wikimedia.org/wikipedia/commons/thumb/3/31/Mertensia_virginica.bbg.jpg/960px-Mertensi...",
            "link": "https://en.wikipedia.org/wiki/File:Mertensia_virginica.bbg.jpg"
          },
          {
            "description": "Virginia Bluebells along the Rocky River in Berea, OH. Photo by Geoffrey A. Landis",
            "imageLinkFull": "https://upload.wikimedia.org/wikipedia/commons/6/6f/Virginia_Bluebells_at_Rocky_River.jpg",
            "imageLinkThumbnail": "https://upload.wikimedia.org/wikipedia/commons/thumb/6/6f/Virginia_Bluebells_at_Rocky_River.jpg/960p...",
            "link": "https://en.wikipedia.org/wiki/File:Virginia_Bluebells_at_Rocky_River.jpg"
          }
        ],
        "created": "2025-09-25T18:35:28+00:00",
        "updated": "2025-09-25T18:35:28+00:00",
        "name": "Bluebell",
        "scenario": "general.botanicExample",
        "scientificName": "M. virginica",
        "link": "https://en.wikipedia.org/wiki/Mertensia_virginica",
        "description": "Mertensia virginica (common names Virginia bluebells,[1] Virginia cowslip,[2] lungwort oysterleaf, R..."
      }
    }
  ],
  "debug": [
    {
      "input": {
        "type": "elasticsearch-query-dsl-mixin",
        "query": {
          "term": {
            "name.keyword": {
              "value": "Bluebell"
            }
          }
        },
        "parameters": {
          "stepResults": []
        }
      },
      "step-handler": "elasticsearch-query-dsl-mixin (App\\EventSystem\\SearchStep\\EventListener\\ElasticsearchQueryDslMixinSe...",
      "start": 1758825390.524884,
      "indices": "*",
      "combinedQuery": {
        "_source": [
          "_id"
        ],
        "from": 0,
        "size": 25,
        "query": {
          "bool": {
            "must": [
              {
                "term": {
                  "name.keyword": {
                    "value": "Bluebell"
                  }
                }
              },
              {
                "bool": {
                  "should": [
                    {
                      "terms": {
                        "_groupsWithSearchAccess.keyword": []
                      }
                    },
                    {
                      "term": {
                        "_usersWithSearchAccess.keyword": {
                          "value": "7baba8b7-a6bb-4184-9a9a-925a4d2736b0"
                        }
                      }
                    }
                  ],
                  "minimum_should_match": 1
                }
              }
            ]
          }
        }
      },
      "end": 1758825390.554652,
      "duration": 0.029768
    },
    {
      "input": {
        "type": "element-hydration",
        "query": null,
        "parameters": {
          "stepResults": [
            {
              "elements": [
                {
                  "id": "83b35321-4a91-4e9f-a49b-66d718c32ba7",
                  "type": "Plant",
                  "metadata": {
                    "score": 3.9060724
                  }
                }
              ],
              "totalHits": 1,
              "maxScore": 3.9060724
            }
          ]
        }
      },
      "step-handler": "element-hydration (App\\EventSystem\\SearchStep\\EventListener\\ElementHydrationSearchStepEventListener)",
      "start": 1758825390.554819,
      "accessibleElementIds": [
        "83b35321-4a91-4e9f-a49b-66d718c32ba7"
      ],
      "end": 1758825390.569048,
      "duration": 0.014229
    }
  ]
}
```

##### Response Headers

```http
Access-Control-Allow-Headers: *
Access-Control-Allow-Methods: GET, HEAD, POST, OPTIONS, PUT, PATCH, DELETE, PROPFIND, PROPPATCH, MKCOL, COPY, MOVE, LOCK, UNLOCK
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: ETag, Location
Allow: GET, HEAD, POST, OPTIONS, PUT, PATCH, DELETE, PROPFIND, PROPPATCH, MKCOL, COPY, MOVE, LOCK, UNLOCK
Cache-Control: no-cache, private
Content-Type: application/json; charset=utf-8
Date: Thu, 11 Sep 2025 20:23:41 GMT
Transfer-Encoding: chunked
X-Powered-By: Ember Nexus API
```

As only a single element has the name "Bluebell", the search response is almost empty.

---

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

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

Previous: [Full text search](/reference/search/elasticsearch-query-dsl-mixin/full-text-search.md)

Next: [Combining queries with bool](/reference/search/elasticsearch-query-dsl-mixin/combining-queries-with-bool.md)