Tuning the semantic layer

The semantic layer maps natural language questions to ServiceNow AI Platform® tables and fields. Tune the semantic layer to improve AI Data Explorer accuracy for your organization's terminology and data structure.

The semantic layer identifies the best matching entities (tables), dimensions (fields), and segments (filters) when users ask questions in AI AI Data Explorer. Tuning improves these matches so users consistently get the right table, field, and filter.

How the semantic layer works

When a user asks a question, the system identifies the best matching components and passes that context into query generation. The semantic layer has three building blocks:

• Entities

  Represent tables such as Incident [incident], Change Request [change_request], or CMDB Class Information [cmdb_class_info].

• Dimensions

  Represent fields on those tables such as Priority, Assigned to, or State. Dimensions can follow reference fields across tables. For example, caller_id.department traverses from an incident's caller to their department.

• Segments

  Pre-defined filter conditions such as "Open incidents" = active=true.

When to tune the semantic layer

Before you tune, verify that the issue is repeatable. The LLM occasionally makes incorrect decisions. Try the same question or a similar one multiple times first. Only tune if the problem is consistent.

Tune the semantic layer when:

• The system selects the wrong table or cannot find one. For example, the system could be processing queries on reference fields, and the referenced tables are missing from the semantic layer.
• A field is missing or the wrong field is selected
• Your organization uses different terminology than the auto-generated labels
• The right table or field is selected, but the query is constructed incorrectly
• Special terminology of your organization is not translated accurately to filter conditions

Validation and iteration process

1. Capture the utterance and expected result.
2. Classify the failure as entity, dimension, segment, or ACL.
3. If results are wrong for only some users, verify read ACL access to the intended table and fields before retuning.
4. Apply one targeted tuning change.
5. Retest the same utterance.
6. Check Query Generation > Logs and confirm the improved match path.

7. Repeat only if still incorrect.

8. Query Generation Health page
   The health page shows the state of the Now LLM and AI Search, along with the states of Query Generation system properties, enabled products, and dependency plugins.

9. Customizing semantic metadata
   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.
10. Database views for cross-table data
    Database views combine fields from multiple tables into a single queryable entity. Add views to the semantic layer to answer cross-table questions in one query instead of requiring separate questions.
11. Segments in the Query Generation semantic layer
    Segments are predefined filter conditions that map business terminology to specific query filters, helping the semantic layer translate natural language questions into accurate database queries.

Parent Topic:Configuring Query Generation