Customize column descriptions and usage instructions

Create custom column descriptions and usage instructions in the Semantic Column Configuration table so that customizations can be transferred between instances via update sets.

Before you begin

Role required: sn_query_gen.admin or higher

About this task

The Query Generation semantic layer uses column descriptions and usage instructions to help AI understand what each field represents and how to query it. You can override the auto-generated descriptions from the sys_documentation table and add usage instructions that guide query construction.

This procedure uses the Semantic Column Configuration table. Customizations made this way can be transferred between instances via update sets and override descriptions and usage instructions set directly in the Dimension table. For simpler, single-instance testing, you can edit the Semantic Label and Semantic Usage Instructions fields directly in the Dimension [sn_query_gen_dimension] table instead. Such changes might be overridden by changes to the Dimension table included in a plugin upgrade.

Use column configuration when you want to provide custom descriptions, add usage instructions for query guidance, or deactivate specific columns without removing the entire table from the semantic layer.

Procedure

1. Navigate to Query Generation > Semantic Column Configuration.
2. Select New.
3. In the Semantic Column Configuration form, fill in the following information.

   Table 1. Semantic Column Configuration form

   Field	Description
   Table Name	The table the column belongs to. Must have an active entity in the semantic layer.
   Column Name	The column to configure. Use the database column name, not the display label.
   Semantic Description	Custom description of what the column represents in business terms. Overrides the auto-generated description from sys_documentation. Maximum 2,000 characters.
   Semantic Usage Instructions	Guidance to AI on how to use this column during query generation. Include preferred operators, expected value formats, and filtering behavior. Maximum 2,000 characters.
   Active	Whether the column configuration is applied. When cleared, the column falls back to auto-generated state.

4. Select Submit.
   The system automatically syncs the configuration to the corresponding dimension record in the semantic layer.

Result

The custom column configuration is active and will be used by Query Generation when processing queries that involve this column. Because this customization is stored in the Semantic Column Configuration table, it can be included in an update set and transferred to other instances. For more information, see System update sets.

Column configurations

The following examples show effective column descriptions and usage instructions:

Table 2. Column configuration examples

Column	Type	Semantic Description	Usage Instructions
creation_type	Choice	Indicates how the dataset was produced. Values: 'Curated' (hand-selected), 'Derived' (transformed from existing datasets), 'Synthetic' (artificially generated).	Leave empty — choice values are auto-populated by the system
dataset_creation_date	Date	The date the dataset itself was originally created or compiled, independent of when the asset record was added to the instance.	Use date operators (>=, <=, BETWEEN) with YYYY-MM-DD format.
base_datasets	Reference	A list of other AI dataset assets this dataset is derived from or built upon, representing dataset lineage.	Reference field. Use IS EMPTY to find original/root datasets. Use IS NOT EMPTY to find derived datasets.

What to do next

Test your column configuration by asking questions that involve this field in Query Generation and verifying that the correct filters are generated.