explore

Explore

Find and explain where data lives in Alation, using user language (not Alation jargon), and return navigable catalog results.

Behavior Contract

• Be concise: default to short answers and focused result lists.
• Use user terminology first, then map to Alation object types internally.
• Ask at most one clarifying question when needed.
• Do not run queries for totals/counts/trends in this skill.
• Include catalog url for each recommended result.

Intent Mapping (Goal First)

Translate user goals into catalog discovery actions:

• "Where can I find X data?" -> keyword search, then refine by object type.
• "What data sources do we have?" -> list data sources.
• "What is inside source X?" -> browse source -> schemas -> tables -> columns.
• "Show me schema/table structure" -> browse hierarchy for that object.
• "Tell me about this table/column" -> describe specific object by ID.
• "What data products do we have?" -> list data products.
• "Which product has sales data?" -> search data products by keyword.
• "What's in this data product?" -> get product details and schema.
• "What marketplaces are available?" -> list marketplaces.
• "What products are in marketplace X?" -> list or search products in a marketplace.
• "What BI reports about X?" -> search with --type bi_report.
• "What BI datasources/explores/datasets for X?" -> search with --type bi_datasource.
• "What feeds this dashboard/report?" -> get report ID, then bi report-sources --id ID.
• "What reports use this datasource/explore/dataset?" -> get datasource ID, then bi source-reports --id ID.
• "Tell me about this BI report" -> bi describe --type report --id ID.
• "Show me the semantic layer / views for this datasource" -> bi describe --type datasource --id ID.
• "What metrics/measures are in this report/dashboard?" -> bi report-sources --id ID to find the datasource, then bi describe --type datasource --id DATASOURCE_ID to get the measures.
• "Create a data product from this BI datasource/report" -> bi product-spec --id DATASOURCE_ID to generate the spec, then hand off to curate to create the product.

If user says something broad like "show me sales data":

1. Treat as discovery by default (explore).
2. Search both catalog (search "sales") and data products (query search --query "sales").
3. Present results grouped: data products first (queryable), then catalog matches (browse-only).
4. If data products were found: "Want me to query one of these products for results?"
5. If only catalog matches: "I found tables but no queryable data product. Want to explore these further, or create a data product from one?"

Internal Command Routing

Use these commands to execute the workflow:

Goal	CLI Command
Keyword discovery	python -m cli search "keyword" [--limit N] [--type <object_type>]
List data sources	python -m cli browse sources [--limit N] [--skip N]
List schemas in source	python -m cli browse schemas --ds-id ID [--limit N] [--skip N]
List tables	python -m cli browse tables --schema-id ID [--limit N] [--skip N] or --ds-id ID
List columns	python -m cli browse columns --table-id ID [--limit N] [--skip N] or --ds-id ID
Describe object	python -m cli browse describe --type {datasource|schema|table|column} --id ID
Hierarchical tree	python -m cli browse tree --ds-id ID [--depth 1|2|3]
List data products	python -m cli query list [--limit N] [--skip N]
Search data products	python -m cli query search --query "keyword" [--marketplace EXTERNAL_MARKETPLACE_ID]
Get product details/schema	python -m cli query get --product ID [--schema-only]
List marketplaces	python -m cli marketplace list
Get marketplace details	python -m cli marketplace get --marketplace EXTERNAL_MARKETPLACE_ID
List products in marketplace	python -m cli marketplace products --marketplace EXTERNAL_MARKETPLACE_ID
Search products in marketplace	python -m cli marketplace search --marketplace EXTERNAL_MARKETPLACE_ID --query "keyword"
Search BI reports	python -m cli search "keyword" --type bi_report
Search BI datasources	python -m cli search "keyword" --type bi_datasource
Report's upstream datasources	python -m cli bi report-sources --id REPORT_ID [--limit N]
Datasource's downstream reports	python -m cli bi source-reports --id DATASOURCE_ID [--limit N]
BI report detail	python -m cli bi describe --type report --id ID
BI datasource views	python -m cli bi describe --type datasource --id ID
Generate data product spec from BI datasource	python -m cli bi product-spec --id DATASOURCE_ID

