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 — one INFORMATION_SCHEMA query plus SHOW IMPORTED KEYS. 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. 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.