explore:schema
rai explore:schema [OPTIONS]Explore a source database schema and write it as JSON.
Produces a deterministic document describing column types (with the RAI type to declare), PK candidates, FK candidates with multiplicity, value distributions for low-cardinality columns, numeric ranges, and optionally graph topology.
Depth controls cost, not shape: structure metadata only (on Snowflake, SHOW commands, which need no warehouse). No table scans, safe on any schema. profile adds one aggregate scan per table: live row counts, distinct/null counts, numeric ranges, value distributions, PK candidates, FK multiplicity. full adds graph topology (edge and broken-edge counts).
Every key exists at every depth; the ones a shallower depth did not
compute are null. Degradations (an unreadable set of declared foreign
keys, an empty schema) are recorded in the document’s warnings
array and exit 0; a table whose columns can’t be read is listed with
columns_unavailable saying why. Anything that would make the
document wrong exits non-zero instead.
This is read-only against the database and writes only to --out.
Examples: rai explore schema —database DEMO_TELCO —schema RAW rai explore schema —database DEMO_TELCO —schema RAW —depth profile rai explore schema —database DEMO_TELCO —schema RAW —depth full -o telco.json rai explore schema —database DEMO_TELCO —schema RAW —table SUBSCRIBERS —table PLANS rai explore schema —database DEMO_TELCO —schema RAW —out - | jq ‘.tables[].table_name’
Options
| Option | Type | Description |
|---|---|---|
--database | text | Source database to read. Required. Default: Sentinel.UNSET. |
--schema | text | Schema within the database. Required. Default: Sentinel.UNSET. |
--depth | choice | How much to collect. ‘structure’ is metadata-only (no table scans); ‘profile’ adds one aggregate scan per table; ‘full’ adds graph topology. Default: structure. |
--table | text[] | Restrict to this table. Repeatable. Defaults to every table in the schema. Default: Sentinel.UNSET. |
-o, --out | text | Where to write the JSON document. Use ’-’ for stdout. Default: schema.json. |
--stamp | Boolean | Include a generated_at timestamp. Off by default so repeated runs over unchanged data produce byte-identical output. Default: False. |
See Also
None.