Parameterized cypher search
This example shows how to pass parameters into a Cypher path query, as query variables 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.
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[ { "input": { "type": "elasticsearch-query-dsl-mixin", "query": { "match": { "description": { "query": "lily" } } }, "parameters": [], "isQueryVerifiedToBeSafe": false }, "step-handler": "elasticsearch-query-dsl-mixin (App\\EventSystem\\SearchStep\\EventListener\\ElasticsearchQueryDslMixinSearchStepEventListener)", "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", "3283fd3d-8083-4170-882a-41b1cd152c55", "74023bac-88ea-4031-b4a5-68d861ea2e91", "de004523-5165-4f10-872b-92eb9637a5d1", "8940d70b-5b6f-43b7-bee4-41d073396ff8", "c3b3dcf9-4947-43b3-b877-7a337eea5fda" ], "totalElements": 8 }, "isQueryVerifiedToBeSafe": false }, "step-handler": "element-hydration (App\\EventSystem\\SearchStep\\EventListener\\ElementHydrationSearchStepEventListener)", "start": 1757622122.764754, "end": 1757622122.837879, "duration": 0.07312488555908203 }]{ "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 flame lily, climbing lily, creeping lily, glory lily,[3] gloriosa lily, tiger claw,[4] and fire lily.[5]" } }, { "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 tritomea, torch lily, or red hot poker, due to the shape and color of its inflorescence. The leaves are reminiscent of a lily, and the flowerhead can reach up to 1.5 m (5 ft) in height. There are many varieties of torch lily, and they bloom at different times during the growing season. The flowers are red, orange, and yellow." } }, { "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 native to the Balkans and Middle East, and naturalized in other parts of Europe, including France, Italy, and Ukraine, and in North Africa, the Canary Islands, Mexico, and other regions.[1][5] It has been cultivated since antiquity, for at least 3,000 years,[6] and has great symbolic value since then for many cultures. It is susceptible to several virus diseases common to lilies, and especially to Botrytis fungus. One technique to avoid problems with viruses is to grow plants from seed instead of bulblets." } }, { "type": "Plant", "id": "3283fd3d-8083-4170-882a-41b1cd152c55", "data": { "created": "2025-09-08T22:06:44+00:00", "updated": "2025-09-08T22:06:44+00:00", "name": "Lotus", "scenario": "general.botanicExample", "scientificName": "N. nucifera", "link": "https://en.wikipedia.org/wiki/Nelumbo_nucifera", "description": "Nelumbo nucifera, also known as Padma (Sanskrit: \\u092a\\u0926\\u094d\\u092e, romanized: Padm\\u0101, lit.\\u2009'Lotus') or Kamala (Sanskrit: \\u0915\\u092e\\u0932, lit. 'Lotus'), sacred lotus, pink lotus, Indian lotus,[1] or simply lotus, is one of two extant species of aquatic plant in the family Nelumbonaceae. It is sometimes colloquially called a water lily, though this more often refers to members of the family Nymphaeaceae.[2] The lotus belongs in the order Proteales." } }, { "type": "Plant", "id": "74023bac-88ea-4031-b4a5-68d861ea2e91", "data": { "created": "2025-09-08T22:06:44+00:00", "updated": "2025-09-08T22:06:44+00:00", "name": "Magnolia", "scenario": "general.botanicExample", "scientificName": "M. denudata", "link": "https://en.wikipedia.org/wiki/Magnolia_denudata", "description": "Magnolia denudata, the lilytree[2] or Yulan magnolia (simplified Chinese: \\u7389\\u5170\\u82b1; traditional Chinese: \\u7389\\u862d\\u82b1; pinyin: y\\u00f9l\\u00e1nhu\\u0101; lit. 'jade orchid/lily'), is native to central and eastern China.[3] It has been cultivated in Chinese Buddhist temple gardens since 600 AD. Its flowers were regarded as a symbol of purity in the Tang dynasty and it was planted in the grounds of the emperor's palace. It is the official city flower of Shanghai." } }, { "type": "Plant", "id": "de004523-5165-4f10-872b-92eb9637a5d1", "data": { "created": "2025-09-08T22:06:44+00:00", "updated": "2025-09-08T22:06:44+00:00", "name": "Desert Rose", "scenario": "general.botanicExample", "scientificName": "A. obesum", "link": "https://en.wikipedia.org/wiki/Adenium_obesum", "description": "Adenium obesum, more commonly known as a desert rose, is a poisonous species of flowering plant belonging to the tribe Nerieae of the subfamily Apocynoideae of the dogbane family, Apocynaceae.[3] It is native to the Sahel regions south of the Sahara (from Mauritania and Senegal to Sudan), tropical and subtropical eastern and southern Africa, as well as the Arabian Peninsula. Other names for the flower include Sabi star, kudu, mock azalea, and impala lily. Adenium obesum is a popular houseplant and bonsai in temperate regions." } }, { "type": "Plant", "id": "8940d70b-5b6f-43b7-bee4-41d073396ff8", "data": { "created": "2025-09-08T22:06:44+00:00", "updated": "2025-09-08T22:06:44+00:00", "name": "Tulip", "scenario": "general.botanicExample", "scientificName": "Tulipa", "link": "https://en.wikipedia.org/wiki/Tulip", "description": "Tulips are spring-blooming perennial herbaceous bulbiferous geophytes in the Tulipa genus. Their flowers are usually large, showy, and brightly coloured, generally red, orange, pink, yellow, or white. They often have a different coloured blotch at the base of the tepals, internally. Because of a degree of variability within the populations and a long history of cultivation, classification has been complex and controversial. The tulip is a member of the lily family, Liliaceae,[2] along with 14 other genera, where it is most closely related to Amana, Erythronium, and Gagea in the tribe Lilieae." } }, { "type": "Plant", "id": "c3b3dcf9-4947-43b3-b877-7a337eea5fda", "data": { "created": "2025-09-08T22:06:44+00:00", "updated": "2025-09-08T22:06:44+00:00", "name": "Daffodil", "scenario": "general.botanicExample", "scientificName": "N. pseudonarcissus", "link": "https://en.wikipedia.org/wiki/Narcissus_pseudonarcissus", "description": "Narcissus pseudonarcissus, commonly named the wild daffodil or Lent lily (Welsh: Cennin Pedr), is a perennial flowering plant.[1][2][3][4][5][6]\n\nThis species has pale yellow tepals, with a darker central trumpet. The long, narrow leaves are slightly greyish green in colour and rise from the base of the stem. The plant grows from a bulb. The flowers produce seeds which, when germinated, take five to seven years to produce a flowering plant. (Sexual seed reproduction mixes the traits of both parent flowers, so if garden hybrid cultivars are planted close to wild populations of Narcissus pseudonarcissus, there is a danger that the new seedlings, having hybrid vigour, could out-compete the wild plants.)[7]" } } ], "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\\ElasticsearchQueryDslMixinSearchStepEventListener)", "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", "3283fd3d-8083-4170-882a-41b1cd152c55", "74023bac-88ea-4031-b4a5-68d861ea2e91", "de004523-5165-4f10-872b-92eb9637a5d1", "8940d70b-5b6f-43b7-bee4-41d073396ff8", "c3b3dcf9-4947-43b3-b877-7a337eea5fda" ], "totalElements": 8 }, "isQueryVerifiedToBeSafe": false }, "step-handler": "element-hydration (App\\EventSystem\\SearchStep\\EventListener\\ElementHydrationSearchStepEventListener)", "start": 1757622122.764754, "end": 1757622122.837879, "duration": 0.07312488555908203 } ]}Access-Control-Allow-Headers: *Access-Control-Allow-Methods: GET, HEAD, POST, OPTIONS, PUT, PATCH, DELETE, PROPFIND, PROPPATCH, MKCOL, COPY, MOVE, LOCK, UNLOCKAccess-Control-Allow-Origin: *Access-Control-Expose-Headers: ETag, LocationAllow: GET, HEAD, POST, OPTIONS, PUT, PATCH, DELETE, PROPFIND, PROPPATCH, MKCOL, COPY, MOVE, LOCK, UNLOCKCache-Control: no-cache, privateContent-Type: application/json; charset=utf-8Date: Sat, 06 Sep 2025 14:57:35 GMTTransfer-Encoding: chunkedX-Powered-By: Ember Nexus APIPassing 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.