Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Data & analytics

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 · Static checks on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add datahub-project/datahub-skills --skill datahub-sql-workflow

About this skill


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_edited matches and their instructions as 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

Read the complete source ↗