spath

import { Aside } from ‘@astrojs/starlight/components’;

This command is production-ready but its parameters may change based on community feedback.

The spath command extracts fields from structured JSON data stored in a text field. It operates in two modes:

• Path-based mode — When path is specified, extracts a single value at the given JSON path.
• Auto-extract mode — When path is omitted, extracts all fields from the JSON into a map.

This is ideal for semi-structured log bodies that contain JSON payloads — you can extract and query nested fields without re-indexing.

The `spath` command runs on the coordinating node, not on data nodes. It processes data after retrieval, which can be slow on large result sets. For fields you need to filter frequently, consider indexing them directly. The input field must be a **string** containing valid JSON -- struct fields cannot be used directly.

Syntax

spath input=<field> [output=<field>] [[path=]<json-path>]

Arguments

Required

Argument	Description
input=<field>	The field containing JSON data to parse. Must be a string field.

Optional

Argument	Default	Description
output=<field>	Value of path (path mode) or input (auto-extract)	Destination field for the extracted data.
path=<json-path>	—	The JSON path identifying data to extract. When omitted, runs in auto-extract mode. The path= keyword is optional; you can specify the path as a positional argument.

JSON path syntax

Syntax	Description	Example
field	Top-level field	status
parent.child	Dot notation for nested fields	error.message
list{0}	Array element by index	tags{0}
list{}	All array elements	items{}
"['special.name']"	Escaped field names with dots or spaces	"['a.b.c']"

Usage notes

• The spath command always returns extracted values as strings. Use eval with cast() to convert to numeric types for aggregation.
• The input field must contain a valid JSON string. Struct or map fields from the index schema cannot be used directly — you must first convert them to a string representation.
• In auto-extract mode, nested objects produce dotted keys (user.name), arrays produce {} suffix keys (tags{}), and all values are stringified.
• Empty JSON objects ({}) return an empty map. Malformed JSON returns partial results from any fields parsed before the error.
• In auto-extract mode, access individual values via dotted path navigation on the output field (e.g., doc.user.name). For keys containing {}, use backtick quoting.

Examples

Extract a field from a JSON string

Extract the status field from a JSON string. This example uses eval to create a JSON string for demonstration, but in practice you would use this on a body field that already contains JSON:

source=logs-otel-v1*
| head 1
| eval jsonStr = '{"status": 200, "service": "frontend", "latency": 45}'
| spath input=jsonStr path=status output=httpStatus

httpStatus
200

Try in playground →

Extract nested object fields

Traverse multiple levels of nesting using dot notation to extract deeply nested values:

source=logs-otel-v1*
| head 1
| eval jsonStr = '{"error": {"type": "timeout", "message": "upstream timed out"}}'
| spath input=jsonStr path=error.message output=errorMsg

errorMsg
upstream timed out

Try in playground →

Extract array elements

Extract the first element and all elements from an array within JSON data:

source=logs-otel-v1*
| head 1
| eval jsonStr = '{"tags": ["frontend", "v2", "canary"]}'
| spath input=jsonStr path=tags{0} output=firstTag
| spath input=jsonStr path=tags{} output=allTags

firstTag	allTags
frontend	[“frontend”,“v2”,“canary”]

Try in playground →

Cast extracted values for aggregation

Extracted values are strings. Cast them before performing numeric operations:

source=logs-otel-v1*
| head 1
| eval jsonStr = '{"status": 200, "service": "frontend", "latency": 45}'
| spath input=jsonStr path=latency output=latency
| eval latency = cast(latency as double)

Try in playground →

Auto-extract all fields from JSON

Extract all fields from a JSON string into a map, then access individual values:

source=logs-otel-v1*
| head 1
| eval jsonStr = '{"status": 200, "service": "frontend"}'
| spath input=jsonStr output=parsed

parsed
{service: frontend, status: 200}

Try in playground →

Extended examples

Extract multiple error fields from a JSON payload

Chain multiple spath commands to extract several fields from a nested error payload:

source=logs-otel-v1*
| head 1
| eval jsonStr = '{"error": {"type": "timeout", "message": "upstream timed out", "code": 504}}'
| spath input=jsonStr path=error.type output=errorType
| spath input=jsonStr path=error.message output=errorMsg
| spath input=jsonStr path=error.code output=errorCode

errorType	errorMsg	errorCode
timeout	upstream timed out	504

Try in playground →

The OTel demo data in this stack uses plain-text log bodies rather than JSON payloads. The examples above use `eval` to create JSON strings for demonstration. When your application emits JSON-encoded log bodies, you can use `spath input=body` directly without the `eval` step.

See also

• parse — extract fields using regex named capture groups
• grok — extract fields using grok patterns
• rex — regex extraction with sed-mode substitution
• eval — create computed fields and type conversions