Catalog Context Search Guide

This guide explains how to use the Catalog Context Search capabilities in Alation AI to find and explore data assets in your catalog.

How It Works

The Catalog Context Search uses Alation’s search infrastructure internally. When you ask a question:

Your question is analyzed to extract business concepts and keywords
A search is executed against your catalog’s indexed metadata
Results are retrieved based on relevance matching
The agent summarizes the findings to answer your question

Why Good Metadata Matters

The search matches your question against catalog metadata. Objects with good titles and descriptions are more likely to be found:

Title: A clear, business-friendly name helps users find objects by concept
Description: Detailed descriptions improve relevance for complex questions

For example, a table titled “Financial Customer Data” with a description “Contains customer demographics, contact information, and account details for the finance department” will be found for questions like:

“Find customer tables in finance”
“What tables have contact information?”
“Customer demographics data”

What You Can Ask

Based on common usage patterns, here are the types of questions supported:

Find by Business Concept

"Find tables related to customer information in the finance schema"
"What tables and BI reports do we have about Medicare payments?"
"Search for revenue analysis dashboards"

Get Details About Specific Objects

"Tell me about the orders table and show its columns"
"Explain the Sales Performance dashboard and its measures"
"What is the calculation logic for the Revenue measure in the Sales report?"

List Objects by Criteria

"What tables are in the Snowflake healthcare schema?"
"Show me 20 endorsed sales tables"
"Find all columns classified as PII"

Find Relationships

"How do I join the claims table with the hospitals table?"
"Which tables contain the customer_id column?"
"What tables does the monthly_sales query reference?"

Explore Hierarchies

"What columns are in the customers table?"
"What BI reports are in the Sales workbook?"
"What documentation articles are in the Compliance folder?"

Debugging in Agent Studio

When using Agent Studio, you can see exactly what’s happening:

Viewing Tool Calls

After the agent completes, expand the Completed section
You’ll see each tool call the agent made
This shows which search approach was used

Viewing the Signature

Under Processing, expand the details
The signature shows:
- search_phrases: The keywords being searched
- object types: What types of objects we’re looking for (table, column, etc.)
- search_filters: Any metadata filters applied
- fields_required: What information is being retrieved

Example signature you might see:

{
  "table": {
    "search_phrases": ["customer", "finance"],
    "fields_required": ["name", "title", "description", "url", "columns"],
    "search_filters": {
      "fields": {
        "schema_id": [1402]
      }
    },
    "limit": 10
  }
}

This tells you the agent searched for tables matching “customer” and “finance” in a specific schema.

Adjusting Your Question

If the signature doesn’t include what you expected, you can modify your question to guide the search:

Missing object type? Add it to your question: “Also include BI data sources” or “Search for tables and BI reports”
Wrong filters? Be more specific: “In the finance schema” or “In the Marketing domain”
Need more results? Ask explicitly: “Fetch 15 tables” or “Show me 20 columns”

Agent vs Direct Tools

Using the Agent (Recommended)

The Catalog Context Search agent analyzes your question, fetches context from Alation, and returns a summarized answer. This is ideal for:

Quick answers to questions
Conversational interactions
When you want interpreted results

Using Tools Directly

If you need the complete raw context from Alation (not summarized), you can use the underlying tools directly:

get_search_context: Returns full context using semantic search (for finding by name/concept)
get_filter_context: Returns full context using filter-based enumeration (for listing by criteria)

Search vs Filter: Example

These two questions look similar but use different tools:

Question	Tool Used	What Happens
”Fetch 20 sales tables under Alation Analytics”	`get_search_context`	Searches for tables matching “sales” within the Alation Analytics datasource
”Fetch 20 tables under Alation Analytics”	`get_filter_context`	Lists all tables in the Alation Analytics datasource (no keyword search)

The key difference:

First question has a search term (“sales”) - it finds tables related to that concept
Second question has no search term - it simply enumerates/lists all tables matching the filter

When your question includes a keyword, concept, or name to search for, get_search_context is used. When you just want to list everything matching a filter (no keyword), get_filter_context is used.

Using Tools in Custom Agents

To use these directly:

Clone the Curation Agent or create a custom agent
Add get_search_context or get_filter_context to your agent’s tools
The tools are self-contained - no special system prompt is required
The signature generator runs automatically to build the search signature

Your custom agent will receive the entire context payload to process however you need.

This is useful when your agent needs to process the raw catalog data itself rather than a summary. For example, the Curation Agent uses these tools to fetch table and column metadata, then uses that data to generate descriptions - it needs the actual metadata, not a summarized answer about it.

Base Signature

The base_signature is an optional input argument available on the get_search_context and get_filter_context tools. If you don’t provide one, the entire catalog is considered and the agent automatically determines the appropriate object types based on your question.

Use base_signature when you want to focus on specific object types or a particular set of objects:

Restricting searches to specific object types
Pre-applying filters
Customizing what fields are returned

How to Add a Base Signature

To configure a base signature in Agent Studio:

In your agent configuration, go to the Tools section
Click Edit on the tool you want to configure (get_search_context or get_filter_context)
In the dialog that opens, you’ll see the base_signature parameter where you can add your configuration

How Base Signature Works

Without base_signature: The agent analyzes your question and picks appropriate object types automatically.

With base_signature: Only the object types you specify are searched. If you want multiple object types, you must include all of them in the signature.

Simple Example: Search Only Tables

{
  "table": {}
}

This tells the agent to only search for tables. Other object types (columns, BI reports, etc.) will not be included even if relevant to the question.

