Skip to content

ast: tagged, snake_case JSON output for parse and analyze #4592

新建议题

Have a question about this project? 注册 for a free GitHub account to open an issue and contact its maintainers and the community.

注册 for GitHub

By clicking “注册 for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? 登录 to your account

Merged
kyleconroy merged 4 commits into from
Aug 28, 2026
Merged

ast: tagged, snake_case JSON output for parse and analyze #4592

Show file tree
Hide file tree
Changes from all commits
提交
Show all changes
4 commits
Select commit Hold shift + click to select a range
8c81481
ast: tag every node with its type in JSON output
claude Aug 28, 2026
4f101f1
ast: omit absent fields from JSON output
claude Aug 28, 2026
fd144c6
ast: snake_case field names in JSON output
claude Aug 28, 2026
31e5cfc
ast: remove the node tag guard test
claude Aug 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion docs/howto/analyze.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -106,4 +106,6 @@ reports the result columns and parameters:
]
```

Pass `--ast` to also include each statement's parsed AST under an `ast` key.
Pass `--ast` to also include each statement's parsed AST under an `ast` key. It
has the same shape as the output of [`parse`](parse.md), with every node tagged
by type.
57 changes: 53 additions & 4 deletions docs/howto/parse.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,15 +48,64 @@ The output is a JSON array with one object per statement:
"name": "GetAuthor",
"cmd": ":one",
"ast": {
"Stmt": {
"tag": "RawStmt",
"stmt": {
"...": "..."
},
"StmtLocation": 0,
"StmtLen": 42
"stmt_location": 0,
"stmt_len": 42
}
}
]
```

Statements without a `-- name:` annotation (for example schema DDL) omit the
`name` and `cmd` fields.
`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.
136 changes: 75 additions & 61 deletions internal/endtoend/testdata/analyze_ast/postgresql/stdout.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,99 +24,113 @@
}
],
"ast": {
"Stmt": {
"DistinctClause": {
"Items": null
"tag": "RawStmt",
"stmt": {
"tag": "SelectStmt",
"distinct_clause": {
"tag": "List"
},
"IntoClause": null,
"TargetList": {
"Items": [
"target_list": {
"tag": "List",
"items": [
{
"Name": null,
"Indirection": {
"Items": null
"tag": "ResTarget",
"indirection": {
"tag": "List"
},
"Val": {
"Name": "",
"Fields": {
"Items": [
"val": {
"tag": "ColumnRef",
"name": "",
"fields": {
"tag": "List",
"items": [
{
"Str": "name"
"tag": "String",
"str": "name"
}
]
},
"Location": 35
"location": 35
},
"Location": 35
"location": 35
}
]
},
"FromClause": {
"Items": [
"from_clause": {
"tag": "List",
"items": [
{
"Catalogname": null,
"Schemaname": null,
"Relname": "authors",
"Inh": true,
"Relpersistence": 112,
"Alias": null,
"Location": 45
"tag": "RangeVar",
"relname": "authors",
"inh": true,
"relpersistence": 112,
"location": 45
}
]
},
"WhereClause": {
"Kind": 1,
"Name": {
"Items": [
"where_clause": {
"tag": "A_Expr",
"kind": 1,
"name": {
"tag": "List",
"items": [
{
"Str": "="
"tag": "String",
"str": "="
}
]
},
"Lexpr": {
"Name": "",
"Fields": {
"Items": [
"lexpr": {
"tag": "ColumnRef",
"name": "",
"fields": {
"tag": "List",
"items": [
{
"Str": "id"
"tag": "String",
"str": "id"
}
]
},
"Location": 59
"location": 59
},
"Rexpr": {
"Number": 1,
"Location": 64,
"Dollar": true
"rexpr": {
"tag": "ParamRef",
"number": 1,
"location": 64,
"dollar": true
},
"Location": 62
"location": 62
},
"GroupClause": {
"Items": null
"group_clause": {
"tag": "List"
},
"HavingClause": {},
"WindowClause": {
"Items": null
"having_clause": {
"tag": "TODO"
},
"ValuesLists": {
"Items": null
"window_clause": {
"tag": "List"
},
"SortClause": {
"Items": null
"values_lists": {
"tag": "List"
},
"LimitOffset": {},
"LimitCount": {},
"LockingClause": {
"Items": null
"sort_clause": {
"tag": "List"
},
"WithClause": null,
"Op": 0,
"All": false,
"Larg": null,
"Rarg": null
"limit_offset": {
"tag": "TODO"
},
"limit_count": {
"tag": "TODO"
},
"locking_clause": {
"tag": "List"
},
"op": 0,
"all": false
},
"StmtLocation": 0,
"StmtLen": 66
"stmt_location": 0,
"stmt_len": 66
}
}
]
47 changes: 18 additions & 29 deletions internal/endtoend/testdata/parse_basic/clickhouse/stdout.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,42 +3,31 @@
"name": "GetValue",
"cmd": ":one",
"ast": {
"Stmt": {
"DistinctClause": null,
"IntoClause": null,
"TargetList": {
"Items": [
"tag": "RawStmt",
"stmt": {
"tag": "SelectStmt",
"target_list": {
"tag": "List",
"items": [
{
"Name": null,
"Indirection": null,
"Val": {
"Val": {
"Ival": 1
"tag": "ResTarget",
"val": {
"tag": "A_Const",
"val": {
"tag": "Integer",
"ival": 1
},
"Location": 31
"location": 31
},
"Location": 31
"location": 31
}
]
},
"FromClause": null,
"WhereClause": null,
"GroupClause": null,
"HavingClause": null,
"WindowClause": null,
"ValuesLists": null,
"SortClause": null,
"LimitOffset": null,
"LimitCount": null,
"LockingClause": null,
"WithClause": null,
"Op": 0,
"All": false,
"Larg": null,
"Rarg": null
"op": 0,
"all": false
},
"StmtLocation": 0,
"StmtLen": 32
"stmt_location": 0,
"stmt_len": 32
}
}
]
47 changes: 18 additions & 29 deletions internal/endtoend/testdata/parse_basic/duckdb/stdout.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,42 +3,31 @@
"name": "GetValue",
"cmd": ":one",
"ast": {
"Stmt": {
"DistinctClause": null,
"IntoClause": null,
"TargetList": {
"Items": [
"tag": "RawStmt",
"stmt": {
"tag": "SelectStmt",
"target_list": {
"tag": "List",
"items": [
{
"Name": null,
"Indirection": null,
"Val": {
"Val": {
"Ival": 1
"tag": "ResTarget",
"val": {
"tag": "A_Const",
"val": {
"tag": "Integer",
"ival": 1
},
"Location": 30
"location": 30
},
"Location": 30
"location": 30
}
]
},
"FromClause": null,
"WhereClause": null,
"GroupClause": null,
"HavingClause": null,
"WindowClause": null,
"ValuesLists": null,
"SortClause": null,
"LimitOffset": null,
"LimitCount": null,
"LockingClause": null,
"WithClause": null,
"Op": 0,
"All": false,
"Larg": null,
"Rarg": null
"op": 0,
"all": false
},
"StmtLocation": 0,
"StmtLen": 33
"stmt_location": 0,
"stmt_len": 33
}
}
]
Loading
Loading