explore

---
name: explore
description: "Use when the user wants to discover, find, or browse data assets in the Alation catalog, data products, or marketplaces. Triggers: search catalog, find tables, list data sources, browse schemas, show columns, what data do we have, what tables exist, explore database, describe table, what's in this data source, show me the schema, list schemas, list columns, what databases do we have, show table structure, describe this data source, find data products, list data products, what data products do we have, search products, show available products, what products are in the marketplace, browse marketplace, which product has sales data. Use this skill when the user wants to know what data exists, understand table/column structure, or find data products — not when they want actual query results or numbers. Not for answering data questions or running queries — use ask instead. Not for creating or managing data products — use curate instead."
---

# 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                             | `scripts/run-cli search "keyword" [--limit N] [--type T (repeatable)] [--starred] [--watching] [--recent] [--domain ID] [--filters JSON] [--ranges JSON]` |
| Discover filterable fields                    | `scripts/run-cli search-fields "field name" [--limit N]`                                     |
| Resolve filter values to IDs                  | `scripts/run-cli search-values --field FIELD_ID "value name" [--builtin] [--limit N]`        |
| List data sources                             | `scripts/run-cli browse sources [--limit N] [--skip N]`                                      |
| List schemas in source                        | `scripts/run-cli browse schemas --ds-id ID [--limit N] [--skip N]`                           |
| List tables                                   | `scripts/run-cli browse tables --schema-id ID [--limit N] [--skip N]` or `--ds-id ID`        |
| List columns                                  | `scripts/run-cli browse columns --table-id ID [--limit N] [--skip N]` or `--ds-id ID`        |
| Describe object                               | `scripts/run-cli browse describe --type {datasource\|schema\|table\|column} --id ID`         |
| Hierarchical tree                             | `scripts/run-cli browse tree --ds-id ID [--depth 1\|2\|3]`                                   |
| List data products                            | `scripts/run-cli query list [--limit N] [--skip N]`                                          |
| Search data products                          | `scripts/run-cli query search --query "keyword" [--marketplace EXTERNAL_MARKETPLACE_ID]`     |
| Get product details/schema                    | `scripts/run-cli query get --product ID [--schema-only]`                                     |
| List marketplaces                             | `scripts/run-cli marketplace list`                                                           |
| Get marketplace details                       | `scripts/run-cli marketplace get --marketplace EXTERNAL_MARKETPLACE_ID`                      |
| List products in marketplace                  | `scripts/run-cli marketplace products --marketplace EXTERNAL_MARKETPLACE_ID`                 |
| Search products in marketplace                | `scripts/run-cli marketplace search --marketplace EXTERNAL_MARKETPLACE_ID --query "keyword"` |
| Search BI reports                             | `scripts/run-cli search "keyword" --type bi_report`                                          |
| Search BI datasources                         | `scripts/run-cli search "keyword" --type bi_datasource`                                      |
| Report's upstream datasources                 | `scripts/run-cli bi report-sources --id REPORT_ID [--limit N]`                               |
| Datasource's downstream reports               | `scripts/run-cli bi source-reports --id DATASOURCE_ID [--limit N]`                           |
| BI report detail                              | `scripts/run-cli bi describe --type report --id ID`                                          |
| BI datasource views                           | `scripts/run-cli bi describe --type datasource --id ID`                                      |
| Generate data product spec from BI datasource | `scripts/run-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.

## Filtering search results

`search` mirrors the Alation UI's filters. Beyond `--type`, you can scope by
data source, author, schema, custom fields, dates, and user state.

**Built-in filters take numeric IDs, not names.** To filter by "data source =
Snowflake Prod" you must first resolve the name to an ID:

1. `search-fields "data source"` — find the filter field and check its
   `is_builtin`. For built-in facets, the `filter_id` is the string key
   (`ds` for data source, plus `author`, `schema_name`, `steward`). For
   custom fields, the `filter_id` is the numeric `id` from the result.
2. `search-values --field ds --builtin "Snowflake"` — resolve the name to a
   numeric ID. Use `--builtin` whenever the field's `is_builtin` was true.
3. `search "orders" --filters '[{"filter_id":"ds","filter_values":["14"]}]'` —
   run the filtered search. `filter_values` must be the resolved IDs.

Date ranges use `--ranges` with ISO dates:
`--ranges '[{"field":"ts_updated","start":"2025-01-01","end":"2025-06-01"}]'`
(`field` = `ts_updated`, `ts_created`, or a custom DATE field id).

User-state toggles need no resolution: `--starred`, `--watching`, `--recent`.
Scope to domains with `--domain ID` (repeatable).

`search` returns `results` plus a `table_view_url` — a link into the Alation UI
full-search view with the same filters applied. Offer it to the user as
"view all results in Alation" when results are truncated or they want the UI.

## 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 `scripts/run-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.

• SKILL.md 17 KB
• scripts/run-cli 1 KB