Customize Aggregated Context API Calls with Signatures
The signature is a JSON-based parameter supported by the Aggregated Context API that you can use to tailor the API response to your specific use case. It allows you to precisely define:
- Which object types the API should search (for example: tables, columns, or documentation objects)
- Which fields should be included in the results
- What filters should be applied to define the catalog objects that are in scope
- What fields to include for child columns in tables
In this guide:
- Why Use a Signature?
- Context API Modes and the Signature
- Signature Structure
- Fields
- Search Filters
- Child Objects
- Limit
- Full Signature Template
- Signature Examples
- Construct an Effective Signature Step by Step
Why Use a Signature?
Without a signature, the API searches across the entire catalog and can return matches from any supported object type, including content that may not be relevant, such as uncertified or organization-wide assets.
Using a signature allows you to narrow the scope to specific object types, departments, or trusted assets, such as certified or gold standard tables, which helps improve the precision and relevance of the results.
A well-crafted signature can enable:
- Domain-specific results (for example: Only the information in the HR domain)
- Performance optimization of the API request
- Granular control over the context down to the field level
- Support for downstream LLM integrations by reducing response size
Context API Modes and the Signature
The Context API operates in two modes: search
(default) and bulk
that are specified as API request parameters. The mode
parameter defines the mode. If omitted, the search
mode is applied by default.
Understanding these modes is important for working with signatures, as they influence how the signature object is used:
search
(default): This is a conversational mode where you provide a natural language question. Using a signature insearch
mode is recommended, but optional. If you don’t provide a signature, the API defaults to its broadest scope, including all supported object types. In this case, default required fields are used to fetch the context, and all other available fields may be included as optional.bulk
: This mode is for direct object retrieval in bulk operations. The signature object is mandatory inbulk
mode and precisely defines the objects to be retrieved. The Documentation object type is not supported inbulk
mode, and the optional fields aren’t used.
Signature Structure
The top-level keys of a signature JSON object are object types. You can include any combination of the following top-level keys:
schema
table
column
documentation
(available only insearch
mode)query
bi_folder
bi_report
bi_field
Each object type further accepts the following configuration options:
Key | Description |
---|---|
fields_required | List of fields that must be included in the response |
custom_fields | A list of custom field IDs or names to be returned for the objects. To use this key, also include custom_fields in the fields_required parameter. |
fields_optional | List of fields that may be included in the response |
search_filters | Object-level filters for narrowing the search scope |
limit | The maximum number of objects to return for the object type. |
The table
, query
, and bi_report
object types additionally support the child_objects
object:
Key | Description |
---|---|
child_objects | Configuration of which fields to return for nested (child) objects |
Fields
Each object type supports its own specific fields, detailed below. These fields can be listed in the fields_required
, fields_optional
, and child_objects
keys of the signature.
Schema Fields
Field | Description |
---|---|
name | Schema name |
title | Schema title |
description | Schema description |
url | Link to the schema in Alation |
custom_fields | A list of custom fields and their corresponding values for an object. This is only supported within the fields_required key. For more information, refer to Retrieving Custom Fields . |
source_comment | The description of the schema, extracted from the source database, as it appears in the Source Comments field in the Alation catalog. |
object_id | The unique identifier for the schema object in the Alation catalog. |
object_type | The object type name, schema . |
Default required fields: name
, title
, description
,url
Table Fields
Field | Description |
---|---|
name | Table name |
title | Table title |
description | Table description |
url | Link to the table in Alation |
common_joins | Common SQL joins used with this table. Returns top 5 by frequency of use. |
common_filters | Frequently applied filters when querying this table. Returns top 5 by frequency of use. |
columns | Child column objects associated with the table. You have the ability to further specify the list of fields to return for the columns by including columns under the child_objects key. |
common_queries | Published query objects that use the table. The API returns the top 50 queries, ranked by the most recently run or edited. You have the ability to further specify the list of fields to return for the common queries by including common_queries under the child_objects key. |
custom_fields | A list of custom fields and their corresponding values for an object. This is only supported within the fields_required key. For more information, refer to Retrieving Custom Fields . |
source_comment | The description of the schema, extracted from the source database, as it appears in the Source Comments field in the Alation catalog. |
object_id | The unique identifier for the schema object in the Alation catalog. |
object_type | The object type name, table . |
Default required fields: name
, title
, description
, url
Column Fields
Field | Description |
---|---|
name | Column name |
title | Column title |
data_type | Data type of the column |
url | Link to the column in Alation |
description | Column description |
sample_values | Sample data values for the column |
custom_fields | A list of custom fields and their corresponding values for an object. This is only supported within the fields_required key. For more information, refer to Retrieving Custom Fields . |
source_comment | The description of the schema, extracted from the source database, as it appears in the Source Comments field in the Alation catalog. |
object_id | The unique identifier for the column object in the Alation catalog. |
object_type | The object type name, attribute . |
Default required fields: name
, title
, data_type
, url
Documentation Object Fields
Field | Description |
---|---|
title | Title of the document |
content | Body content of the document |
url | Link to the document in Alation |
custom_fields | A list of custom fields and their corresponding values for an object. This is only supported within the fields_required key. For more information, refer to Retrieving Custom Fields . |
object_id | The unique identifier for the documentation object in the Alation catalog. |
object_type | The object type name. It can be one of glossary_v3 , glossary_term , custom_glossary , and article . |
Default required fields: title
, content
, url
Query Fields
Field | Description |
---|---|
title | Title of the saved query |
description | Description of the query |
content | SQL or logic content of the query |
url | Link to the query in Alation |
mentioned_tables | Tables mentioned in the query. The API returns a maximum of 50 tables, selected randomly. You have the ability to further specify the list of fields and columns to return for the mentioned tables by including mentioned_tables under the child_objects key. |
object_id | The unique identifier for the query object in the Alation catalog. |
object_type | The object type name, query . |
Default required fields: title
, description
, content
, url
BI Folder Fields
In Context API requests, use bi_folder
to represent the BI folder object.
Field | Description |
---|---|
name | The name of the BI folder. |
description | The description of the BI folder in the Alation catalog. |
bi_object_type | The BI tool-specific type that captures terminology unique to each BI tool. For example, Tableau objects may return terms like site , project , workbook , dashboard , and worksheet , while Power BI may return workspace , report , and dashboard . |
url | The URL to the BI folder in the Alation catalog. |
object_id | The unique identifier for the BI folder in the Alation catalog. |
object_type | The object type name, bi_folder . |
source_comment | The description of the BI folder, extracted from the BI server, as it appears in the Source Description field in the Alation catalog. |
custom_fields | A list of custom fields and their corresponding values for the BI object. This is only supported within the fields_required key. For more information, refer to Retrieving Custom Fields . |
Default required fields: name
, description
, bi_object_type
, url
BI Report Fields
In Context API requests, use bi_report
to represent the BI report object.
Field | Description |
---|---|
name | The name of the BI report. |
description | The description of the BI report in the Alation catalog. |
bi_object_type | The BI tool-specific type that captures terminology unique to each BI tool. For example, Tableau objects may return terms like site , project , workbook , dashboard , and worksheet , while Power BI may return workspace , report , and dashboard . |
url | The URL to the BI report in the Alation catalog. |
bi_fields | The BI columns that are included into the BI report. |
object_id | The unique identifier for the BI report in the Alation catalog. |
object_type | The object type name, bi_report . |
source_comment | The description of the BI report, extracted from the BI server, as it appears in the Source Description field in the Alation catalog. |
custom_fields | A list of custom fields and their corresponding values for the BI object. This is only supported within the fields_required key. For more information, refer to Retrieving Custom Fields . |
Default required fields: name
, description
, bi_object_type
, url
, bi_fields
BI Field Fields
In Context API requests, use bi_field
to represent the BI report object.
Field | Description |
---|---|
name | The name of the BI field. |
description | The description of the BI field in the Alation catalog. |
bi_object_type | The BI tool-specific type that captures terminology unique to each BI tool. For example, Tableau objects may return terms like site , project , workbook , dashboard , and worksheet , while Power BI may return workspace , report , and dashboard . |
url | The URL to the BI field in the Alation catalog. |
data_type | The data type of the BI field (for example, string or integer ). |
role | The role of the BI field in the BI report (dimension or measure ). |
expression | The expression used to calculate the BI field. |
object_id | The unique identifier for the BI field in the Alation catalog. |
object_type | The object type name, bi_field . |
source_comment | The description of the BI field, extracted from the BI server, as it appears in the Source Description field in the Alation catalog. |
custom_fields | A list of custom fields and their corresponding values for the BI object. This is only supported within the fields_required key. For more information, refer to Retrieving Custom Fields . |
Default required fields: name
, description
, bi_object_type
, data_type
, role
, expression
Retrieving Custom Fields
For richer context, the API can return custom fields for the schema, table, column, documentation, and BI objects.
Query objects currently don’t support the retrieval of custom fields.
For documentation objects, custom fields will not be returned for the legacy
article
object type.article
is a deprecated object type that should be replaced bydocuments
.
custom_fields
can only be requested within the top-level fields_required
key of the signature; it is not supported in fields_optional
or as a child_object
field.
{
"table": {
"fields_required": ["title", "name", "custom_fields"]
}
}
By default, all custom fields and their values associated with an object will be returned if you include custom_fields
into fields_required
. To retrieve a specific subset of custom fields, you can further provide a list of their IDs or names using the custom_fields
key on the same level with fields_required
.
{
"table": {
"fields_required": ["title", "name", "custom_fields"],
"custom_fields": [8, "Certification Date", 10013]
}
}
Using custom field IDs is recommended for signature stability.
Alation allows custom fields of different types to share the same name, though this is not recommended. API requests for custom fields with duplicate names will fail with a 400 error.
Custom field names can be changed by an administrator, which may invalidate a signature in your implementation. If a custom field name specified in a signature cannot be resolved, the Context API call will also fail with a 400 error.
Using the object_id and object_type Fields
The object_id
and object_type
fields can be included into the signature for all object types (schemas, tables, columns, documentation, queries, BI objects) to support integration with other Alation APIs and the AI Agent SDK tools. These fields are returned only when explicitly requested via the fields_required
key.
Search Filters
Use search_filters
to narrow the scope of returned objects. Supported filters can include these keys:
domain_ids
Filter by IDs for domains:
{
"search_filters":{
"domain_ids": [ID_1, ID_2]
}
}
domain_ids
= the key to use for domains[ID_1, ID_2]
= list of specific domain IDs you're filtering with
fields
Filter on custom field values:
{
"search_filters":{
"fields": {
"cf[ID]":["value_1", "value_2"]
}
}
}
cf[ID]
= the system ID of the custom field["value_1", "value_2"]
= the field values you're filtering on
tag_ids
Filter by tags. Tags are referenced inside the fields
key:
{
"search_filters":{
"fields": {
"tag_ids": [ID_1, ID_2]
}
}
}
tag_ids
= the key to use for the tags filter[ID_1, ID_2]
= list of specific tag IDs you’re filtering on
flags
Filter by trust flags:
{
"search_filters": {
"flags":["Endorsement","Deprecation","Warning"]
}
}
flags
= the key to use for the flags filter["Endorsement","Deprecation","Warning"]
= list of the flag values you're filtering on
Example Signature
Let's assume you'd like to construct a signature like the following:
Limit the context to the table object type within the HR domain (has the ID of
10
), with the custom field of Picker type Confidentiality (has the ID of10559
) set to Public or Internal (other confidentiality values of Restricted and Confidential are not included), with the Gold tag (has the ID of1
), and the Endorsed flag:
{
"table": {
"search_filters": {
"domain_ids": [10],
"fields": {
"tag_ids": [1],
"cf[10559]": ["Public", "Internal"]
},
"flags": ["Endorsement"]
}
}
}
Child Objects
Use the child_objects
key to customize which fields
are returned for nested (child) objects.
As of version 2025.1.5, we support the child_objects
key for the table
, query
, and bi_report
object types.
Maximum Child Objects Returned
A maximum of
50
child objects are returned per table and query parent object, and a maximum of100
per BI report. Child objects with popularity data are ranked first. The rest are added afterward in the order they were retrieved or are selected randomly.
You may have noticed that object types can function in two ways within a signature: as higher-level object type keys and as lower-level specifiers for nested objects:
-
Object types keys: When an object type (
schema
,table
, etc.) is used as the object type key in the signature, it limits the overall scope of the request to objects of that type. It acts as the main container, and any other filters included within its definition apply only to matching objects. -
Object types as child objects keys: When an object type is specified for the
child_objects
key, it specifies which related child objects and their fields should be included. This allows you to further refine the data retrieved for these specific child objects by specifying which of their fields you need.
Supported Child Objects
Table Object Type
columns
To customize the response for columns within tables, use the columns
key inside the child_objects
key for the table
object type.
Include this key only if you’ve also included columns
in either the fields_required
or fields_optional
keys of your query signature for the table
object.
The columns
key within child_objects
allows you to define exactly which column fields to return for each column within the returned tables.
In summary:
- If
columns
is included in eitherfields_required
orfields_optional
and inchild_objects
, you will receive the columns for each table, with the fields specified in the nested structure. - If columns is included only in
fields_required
orfields_optional
, but not inchild_objects
, the response will include columns with the default set of column fields. - If columns is included only in
child_objects
, but not infields_required
orfields_optional
, the response will not include columns, as they were not explicitly requested in any of thefields_
keys. This is not a valid format.
Use the following format:
{
"table": {
// List of fields that must be included in the response for tables:
"fields_required": ["name", "title", "description", "url", "columns"],
// Only use context from these specific fields for the child columns:
"child_objects": {
"columns": {
"fields": ["name", "data_type", "description"]
}
}
}
}
This structure translates to:
Retrieve information primarily about table objects. For each table retrieved, also include information about its child column objects, but only return the name, data_type, and description fields for those columns.
common_queries
To customize the list of the query fields to return for each common query associated with a table, use the common_queries
key within the child_objects
section of the table
object.
This key should only be used if common_queries
is also listed in either the fields_required
or fields_optional
sections of your signature for the table
object.
Note
The
child_objects
key is not supported withincommon_queries
. Only thefields
key is allowed.
In summary:
- If
common_queries
is included in eitherfields_required
orfields_optional
and inchild_objects
, you will receive the associated common queries for each table, with the fields specified in the nested structure. - If
common_queries
is included only infields_required
orfields_optional
, but not inchild_objects
, the response will include common queries with a default set of fields. - If
common_queries
is included only inchild_objects
, but not infields_required
orfields_optional
, common queries will not be returned, as they were not explicitly requested in any of thefields_
keys. This is not a valid format.
Use the following format:
{
"table": {
// List of fields that must be included in the response for tables:
"fields_required": ["name", "title", "description", "url", "columns", "common_queries"],
// For each table, also use context from common queries and these fields of the queries:
"child_objects": {
"common_queries": {
"fields": ['title', 'description', 'content', 'url']
}
}
}
}
This structure translates to:
Retrieve information primarily about table objects. For each table retrieved, also include information about its common queries, returning the title, description, content, and the URL fields for those queries.
Query object type
mentioned_tables
To further specify the table fields returned in the response for mentioned tables, use the mentioned_tables
key within the child_objects
key of the query
object.
Include this key only if you’ve also specified mentioned_tables
in either the fields_required
or fields_optional
keys of your signature for the query
object.
For even more detailed control, you can nest another child_objects
key under mentioned_tables
and specify columns
as a child object. The structure of the mentioned_tables
object mirrors that of the table
object, allowing you to define which fields to include for columns within mentioned tables.
Note
The
common_queries
key is not supported undermentioned_tables
and cannot be used at this level of nesting.
In summary:
- If
mentioned_tables
is included in eitherfields_required
orfields_optional
and inchild_objects
, you will receive the mentioned tables in the response, with the specified fields as defined in the nested structure. - If
mentioned_tables
is included only infields_required
orfields_optional
, but not inchild_objects
, the response will include mentioned tables with the default set of table fields. - If
mentioned_tables
is included only inchild_objects
, but not infields_required
orfields_optional
, the response will not include mentioned tables, as they were not explicitly requested in any of thefields_
keys. This is considered an invalid query format.
Use the following format:
{
"query": {
"fields_required": ["title", "description", "content", "mentioned_tables"],
"child_objects": {
"mentioned_tables": {
"fields": ["name", "title", "columns"],
"child_objects": {
"columns": {
"fields": ["name", "data_type", "sample_values"]
}
}
}
}
}
}
This structure translates to:
Retrieve information about query objects. For each query retrieved, return the required fields, also including information about the tables mentioned in the query, returning the name, title, and child columns. For the child columns of mentioned queries, return the fields name, data type, and sample values.
BI report object type
To request BI fields in the response, add the bi_fields
key under bi_report
in either the fields_required
or fields_optional
section. Then, include bi_fields
again under child_objects
within bi_report
to further specify which fields to return for the relevant BI fields.
In summary:
- If
bi_fields
is included in eitherfields_required
orfields_optional
and inchild_objects
, you will receive the specified fields in the response. - If
bi_fields
is included only infields_required
orfields_optional
, but not inchild_objects
, the response will include allbi_fields
with the default set of BI field fields. - If
bi_fields
is included only inchild_objects
, but not infields_required
orfields_optional
, the response will not include thebi_fields
, as they were not explicitly requested in thefields_
section. This is considered an invalid query format.
Use the following format:
{
"bi_report": {
"fields_required": [
"name",
"description",
"bi_object_type",
"bi_fields",
"url",
"source_comment",
"custom_fields",
"object_id",
"object_type"
],
"child_objects": {
"bi_fields": {
"fields": [
"name",
"data_type",
"expression",
"role",
"description"
]
}
}
}
}
This structure translates to: Retrieve information about BI report objects. For each BI report retrieved, return the required fields, also including information about the BI fields included into the BI report and return the name, data type, description, role, and expression for the BI fields.
Limit
The limit
key specifies the maximum number of objects to retrieve. If this key is not provided, the API applies the following default limits:
- Search mode: 2 objects per type
- Bulk mode: 50 objects per type
- Maximum: 1,000 objects per type
{
"table": {
"search_filters": {
"domain_ids": [1]
},
"limit": 50
},
"column": {
"search_filters": {
"domain_ids": [1]
},
"limit": 100
},
}
This structure translates to: Only return 50 table and 100 column objects from a given domain.
Full Signature Template
Here's a full template you can use for constructing your own signature objects:
{
"schema": {
"fields_required": ["name", "title", "description", "url", "custom_fields", "object_id", "object_type"],
"custom_fields": [],
"fields_optional": [],
"search_filters": {},
"limit": <N>
},
"table": {
"fields_required": ["name", "title", "description", "url", "custom_fields", "object_id", "object_type"],
"custom_fields": [],
"fields_optional": ["common_joins", "common_filters", "columns"],
"child_objects": {},
"search_filters": {},
"limit": <N>
},
"column": {
"fields_required": ["name", "title", "data_type", "url", "custom_fields", "object_id", "object_type"],
"custom_fields": [],
"fields_optional": ["sample_values"],
"search_filters": {},
"limit": <N>
},
"documentation": {
"fields_required": ["title", "content", "url", "custom_fields", "object_id", "object_type"],
"custom_fields": [],
"fields_optional": [],
"search_filters": {},
"limit": <N>
},
"query": {
"fields_required": ["title", "description", "content", "url", "object_id", "object_type"],
"fields_optional": [],
"child_objects": {},
"search_filters": {},
"limit": <N>
},
"bi_folder": {
"fields_required": ["name", "description", "bi_object_type","url", "custom_fields", "object_id", "object_type"],
"custom_fields": [],
"fields_optional": [],
"search_filters": {},
"limit": N,
},
"bi_report": {
"fields_required": ["name", "description", "bi_object_type","url", "custom_fields", "bi_fields", "object_id", "object_type"],
"child_objects": {
"bi_fields": {
"fields": ["name", "data_type", "expression", "role", "description"]
}
},
"custom_fields": [],
"fields_optional": [],
"search_filters": {},
"limit": N
},
"bi_field": {
"fields_required": ["name", "description", "data_type", "role", "expression", "bi_object_type", "custom_fields", "object_id", "object_type"],
"custom_fields": [],
"fields_optional": [],
"search_filters": {},
"limit": N,
}
}
Signature Examples
Tables Only
{
"table": {
"fields_required": ["name", "title", "description", "url"]
}
}
This signature:
- Returns only table objects.
- Includes
name
,title
,description
, andurl
in every response as they're required fields. - The
fields_optional
field isn't included, so every response will only include the required fields. - Searches the entire catalog, as no search filters are included.
Tables with Dynamic Field Selection
{
"table": {
"fields_required": ["name", "title", "description", "url"],
"fields_optional": ["common_joins", "common_filters"]
}
}
This signature:
- Returns only table objects.
- Includes
name
,title
,description
, andurl
in every response as they're required fields. - Intelligently includes
common_joins
and/orcommon_filters
only when relevant to the user's question (for example, if a user asks What tables can be joined with the sales table?, the response will include thecommon_joins
data). - Searches the entire catalog, as no search filters are included.
Data Analyst Agent
{
"table": {
"fields_required": ["name", "title", "description", "url", "common_joins", "common_filters", "columns"],
"search_filters": {
"flags": ["Endorsement"],
"fields": {
"tag_ids": [123],
"cf[10568]":["Certified"]
}
},
"child_objects": {
"columns": {
"fields": ["name", "data_type", "description", "sample_values"]
}
}
},
"query": {
"fields_required": ["title", "description", "content", "url"],
"search_filters": {
"fields": {
"tag_ids": [123]
}
}
},
"documentation": {
"fields_required": ["title", "content", "url"],
"search_filters": {
"fields": {
"tag_ids": [123]
}
}
}
}
This signature is optimized for analytical work by focusing on high-quality assets (endorsed and tagged) with complete metadata:
-
Returns
table
,query
, anddocumentation
objects relevant to the question. -
For tables:
- Includes comprehensive information like
common_joins
,common_filters
andcolumns
details. - Filters for only trusted (endorsed) tables with the specific tag ID =
123
and the valueCertified
in the custom field with ID =10568
. - For each table, includes detailed column information with
sample_values
.
- Includes comprehensive information like
-
For queries and documentation objects:
- Includes the complete content to provide analysis context.
- Filters to only include objects with tag ID =
123
.
Question and Answer Agent
{
"schema": {
"fields_required": ["name", "title", "description", "url"],
"search_filters": {
"domain_ids": [123]
}
},
"table": {
"fields_required": ["name", "title", "description", "url"],
"fields_optional": ["common_joins", "common_filters", "columns"],
"search_filters": {
"domain_ids": [123]
},
"child_objects": {
"columns": {
"fields": ["name", "data_type", "description", "sample_values"]
}
}
},
"column": {
"fields_required": ["name", "title", "data_type", "url"],
"fields_optional": ["description", "sample_values"]
},
"documentation": {
"fields_required": ["title", "content", "url"],
"search_filters": {
"domain_ids": [123]
}
},
"query": {
"fields_required": ["title", "description", "content", "url"],
"search_filters": {
"domain_ids": [123]
}
}
}
This signature:
- Is designed for building a Question & Answer system focused on a specific business domain (domain ID =
123
), ensuring all responses remain relevant to that particular subject area. - Supports comprehensive questions and answers by including all major object types (
schema
,table
,column
,documentation
, andquery
). It's important to note that the Alation API will return only the relevant object types for each question, not all types in every response. This means that the search will look across schemas, tables, columns, documentation, and queries, but for any given question, it will only return the types that are relevant to that specific context. - Uses optional fields for tables and columns to provide dynamic responses based on the context of the question.
Analysis Using BI Objects
{
"bi_folder": {
"fields_required": ["name", "description", "bi_object_type", "url"],
"fields_optional": ["source_comment"],
"limit": 5
},
"bi_report": {
"fields_required": ["name", "description", "url", "bi_object_type", "bi_fields"],
"fields_optional": ["source_comment"],
"child_objects": {
"bi_fields": {
"fields": ["name", "data_type", "role", "description", "expression"]
}
},
"limit": 15
},
"table": {
"fields_required": ["name", "title", "description", "url"],
"fields_optional": ["columns"],
"child_objects": {
"columns": {
"fields": ["name", "title", "data_type", "description"]
}
},
"limit": 15
}
}
This signature:
- Returns context for dashboards, key metrics, and supporting data tables relevant to the question.
- Uses optional fields for BI folders, BI reports, and tables to provide dynamic responses based on the context of the question.
- Limits the number of objects to consider per object type using the
limit
key.
Construct an Effective Signature Step by Step
- Step 1: Identify the Object Types you Need
- Step 2: Define Required and Optional Fields for Each Object
- Step 3: Add Search Filters (Optional)
- Step 4: Add Child Objects (Optional)
- Step 5: Add Limit
- Step 6: Combine into a Signature Object
- Step 7: Validate and Test
- Step 8: Iterate to Optimize
Step 1: Identify the Object Types you Need
Start by deciding which types of supported catalog objects your application or agent needs to process.
Step 2: Define Required and Optional Fields for Each Object
Each object type in the Aggregated Context API supports a defined set of fields. For each object type:
-
Use
fields_required
to specify fields that must always be included in the response (for example,name
anddescription
). This provides a predictable and repeatable structure of the response, which can be important in AI application development where consistent output is the goal. Includecustom_fields
intofields_required
for richer context. -
Use
fields_optional
for fields that are helpful but not essential (for example,sample_values
,common_joins
). These fields can enrich responses, but since their availability varies, they may appear inconsistently or more frequently than expected.fields_optional
should only be used in thesearch
mode.
If both fields_required
and fields_optional
are left empty, the API falls back to default fields. This is acceptable in exploratory or low-stakes scenarios, but including at least fields_required
is strongly recommended for more controlled and stable behavior.
Best practice
Use
fields_required
for the core fields your application depends on. Add only a small number of carefully selected fields tofields_optional
if you need additional context.
Example:
{
"table":{
"fields_required": ["name", "title", "description", "url"],
"fields_optional": ["common_joins", "columns"]
}
}
Step 3: Add Search Filters (Optional)
Use search_filters to scope your context query to specific slices of the catalog.
You can filter by:
- Domains: For example, restrict the context to catalog metadata from a particular domain only
- Custom fields: For example, filter on specific custom field with specific values only
- Tags: For example, restrict the context to objects with a specific tag only
- Flags: For example, restrict to “Endorsed” objects only
Constructing search filters within the signature requires that you know the system IDs of the entities that you include into the search filters.
You can find out the domain IDs, custom field IDs, and tag IDs from your Alation catalog user interface. Flag values are fixed system values.
- Find out the Domain ID
- Find out the Custom Field ID
- Find out the Tag ID
- Flag Values to Use
- Example of a Search Filter
Find out the Domain ID
-
Log in to Alation.
-
Use the left-side navigation to select the domain you need. The catalog page of the domain will open. (Do not use the drop down at the top of the page where you can select My domains Only.)
-
Look at the URL. It includes the domain ID. For example, in the URL
https://my_catalog.com/app/domain/36/overview
,36
is the domain ID. -
Make a note of this ID value, along with the domain name. For example:
Domain name:
Alation Discovery Series
ID =36
5 Repeat the search for each domain you want to include into the signature.
Alternatively:
You can use the Get Domains API to retrieve a list of all domains and their IDs. This endpoint is accessible to users with the Catalog Admin and Server Admin roles.
Find out the Custom Field ID
-
Log in to Alation.
-
Click into the Search bar and hit return. The full-page Search page will open.
-
Under Filters in the left-side filter panel, locate or add the custom field you need.
-
Select a field value. For example, in the screenshot below, the Bank Details value of the Categories of Personal Data custom field is selected.
-
After you select a value, the Search results page will update, only displaying matching objects.
-
Look at the URL field. The field ID will be included in the encoded URL. For example, in the URL like:
https://my_catalog.com/app/full_search?limit=25&row_num=0&results_view=list&filters=%7B%22fields%22%3A%7B%22cf%5B10578%5D%22%3A%5B%22Bank+Details%22%5D%7D%7D
, the encoded custom field ID is%22cf%5B10578%5D%22%3A%5B%22
. -
Use URL decoder software of your choice to retrieve the field ID. In the example above, it's
10578
. -
Make a note of the ID value, along with the field name. For example:
Custom field:
Categories of Personal Data
ID =10578
Available values:Bank Details
,Contact Details
,Employment History
-
Repeat the search for each custom field you want to include into the signature.
Alternatively:
If you are a Server or Catalog Admin, you can use the
GET
endpoint of the Custom Fields API to see which fields are available and what the field IDs are:<base_instance_URL>/integration/v2/custom_field/?values=id,name_singular&limit=1000
.
Find out the Tag ID
-
Log in to Alation.
-
In the Search bar, type the keyword for the tag you're interested in and hit return. The Search results page will open.
-
Under Filters in the left-side filter panel, expand the Object Types filter.
-
Select the Tag object type. The Search results page will update to only display tag objects.
-
Click the tag you want the ID for. The catalog page of this object will open.
-
Look at the URL. The number after
/tag/
is the tag ID. For example, in the URLhttps://my_catalog.com/app/tag/1/overview
,1
is the ID of this tag. -
Make a note of this ID, with the tag name for reference. For example:
Tag:
healthcare
ID =1
-
Repeat the search for other tags you need.
Alternatively:
In your Alation catalog, locate a catalog object that has the desired tag applied. Click the tag name to open its detail page. The URL will include the tag's unique ID.
Flag Values to Use
To create a search filter by flags, use these values:
"Endorsement"
for the endorsement flag"Deprecation"
for the deprecation flag"Warning"
for the warning flag in the Classic User Experience or the Important Info flag in the New User Experience.
The values are case-sensitive as should be used as shown below. You can include one or multiple values into the filter:
One flag:
{
"search_filters":{
"flags":["Endorsement"]
}
}
Multiple flags:
{
"search_filters":{
"flags":["Endorsement","Deprecation","Warning"]
}
}
Alternatively:
Listing all three flag types (
"Endorsement"
,"Deprecation"
,"Warning"
) will not return all objects. It will only return objects that have one or more of these flags applied. Any object without a flag will be excluded from the results.
Example of a Search Filter
The example below shows multiple keys and values used in the search_filters
key. (This example is intended as an illustration to demonstrate format and structure. It's not meant to reflect a typical or recommended use case. In practice, most configurations will use a smaller, more focused set of options.)
{
"search_filters":{
"domain_ids":[10, 11, 12],
"fields": {
"tag_ids":[1, 10, 20],
"cf[10559]":["Candidate", "Done"],
"cf[10558]":["In review", "Approved"],
"cf[10557]":["Yes"]
},
"flags":["Endorsement","Warning"]
}
}
Step 4: Add Child Objects (Optional)
If the responses can potentially include a lot of nested (child) objects, you can specify which fields to return for those child objects using child_objects. Use the child_objects
key to potentially reduce token usage and improve response precision.
{
"table": {
"fields_required": ["name", "columns"],
"child_objects": {
"columns": {
"fields": ["name", "data_type", "sample_values"]
}
}
}
}
Step 5: Add Limit
If necessary, add the limit
key to the objects you included. See Limit.
Step 6: Combine into a Signature Object
Structure your final signature as a top-level JSON object with each configured object type as a key.
Example:
{
"schema": {
"fields_required": ["name", "title", "description", "url"]
},
"table": {
"fields_required": ["name", "title", "description", "url", "custom_fields"],
"custom_fields": [80, 10034, 10078],
"fields_optional": ["common_joins", "columns"],
"search_filters":{
"fields":{
"tag_ids": [1]
}
},
"child_objects": {
"columns": {
"fields": ["name", "data_type"]
}
},
"limit": 50
},
"column": {
"fields_required": ["name", "title", "data_type", "url"]
}
}
Step 7: Validate and Test
Before deploying, validate your signature by:
- Checking if all required fields are present
- Running a test call against the Aggregated Context API
- Reviewing if filtering behaves as expected
- Monitoring response size and performance
Step 8: Iterate to Optimize
Once you've finalized your signature:
- Save reusable templates for different use cases
- Tune filters as your catalog grows
- Revisit fields periodically as new metadata types or fields are added to Alation
Updated about 1 month ago