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.

Segments provide non-obvious context to assist the semantic layer in selecting the correct entity, dimension, and values. For example, in the utterance "How many open emergency change requests are there?", a segment identifies that "open" means "active=true" and "emergency" is a Type, not a Priority.

How segments work

The system uses AI search to find segments that are semantically similar to the user's query. AI search indexes the Name, Description, Entity, and Filter fields in the Segments table, comparing them to the user's query to produce a subset of relevant segments.

In the LLM call, the system passes the Name, Description, Entity, and Filters. The LLM uses the segments as building blocks for generating a new query. For example, if a user asks "Unassigned Incidents located in San Diego" and the segment "Unassigned Incidents" is passed to the LLM, the LLM uses the segment's filter as the starting point and attaches the location filter "San Diego" on top of the segment.

Table 1. Segment process summary

Step	Purpose	Output
1: Input	Capture user's natural language query	Raw query text
2: Search	Find semantically similar prebuilt segments	Subset of relevant segments
3: Context	Provide segment metadata to LLM	Structured segment data
4: Generate	Combine segment logic with new conditions	Complete executable query

Automatic segment sources

The system auto-generates segments from existing ServiceNow data sources on a schedule. The Query Generation Sync Segments job creates segments automatically, running at installation and then weekly by default.

Table 2. Automatic segment sources

Source	What it pulls
Saved Reports (sys_report)	Report filters from recently viewed reports
Report Sources (sys_report_source)	Analytics data source filters
PA Indicators (pa_cubes)	Performance Analytics indicator conditions
Saved Filters (sys_filter)	Global saved filters only (excludes user-specific and group-specific filters)
App Modules (sys_app_module)	Module-level list view filters

Automated segment rules

To reduce noise from outdated and irrelevant segments, the job follows specific rules. Segments based on reports, report sources, or indicator sources are active only if the records meet certain criteria:

• Reports must be shared, created by a user with an analytics manager role (admin, dashboard_admin, report_admin, pa_admin, or viz_admin), and have run recently (within 180 days by default).
• Report sources must be included in a data visualization or used in a report that has run recently.
• Indicator sources must be linked to indicators with scores that have recently changed.

Important:

Segments cannot be created from indicator sources or modules on domain-separated instances.

For reports, "run recently" is defined by the sn_query_gen.segments.reports.last_viewed_threshold_days system property. The default value is 180 days.

For indicator sources, the time span for "recently changed" depends on the indicator frequency:

• Daily: last 7 days
• Weekly: last 30 days
• Bi-weekly: last 30 days
• Monthly: last 90 days
• Four weeks: last 90 days
• Bi-monthly: last 90 days
• Quarterly: last 180 days
• Fiscal quarterly: last 180 days
• Six months: last 12 months
• Yearly: last 24 months
• Fiscal yearly: last 24 months

You can change the time spans for indicator sources by applying a multiplier using the sn_query_gen.segments.indicator.inactivity_threshold_multiplier system property. The value must be an integer, meaning you can only lengthen the periods, not shorten them.

Disabling segment sources

You can disable segment creation altogether, or for individual source types. You might disable segment generation to troubleshoot, or if segments from a source are "noisy." Each source type has a corresponding sn_query_gen.segments.disable.* system property. Disable segments for that source by setting the corresponding system property to true. All existing segments created from sources of that type are excluded from AI Data Explorer search results. No new segments of that type are created. During the next Sync Segments job, all segments of that type are deactivated. For more information, see Query Generation properties.

Related reference

• Roles, tables, and scheduled jobs included with Query Generation
• Query Generation properties

Create a manual segment

Manual segments are admin-created filter conditions that map business terminology to specific query filters.

Before you begin

Role required: sn_query_gen.admin or higher

About this task

Create manual segments in the following circumstances:

• Your organization has standard terminology that maps to specific filters (for example, "Sev1", "VIP", "overdue")
• Users repeatedly ask the same filtered question and the system does not automatically pick up the right filter
• You want to encode business logic that cannot be inferred from field values alone (for example, "at-risk accounts" = combination of multiple conditions)
• The special terminology of your organization is not translated accurately to filter conditions

Tip:

The name and description are what AI search matches against. Use natural phrasing your users would say, keep one segment per concept, and test by asking the question and checking if the segment appears in the logs.

Procedure

1. Navigate to Query Generation > Administration > Manual Segment Config.
2. Press New.
3. In the Manual Segment Config form, fill in the following information.

   Field	Description
   Name	A clear and specific phrase using words users are likely to use when referring to this segment, such as "Overdue incidents" or "Release blocker." Avoid abbreviations or special characters unless they are commonly used.
   Description	An optional short phrase that expands on the name using similar, commonly used terms. Use a description to clarify the segment when the name alone may not be sufficient. Avoid irrelevant notes or long explanations. If there are no abbreviations or special characters in the name, don't put any in the description, either.
   Entity	The table on which the segment is based. The system looks for the entity table first, then the segment within that table. The LLM can use a segment to select an entity if the segment fits the user query. The LLM can also select the entity separately and then select a segment based on the entity. The prompt instructions give it this freedom.
   Application	Read-only field for the application scope of the Entity table.
   Active	Whether the system uses the segment or not. Manual segments are active by default.
   Filter	Conditions to apply for identifying records from the Entity table that may contain the segment.

General guidelines

Follow these suggestions to help you use segments in the semantic layer effectively.

• Test segments by asking the question and verifying the segment appears in Query Generation > Logs.
• Disable noisy auto-generated segments rather than trying to overfit with multiple manual ones.
• Use natural phrasing that matches how your users actually speak.
• Keep one segment per concept to avoid confusion.
• Monitor segment usage through the logs to identify which segments are most valuable.