JSON TransformArray
find
Return the first element matching a JMESPath condition
find
Walks the array and returns the first element for which the JMESPath expression evaluates to true. If nothing matches, returns null.
Options
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
expression | string | Yes | — | JMESPath boolean expression. item and @ refer to the current element. |
Example
Input
[
{ "id": 1, "role": "user" },
{ "id": 2, "role": "assistant" },
{ "id": 3, "role": "user" }
]Operation
{ "type": "find", "options": { "expression": "item.role == `assistant`" } }Output
{ "id": 2, "role": "assistant" }In a Circuit Step
{
"name": "first_assistant_message",
"description": "Find the first assistant turn in the conversation",
"function": "circuit.core.transform.json",
"input": {
"source": "${{ messages }}",
"operations": [
{ "type": "find", "options": { "expression": "item.role == `assistant`" } }
]
},
"outputs": [
{
"name": "first_assistant",
"description": "First assistant message, or null if none exists",
"value": "${{ first_assistant_message.output.transformed_result }}"
}
]
}Notes & gotchas
- Errors with
find: expected arrayif the input is not an array. - The expression must evaluate to
true(a JSON boolean). Anything else, including truthy values like non-empty strings, is treated as a non-match. - A non-matching scan returns
null, not an empty array. - For multi-result queries, use
filter(compact syntax) or chainfilter+slice.