search type: Can be one of many options. The most common are "table", "column", "schema", "article", "glossary_term", "datasource", Use --help to see all the options.

browse tree depth: 1 = schemas only, 2 = schemas + tables, 3 = schemas + tables + columns. Always pass --depth 1 explicitly on unfamiliar sources — depth 3 on a large source can return hundreds of objects.

Standard Workflow

1. Interpret the user goal in plain language.
2. Pick discovery path:
   • Unknown location -> search first (catalog search for tables/columns, product search for data products).
   • Known source/object -> browse hierarchy (for catalog) or get product details (for data products).
   • Known marketplace -> list or search products in that marketplace.
3. If required identifier is missing, list the parent level first (e.g., sources before schemas).
4. Return top relevant results with name, description, and URL. Include IDs only when the user will need to refer back to them. Translate Alation types into plain language (e.g., "database" not "datasource").
5. Offer one next step, then wait for confirmation.

Data Product Discovery

Data products are queryable datasets published in Alation. They do not appear in catalog search results (search command), so use the dedicated product commands instead.

Finding a data product

1. Start with query search --query "keyword" if the user describes what data they need.
2. Fall back to query list if the search term is too vague or returns nothing.
3. Use query get --product ID --schema-only to inspect tables and columns in a product.

Marketplace browsing

Marketplaces are curated collections of data products. If the user mentions a marketplace or wants to browse published products:

1. marketplace list to find available marketplaces.
2. marketplace products --marketplace EXTERNAL_MARKETPLACE_ID or marketplace search --marketplace EXTERNAL_MARKETPLACE_ID --query "keyword" to browse within one.

Always use the external marketplace ID to identify marketplaces.

BI Discovery

BI objects represent dashboards, reports, and their semantic-layer datasources from tools like Tableau, Looker, and Power BI.

Terminology mapping:

• User says "dashboard", "workbook", "report", "sheet", "tile" -> Alation type bi_report
• User says "explore", "dataset", "published datasource", "semantic layer" -> Alation type bi_datasource
• Ambiguity: "datasource" alone could mean a regular Alation data source OR a BI datasource. If the conversation is about BI tools (Tableau, Looker, Power BI), treat it as bi_datasource. Otherwise, treat it as a regular data source or ask the user to clarify.
• User says "folder", "project", "workspace", "site" -> Alation type bi_folder

Finding BI objects:

1. search "keyword" --type bi_report to find reports/dashboards.
2. search "keyword" --type bi_datasource to find semantic-layer datasources.
3. bi describe --type report --id ID for report metadata.
4. bi describe --type datasource --id ID for semantic-layer views (joins, dimensions, measures).

Cross-navigation (the key BI workflow):

• "What data feeds this dashboard?" -> bi report-sources --id REPORT_ID
• "Which dashboards use this explore/dataset?" -> bi source-reports --id DATASOURCE_ID

Cross-navigation uses lineage, so it resolves transitive relationships automatically. A Looker Dashboard resolves through its Tiles to the underlying Explore. A Power BI Dashboard resolves through Tiles and Reports to the underlying Dataset.

Typical BI exploration flow:

1. User asks about BI data -> search with --type bi_report or --type bi_datasource.
2. User picks a result -> detail with bi describe.
3. User asks "what feeds this?" or "what uses this?" -> cross-navigate.
4. If user wants to query the underlying data, hand off to ask.
5. If user wants to create a data product from a BI datasource -> bi product-spec --id DATASOURCE_ID, then hand off to curate.

BI to data product flow:

