Parameterized element ids

Since elementIds accepts an expression string instead of a literal array, the list of ids to hydrate can be computed from the step’s parameters. This example receives a list of elements objects, each carrying an arbitrary score, and uses Expr Lang’s filter, sortBy and map functions to keep only elements scoring above 1.0, sort them by score descending, and extract just their ids - all without a prior search step.

curl -X POST \
  -H 'Authorization: Bearer secret-token:PIPeJGUt7c00ENn8a5uDlc' \
  -H 'Content-Type: application/json' \
  -d '{
        "debug": true,
        "steps": [
          {
            "type": "element-hydration",
            "query": {
              "elementIds": "{{map(sortBy(filter(elements, #.score > 1.0), .score, \"desc\"), #.id)}}"
            },
            "parameters": {
              "elements": [
                {"id": "d747bfe6-0d52-4119-87c6-1fc37ed9395b", "score": 0.9},
                {"id": "70965ab5-bc3e-4bbe-aacf-1b7e12b76110", "score": 4.0},
                {"id": "b133d1d5-a24c-4409-955f-99b53b3f2a73", "score": 1.4},
                {"id": "4a335e0b-e6bf-4c64-8c28-2a17bd6f0dec", "score": 3.2}
              ]
            }
          }
        ]
      }' \
  https://api.example.com/search
