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

 Release :

    - brazil

ft:locale :

    - en-US

ft:publication_title :

    - Brazil Platform Analytics

ft:clusterId :

    - par

bundleId :

    - par

workflow :

    - Platform


---

# Tuning the semantic layer

# Tuning the semantic layer {#ariaid-title1}

Release version: Brazil  
Updated March 25, 2026  
![](https://www.servicenow.com/docs/portal-asset/ico-clock) 1 minute to read  
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](https://www.servicenow.com/docs/IdnWqSqSuznwHmUlqWEvYg#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).") identifies the best matching [entities](https://www.servicenow.com/docs/IdnWqSqSuznwHmUlqWEvYg#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), [dimensions](https://www.servicenow.com/docs/IdnWqSqSuznwHmUlqWEvYg#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), and [segments](https://www.servicenow.com/docs/IdnWqSqSuznwHmUlqWEvYg#gloss-segment "A predefined filter condition in the Query Generation semantic layer that maps business terminology to specific query filters. Segments help the system translate natural language questions into accurate database queries. Segments can be automated or manual.") (filters) when users ask questions in AI AI Data Explorer. Tuning improves these matches so users consistently get the right table, field, and filter.{#semantic-layer-tuning-overview__semantic-layer-tuning-overview-para-1}

## 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:{#semantic-layer-tuning-overview__semantic-layer-tuning-overview-para-2}

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](https://www.servicenow.com/docs/IdnWqSqSuznwHmUlqWEvYg#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.") occasionally makes incorrect decisions. Try the same question or a similar one multiple times first. Only tune if the problem is consistent.{#semantic-layer-tuning-overview__semantic-layer-tuning-overview-para-3}

Tune the semantic layer when:{#semantic-layer-tuning-overview__semantic-layer-tuning-overview-para-4}

* 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](https://www.servicenow.com/docs/IdnWqSqSuznwHmUlqWEvYg#gloss-utterance "A natural language question or input submitted by a user to an AI system. Query Generation processes utterances to identify the correct entities, dimensions, and segments needed to construct an executable query.") 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 GenerationLogs and confirm the improved match path.
7. Repeat only if still incorrect.
* **[Query Generation Health page](https://www.servicenow.com/docs/RwE7aFrVCnbmqSYs~MEJlA)**   
  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.
* **[Customizing semantic metadata](https://www.servicenow.com/docs/ljK5GP6kqKFjnMx6ZWDiig)**   
  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.
* **[Database views for cross-table data](https://www.servicenow.com/docs/HI0niNp6IQwYLNLzLokYeA)**   
  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.
* **[Segments in the Query Generation semantic layer](https://www.servicenow.com/docs/NOC1a9gHlH7q9p__xcmuLQ)**   
  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.

*[\>]: and then