`dft schema-search`¶

Full-text and filter search across the schema corpus. Companion to dft schema: drill-down navigates the hierarchy, schema-search finds matches across names, descriptions, tags, tests, meta, and owner.

dft schema-search [OPTIONS] KEYWORD

Results are a flat list of fully-qualified hits in stable iteration order — no ranking, no top-N.

Arguments¶

Argument	Description
`KEYWORD`	Substring to match (case-insensitive). Use `''` for filters-only queries.

Options¶

Flag	Description
`--scope TEXT`	Comma-list of fields to search: `name`, `description`, `tag`, `tests`, `meta`, `owner`. Default: all.
`--regex`	Treat `KEYWORD` as a Python regex.
`--role TEXT`	Filter columns by profiled role (e.g. `primary_key`, `foreign_key`, `date`, `categorical`).
`--tag TEXT`	Filter to rows tagged with this value.
`--has-test TEXT`	Filter columns whose tests include this name (e.g. `unique`, `not_null`).
`--missing TEXT`	Emit synthetic hits for rows lacking this field.
`--column-name TEXT`	Filter to columns matching this fnmatch glob.
`--table-name TEXT`	Filter to tables matching this fnmatch glob.
`--fk-to TEXT`	Filter to columns with `relationships:` tests pointing at this table.
`--meta KEY=VALUE`	Filter by exact-match meta key=value (repeatable).
`--fields TEXT`	Project each hit to a comma-list of fields (e.g. `location,matched_field`).
`--limit INTEGER`	Truncate to N hits. Total and truncated count reported.
`--json`	Output as JSON.
`--project-dir PATH`	Project directory for resolving relative paths.

Examples¶

Keyword search across the whole corpus¶

dft schema-search mrr

Returns every table, column, description, or tag whose text contains mrr.

Find all primary keys¶

dft schema-search "" --role primary_key

Empty keyword + filter is the canonical way to do a predicate-only query.

Customer columns whose name ends in `_id`¶

dft schema-search customer --column-name "*_id"

Tables missing a description¶

dft schema-search "" --missing description --table-name "stg_*"

Useful for documentation-coverage audits.

Columns with FK-style tests pointing at `dim_customers`¶

dft schema-search "" --fk-to dim_customers

Regex hunt for timestamp columns, projected to compact form¶

dft schema-search ".*_at$" --regex --json --fields location,matched_field

Returns just the location string (warehouse.analytics.fct_orders.created_at) and the field where the match landed, suitable for piping into another tool.

Combine filters¶

dft schema-search revenue \
  --scope description,name \
  --table-name "fct_*" \
  --has-test not_null \
  --limit 20 \
  --json

Reads as: "anything in fact-table names or descriptions matching revenue, restricted to columns with a not_null test, first 20 hits, JSON output."

Output shape¶

Each hit reports:

location — fully qualified path: source.schema.table[.column]
kind — source, schema, table, or column
matched_field — which field the keyword matched (name, description, tag, etc.) — null for filter-only queries
matched_text — excerpt of the matching text — null for filter-only queries
Selected metadata (role, tags, tests, etc.) relevant to the hit kind

Use --fields to project to a subset; otherwise the full hit shape is emitted.

When to use which verb¶

If you want to…	Use
Navigate the hierarchy (sources → schemas → tables → columns)	`dft schema`
Profile one specific table or column in depth	`dft schema`
Find a keyword anywhere across names / descriptions / tags	`dft schema-search`
Filter by role / test / FK / tag / missing fields	`dft schema-search`
Audit documentation or test coverage	`dft schema-search "" --missing ...`
Discover relationships before writing SQL	`dft schema-search` with `--fk-to`
Do an ad-hoc cross-cutting query the verbs don't anticipate	`dft schema --json \| jq`

dft schema — hierarchical drill-down
dft search — search dashboards (faces), not schemas
dft context — question-aware retrieval over the Super Schema artifact

dft schema-search¶