We strongly encourage developers to craft a signature to adapt the Aggregated Context API to their specific needs.
In a nutshell the signature defines the contract for the Aggregated Context API both in terms of what is searched and how results are returned.
In search mode (default): Signature is optional. Requests without a signature will search the whole catalog. If you're interested in a subset, for instance trusted assets, use a signature to limit scope to only those objects.
In bulk mode: Signature is required. Documentation object type is not supported in bulk mode.
A signature is expressed as a JSON object with top level keys controlling which object types to search. Each object type value can independently configure which fields are returned with the objects and which slice of the catalog to search.
The object type value's search filters should be used to narrow the set of objects down that best match the agent's goal. For instance, returning content specific to an organization or objects that are gold certified etc.
These following object types are supported as top level keys in the signature parameter of the Aggregated Context API.
Search mode: schema, table, column, query, documentation, bi_folder, bi_report, bi_field
Bulk mode: schema, table, column, query, bi_folder, bi_report, bi_field (documentation object type is not supported)
Each object type can be configured with the following:
fields_required: The fields that MUST be returned with any matching objects.fields_optional: The fields that MAY be returned with any matching objects if they are deemed relevant to the user question.search_filters: The search filters to apply along with the object type.child_objects: A configuration specific to child objects.limit: The maximum number of objects to return for this type (optional, uses mode default if not specified).custom_fields: A list of custom field IDs or names to be returned with the object. To use this, you must include custom_fields in the fields_required parameter.
- Search mode: Default limit is 2 objects per type
- Bulk mode: Default limit is 50 objects per type
- Maximum: 1,000 objects per type
Each object supports only its own set of fields and is expressed as a list of field identifiers.
When both fields_required and fields_optional are omitted: Default values for both are used.
When either one is used and the other is omitted or empty.
- If
fields_required is omitted or empty: No fields are guaranteed in responses.
- If
fields_optional is omitted or empty: No optional field selection occurs.
For more detail, see the relevant entry under Supported Object Fields below.
The Aggregated Context API supports the same set of search filters as the Search API. As the Search API is modified to support new filters, they will be reflected here as well.
Here is a non-exhaustive set of search filters we imagine you should consider using.
domain_ids: The data domain IDs to filter on. These may be useful for agents specific to a department or business unit.fields: The fields to filter on. These can target built-in Alation fields such as tags, data sources etc or any custom field values.flags: The trust flags to filter on. If your organization uses endorsements to indicate canonical objects this may be a useful filter. Please note these values are case sensitive.
Certain field values support filtering. For instance, the tag_ids field can be used to filter on tags. This may be useful for agents to only use a subset of data. For instance a set of high quality (gold) tables.
{
"table": {
"search_filters": {
"fields": {
"tag_ids": [1] // only include tables tagged with tag_id 1
}
}
}
}
See futher Search Filter examples in the Examples section.
When a field represents an object type, it's possible to control which fields are returned with them through child_objects configuration.
For instance, a table object may have columns and common_queries as child object fields.
We enforce an upper limit of 50 columns, common_queries, and mentioned_tables child objects per parent object, and an upper limit of 100 bi_fields child objects per bi_report object.
common_queries and mentioned_tables fields can only be included as top level child object fields.
This is to keep the response size small which helps with the performance of subsequent LLM calls and token usage.
The configuration value of child_objects is keyed by the same parent object's field identifier and indicates which fields should be included with each child object.
The structure of child_objects mirrors the nesting of object fields. If a parent field (e.g. mentioned_tables) includes child objects (e.g. columns),
those are configured by nesting another child_objects object inside.
{
"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"]
}
}
}
}
}
}
When "custom_fields" is included in fields_required, all available custom fields on the object will be returned.
To return a specific set of custom fields, use the custom_fields parameter to specify a list of custom field ids or names to be returned with the object.
The request fails when the requested custom fields share the same name. Work with your Alation admin to ensure custom field names are unique, or ensure the requested custom fields do not contain duplicate names.
{
"schema": {
"fields_required": ["title", "name", "custom_fields"],
"custom_fields": [8, "Completion Date", 10013], # Both field id and name are supported
}
}
Schema objects support the following fields:
description: The description of the schema.name: The name of the schema as it appears in the database.object_id: The unique identifier for the schema object.object_type: The object type name, "schema". This is Alation's internal identifier.source_comment: The description of the schema on the source database.title: The assigned title of the schema.url: The URL to the schema in Alation.custom_fields: The custom field name and value pairs added to the schema.
The following fields are required by default: description, name, title, and url
Table objects support the following fields:
description: The description of the table.common_joins: Common SQL joins for this table.common_filters: Common SQL filters for this table.common_queries: Common SQL queries for this table.columns: The columns belonging to the table.name: The name of the table as it appears in the database.object_id: The unique identifier for the table object.object_type: The object type name, "table". This is Alation's internal identifier.source_comment: The description of the table on the source database.title: The assigned title of the table.url: The URL to the table in Alation.custom_fields: The custom field name and value pairs added to the table.
The following fields are required by default: description, name, title, and url
Column objects support the following fields:
data_type: The data type of the column.description: The description of the column.name: The name of the column as it appears in the database.object_id: The unique identifier for the column object.object_type: The object type name, "attribute". This is Alation's internal identifier.sample_values: Sample values for the column.source_comment: The description of the column on the source database.title: The assigned title of the column.url: The URL to the column in Alation.custom_fields: The custom field name and value pairs added to the column.
The following fields are required by default: name, title, data_type, and url
Query objects support the following fields:
content: The content of the query.description: The description of the query.mentioned_tables: The tables mentioned in the query.object_id: The unique identifier for the query object.object_type: The object type name, "query". This is Alation's internal identifier.title: The assigned title of the query.url: The URL to the query in Alation.
The following fields are required by default: title, description, content, and url
Documentation objects support the following fields:
content: The content of the documentation.object_id: The object ID of the documentation object. With object_type, it uniquely identifies the object in Alation.object_type: The object type name. It can be one of "glossary_v3", "glossary_term", "custom_glossary", and "article". This is Alation's internal identifier.title: The assigned title of the documentation.url: The URL to the documentation in Alation.custom_fields: The custom field name and value pairs added to the documentation.
The following fields are required by default: title, content, and url
BI Folder objects support the following fields:
bi_object_type: The BI tool specific type to capture BI specific terminology. e.g., for Tableau, "site", "project", "workbook", "dashboard", and "worksheet" can be returned, and for Power BI, "workspace", "report", and "dashboard" can be returned.custom_fields: The custom field name and value pairs added to the BI folder.description: The description of the BI folder.name: The name of the BI folder.object_id: The unique identifier for the bi folder object.object_type: The object type name, "bi_folder". This is Alation's internal identifier.source_comment: The description of the BI folder on the BI server.url: The URL to the BI folder in Alation.
The following fields are required by default: name, description, bi_object_type, and url
BI Report objects support the following fields:
bi_fields: The BI columns that affect the BI report.bi_object_type: The BI tool specific type to capture BI specific terminology. e.g., for Tableau, "site", "project", "workbook", "dashboard", and "worksheet" can be returned, and for Power BI, "workspace", "report", and "dashboard" can be returned.custom_fields: The custom field name and value pairs added to the BI report.description: The description of the BI report.name: The name of the BI report.object_id: The unique identifier for the BI report object.object_type: The object type name, "bi_report". This is Alation's internal identifier.source_comment: The description of the BI report on the BI server.url: The URL to the BI report in Alation.
The following fields are required by default: name, description, bi_object_type, bi_fields, and url
BI Field objects support the following fields:
bi_object_type: The BI tool specific type to capture BI specific terminology. e.g., for Tableau, "site", "project", "workbook", "dashboard", and "worksheet" can be returned, and for Power BI, "workspace", "report", and "dashboard" can be returned.custom_fields: The custom field name and value pairs added to the BI field.data_type: The data type of the BI field. e.g., string, integer etc.description: The description of the BI field.expression: The expression used to calculate the BI field.name: The name of the BI field.object_id: The unique identifier for the BI field object.object_type: The object type name, "bi_report_column". This is Alation's internal identifier.
- Note: While BI Field objects are requested with "bi_field" in the signature, the object_type returned is "bi_report_column".
role: The role of the BI field in the BI report. e.g., dimension, measure etc.source_comment: The description of the BI field on the BI server.url: The URL to the BI field in Alation.
The following fields are required by default: name, description, data_type, role, expression, and bi_object_type
{
"schema": {},
"table": {},
"column": {}
}
{
"schema": {},
"table": {
// Omits the "columns" field by removing it from the default fields_optional list.
"fields_optional": ["common_joins", "common_filters"],
},
"column": {
// Extends fields_required to include "sample_values"
"fields_required": ["description", "name", "title", "url", "sample_values"],
}
}
{
"table": {
"search_filters": {
"domain_ids": [1]
},
"limit": 50,
},
"column": {
"search_filters": {
"domain_ids": [1]
},
"limit": 100,
},
}
{
"table": {
"search_filters": {
"fields": {
"tag_ids": [1] // only include tables with tags 1
}
}
}
}
