Data dictionaries and query docs drafted from the SQL itself
Documentation debt is universal: tables nobody defined, columns with cryptic names, metrics whose definition lives only in a senior analyst's head. Feeding AI the DDL or the SQL model and getting first-draft column descriptions and a data dictionary clears the backlog fast — but only if the model marks what it is guessing so an owner can confirm the real meaning.
You are an analytics engineer writing clear documentation for a data model. Draft a data dictionary from the SQL I provide. The DDL or SQL model definition: {{ddl_or_sql}} Business context for this table: {{business_context}} Metric definitions already agreed (use these verbatim): {{known_definitions}} Produce: 1. Table summary — what one row represents (the grain), the primary key, and how the table is populated, based only on the SQL. 2. Column dictionary — a table with: column name, inferred type, and a one-line description. 3. Metrics — any metric computed in the SQL, with its exact definition from my "known definitions" list where I gave one. Rules: - Describe only columns and logic that appear in the SQL. Do not invent a column or its meaning. If a column's purpose is not clear from its name plus the context I gave, write the description as "[NEEDS OWNER CONFIRMATION]" rather than guessing. - For any metric not in my agreed list, describe how the SQL computes it and mark it "definition not yet confirmed" — do not assert a business meaning. - Flag columns whose names are ambiguous or look like they could be misread, so a human can clarify them.
Fill in your details and the prompt updates live — then copy.
Table: fct_orders Grain: one row per completed order. Primary key: order_id. Populated from the orders source, filtered to completed status. | Column | Type | Description | |-------------|---------|---------------------------------------------------------| | order_id | string | Unique identifier for the order (primary key). | | customer_id | string | The customer who placed the order. | | order_date | date | Date the order was completed. | | net_amount | numeric | Gross minus discounts and refunds, excluding tax/ship. | | is_repeat | boolean | [NEEDS OWNER CONFIRMATION] — appears to flag returning customers; logic not shown in this SQL. | Metric net_amount uses the confirmed definition above.
The full workflow
- Paste the DDL or model SQL and any metric definitions already agreed with the business
- Confirm every [NEEDS OWNER CONFIRMATION] and unconfirmed metric with the data owner, not from memory
- Check that documented metric definitions match your semantic layer or BI tool exactly
- Commit the reviewed dictionary alongside the model so it stays version-controlled
Watch out for
The model will confidently guess what a cryptically named column means and be wrong. Treat every AI-written definition as a draft until the table's owner confirms it — a wrong definition in the data dictionary misleads everyone downstream.
Metric definitions must match the source of truth. If the documented definition drifts from the semantic layer or dashboard logic, you have created two conflicting definitions instead of one.
Do not paste production schemas containing sensitive table or column names, or embedded credentials, into a consumer tool — redact first and use an approved instance.
Where this comes from
Every use case on this site is grounded in real reports from working data analysts — not invented by us.