Skip to content

Data Query Plugin

The data_query plugin provides a tool to query JSON and YAML data using JSONPath expressions. It accepts either a file on disk or an inline content string, and returns all matched values together with their count.

Tools

query_json_data_file

Evaluates a JSONPath expression against a JSON or YAML data source.

Arguments:

  • file_path (string, optional): Path to a JSON or YAML file on disk. The format is auto-detected from the file extension (.json, .yaml, .yml). Mutually exclusive with content.
  • content (string, optional): Raw JSON or YAML content string. Mutually exclusive with file_path. Requires format to be set explicitly.
  • format (string, optional): Data format — "json" or "yaml". Required when content is used. When file_path is used, inferred from the extension unless overridden.
  • jsonpath_expression (string, required): JSONPath expression to evaluate (e.g. $.servers[*].host).

Exactly one of file_path or content must be supplied.

Return value:

{
  "status": "ok",
  "results": ["value1", "value2"],
  "count": 2
}

On failure:

{
  "status": "error",
  "message": "Reason for the failure."
}

Features:

  • JSONPath support: Full JSONPath syntax via jsonpath-ng, including recursive descent (..), wildcards ([*]), array slices, and filter expressions ([?(@.key=='value')]).
  • Dual input modes: Query a file by path or pass content directly as a string — useful for querying data already held in memory by an agent.
  • Auto format detection: Derives the parse format from .json, .yaml, or .yml extensions so callers rarely need to set format explicitly.
  • .aiignore compliance: Refuses to read files matched by .aiignore rules.
  • No size limit: Suitable for large configuration or data files.

Examples

Query a JSON file

Given config.json:

{
  "servers": [
    {"host": "api.example.com", "env": "prod"},
    {"host": "staging.example.com", "env": "staging"},
    {"host": "db.example.com", "env": "prod"}
  ]
}

Retrieve all hostnames:

{
  "file_path": "config.json",
  "jsonpath_expression": "$.servers[*].host"
}

{
  "status": "ok",
  "results": ["api.example.com", "staging.example.com", "db.example.com"],
  "count": 3
}

Filter expression on a YAML file

Given services.yaml:

servers:
  - host: api.example.com
    env: prod
  - host: staging.example.com
    env: staging
  - host: db.example.com
    env: prod

Retrieve only production hosts:

{
  "file_path": "services.yaml",
  "jsonpath_expression": "$.servers[?(@.env=='prod')].host"
}

{
  "status": "ok",
  "results": ["api.example.com", "db.example.com"],
  "count": 2
}

Inline content

{
  "content": "{\"version\": \"1.0\", \"name\": \"my-app\"}",
  "format": "json",
  "jsonpath_expression": "$.version"
}

{
  "status": "ok",
  "results": ["1.0"],
  "count": 1
}