[
  {
    "input": {
      "type": "element-hydration",
      "query": {
        "elementIds": "{{map(sortBy(filter(elements, #.score > 1.0), .score, \"desc\"), #.id)}}"
      },
      "parameters": {
        "elements": [
          {
            "id": "d747bfe6-0d52-4119-87c6-1fc37ed9395b",
            "score": 0.9
          },
          {
            "id": "70965ab5-bc3e-4bbe-aacf-1b7e12b76110",
            "score": 4
          },
          {
            "id": "b133d1d5-a24c-4409-955f-99b53b3f2a73",
            "score": 1.4
          },
          {
            "id": "4a335e0b-e6bf-4c64-8c28-2a17bd6f0dec",
            "score": 3.2
          }
        ],
        "stepResults": []
      }
    },
    "step-handler": "element-hydration (App\\EventSystem\\SearchStep\\EventListener\\ElementHydrationSearchStepEventListener)",
    "start": 1758825392.623079,
    "accessibleElementIds": [
      "70965ab5-bc3e-4bbe-aacf-1b7e12b76110",
      "4a335e0b-e6bf-4c64-8c28-2a17bd6f0dec",
      "b133d1d5-a24c-4409-955f-99b53b3f2a73"
    ],
    "end": 1758825392.730921,
    "duration": 0.107842
  }
]
{
  "type": "_SearchResultResponse",
  "results": [
    {
      "type": "Plant",
      "id": "70965ab5-bc3e-4bbe-aacf-1b7e12b76110",
      "data": {
        "images": [
          {
            "description": "White trillium (Trillium grandiflorum) blooming in Backus Woods.",
            "imageLinkFull": "https://upload.wikimedia.org/wikipedia/commons/e/e7/Trillium_grandiflorum_at_Backus_Woods.jpg",
            "imageLinkThumbnail": "https://upload.wikimedia.org/wikipedia/commons/thumb/e/e7/Trillium_grandiflorum_at_Backus_Woods.jpg/960px-Trillium_grandiflorum_at_Backus_Woods.jpg",
            "link": "https://en.wikipedia.org/wiki/File:Trillium_grandiflorum_at_Backus_Woods.jpg"
          },
          {
            "description": "Pink form of Trillium grandiflorum",
            "imageLinkFull": "https://upload.wikimedia.org/wikipedia/commons/0/0e/Trillium_grandiflorum_pink1.jpg",
            "imageLinkThumbnail": "https://upload.wikimedia.org/wikipedia/commons/thumb/0/0e/Trillium_grandiflorum_pink1.jpg/960px-Trillium_grandiflorum_pink1.jpg",
            "link": "https://en.wikipedia.org/wiki/File:Trillium_grandiflorum_pink1.jpg"
          },
          {
            "description": "Photograph of the flower of the White Trilliumen (Trillium grandiflorum en ). Photo taken at the Mt. Cuba Center where it was identified.",
            "imageLinkFull": "https://upload.wikimedia.org/wikipedia/commons/0/0c/White_Trillium_Trillium_grandiflorum_Flower_2613px.jpg",
            "imageLinkThumbnail": "https://upload.wikimedia.org/wikipedia/commons/thumb/0/0c/White_Trillium_Trillium_grandiflorum_Flower_2613px.jpg/960px-White_Trillium_Trillium_grandiflorum_Flower_2613px.jpg",
            "link": "https://en.wikipedia.org/wiki/File:White_Trillium_Trillium_grandiflorum_Flower_2613px.jpg"
          }
        ],
        "created": "2025-09-25T18:35:28+00:00",
        "updated": "2025-09-25T18:35:28+00:00",
        "name": "Trillium",
        "scenario": "general.botanicExample",
        "scientificName": "T. grandiflorum",
        "link": "https://en.wikipedia.org/wiki/Trillium_grandiflorum",
        "description": "Trillium grandiflorum, the white trillium,[3] large-flowered trillium, great white trillium,[4] white wake-robin or French: trille blanc, is a species of flowering plant in the family Melanthiaceae. A monocotyledonous, herbaceous perennial, the plant is native to eastern North America, from northern Quebec to the southern parts of the United States through the Appalachian Mountains into northernmost Georgia and west to Minnesota. There are also several isolated populations in Nova Scotia, Maine, southern Illinois, and Iowa.[5]"
      }
    },
    {
      "type": "Plant",
      "id": "4a335e0b-e6bf-4c64-8c28-2a17bd6f0dec",
      "data": {
        "images": [
          {
            "description": "Hibiscus heterophyllus cultivated plant growing in Thirlmere",
            "imageLinkFull": "https://upload.wikimedia.org/wikipedia/commons/c/c8/Hibiscus_heterophyllus_flower_image.jpg",
            "imageLinkThumbnail": "https://upload.wikimedia.org/wikipedia/commons/thumb/c/c8/Hibiscus_heterophyllus_flower_image.jpg/500px-Hibiscus_heterophyllus_flower_image.jpg",
            "link": "https://en.wikipedia.org/wiki/File:Hibiscus_heterophyllus_flower_image.jpg"
          },
          {
            "description": "Hibiscus heterophyllus in flower, Chatswood West",
            "imageLinkFull": "https://upload.wikimedia.org/wikipedia/commons/1/19/Hibiscus_heterophyllus_Chatswood_West.jpg",
            "imageLinkThumbnail": "https://upload.wikimedia.org/wikipedia/commons/1/19/Hibiscus_heterophyllus_Chatswood_West.jpg",
            "link": "https://en.wikipedia.org/wiki/File:Hibiscus_heterophyllus_Chatswood_West.jpg"
          }
        ],
        "created": "2025-09-25T18:35:28+00:00",
        "updated": "2025-09-25T18:35:28+00:00",
        "name": "Hibiscus",
        "scenario": "general.botanicExample",
        "scientificName": "H. heterophyllus",
        "link": "https://en.wikipedia.org/wiki/Hibiscus_heterophyllus",
        "description": "Hibiscus heterophyllus, commonly known as native rosella or toilet paper bush,[2] is a flowering plant in the family Malvaceae. It a shrub or small tree with white, pale pink or yellow flowers with a dark red centre and grows in New South Wales and Queensland."
      }
    },
    {
      "type": "Plant",
      "id": "b133d1d5-a24c-4409-955f-99b53b3f2a73",
      "data": {
        "images": [
          {
            "description": "Arabian jasmin 'Grand Duke of Tuscany'",
            "imageLinkFull": "https://upload.wikimedia.org/wikipedia/commons/a/ab/Jasminum_sambac_%27Grand_Duke_of_Tuscany%27.jpg",
            "imageLinkThumbnail": "https://upload.wikimedia.org/wikipedia/commons/thumb/a/ab/Jasminum_sambac_%27Grand_Duke_of_Tuscany%27.jpg/500px-Jasminum_sambac_%27Grand_Duke_of_Tuscany%27.jpg",
            "link": "https://en.wikipedia.org/wiki/File:Jasminum_sambac_%27Grand_Duke_of_Tuscany%27.jpg"
          }
        ],
        "created": "2025-09-25T18:35:28+00:00",
        "updated": "2025-09-25T18:35:28+00:00",
        "name": "Jasmine",
        "scenario": "general.botanicExample",
        "scientificName": "J. sambac",
        "link": "https://en.wikipedia.org/wiki/Jasminum_sambac",
        "description": "Jasminum sambac (Arabian jasmine or Sambac jasmine)[1][3] is a species of jasmine native to Bhutan and India.[4][5] It is cultivated in many places, especially West Asia, South Asia and Southeast Asia. It is naturalised in many scattered locales: Mauritius, Madagascar, the Maldives, Christmas Island, Chiapas, Central America, southern Florida, the Bahamas, Cuba, Hispaniola, Jamaica, Puerto Rico, and the Lesser Antilles.[6][4][7]"
      }
    }
  ],
  "debug": [
    {
      "input": {
        "type": "element-hydration",
        "query": {
          "elementIds": "{{map(sortBy(filter(elements, #.score > 1.0), .score, \"desc\"), #.id)}}"
        },
        "parameters": {
          "elements": [
            {
              "id": "d747bfe6-0d52-4119-87c6-1fc37ed9395b",
              "score": 0.9
            },
            {
              "id": "70965ab5-bc3e-4bbe-aacf-1b7e12b76110",
              "score": 4
            },
            {
              "id": "b133d1d5-a24c-4409-955f-99b53b3f2a73",
              "score": 1.4
            },
            {
              "id": "4a335e0b-e6bf-4c64-8c28-2a17bd6f0dec",
              "score": 3.2
            }
          ],
          "stepResults": []
        }
      },
      "step-handler": "element-hydration (App\\EventSystem\\SearchStep\\EventListener\\ElementHydrationSearchStepEventListener)",
      "start": 1758825392.623079,
      "accessibleElementIds": [
        "70965ab5-bc3e-4bbe-aacf-1b7e12b76110",
        "4a335e0b-e6bf-4c64-8c28-2a17bd6f0dec",
        "b133d1d5-a24c-4409-955f-99b53b3f2a73"
      ],
      "end": 1758825392.730921,
      "duration": 0.107842
    }
  ]
}
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

The element scoring 0.9 is filtered out, and the remaining three are hydrated in descending score order - even though they were listed in a different order in the input elements parameter.

Note: this same technique commonly appears as the last step of a multi-step pipeline, filtering or reordering the stepResults of an earlier step rather than a client-supplied parameter.