0f4df23290
Some checks failed
kotlin / test (push) Has been skipped
python / test (push) Has been skipped
typescript / test (push) Has been skipped
go / build darwin/amd64 (push) Has been cancelled
go / build linux/amd64 (push) Has been cancelled
go / build windows/amd64 (push) Has been cancelled
go / build darwin/arm64 (push) Has been cancelled
go / build linux/arm64 (push) Has been cancelled
go / build windows/arm64 (push) Has been cancelled
go / test (push) Has been cancelled
go / vuln_check (push) Has been cancelled
112 lines
2.5 KiB
Markdown
112 lines
2.5 KiB
Markdown
# `parse` - Parsing SQL into an AST
|
|
|
|
> [!NOTE]
|
|
> `parse` is in beta. Its flags and the shape of the JSON AST it
|
|
> prints may change in a future release.
|
|
|
|
`sqlc parse` parses SQL from a file or standard input and prints the abstract
|
|
syntax tree (AST) as a single JSON document. It does not require a configuration
|
|
file or a database connection.
|
|
|
|
Each statement is reported with its sqlc query name and command (when the
|
|
statement carries a [`-- name:`](../reference/query-annotations.md) annotation)
|
|
alongside its AST.
|
|
|
|
## Usage
|
|
|
|
```sh
|
|
sqlc parse --dialect <dialect> [file]
|
|
```
|
|
|
|
The SQL is read from the given file, or from standard input when no file is
|
|
provided.
|
|
|
|
## Flags
|
|
|
|
- `--dialect`, `-d` - The SQL dialect to use. One of `postgresql`, `mysql`,
|
|
`sqlite`, `clickhouse`, `googlesql`, `mssql`, or `duckdb`. Required.
|
|
|
|
## Examples
|
|
|
|
Parse a query file:
|
|
|
|
```sh
|
|
sqlc parse --dialect postgresql query.sql
|
|
```
|
|
|
|
Parse SQL piped via standard input:
|
|
|
|
```sh
|
|
echo "SELECT 1;" | sqlc parse --dialect mysql
|
|
```
|
|
|
|
The output is a JSON array with one object per statement:
|
|
|
|
```json
|
|
[
|
|
{
|
|
"name": "GetAuthor",
|
|
"cmd": ":one",
|
|
"ast": {
|
|
"tag": "RawStmt",
|
|
"stmt": {
|
|
"...": "..."
|
|
},
|
|
"stmt_location": 0,
|
|
"stmt_len": 42
|
|
}
|
|
}
|
|
]
|
|
```
|
|
|
|
Statements without a `-- name:` annotation (for example schema DDL) omit the
|
|
`name` and `cmd` fields. Field names are `snake_case` versions of the AST node
|
|
field names.
|
|
|
|
## Node types
|
|
|
|
Every node in the AST carries a `tag` naming its type. Some nodes have no
|
|
fields of their own, so without it a star, a null literal and an untranslated
|
|
clause would all print as `{}`.
|
|
|
|
```json
|
|
"val": {
|
|
"tag": "ColumnRef",
|
|
"name": "",
|
|
"fields": {
|
|
"tag": "List",
|
|
"items": [
|
|
{
|
|
"tag": "A_Star"
|
|
}
|
|
]
|
|
},
|
|
"location": 93
|
|
}
|
|
```
|
|
|
|
A `tag` of `TODO` marks a clause the dialect's converter does not translate
|
|
yet. It means the clause was parsed but is not represented in the AST, not that
|
|
the clause was absent from the query.
|
|
|
|
## Absent fields
|
|
|
|
A field the statement does not use is left out rather than printed as `null`.
|
|
An `A_Const` carrying an integer reports only what it has:
|
|
|
|
```json
|
|
"val": {
|
|
"tag": "A_Const",
|
|
"val": {
|
|
"tag": "Integer",
|
|
"ival": 1
|
|
},
|
|
"location": 30
|
|
}
|
|
```
|
|
|
|
Only absent fields — and empty lists, which engines construct differently for
|
|
the same SQL — are omitted. A zero keeps its place, because zero is a value the
|
|
parser can find: `stmt_location` is 0 for the first statement in a file, and
|
|
`LIMIT 0` parses to an `ival` of 0.
|