OutlineDriven dbt model index
Contract
| Field | Bound contract |
|---|---|
| Trigger | The user needs to query data in a dbt-powered data warehouse or resolve a data question. |
| Authority | Read-only. No file, VCS, credential, paid, published, deployed, or remote mutation. Consults the curated model index and emits SQL without executing it. |
| Side effect | Produces a BigQuery SQL query that references the correct model; no warehouse mutation |
| Done | Query uses the correct fully-qualified model name, respects documented standard filters, partition fields, grain, and cost controls |
Inputs
- A data question or query intent (required). May be vague or ambiguous.
- The human-curated model index in the Curated Model Index section (required). The human maintains one entry per dbt model, organized by domain. Each entry must record: fully-qualified table reference, grain (one row per what), useful-for query patterns, join keys, standard filters, and partition fields.
- Standard filters, production dataset path, plan or tier valid values, and sensitive-dataset callouts documented in the Curated Model Index section (required when the project has them).
Procedure
- Read the data question. If it names specific models, skip to step 4. Done when: the data question is read and the path (model-named or index-scan) is determined.
- Scan the Curated Model Index section. Match the question to the model whose grain and useful-for patterns best fit the intent. Done when: the best-fit model is identified from the index.
- If no single model fits, identify the join keys that connect candidate models and note each model's grain to avoid fan-out. Done when: join keys are identified and grains noted, or a single model is selected.
- Construct the fully-qualified table reference using the production dataset path documented in the Curated Model Index section. For sensitive datasets, use the separate dataset path called out there. Done when: the fully-qualified table reference uses the correct dataset path.
- Apply every standard filter documented in the Curated Model Index section (for example, excluding test accounts, soft-deleted records, internal users, flagged or fraudulent users). Omit none. Done when: every documented standard filter is applied.
- For partitioned tables, filter on the partition field and constrain the date range. Never issue an unbounded scan of a large partitioned table. Done when: partitioned tables are filtered on the partition field with a bounded date range.
- Include a comment stating the model grain (one row per what) so join cardinality is explicit. Done when: the query includes a grain comment.
- If the query references plan or tier types, filter only on the valid values documented in the Curated Model Index section. Done when: plan or tier filters use only documented valid values.
- Emit the BigQuery SQL query. Done when: the BigQuery SQL query is emitted with correct model name, all standard filters, partition constraints, grain comment, and valid-value filters.
Failure and recovery
- No model in the index matches the question: stop and report which models were considered and why each was rejected. Do not invent a model or guess a table name.
- The index is empty or an entry is missing required metadata (grain, filters, partition fields): stop and report the gap. Do not emit SQL that skips an undocumented standard filter or partition constraint.
- Joining models would cause a grain fan-out: report the conflict and the grains involved. Do not emit SQL that silently multiplies rows.
- Partial result: never emit a query that respects some but not all documented standard filters or cost controls. The done predicate is all-or-nothing.
Output
A BigQuery SQL query that references the correct fully-qualified model name, applies every documented standard filter, constrains partitioned-table scans to a bounded date range, and states the model grain. Also name each selected model and explain why it was chosen.