Customizing semantic metadata

  • Release version: Zurich
  • Updated April 17, 2026
  • 4 minutes to read
    • Summarize
    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

    Customizing semantic metadata in ServiceNow's Query Generation allows you to tailor how the system interprets natural language queries by refining descriptions, labels, and usage instructions for entities (tables) and dimensions (fields). This customization improves accuracy and relevance by aligning the AI’s understanding with your organization’s specific terminology and data context.

    Show full answer Show less

    Semantic metadata consists of three key fields:

    • Semantic Label: A short alias used as a search keyword to match user questions with the correct table or field.
    • Semantic Description: A natural-language business context description helping distinguish similar tables or fields.
    • Semantic Usage Instructions: Guidance injected into the AI model explaining how to query the data, including operators, abbreviation handling, and hierarchical expansions.

    When to Customize

    • If the system selects incorrect or missing tables or fields — update labels and descriptions.
    • If your business uses terminology different from auto-generated labels — update labels.
    • If queries are constructed incorrectly despite correct table/field selection — update usage instructions.
    • Focus only on fields involved in consistently failing queries; avoid reviewing all dimensions indiscriminately.

    Methods for Customization

    There are two methods to customize metadata, each suited for different use cases:

    • Semantic Table and Column Configuration Tables: Use snquerygentableconfig and snquerygencolumnconfig to edit records. This is the preferred, update set-compatible method allowing transfer of changes across instances. It supports entity and dimension descriptions and dimension usage instructions but not entity labels or usage instructions.
    • Entity and Dimension Tables: Use snquerygenentity and snquerygendimension for simpler, instance-specific edits. This method allows changing entity labels and usage instructions but is not transferable between instances and may be overwritten by upgrades.

    Both approaches require the snquerygen.admin role or higher.

    Best Practices for Writing Metadata

    • Descriptions: Write concise (1–2 sentences) descriptions focused on how users reference the data, including common synonyms and abbreviations. Avoid lengthy paragraphs.
    • Usage Instructions: Be specific and structured. Use clear rules, examples, and edge cases. Include matching strategies (e.g., CONTAINS, exact match) and expansion logic where applicable. Focus each instruction on a single entity or field.

    Usage Instructions vs. Segments

    Usage instructions dynamically guide the AI on how to query fields, ideal for free-text or variable data (e.g., locations). Segments are static filters suited for fixed business terms (e.g., priority levels). For fields with broad possible values like locations, usage instructions provide flexibility and accuracy.

    Practical Examples and Patterns

    For example, enhance an Incident entity description from “Incident table” to “IT incidents, outages, service disruptions, and IT support tickets” to reflect real user terminology.

    For fields like State or Country that use abbreviations and aliases, usage instructions should specify querying both full names and abbreviations (e.g., “California” and “CA”) and include known synonyms (e.g., “UK” and “United Kingdom”).

    Complex query logic can be encoded in usage instructions to dynamically expand hierarchical geographic terms (e.g., “Europe” expands to a list of countries), combining OR-based CONTAINS filters to capture all relevant data.

    This approach teaches the AI the querying logic once, enabling it to handle a wide range of user questions accurately and consistently.

    Implementing Customizations

    • Create or modify entity descriptions in the Semantic Table Configuration table to enable update set transfers between instances.
    • Create or modify column descriptions and usage instructions in the Semantic Column Configuration table for similar update set compatibility.

    Summary for ServiceNow Customers

    By customizing semantic metadata, you can significantly improve Query Generation’s natural language understanding and query accuracy tailored to your organization's terminology and data structures. Use update set-compatible tables for scalable customizations across environments, and write clear, concise descriptions and structured usage instructions to guide the AI effectively. Focus your efforts on problematic fields identified by failing queries rather than attempting broad changes. This ensures efficient improvements, better user experience, and more relevant query results.

    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 (tables) and dimensions (fields) in the semantic layer have three metadata fields that Query Generation uses when processing a question:

    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 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

    Metadata is auto-generated and works well in its baseline state. Customize it only when you observe consistent, repeatable problems:

    • 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

    Two methods are available. Editing the configuration tables is considered the default approach.

    Table 1. Metadata customization methods
    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.
    Note:
    Both methods require the sn_query_gen.admin role or higher.

    Writing effective descriptions

    Follow these guidelines when writing semantic descriptions:

    • 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

    Follow these guidelines when writing semantic usage instructions:

    • 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

    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.

    Semantic description

    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.

    Data conventions in usage instructions

    For a State field that stores abbreviations:

    "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

    These usage instructions are for a free-text Approximate Location field with hierarchical expansion and synonym handling:

    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.
    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").
    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.

    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"...