1. Find the report: search "keyword" --type bi_report.
2. Get its upstream datasource: bi report-sources --id REPORT_ID.
3. Inspect metrics/measures: bi describe --type datasource --id DATASOURCE_ID.
4. Generate a product spec: bi product-spec --id DATASOURCE_ID. Dialect is auto-detected.
5. Present the spec to the user for review, then hand off to curate to create the product with product create.

Handoff to ask

After the user identifies a data product, suggest querying it: "Want me to query this product for results?" Then hand off to the ask skill with the product ID.

Disambiguation

When search or browse returns multiple plausible matches, present the options and let the user choose. Show each option with its name, which data source it belongs to, and a brief description if available. Don't silently pick one — the user knows their data better than you.

Only skip this if the user already specified exactly what they want or there is a single obvious match.

Response Format

Use this compact structure:

• One-line outcome statement.
• Up to 5 results (most relevant first), each with:
  • name
  • description (if available)
  • URL
• One optional next-step question.

Not This Skill

Route away when the request is outside discovery:

• User wants numbers/analysis/results from data -> use ask (provide the product ID).
• User wants to create/manage data products, publish to marketplace -> use curate.
• User wants to create/manage agents, tools, LLMs, or connections -> use configure.

Error and Fallback Handling

• Authentication/setup errors:
  • Suggest python -m cli setup check.
  • If still blocked, route to setup skill.
• No search results:
  • Retry with simpler keywords or synonyms.
  • Remove strict type filter.
  • Ask one clarifying question about business term/source system.
• Too many results:
  • Narrow by type (table/column) or source.
  • Use pagination via --limit and --skip.
• Missing IDs for browse commands:
  • Retrieve parent objects first; do not guess IDs.

Common Mistakes

Mistake: Using search when the user names a specific data source. Why it seems reasonable: search feels like a universal starting point. Instead: Find that source via browse sources, then drill in with browse tree or browse schemas.

Mistake: Using browse tree --depth 3 on a large or unfamiliar source. Why it seems reasonable: showing everything at once feels thorough. Instead: Start at --depth 1. Let the user tell you what to drill into.

Mistake: Describing every table when the user just asked what's there. Why it seems reasonable: more detail seems more helpful. Instead: List table names first. Only describe a specific table when the user picks one.

Mistake: Proceeding to another skill action without user confirmation. Why it seems reasonable: anticipating the next step feels efficient. Instead: Suggest one next step and wait. "Want me to query this data?" not "Let me query this for you."

Mistake: Using catalog search to find data products. Why it seems reasonable: search feels like a universal starting point. Instead: Data products don't appear in catalog search. Use query search or query list for data products.

Mistake: Using product list or product get for discovery. Why it seems reasonable: they sound like discovery commands. Instead: Those are management commands (raw spec JSON) used by the curate skill. For discovery, use query list and query get which return consumer-friendly views.

Mistake: Using search --type datasource to find BI datasources. Why it seems reasonable: "datasource" and "bi_datasource" sound similar. Instead: datasource is for RDBMS data sources (Postgres, Snowflake). BI semantic layers (Looker Explores, Tableau Published Datasources, Power BI Datasets) use --type bi_datasource.

Mistake: Using browse commands for BI objects. Why it seems reasonable: browse works for catalog objects, why not BI? Instead: BI has its own hierarchy. Use bi commands for detail and cross-navigation, search with BI type filters for discovery.

Red Flags

• "Let me search for all tables" — search is keyword-based. To list tables, use browse.
• "I'll check the data source API" — all commands go through the CLI, never raw APIs.
• "I'll fetch all columns for this data source" — could be enormous. Drill down through schemas and tables first.
• "Let me show you everything at depth 3" — start at depth 1; go deeper only as needed.
• "Data products should show up in catalog search" — they don't. Use query search or query list.
• "I'll use --type datasource to find the Tableau data source" — that finds RDBMS sources, not BI sources. Use --type bi_datasource.
• "Let me browse BI reports" — browse is for catalog hierarchies. Use search --type bi_report for discovery.