Filter Example: Only Endorsed Objects

{
  "table": {
    "search_filters": {
      "fields": {
        "flag_types": ["Endorsement"]
      }
    }
  }
}

This searches for tables that have the Endorsement trust flag.

Multi-Object Type with Selective Filters

{
  "table": {
    "search_filters": {
      "fields": {
        "flag_types": ["Endorsement", "Warning"]
      }
    }
  },
  "column": {
    "search_filters": {
      "fields": {
        "flag_types": ["Endorsement", "Warning"]
      }
    }
  },
  "bi_report": {},
  "bi_field": {},
  "documentation": {}
}

In this example:

table and column: Searched with trust flag filters applied
bi_report, bi_field, documentation: Included in search but without filters (the empty {} means “include this type with no extra filters”)

If you want an object type to be searched, you must include it in the base_signature, even if you don’t need filters for it.

Using the Signature Generator Agent

The Signature Generator is a native agent that helps you build base signatures. If you’re not sure how to structure a signature, you can ask this agent to generate one for you.

How to Use It

In Agent Studio, select the Signature Generator agent
Ask a question like: “Fetch tables and schemas under Financial domain with ABC tag”
The agent will generate a complete signature
Expand Completed > final_result to see the signature
Copy and simplify it for use as a base_signature

Example

Question: “Fetch tables and schemas under Financial domain with ABC tag”

Generated signature (from final_result):

{
  "table": {
    "fields_required": ["name", "title", "description", "url", "object_id", "parent_objects"],
    "search_filters": {
      "domain_ids": [42],
      "fields": {
        "tag_ids": [15]
      }
    },
    "limit": 20
  },
  "schema": {
    "fields_required": ["name", "title", "description", "url", "object_id", "parent_objects"],
    "search_filters": {
      "domain_ids": [42],
      "fields": {
        "tag_ids": [15]
      }
    },
    "limit": 20
  }
}

Simplified for base_signature (remove limit and fields_required - the agent will fill these in):

{
  "table": {
    "search_filters": {
      "domain_ids": [42],
      "fields": {
        "tag_ids": [15]
      }
    }
  },
  "schema": {
    "search_filters": {
      "domain_ids": [42],
      "fields": {
        "tag_ids": [15]
      }
    }
  }
}

This simplified signature can now be used as a base_signature to always filter by that domain and tag.

Result Limits

Question Type	Default Limit	Example
Specific object details	3	”Tell me about the orders table”
List/fetch all questions	20	”What tables are in this schema?”

To get more results, specify a number: “Fetch 50 tables in the Finance domain”

Child objects (like columns within a table) are limited to 50 per parent.

Supported Object Types

Object Type	Description	Fields
table	Database tables	name, title, description, url, object_id, parent_objects, columns, common_joins, common_filters, source_comment, custom_fields
column	Table columns	name, title, data_type, description, url, object_id, parent_objects, sample_values, source_comment, custom_fields
schema	Database schemas	name, title, description, url, object_id, parent_objects, source_comment, custom_fields
query	Saved SQL queries	title, description, content, url, object_id, parent_objects, mentioned_tables
documentation	Articles, glossary terms	title, content, url, object_id, parent_objects, custom_fields
datasource	RDBMS connections	title, description, dbtype, url, custom_fields
bi_report	BI dashboards/reports	name, description, bi_object_type, url, object_id, parent_objects, bi_fields, source_comment, custom_fields
bi_field	BI measures/dimensions in a BI report	name, description, data_type, role, expression, bi_object_type, url, object_id, parent_objects, source_comment, custom_fields
bi_folder	BI workbooks/folders	name, description, bi_object_type, url, object_id, parent_objects, source_comment, custom_fields
bi_datasource	BI published data sources	name, description, bi_object_type, url, source_comment, custom_fields

Common Filters

Filter	Use For	Example
schema_id	Tables/columns in a schema	”Tables in the finance schema”
ds_id	Objects in a data source	”Tables in Snowflake”
domain_ids	Objects in a domain	”Tables in Marketing domain”
tag_ids	Tagged objects	”Objects tagged as PII”
flag_types	Trust flags	”Endorsed tables”, “Deprecated columns”
cf[field_id]	Custom field values	”Tables classified as Confidential”
steward	Steward (via custom field)	“Tables stewarded by John”
bi_server_id	BI objects on a server	”Reports in Tableau Server”
parent_folder_id	BI objects in a folder	”Reports in Sales workbook”
table_type	VIEW or TABLE	”Show only views”
published	Published queries	”Published queries”
scheduled	Scheduled queries	”Scheduled queries”

Note: Filters use IDs internally, but you can use names in your questions. The system automatically resolves names (like “finance schema” or “PII tag”) to their IDs.

Tips for Better Results

Be specific about object types when you can
- “Find sales tables” is better than “Find sales data”
Mention the data source or schema to narrow results
- “Tables in the Snowflake healthcare schema”
Use business terms - the search understands concepts, not just exact names
Ask for related objects when exploring
- “Show me the table with its columns”
Check metadata quality if searches aren’t returning expected results
- Good titles and descriptions significantly improve discoverability
Specify counts when you need more results
- “Fetch 50 tables” instead of “Fetch all tables”

What’s Not Supported

Limitation	Notes
BI datasource columns	Columns under a BI datasource are not searchable
Popularity/usage ranking	Results are ordered by relevance, not usage frequency
Domain/tag values in response	These are used for filtering, not returned as metadata fields