API version: dev --- # Search ## General search process Every search request is written in **search steps** - smaller execution units, which are specialized for one specific database or technology. Results of earlier search steps are available to later search steps as input parameters, allowing **cross-database search logic**. Ember Nexus currently offers three search steps: an Elasticsearch query for full text and explorative search, a Cypher path query for structural, relation-aware search, and an element hydration step that turns raw ids into full elements. See [choosing a search step](/guide/search/choosing-a-search-step.md) for guidance on which one (or combination) fits your use case, and the [reference page](/reference/search.md) for the full technical details and security constraints of each. ## Guides - [Choosing a search step](/guide/search/choosing-a-search-step.md) - [Writing an Elasticsearch query](/guide/search/writing-an-elasticsearch-query.md) - [Writing a Cypher query](/guide/search/writing-a-cypher-query.md) - [Parameters and expressions](/guide/search/parameters-and-expressions.md) ## A first example In this example, only Elasticsearch is queried for all elements, whose `description`-property contains the word `lily`.\ The `element-hydration`-step only makes sure, that the results from Elasticsearch are correctly hydrated and returned. See also [Elasticsearch's documentation about the match query clause](https://www.elastic.co/docs/reference/query-languages/query-dsl/query-dsl-match-query). ```bash curl \ -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 ``` ##### Response Body ```json { "type": "_SearchResultResponse", "results": [ { "type": "Taxon", "id": "16884ac8-ba7a-4c91-8449-4fdd803644b6", "data": { "created": "2025-09-25T18:35:26+00:00", "updated": "2025-09-25T18:35:26+00:00", "name": "Gloriosa", "path": "/Plantae/Tracheophytes/Angiosperms/Monocots/Liliales/Colchicaceae/Gloriosa", "scenario": "general.botanicExample", "link": "https://en.wikipedia.org/wiki/Gloriosa_(plant)", "description": "Gloriosa is a genus of 12 species in the plant family Colchicaceae, and includes the formerly recogn..." } }, { "type": "Plant", "id": "258c0dfe-b1d8-4839-beed-d00d1b544a96", "data": { "images": [ { "description": "", "imageLinkFull": "https://upload.wikimedia.org/wikipedia/commons/f/fe/Flame_lily.png", "imageLinkThumbnail": "https://upload.wikimedia.org/wikipedia/commons/thumb/f/fe/Flame_lily.png/500px-Flame_lily.png", "link": "https://en.wikipedia.org/wiki/File:Flame_lily.png" }, { "description": "Gloriosa superba at Mabvuku, Harare, Zimbabwe", "imageLinkFull": "https://upload.wikimedia.org/wikipedia/commons/b/bc/Gloriosa_superba_1.jpg", "imageLinkThumbnail": "https://upload.wikimedia.org/wikipedia/commons/thumb/b/bc/Gloriosa_superba_1.jpg/960px-Gloriosa_supe...", "link": "https://en.wikipedia.org/wiki/File:Gloriosa_superba_1.jpg" } ], "created": "2025-09-25T18:35:28+00:00", "updated": "2025-09-25T18:35:28+00:00", "name": "Flame Lily", "scenario": "general.botanicExample", "scientificName": "G. superba", "link": "https://en.wikipedia.org/wiki/Gloriosa_superba", "description": "Gloriosa superba is a species of flowering plant in the family Colchicaceae. Common names include fl..." } }, { "type": "Taxon", "id": "1feedd9f-0c12-490c-8461-b12ff7447ac8", "data": { "created": "2025-09-25T18:35:26+00:00", "updated": "2025-09-25T18:35:26+00:00", "name": "Lilieae", "path": "/Plantae/Tracheophytes/Angiosperms/Monocots/Liliales/Liliaceae/Lilioideae/Lilieae", "scenario": "general.botanicExample", "link": "https://en.wikipedia.org/wiki/Lilieae", "description": "The Lilieae are a monophyletic tribe of monocotyledon perennial, herbaceous mainly bulbous flowering..." } }, "... 17 more items omitted (shapes seen: type:Taxon, type:Plant) ..." ], "debug": [ { "input": { "type": "elasticsearch-query-dsl-mixin", "query": { "match": { "description": { "query": "lily" } } }, "parameters": { "stepResults": [] } }, "step-handler": "elasticsearch-query-dsl-mixin (App\\EventSystem\\SearchStep\\EventListener\\ElasticsearchQueryDslMixinSe...", "start": 1758825391.222043, "indices": "*", "combinedQuery": { "_source": [ "_id" ], "from": 0, "size": 25, "query": { "bool": { "must": [ { "match": { "description": { "query": "lily" } } }, { "bool": { "should": [ { "terms": { "_groupsWithSearchAccess.keyword": [] } }, { "term": { "_usersWithSearchAccess.keyword": { "value": "7baba8b7-a6bb-4184-9a9a-925a4d2736b0" } } } ], "minimum_should_match": 1 } } ] } } }, "end": 1758825391.252388, "duration": 0.030345 }, { "input": { "type": "element-hydration", "query": null, "parameters": { "stepResults": [ { "elements": [ { "id": "16884ac8-ba7a-4c91-8449-4fdd803644b6", "type": "Taxon", "metadata": { "score": 4.5739636 } }, { "id": "258c0dfe-b1d8-4839-beed-d00d1b544a96", "type": "Plant", "metadata": { "score": 3.9976888 } }, { "id": "1feedd9f-0c12-490c-8461-b12ff7447ac8", "type": "Taxon", "metadata": { "score": 3.7564187 } }, "... 17 more items omitted (shapes seen: type:Taxon, type:Plant) ..." ], "totalHits": 20, "maxScore": 4.5739636 } ] } }, "step-handler": "element-hydration (App\\EventSystem\\SearchStep\\EventListener\\ElementHydrationSearchStepEventListener)", "start": 1758825391.25256, "accessibleElementIds": [ "16884ac8-ba7a-4c91-8449-4fdd803644b6", "258c0dfe-b1d8-4839-beed-d00d1b544a96", "1feedd9f-0c12-490c-8461-b12ff7447ac8", "... 17 more items omitted (shapes seen: string) ..." ], "end": 1758825391.322722, "duration": 0.070162 } ] } ``` ##### Response Headers ```http Access-Control-Allow-Headers: Authorization, Origin, X-Requested-With, Content-Type, Accept, Access-Control-Request-Method 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: Sat, 06 Sep 2025 14:57:35 GMT Transfer-Encoding: chunked X-Powered-By: Ember Nexus API ``` As Elasticsearch only returns individual elements, no paths can be observed. For more examples - including structural Cypher searches and requests that combine both databases in one pipeline - see the [reference examples](/reference/search.md#examples). --- Home: [Ember Nexus API docs](/index.md) Full site map: [llms.txt](/llms.txt) Previous: [Elements](/guide/elements.md) Next: [Choosing a search step](/guide/search/choosing-a-search-step.md)