Skip to content

Commit b0e1cf0

Browse files
committed
docs: describe the types analyze reports and how the design landed
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Qryf7a1doPFuCz2eGT3bCr
1 parent 4144f5d commit b0e1cf0

2 files changed

Lines changed: 58 additions & 6 deletions

File tree

‎docs/howto/analyze.md‎

Lines changed: 16 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -71,7 +71,7 @@ reports the result columns and parameters:
7171
{
7272
"name": "id",
7373
"type": {
74-
"name": "bigserial"
74+
"name": "bigint"
7575
},
7676
"table": "authors"
7777
},
@@ -97,7 +97,7 @@ reports the result columns and parameters:
9797
"column": {
9898
"name": "id",
9999
"type": {
100-
"name": "bigserial"
100+
"name": "bigint"
101101
},
102102
"table": "authors"
103103
}
@@ -109,10 +109,20 @@ reports the result columns and parameters:
109109

110110
A column's `type` is written as a call expression: a `name` applied to
111111
`args`, each of which carries an optional `label` and exactly one of `type`,
112-
`int`, `bool` or `string`, with `nullable` set at whatever depth it applies.
113-
An array of text is `array` applied to `text`; a `Map(String, Nullable(UInt8))`
114-
in ClickHouse is `map` applied to `string` and a nullable `uint8`. Names are
115-
recorded as the engine reports them.
112+
`int`, `bool`, `string` or `ident`, with `nullable` set at whatever depth it
113+
applies. A `numeric(10,2)` column is `numeric` applied to `10` and `2`; an
114+
array of text is `array` applied to `text`, and an array of arrays nests
115+
one `array` per dimension; a `Map(String, Nullable(UInt8))` in ClickHouse is
116+
`map` applied to `string` and a nullable `uint8`; a `STRUCT<a INT64>` in
117+
GoogleSQL is `struct` applied to an `int64` labelled `a`; the `MAX` of SQL
118+
Server's `nvarchar(max)` is the identifier `max`.
119+
120+
Types are reported the way the engine itself stores and reports them rather
121+
than the way the schema spelled them: PostgreSQL's `int` and `bigserial` are
122+
`integer` and `bigint`, as `format_type` prints them; MySQL's `BOOLEAN` is
123+
`tinyint(1)`; ClickHouse's `Decimal32(4)` is `decimal(9, 4)`; DuckDB's
124+
`TEXT` is `varchar`; SQL Server's `FLOAT(24)` is `real`. SQLite, which
125+
keeps a declared type as written, is reported as written.
116126

117127
Pass `--ast` to also include each statement's parsed AST under an `ast` key. It
118128
has the same shape as the output of [`parse`](parse.md), with every node tagged

‎internal/core/types.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -645,6 +645,48 @@ nesting, so Go codegen renders `[][]int32` as the legacy path does.
645645
DuckDB's `INTEGER[][]` and ClickHouse's `Array(Array(Int32))` produce the
646646
same rows and output, with `int32` in ClickHouse's case.
647647

648+
## As implemented
649+
650+
The design above is implemented, engine by engine, with these departures
651+
and details settled on the way:
652+
653+
- The three per-dialect hooks are registered by an engine package at init,
654+
by the name its `dialect.json` records, and looked up by that name, so a
655+
catalog restored from the cache — which runs no seed — has them:
656+
`core.RegisterCanonicalizer`, `core.RegisterUserTypeBase` (SQLite's
657+
affinity rule, applied when the schema declares a family the seed does
658+
not list) and `core.RegisterResultType` (ClickHouse's `toDecimal64(x, 4)`
659+
and `toDateTime64(x, 3)`).
660+
- SQLite's `dialect.json` says `"alias": "base"`, which makes each alias in
661+
its `types.jsonl` a type of its own standing on the type it aliases,
662+
rather than another spelling of it.
663+
- An engine hands the core either a spelling (`TypeName.Spelling`, read by
664+
`ParseTypeExpr`, which also reads words after a closing parenthesis as
665+
part of the name, as in `decimal(10,2) unsigned`) or a name with
666+
`Typmods` and `ArrayBounds`, where an integer constant is an integer
667+
argument, a bare `ast.String` is an identifier and a quoted constant a
668+
string. `ColumnDef.IsUnsigned` and `ColumnDef.Vals` add MySQL's unsigned
669+
and enum members. `ParamRef.Name` carries the name a `{name:Type}`
670+
placeholder gives itself.
671+
- A cast is NULL when its operand is, or when its type says so, as
672+
`Nullable(String)` does; a cast of a placeholder types the placeholder
673+
and takes its name and source from what it is compared with.
674+
- MySQL types `CAST(x AS CHAR(10))` as `varchar(10)` and `CAST(x AS
675+
BINARY(8))` as `varbinary(8)`, which is what its metadata and a view over
676+
the cast both report, rather than the `char(10)` the table above
677+
proposed. `goldeneye` reads a table column's type from `COLUMN_TYPE`, in
678+
the relations seed and in the analyze check, and compares an expression
679+
by family alone, since the wire carries no arguments.
680+
- SQLite reports a cast to a spelling that is not a storage class, such as
681+
`DECIMAL(5,2)`, as that spelling, while the value's storage class is what
682+
a run would show; the check's cases keep to storage classes.
683+
- DuckDB's `JSON` is grouped under `varchar` by `duckdb_types()`'s logical
684+
type, so a JSON column reports `varchar`; a named enum reports its name,
685+
not its labels, since the canonicalizer cannot see the catalog. A
686+
GoogleSQL array or struct constructor in a select list is still untyped.
687+
- PostgreSQL's `relations.jsonl` still spells array columns as `pg_type`
688+
does (`_text`), which the canonicalizer reads as `array(text)`.
689+
648690
## Order of work
649691

650692
1. The tables and the interning entry point: `sql_type.expr`, `family_oid`,

0 commit comments

Comments
 (0)