Semantic usage instructions

  • Release version: Yokohama
  • Updated March 25, 2026
  • 3 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 Semantic usage instructions

    Semantic usage instructions define how the system queries data by specifying matching strategies, expansion logic, and data conventions. They are applied when the correct table or field is selected but queries are constructed incorrectly, enabling more accurate and context-aware data retrieval. These instructions are injected into the LLM prompt at the field level, acting as custom prompts that teach the system how to interpret and query specific fields effectively.

    Show full answer Show less

    When and Where to Edit

    • Edit semantic usage instructions when the query logic is incorrect despite correct table or field selection, or when fields contain non-standard data such as free-text, abbreviations, or hierarchical values.
    • For tables, semantic usage instructions are stored in the Entity [snquerygenentity] table.
    • For columns/fields, they are in the Dimension [snquerygendimension] table.
    • Editing requires the snquerygen.admin role or higher.

    Writing Effective Usage Instructions

    • Be specific and structured, incorporating rules, examples, and edge cases.
    • Use numbered steps or labeled sections for complex logic.
    • Include example user questions and the corresponding query format.
    • For free-text fields, define matching strategies (e.g., CONTAINS, exact match) and expansion rules.
    • Focus instructions on the needs of a single entity or field.

    Usage Instructions vs. Segments

    Usage instructions dynamically teach the LLM how to query fields based on defined logic, handling diverse scenarios. In contrast, segments hard-code specific filter values. Usage instructions are ideal for fields like free-text locations where all possible values cannot be predefined, while segments suit fixed business terminology such as priority levels.

    Practical Examples

    • Data conventions: For a State field, query both full names and two-letter abbreviations; for countries, include common aliases.
    • Complex query logic: For a free-text Approximate Location field, use case-insensitive CONTAINS matching with hierarchical expansion (e.g., continents expand to countries, states include abbreviations).
    • Define core query logic, expansion rules, and implementation patterns so the LLM can dynamically construct appropriate queries from user input.

    Example User Queries and Corresponding Logic

    • User asks for data in "Japan" → Query: location CONTAINS "Japan"
    • User asks for data in "Asian countries" → Decompose Asia into countries like Japan, China, etc., then query with OR logic
    • User asks for "North Carolina" → Query includes both "North Carolina" and "NC"
    • User asks for "Europe" → Expand to countries like UK, Spain, France with aliases and combine queries with OR

    Key Benefits for ServiceNow Customers

    By defining semantic usage instructions, you empower the ServiceNow Query Generation system to interpret complex and varied user inputs accurately, improving the quality and relevance of query results. This approach reduces manual query adjustments, handles non-standard data gracefully, and supports flexible, dynamic querying for fields with diverse or hierarchical values.

    Semantic usage instructions teach the system how to query data by defining matching strategies, expansion logic, and data conventions. Use these instructions when the right table or field is selected but the query is constructed incorrectly.

    The Semantic Usage Instructions field is injected directly into the LLM prompt when a table or field is selected. This field functions as a custom prompt at the field level, teaching the system how to query the data.

    When to edit semantic usage instructions

    Edit semantic usage instructions when:

    • The right table or field is selected, but the query is constructed incorrectly.
    • A field has non-standard data that needs special handling, such as free-text, abbreviations, or hierarchical values.

    Where to edit semantic usage instructions

    Semantic usage instructions for tables are in the Entity [sn_query_gen_entity] table. Semantic usage instructions for columns/fields are in the Dimension [sn_query_gen_dimension] table. To edit these tables, you must have the sn_query_gen.admin role or higher.

    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.

    Examples

    The following examples show different types of usage instructions:

    Data conventions

    For a State field that stores abbreviations:

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

    Complex query logic

    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 (e.g. "Atlantic Coast" -> NC, VA, FL, etc.).
    • States/Provinces: Include both full names and standard abbreviations (e.g. "North Carolina" OR "NC").
    • Countries: Include common aliases (e.g. "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"...