datahub-sql-workflow
Ground text-to-SQL work in DataHub catalog evidence. Use when a user asks to write, draft, debug, or execute SQL; answer a data question that requires SQL; calculate a metric; query named tables; or investigate SQL results with DataHub MCP tools available. Always begin with find_sql_context, even when the user already supplied tables or dataset URNs.
datahub · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add datahub-project/datahub-skills --skill datahub-sql-workflow技能说明
name: datahub-sql-workflow description: Ground text-to-SQL work in DataHub catalog evidence. Use when a user asks to write, draft, debug, or execute SQL; answer a data question that requires SQL; calculate a metric; query named tables; or investigate SQL results with DataHub MCP tools available. Always begin with find_sql_context, even when the user already supplied tables or dataset URNs. license: Apache-2.0 compatibility: Requires DataHub MCP tools (find_sql_context and catalog metadata tools); SQL execution engine optional metadata: author: datahub version: "2.2"
DataHub SQL Workflow
Ground every query in DataHub evidence. Treat business context as the authority for meaning, catalog metadata as the authority for physical shape, and historical SQL context as evidence of analyst practice.
Require find_sql_context and DataHub metadata tools. If it is still unavailable,
stop and ask the user to enable the DataHub MCP tools — do not fall back to any other
evidence source (other discovery tools, local files, memory, web).
Treat every other tool as capability-dependent: if one is unavailable, disclose the limitation and continue with the supported steps; never replace missing evidence with guesses.
1. Find SQL context first
Call find_sql_context(question=<user's complete question>) before any other
catalog, drafting, probing, or execution tool. Do this even when the user names
tables or supplies Dataset URNs.
Read the response by shape and follow its message:
- Treat
user_editedmatches and theirinstructionsas authoritative. They may intentionally contain no datasets, patterns, or snippets. - Prefer curated
external:*matches over generated history when they conflict. - With usable matches, use their patterns and datasets as primary candidates.
Cross-check
suggested_tables; suggestions can appear even for a strong match. - With no usable match but suggested tables, inspect those Dataset URNs and follow the message's drafting recommendation.
- With neither usable matches nor suggestions, continue business-context and catalog discovery. Call the drafting tool only with concrete Dataset URNs.
- If the message reports a persisted-anchor metadata retrieval error, retry
find_sql_context. Do not reinterpret that failure as an anchor miss.
If two or more usable matches name disjoint datasets for the same metric or question, resolve the tie through business meaning (step 2). Prefer a dedicated metric or fact table over a same-named attribute column on an entity table, and present both candidates if the tie survives.
Generated matches can contain partial document fragments. Call
grep_documents(pattern=".*", start_offset=..., context_chars=...) only when a
returned offset can recover context needed for the query.
Interpret shared_snippets as modeled sibling semantics, not proof of literal
warehouse values. Treat suggested_tables[].evidence.source == "both" as useful
corroboration from independent discovery surfaces, not automatic correctness.
1a. Route schema-discovery questions away from anchors
Some questions ask about catalog structure rather than about data: which tables exist in a schema, what columns a table has, or what values a column takes. Anchors and curated documents cannot answer these — anchors describe query patterns, and per-table documentation does not enumerate a schema.
When the question is schema discovery, skip the curated-document step below and
answer from search, get_entities, and list_schema_fields. Spending a
document fan-out here costs context and cannot succeed.
1b. Read curated documentation
find_sql_context reads only documents whose subtype is Semantic Anchor —
the ones DataHub generates from query history. Every other document in the
catalog is customer-authored and invisible to it. Those are frequently where
join keys, SCD and latest-row rules, unit conventions, and "do not use this
table" warnings actually live.
After find_sql_context, make these search_documents calls in order:
Call 1 — question-keyed search (finds concept-level documentation):
search_documents(
query=<user's complete question>,
semantic_query=<user's complete question>,
filter='subtype != "Semantic Anchor"',
num_results=10,
)
Calls 2–4 — per-table keyword searches (finds table-specific documentation):
Extract the distinct table short names from matches[].datasets URNs (the
last segment after the final dot — e.g., db.schema.MY_TABLE → MY_TABLE).
For each of the top 3 distinct table names, call:
search_documents(
query=<TABLE_SHORT_NAME>,
filter='subtype != "Semantic Anchor"',
num_results=3,
)
Do not pass semantic_query in the per-table calls — keyword matching on
the table name reliably finds table-specific documentation.
If any negated filter returns nothing, re-run that call with no filter and
discard hits whose subType is Semantic Anchor. Some deployments drop negated
clauses from the semantic leg, which silently reduces the call to keyword-only.
From the combined results across all calls, hydrate up to three documents
total with grep_documents — not three per call, and not a fourth extra read.
Choose by subType and title: prefer documents whose title names one of the
candidate tables and whose subType indicates table documentation (e.g.,
Context) over notebook-style documents.
Count the strongest question-keyed non-anchor table document toward that cap, and fully read it before choosing a source table when its title or matched text covers the requested grain or measures, even when anchors did not name that table. If competing curated documents describe different grains, compare them before selecting.
When a governed table already provides the requested measures at the requested grain, use its documented native columns instead of reconstructing them from lower-grain tables.
These table-specific documents frequently contain routing
阅读完整来源 ↗