Segments in the Query Generation semantic layer

  • Release version: Zurich
  • Updated January 27, 2026
  • 5 minutes to read

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

    When a user asks a question, the Query Generation engine searches for matching segments and includes their filters in the LLM prompt so the model can reuse them to construct accurate queries.

    There are two types of segments:

    Automated Segments
    System-generated from reports, dashboards, filters, modules, and indicator sources. Names are often technical—for example, "Incidents.Open".
    Manual Segments
    Created by admins via the Manual Segment Config table. Names are user-friendly— for example, "Critical Open Incidents". Manual segments use a two-table data model with automatic synchronization and can be shipped with applications via plugins.
    Table 1. Comparison: Manual vs automated segments
    Manual Segments Automated Segments
    Created by Admin, shipped via update set System-generated from reports, dashboards, filters, modules
    Name quality User-friendly, tuned for search Often technical—for example, "Incidents.Open"
    Search priority 5% boost over automated (adjustable insn_query_gen.segments.manual_segment_scale_factor) Standard scoring
    LLM treatment Retain all filters unless irrelevant Critique each filter individually
    Prompt label user_defined_segment automated_segment
    Lifecycle Fully controlled by admin Tied to source record activity/usage
    Shipped with app Yes (update set) No (generated at runtime)

    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 2. 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: Scoring Rank the set of relevant segments based on their semantic similarity scores The subset of relevant segments, now ranked and sorted
    4: Context Provide segment metadata to LLM Structured segment data
    5: Generate Combine segment logic with new conditions Complete executable query

    How manual segments work

    Manual segments serve two roles at query time:

    Entity discovery
    On first-time queries with no previous context, segment matches can add or boost entities in the entity list. A match against a manual segment name helps identify the intended entity by adding or boosting it in the candidate list. If a user asks "Show me critical open incidents" and a manual segment named "Critical Open Incidents" exists on the Incident [incident] table, the incident entity gets boosted in the results.
    Filter provision
    Matching segments are formatted into the LLM prompt context. The LLM sees: 
    **Related Segments**:
- **Critical Open Incidents** (user_defined_segment)
  - description : High priority incidents that are open and unresolved
  - entity : incident
  - filter : { conditions : [{"field":"incident.priority","operator":"=","value":"1"}, ...] }
    The LLM then decides whether to reuse the segment's filters fully or partially when constructing the query. Manual segments are labeled user_defined_segment in the prompt, which tells the LLM to retain all filters unless completely irrelevant.

    Manual segment scoring boost

    Manual segments receive a priority boost. When the engine searches for relevant segments, it scores each result by semantic similarity—how closely the segment's name and description match the user's question. By default, manual segments receive a 5% boost applied on top of their raw similarity score.

    The boost factor is configurable via the system property sn_query_gen.segments.manual_segment_scale_factor. Increasing it, for example to 1.10, elevates manual segments more strongly. Setting it to 1.0 removes the boost entirely.

    In practice, automated segments often have names that partially match user utterances. For example, a report called "Open Incidents" may score similarly to a manual segment called "Critical Open Incidents". The boost ensures that your handmade, domain-tuned segments surface ahead of system-generated ones when both are close matches.

    How segment scoring works

    1. AI Search returns a raw semantic similarity score (0.0–1.0) for each candidate segment.
    2. Segments below the match threshold (default 0.70) are discarded.
    3. Manual segment scores are multiplied by the scale factor (default 1.05).
    4. Results are sorted by boosted score and capped at the result limit.

    Automatic segment sources

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

    Table 3. 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.