Skip to content

query tool

Use query to find code by its syntax, as xpd run does, and to preview a replacement. Give exactly one of pattern and kind. It changes no file, and rewrite writes a replacement.

query(query, paths=null)
  • Changes no file
  • A second call with the same arguments changes nothing more
  • Stays inside the project

Tags: structure.

The server gives the agent this description of the tool.

Find AST patterns or syntax kinds and preview replacements without changing files.

Type: object. Required.

The pattern or kind to find, and the replacement to preview.

Field Type Required Default Description
query.pattern string or null no null AST pattern with $VARIABLE captures.
query.kind string or null no null Syntax kind instead of a pattern.
query.language string or null no null The language of the pattern, such as python. Default: each file's extension.
query.selector string or null no null The kind of the part of the pattern that is the match.
query.rewrite string or null no null Replacement template to preview.

Type: list of string or null. Optional, default null.

Files or folders inside the project root. Default: the whole root.

The 17 fields of the result
Field Type Required Default Description
result list of object yes
result[].text string yes
result[].file string yes
result[].language string yes
result[].range object yes
result[].range.byteOffset object yes
result[].range.byteOffset.start integer yes
result[].range.byteOffset.end integer yes
result[].range.start object yes
result[].range.start.line integer yes
result[].range.start.column integer yes
result[].range.end object yes
result[].range.end.line integer yes
result[].range.end.column integer yes
result[].replacement string or null no null
result[].replacementOffsets object or null no null
result[].metaVariables object no
{"query":{"pattern":"$X.iterrows()","language":"python"},"paths":["samples/bad.py"]}

The result is a list with one entry for each match. The one match is shown without its byte offsets and metavariables. Lines and columns count from zero.

[{"text":"df.iterrows()","file":"samples/bad.py","language":"Python","range":{"start":{"line":4,"column":14},"end":{"line":4,"column":27}},"replacement":null,"lines":"for i, row in df.iterrows():"}]

A query with both or neither of pattern and kind fails with "Provide exactly one of pattern or kind." A path outside the project root fails before xpd runs. No match is an empty list, not an error.