---
sourceDocument: Australia Platform Analytics
sourceDocumentLink: https://www.servicenow.com/docs/r/australia/now-intelligence

 Release :

    - australia

ft:locale :

    - en-US

ft:publication_title :

    - Australia Platform Analytics

ft:clusterId :

    - par

bundleId :

    - par

workflow :

    - Platform


---

# Customizing semantic metadata

# Customizing semantic metadata {#ariaid-title1}

Release version: Australia  
Updated April 17, 2026  
![](https://www.servicenow.com/docs/portal-asset/ico-clock) 4 minutes to read
Summarize  
![AI sparkle icon](https://servicenow.com/docs/portal-asset/ai-sparkle-icon) Summarized using AI  
This content was generated using new OpenAI-powered functionality. Results are provided on an as is basis and are not guaranteed to be accurate or complete.  

## Summary of Customizing semantic metadata

Semantic metadata in Query Generation---comprising semantic labels, descriptions, and usage instructions---guides how natural language questions are interpreted and converted into queries.
Customizing these metadata fields enables ServiceNow customers to tailor AI query understanding to their organization's specific terminology and data context, improving accuracy and relevance.
Show full answer Show less  

## When and Why to Customize

* Customize metadata only if you notice consistent issues, such as incorrect table or field selection, missing fields, or incorrect query construction.
* Adjust semantic labels and descriptions to align with your organization's terminology and to help the system distinguish similar data entities.
* Modify usage instructions to instruct the AI on how to correctly query specific fields, including handling abbreviations, operators, or hierarchical expansions.

## Customization Methods

Two primary methods exist for modifying semantic metadata:

* **Semantic Table and Column Configuration tables:** Recommended for production use as these changes can be packaged in update sets and migrated across instances. Supports editing entity and dimension descriptions and dimension usage instructions but not entity labels or usage instructions.
* **Entity and Dimension tables:** Useful for testing on a single instance. Allows editing entity labels and entity-level usage instructions but changes cannot be transferred via update sets and may be overwritten during upgrades.

Both methods require the `snquerygen.admin` role or higher.

## Best Practices for Writing Metadata

* **Descriptions:** Keep concise (1-2 sentences), focused on business meaning, and include common synonyms or abbreviations relevant to users.
* **Usage Instructions:** Be specific and structured, using rules, examples, and edge cases. Include matching strategies (e.g., CONTAINS versus exact match) and focus instructions on each entity or field's needs.

## Usage Instructions vs. Segments

Usage instructions dynamically guide the AI in querying data fields across many scenarios (especially free-text fields), while segments define fixed filter values for specific business terms. Usage instructions are preferred for flexible fields like locations, whereas segments fit static classifications such as priority levels.

## Examples and Implementation Patterns

For example, usage instructions for a free-text geographic location field can define hierarchical expansions (continent → countries → states), synonyms (e.g., "UK" vs. "United Kingdom"), and specify case-insensitive CONTAINS matching. This logic allows the AI to interpret and expand queries like "Show me things in Europe" into multiple OR-based filters automatically.

## Applying Customizations

* Create and maintain custom entity descriptions in the Semantic Table Configuration table to ensure changes migrate across instances.
* Customize column descriptions and usage instructions in the Semantic Column Configuration table for consistent transfer via update sets.

Focusing on fields involved in failing queries rather than reviewing all metadata is recommended for efficiency.  
Semantic metadata --- descriptions, labels, and usage instructions --- control how Query Generation interprets natural language questions. Customize these metadata to improve accuracy for your organization's terminology and data.

Both [entities](https://www.servicenow.com/docs/4q6x4QEhbrGjzdIOBwTbMw#gloss-entity "A semantic layer record that represents a database table. Query Generation uses entities to identify the correct facts table when processing a natural language question.") (tables) and [dimensions](https://www.servicenow.com/docs/4q6x4QEhbrGjzdIOBwTbMw#gloss-dimension "A semantic layer record that represents a column on a database table. Dimensions can follow reference fields across tables. Query Generation uses dimensions to identify the correct fields when processing a natural language question.") (fields)
in the [semantic layer](https://www.servicenow.com/docs/4q6x4QEhbrGjzdIOBwTbMw#gloss-semantic-layer "A flat representation of database tables and columns used by Query Generation to identify the correct data sources when processing a natural language question. The semantic layer consists of entities (tables), dimensions (columns), and segments (filter conditions).") have three metadata fields that Query Generation uses when processing a question:{#customize-semantic-metadata__customize-semantic-metadata-para-1}

Semantic Label
:   A short name or alias for the entity or dimension. Functions as a search keyword
    that helps AI search identify the correct table or field when a user's question
    does not match the default field label.

Semantic Description
:   A natural-language description of what the entity or dimension represents in
    business terms. Provides context that helps the system distinguish between
    similar tables or fields.

Semantic Usage Instructions
:   Instructions injected directly into the [LLM](https://www.servicenow.com/docs/4q6x4QEhbrGjzdIOBwTbMw#gloss-llm "An AI model trained on large volumes of text data to understand and generate natural language. Query Generation uses an LLM to interpret user questions and produce semantic queries.") prompt when the entity or dimension
    is selected. Teaches the system how to query the data --- for example, which
    operators to use, how to handle abbreviations, or how to expand hierarchical
    values.

## When to customize {#customize-semantic-metadata__customize-semantic-metadata-section-1}

Metadata is auto-generated and works well in
its baseline state. Customize it only when you observe consistent, repeatable
problems:{#customize-semantic-metadata__customize-semantic-metadata-para-2}

* The system selects the wrong table or cannot find one --- edit descriptions and labels
* The wrong field is selected or a field is missing --- edit descriptions and labels
* Your organization uses different terminology than the auto-generated labels --- edit labels
* The right table or field is selected but the query is constructed incorrectly --- edit usage instructions

Note:  
There are thousands of dimensions. Do not try to review them all. Focus on fields that appear in failing queries.

## Two methods for customizing metadata {#customize-semantic-metadata__customize-semantic-metadata-section-2}

Two methods are available. Editing the configuration tables is considered the default approach.{#customize-semantic-metadata__customize-semantic-metadata-para-3}
{#customize-semantic-metadata__customize-semantic-metadata-section-2__entry__3}

| Method | Tables | When to use |
|-|-|-|
| Edit records on the Semantic Table Configuration and Semantic Column Configuration tables | Semantic Table Configuration \[sn_query_gen_table_config\] and Semantic Column Configuration \[sn_query_gen_column_config\] | Update set compatible. Customizations can be included in update sets and transferred between instances. Overrides values set in the Entity and Dimension tables. Supports entity and dimension descriptions and dimension usage instructions. Doesn't support entity labels or usage instructions. |
| Edit records on the Entity and Dimension tables | Entity \[sn_query_gen_entity\] and Dimension \[sn_query_gen_dimension\] | Simpler. Suitable for testing on a single instance. These customizations cannot be transferred between instances. However, this is the only method for changing entity labels and entity-level usage instructions. Could be overridden by an update to the table from an upgrade. |
[Table 1. Metadata customization methods]

Note:  
Both methods require the sn_query_gen.admin role or higher.

## Writing effective descriptions {#customize-semantic-metadata__customize-semantic-metadata-section-3}

Follow these guidelines when writing semantic descriptions:{#customize-semantic-metadata__customize-semantic-metadata-para-4}

* Keep descriptions to 1--2 sentences focused on how users refer to this data
* Include common synonyms and abbreviations your users would say
* Avoid full paragraphs. Concise descriptions match better than verbose ones

## Writing effective usage instructions {#customize-semantic-metadata__customize-semantic-metadata-section-4}

Follow these guidelines when writing semantic usage instructions:{#customize-semantic-metadata__customize-semantic-metadata-para-6}

* Be specific and structured. Include rules, examples, and edge cases
* Use numbered steps or labeled sections if the logic is complex
* Include example user questions and what the query should look like
* For free-text fields, specify matching strategy (CONTAINS, exact match) and expansion rules
* Keep instructions focused on one entity or field's needs

## Usage instructions vs. Segments {#customize-semantic-metadata__customize-semantic-metadata-section-5}

Usage instructions teach the LLM how to query a field dynamically, allowing the LLM to handle many scenarios based on your rules. Segments hard-code specific filter values. For fields
like free-text location, usage instructions are the correct approach because you cannot predefine every possible location query. Segments are better for fixed business terminology such as "Sev1" = priority 1.{#customize-semantic-metadata__customize-semantic-metadata-para-7}  

## Semantic description {#customize-semantic-metadata__example_sm1_pz5_bjc}

For an Incident entity, instead of using just "Incident table", use a description like "IT incidents, outages, service disruptions, and IT support tickets" to include terminology your
users actually say.{#customize-semantic-metadata__customize-semantic-metadata-para-5}  

## Data conventions in usage instructions {#customize-semantic-metadata__example_ypq_fz5_bjc}

For a State field that stores abbreviations:{#customize-semantic-metadata__customize-semantic-metadata-para-9}

    "Values in this field may be full state names or two-letter abbreviations (for example, 'California' or 'CA'). Always query for both forms. For country names, also include common aliases (for example, 'United Kingdom' OR 'UK')."

## Complex query logic in usage instructions {#customize-semantic-metadata__example_l1h_jz5_bjc}

These usage instructions are for a free-text Approximate Location field with hierarchical expansion and synonym handling:{#customize-semantic-metadata__customize-semantic-metadata-para-10}

Field: Approximate Location - Usage Instruction
:   The Approximate Location field is a non-normalized, free-text string. All queries must use case-insensitive CONTAINS matching and handle hierarchical expansion.

Core Query Logic
:
    1. Identify the geographic entity (Neighborhood, City, State, Country, Region, or Continent).
    2. Expand broader entities into explicit lists of sub-entities before querying.
    3. Use OR logic for all expanded terms and synonyms.
    {#customize-semantic-metadata__ol_nsm_2z5_bjc}

Expansion Rules
:
    * Continents: Expand to a list of all major countries within that continent.
    * Regions: Expand to relevant states or countries (for example, "Atlantic Coast" -\> NC, VA, FL, etc.).
    * States/Provinces: Include both full names and standard abbreviations (for example, "North Carolina" OR "NC").
    * Countries: Include common aliases (for example, "UK" OR "United Kingdom").
    {#customize-semantic-metadata__ul_osm_2z5_bjc}

Implementation Pattern
:
    1. Extract geographic intent.
    2. Classify entity level.
    3. Expand downward (Continent \> Country) or include synonyms (State \> Abbreviation).
    4. Construct a single query string using OR-based CONTAINS filters.

    {#customize-semantic-metadata__ol_psm_2z5_bjc}

    Notice the pattern: the instruction defines rules and examples, and the LLM can handle many related queries dynamically based on the rules you provide. You teach the logic once, and the model applies it to any
    input.

Examples of user questions converted to queries
:
    * User: "Show me things in Japan" → Query: location CONTAINS "Japan"
    * User: "Show me things in Asian countries" → Decomposition: Asia -\> \[Japan, China, Indonesia...\] → Query: location CONTAINS "Japan" OR location CONTAINS "China" OR location CONTAINS "Indonesia"...

    * User: "Show me things in North Carolina" → Query: location CONTAINS "North Carolina" OR location CONTAINS "NC"
    * User: "Show me everything in Europe" → Decomposition: Europe \> \[UK, Spain, France, Germany...\] → Query: location CONTAINS "UK" OR location CONTAINS "United Kingdom" OR location CONTAINS "Spain" OR location CONTAINS "France"...
    {#customize-semantic-metadata__ul_qsm_2z5_bjc}
* **[Customize entity descriptions for the semantic layer](https://www.servicenow.com/docs/uUkf2B1xkCMHbPykEcmWFA)**   
  Create custom entity descriptions in the Semantic Table Configuration table so that customizations can be transferred between instances via update sets.
* **[Customize column descriptions and usage instructions](https://www.servicenow.com/docs/i1~~QehgpkihcmfFwayBZQ)**   
  Create custom column descriptions and usage instructions in the Semantic Column Configuration table so that customizations can be transferred between instances via update sets.

**Related reference**   

* [Roles, tables, and scheduled jobs included with Query Generation](https://www.servicenow.com/docs/aK39momxE_OECDBz6aOoiA "Several types of components are installed with Query Generation, including tables and scheduled jobs.")