Traversal searching using the via field
- Last UpdatedOct 23, 2026
- 3 minute read
Faceted Search supports multi-hop association queries. Use the via field in the POST /query request to retrieve entities connected through a chain of associations, such as all tags in a plant through location associations. The response indicates whether the results were truncated because of time constraints.
Note: If using via field in request, the ID value can only be that of an existing entity.
The maximum number of hops supported is five. The association(s) required must be declared on the via parameter as can be seen in the examples.
Request and response examples supporting via field:
Example 1
Request:
{
"psize": 200,
"pno": 1,
"criteria": {
"id": "*",
"association": [
{
"type": "is located in",
"id": "SRCH|BUK|ONG|15B",
"operator": "equals",
"via": [
"is the location of"
]
}
]
}
}
Response:
{
"result": {
"data": [
{
"fullId": "SRCH|BUK|ONG|15B",
"name": "IED-AREA-15B",
"className": "Area",
"category": "",
"projections": [
{
"label": "Area Code",
"value": "15B"
},
{
"label": "Tag Description",
"value": "IED-AREA-15B"
}
]
},
{
"fullId": "SRCH|BUK|ONG|G10",
"name": "IED-AREA-G10",
"className": "Area",
"category": "",
"projections": [
{
"label": "Area Code",
"value": "G10"
},
{
"label": "Tag Description",
"value": "IED-AREA-G10"
}
]
},
{
"fullId": "SRCH|BUK|ONG|OnG-Downstream-IED",
"name": "",
"className": "Site",
"category": "",
"projections": [
{
"label": "DataSetBody",
"value": ""
},
{
"label": "Plant Code",
"value": "OnG-Downstream-IED"
}
]
}
],
"error": null,
"totalHits": 3,
"continuationKey": null,
"isTruncated": false,
"truncationReason": null
}
}
Example 2 of maximum hops, where five relationship values are allowed:
Request:
{
"psize": 200,
"pno": 1,
"criteria": {
"id": "*",
"association": [
{
"type": "is located in",
"id": "SRCH|BUK|ONG|15B",
"operator": "equals",
"via": [
"is the location of",
"is located in",
"is the location of",
"is located in",
"is the location of"
]
}
]
}
}
Response:
{
"result": {
"data": [
{
"fullId": "SRCH|BUK|ONG|15A",
"name": "IED-AREA-15A",
"className": "Area",
"category": "",
"projections": [
{
"label": "Area Code",
"value": "15A"
},
{
"label": "Tag Description",
"value": "IED-AREA-15A"
}
]
},
{
"fullId": "SRCH|BUK|ONG|15B",
"name": "IED-AREA-15B",
"className": "Area",
"category": "",
"projections": [
{
"label": "Area Code",
"value": "15B"
},
{
"label": "Tag Description",
"value": "IED-AREA-15B"
}
]
},
{
"fullId": "SRCH|BUK|ONG|15C",
"name": "IED-AREA-15C",
"className": "Area",
"category": "",
"projections": [
{
"label": "Area Code",
"value": "15C"
},
{
"label": "Tag Description",
"value": "IED-AREA-15C"
}
]
},
{
"fullId": "SRCH|BUK|ONG|15D",
"name": "IED-AREA-15D",
"className": "Area",
"category": "",
"projections": [
{
"label": "Area Code",
"value": "15D"
},
{
"label": "Tag Description",
"value": "IED-AREA-15D"
}
]
},
{
"fullId": "SRCH|BUK|ONG|15R",
"name": "IED-AREA-15R",
"className": "Area",
"category": "",
"projections": [
{
"label": "Area Code",
"value": "15R"
},
{
"label": "Tag Description",
"value": "IED-AREA-15R"
}
]
},
{
"fullId": "SRCH|BUK|ONG|CW",
"name": "IED-SYSTEM-CW",
"className": "System Code",
"category": "",
"projections": [
{
"label": "Area Code",
"value": "CW"
},
{
"label": "System Code",
"value": "CW"
},
{
"label": "Tag Description",
"value": "IED-SYSTEM-CW"
}
]
},
{
"fullId": "SRCH|BUK|ONG|G10",
"name": "IED-AREA-G10",
"className": "Area",
"category": "",
"projections": [
{
"label": "Area Code",
"value": "G10"
},
{
"label": "Tag Description",
"value": "IED-AREA-G10"
}
]
},
{
"fullId": "SRCH|BUK|ONG|OnG-Downstream-IED",
"name": "",
"className": "Site",
"category": "",
"projections": [
{
"label": "DataSetBody",
"value": ""
},
{
"label": "Plant Code",
"value": "OnG-Downstream-IED"
}
]
},
{
"fullId": "SRCH|BUK|ONG|OnG-Downstream-SWS",
"name": "",
"className": "Site",
"category": "",
"projections": [
{
"label": "DataSetBody",
"value": ""
},
{
"label": "Plant Code",
"value": "OnG-Downstream-SWS"
}
]
},
{
"fullId": "SRCH|BUK|ONG|Plant",
"name": "SWS-Plant",
"className": "Area",
"category": "",
"projections": [
{
"label": "Area Code",
"value": "Plant"
},
{
"label": "Tag Description",
"value": "SWS-Plant"
}
]
},
{
"fullId": "SRCH|BUK|ONG|VT",
"name": "IED-SYSTEM-VT",
"className": "System Code",
"category": "",
"projections": [
{
"label": "Area Code",
"value": "VT"
},
{
"label": "System Code",
"value": "VT"
},
{
"label": "Tag Description",
"value": "IED-SYSTEM-VT"
}
]
}
],
"error": null,
"totalHits": 11,
"continuationKey": null,
"isTruncated": false,
"truncationReason": null
}
}
The following are the limitations of the traversal searching using via field:
-
The NestedAssociationMaxIntermediateIds limit defaults to 10,000. If traversal exceeds this limit for an association depth, the API returns a 400 error with the message: Nested association traversal exceeded the maximum intermediate ID limit of 10,000. The traversal scope is too broad.
-
Lambda timeout set at 30 seconds.
-
OpenSearch limits a terms query to 65,536 values.
-
isTruncated: true — the result set is incomplete because the request time budget was exceeded. Check truncationReason to see where:
-
TraversalTimeBudgetExceeded: a nested (via) traversal exceeded its time budget (default 20s) part‑way through the hop chain. A partial result set is returned from the last completed hop, and the request still succeeds (HTTP 200).
-
SyncTimeBudgetExceeded: the overall request time budget was exhausted before any partial data was available (for example, the first or anchor hop timed out). The request fails with HTTP 408 (Request Timeout) and the reason is reported in errors.
-