API version: dev

---

# Parameterized cypher search

This example shows how to pass parameters into a Cypher path query, as [query variables](/reference/search/cypher-path-subset.md#input-parameters)
rather than string interpolation. Cypher path query does not support expressions like the Elasticsearch query
step does - instead, any step or global parameter is directly available inside the query as a `$variable`.\
Here, `$taxonNames` restricts the search to plants belonging to any of the given taxa, and Cypher's own `IN` operator
performs the membership check.

```bash
curl -X POST \
  -H 'Authorization: Bearer secret-token:PIPeJGUt7c00ENn8a5uDlc' \
  -H 'Content-Type: application/json' \
  -d '{
        "debug": true,
        "steps": [
          {
            "type": "cypher-path-subset",
            "query": "MATCH path=((:Plant)-[:IS_MEMBER_OF*..]->(t:Taxon)) WHERE t.name IN $taxonNames RETURN path LIMIT 5",
            "parameters": {
              "taxonNames": ["Liliales"]
            }
          },
          {
            "type": "element-hydration"
          }
        ]
      }' \
  https://api.example.com/search
```

##### Response Body

```json
{
  "type": "_SearchResultResponse",
  "results": [
    {
      "type": "Plant",
      "id": "258c0dfe-b1d8-4839-beed-d00d1b544a96",
      "data": {
        "created": "2025-09-08T22:06:44+00:00",
        "updated": "2025-09-08T22:06:44+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": "Plant",
      "id": "f8179dfc-5578-44de-adc0-d6b613eb7a32",
      "data": {
        "created": "2025-09-08T22:06:44+00:00",
        "updated": "2025-09-08T22:06:44+00:00",
        "name": "Red Hot Poker",
        "scenario": "general.botanicExample",
        "scientificName": "K. uvaria",
        "link": "https://en.wikipedia.org/wiki/Kniphofia_uvaria",
        "description": "Kniphofia uvaria is a species of flowering plant in the family Asphodelaceae, commonly known as trit..."
      }
    },
    {
      "type": "Plant",
      "id": "23508e6c-632a-496d-9bd6-8c62a03216af",
      "data": {
        "created": "2025-09-08T22:06:44+00:00",
        "updated": "2025-09-08T22:06:44+00:00",
        "name": "Lily",
        "scenario": "general.botanicExample",
        "scientificName": "L. candidum",
        "link": "https://en.wikipedia.org/wiki/Lilium_candidum",
        "description": "Lilium candidum, the Madonna lily[2][3] or white lily,[4] is a plant in the true lily family. It is ..."
      }
    },
    "... 5 more items omitted (shapes seen: type:Plant) ..."
  ],
  "debug": [
    {
      "input": {
        "type": "elasticsearch-query-dsl-mixin",
        "query": {
          "match": {
            "description": {
              "query": "lily"
            }
          }
        },
        "parameters": [],
        "isQueryVerifiedToBeSafe": false
      },
      "step-handler": "elasticsearch-query-dsl-mixin (App\\EventSystem\\SearchStep\\EventListener\\ElasticsearchQueryDslMixinSe...",
      "start": 1757622122.749882,
      "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
                }
              }
            ]
          }
        }
      },
      "indices": "*",
      "end": 1757622122.764609,
      "duration": 0.014727115631103516
    },
    {
      "input": {
        "type": "element-hydration",
        "query": null,
        "parameters": {
          "elementIds": [
            "258c0dfe-b1d8-4839-beed-d00d1b544a96",
            "f8179dfc-5578-44de-adc0-d6b613eb7a32",
            "23508e6c-632a-496d-9bd6-8c62a03216af",
            "... 5 more items omitted (shapes seen: string) ..."
          ],
          "totalElements": 8
        },
        "isQueryVerifiedToBeSafe": false
      },
      "step-handler": "element-hydration (App\\EventSystem\\SearchStep\\EventListener\\ElementHydrationSearchStepEventListener)",
      "start": 1757622122.764754,
      "end": 1757622122.837879,
      "duration": 0.07312488555908203
    }
  ]
}
```

##### 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: Sat, 06 Sep 2025 14:57:35 GMT
Transfer-Encoding: chunked
X-Powered-By: Ember Nexus API
```

Passing a list with more than one taxon name would widen the search to plants belonging to any of them, without
changing the query string itself - useful for building search forms where the set of matched taxa is chosen by the
end user.

---

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

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

Previous: [Find nested elements](/reference/search/cypher-path-subset/find-nested-elements.md)

Next: [Grammar](/reference/search/cypher-path-subset/grammar.md)