Element hydration

The element hydration search step is a single task, executable within POST /search requests.

The hydration step converts a list of element ids to a collection response, containing elements and all their properties. This step is mostly used to convert results of other search steps to collection responses usable by clients.

Security aspects

As all element ids are internally checked for access by the current user and only accessible elements are hydrated and returned, this search step is considered safe and can therefore be executed by any user.

Input parameters

This search step does not have explicit parameters defined. Parameters are available within expressions.

Input query

The query must be an object containing the following properties:

  • elementIds: List of element ids (string) or a single string containing an expression, which returns a list of element ids (string).

Step result

List of hydrated elements.

Examples

Example

Request

{
  "debug": true,
  "steps": [
    {
      "type": "element-hydration",
      "query": {
        "elementIds": [
          "258c0dfe-b1d8-4839-beed-d00d1b544a96",
          "3283fd3d-8083-4170-882a-41b1cd152c55",
          "8940d70b-5b6f-43b7-bee4-41d073396ff8"
        ]
      }
    }
  ]
}
curl \
  -H 'Authorization: Bearer secret-token:PIPeJGUt7c00ENn8a5uDlc' \
  -H 'Content-Type: application/json' \
  --data-binary @payload.json \
  https://api.example.com/search

Response

[
  {
    "input": {
      "type": "element-hydration",
      "query": {
        "elementIds": [
          "258c0dfe-b1d8-4839-beed-d00d1b544a96",
          "3283fd3d-8083-4170-882a-41b1cd152c55",
          "8940d70b-5b6f-43b7-bee4-41d073396ff8"
        ]
      },
      "parameters": {
        "stepResults": []
      }
    },
    "step-handler": "element-hydration (App\\EventSystem\\SearchStep\\EventListener\\ElementHydrationSearchStepEventListener)",
    "start": 1758825391.88911,
    "accessibleElementIds": [
      "258c0dfe-b1d8-4839-beed-d00d1b544a96",
      "3283fd3d-8083-4170-882a-41b1cd152c55",
      "8940d70b-5b6f-43b7-bee4-41d073396ff8"
    ],
    "end": 1758825391.926094,
    "duration": 0.036984
  }
]
{
  "type": "_SearchResultResponse",
  "results": [
    {
      "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_superba_1.jpg",
            "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 flame lily, climbing lily, creeping lily, glory lily,[3] gloriosa lily, tiger claw,[4] and fire lily.[5]"
      }
    },
    {
      "type": "Plant",
      "id": "3283fd3d-8083-4170-882a-41b1cd152c55",
      "data": {
        "images": [
          {
            "description": "Flower of Nelumbo nucifera, bean of India.",
            "imageLinkFull": "https://upload.wikimedia.org/wikipedia/commons/e/ed/Sacred_lotus_Nelumbo_nucifera.jpg",
            "imageLinkThumbnail": "https://upload.wikimedia.org/wikipedia/commons/thumb/e/ed/Sacred_lotus_Nelumbo_nucifera.jpg/960px-Sacred_lotus_Nelumbo_nucifera.jpg",
            "link": "https://en.wikipedia.org/wiki/File:Sacred_lotus_Nelumbo_nucifera.jpg"
          },
          {
            "description": "Nelumbo nucifera",
            "imageLinkFull": "https://upload.wikimedia.org/wikipedia/commons/3/34/Nelumbo_nucifera1romainguy.jpg",
            "imageLinkThumbnail": "https://upload.wikimedia.org/wikipedia/commons/thumb/3/34/Nelumbo_nucifera1romainguy.jpg/500px-Nelumbo_nucifera1romainguy.jpg",
            "link": "https://en.wikipedia.org/wiki/File:Nelumbo_nucifera1romainguy.jpg"
          }
        ],
        "created": "2025-09-25T18:35:28+00:00",
        "updated": "2025-09-25T18:35:28+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": "8940d70b-5b6f-43b7-bee4-41d073396ff8",
      "data": {
        "images": [
          {
            "description": "in Seoul Forest, South Korea",
            "imageLinkFull": "https://upload.wikimedia.org/wikipedia/commons/7/7b/Tulips_in_Seoul_Forest%2C_South_Korea1.jpg",
            "imageLinkThumbnail": "https://upload.wikimedia.org/wikipedia/commons/thumb/7/7b/Tulips_in_Seoul_Forest%2C_South_Korea1.jpg/500px-Tulips_in_Seoul_Forest%2C_South_Korea1.jpg",
            "link": "https://en.wikipedia.org/wiki/File:Tulips_in_Seoul_Forest,_South_Korea1.jpg"
          },
          {
            "description": "A Yonina cultivar (Division 6) tulip at the Tulip Fest in Albany, New York, United States.",
            "imageLinkFull": "https://upload.wikimedia.org/wikipedia/commons/7/7b/Yonina_Tulip.jpg",
            "imageLinkThumbnail": "https://upload.wikimedia.org/wikipedia/commons/thumb/7/7b/Yonina_Tulip.jpg/960px-Yonina_Tulip.jpg",
            "link": "https://en.wikipedia.org/wiki/File:Yonina_Tulip.jpg"
          },
          {
            "description": "Tulipa orphanidea, garden plant",
            "imageLinkFull": "https://upload.wikimedia.org/wikipedia/commons/c/c4/Tulipa_orphanidea_060506.jpg",
            "imageLinkThumbnail": "https://upload.wikimedia.org/wikipedia/commons/thumb/c/c4/Tulipa_orphanidea_060506.jpg/500px-Tulipa_orphanidea_060506.jpg",
            "link": "https://en.wikipedia.org/wiki/File:Tulipa_orphanidea_060506.jpg"
          }
        ],
        "created": "2025-09-25T18:35:26+00:00",
        "updated": "2025-09-25T18:35:26+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."
      }
    }
  ],
  "debug": [
    {
      "input": {
        "type": "element-hydration",
        "query": {
          "elementIds": [
            "258c0dfe-b1d8-4839-beed-d00d1b544a96",
            "3283fd3d-8083-4170-882a-41b1cd152c55",
            "8940d70b-5b6f-43b7-bee4-41d073396ff8"
          ]
        },
        "parameters": {
          "stepResults": []
        }
      },
      "step-handler": "element-hydration (App\\EventSystem\\SearchStep\\EventListener\\ElementHydrationSearchStepEventListener)",
      "start": 1758825391.88911,
      "accessibleElementIds": [
        "258c0dfe-b1d8-4839-beed-d00d1b544a96",
        "3283fd3d-8083-4170-882a-41b1cd152c55",
        "8940d70b-5b6f-43b7-bee4-41d073396ff8"
      ],
      "end": 1758825391.926094,
      "duration": 0.036984
    }
  ]
}
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