> ## Documentation Index
> Fetch the complete documentation index at: https://site.aspect.build/llms.txt
> Use this file to discover all available pages before exploring further.

# Query API

> Learn the Aspect CLI Starlark Query API for Gazelle extensions, including RegexQuery and tree-sitter AST queries used to detect imports and rule kinds in Bazel.

## Query types

The `PrepareResult` may need to inspect the contents of the files being visited, to understand their dependencies, whether they appear to be a test or executable, or scan for any other syntax you care to detect.

See the full list in the [orion Query Types documentation](https://github.com/aspect-build/aspect-gazelle/blob/main/language/orion/README.md#query-types).

There are six query factories: `RegexQuery`, `AstQuery` (tree-sitter), `JsonQuery` (jq), `YamlQuery` (yq), `TomlQuery`, and `RawQuery` (file content as-is). The two most common are covered below; the structured-data variants are handy when dependencies live in config files rather than source.

Every query factory accepts two optional filters:

* `filter` — a glob matching file **paths** the query should run on.
* `content_filter` — an [RE2](https://github.com/google/re2/wiki/Syntax) pattern the file **content** must match before the query (and, for parse-based queries, the parse itself) runs. This is a cheap gate ahead of an expensive parse — use a keyword every match contains, e.g. `"import"` for an import-statement query.

### Regex

Regular expressions work great, until they don’t. It’s a simple way to get started and it’s possible it will work for all cases you ever encounter.

For example, to detect whether a shell file has a shebang line (and therefore should be in `sh_binary`) the `shell.axl` example above has:

```python theme={null}
"shebang": aspect.RegexQuery(
    expression = "#!/.*sh",
),
```

### Tree-sitter

The tree-sitter query language lets you express AST search-and-match on any language tree-sitter can parse. An online playground is very useful for rapid prototyping of queries, and your favorite AI assistant can probably give you a partially working query to start from.

Aspect CLI has a number of tree-sitter grammars built in, and we're planning to add essentially all of them as needed.

The [tree-sitter playground](https://tree-sitter.github.io/tree-sitter/7-playground.html) looks like the screenshot below. Here we've pasted some sample Java code and want to extract the name of any "main" classes. The query is color-coded, with highlights showing each matching region, and the AST is shown alongside to help navigate the language structure.

<img src="https://mintcdn.com/aspectbuild/gtqBKXWWd-jWHweY/learning/aspect-150/tree-sitter.png?fit=max&auto=format&n=gtqBKXWWd-jWHweY&q=85&s=a064cce9316110ae203720a2a2193859" alt="Tree-sitter playground showing a query that matches Java main classes, with the AST displayed alongside" width="1932" height="1908" data-path="learning/aspect-150/tree-sitter.png" />

### Structured data: JSON, YAML, TOML

When the information you need lives in a config file rather than source code, query it directly instead of writing a regex:

* `aspect.JsonQuery(query = ...)` runs a [jq](https://jqlang.github.io/jq/manual/#basic-filters) filter expression over a JSON document.
* `aspect.YamlQuery(query = ...)` runs a [yq](https://mikefarah.gitbook.io/yq) expression (jq-like syntax) over a YAML document.
* `aspect.TomlQuery(query = ...)` runs the same jq-like syntax over a TOML document.

Each returns a list of matching nodes (an array of one for single-result queries, or empty if nothing matches), with values represented as Starlark primitives, lists, and maps.

```python theme={null}
"scripts": aspect.JsonQuery(
    query = ".scripts | keys",
    filter = "package.json",
),
```

### Raw

`aspect.RawQuery()` returns the file content as-is, with no parsing — useful when you want to do your own processing in Starlark.