Segments in Query Generation

  • Versão de lançamento: Australia
  • Atualizado 12 de mar. de 2026
  • 3 min. de leitura

    • Segments are reusable definitions that provide non-obvious context, to assist the semantic layer or large language model (LLM) to select the correct entity, dimension, and values. Segments are created manually or automatically.

    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. Admins can add new segments, delete existing segments, or edit segment names and descriptions.

    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. It compares them to the user's query to produce a subset of segments. The system uses that subset as the context for the LLM call.

    In the LLM call, the system passes the Name, Description, Entity, and Filters so the LLM can use the segments as building blocks for generating a new query. For example, if the user query is "Unassigned Incidents located in San Diego," and the LLM was given the segment "Unassigned Incidents," the LLM could use the segment's filter as the starting point. The LLM would then attach the location filter on top of the segment.

    Tabela 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
    Segments can be created automatically or manually. Manual segments are described in Create a Query Generation segment manually. The [Query Generation] Sync Segments job creates segments automatically and synchronizes manual segments up to the Segments [sn_query_gen_segment] table. The job runs at installation and then weekly by default. It creates segments based on records in the following tables:
    • Reports [sys_report]
    • Report sources [sys_report_source], which includes saved filters for data visualization data sources
    • Filters built with the condition builder [sys_filter]
    • Indicator sources [pa_cubes]
    • Modules [sys_app_module]
    Importante:
    Segments cannot be created from indicator sources or modules on domain-separated instances.
    To reduce the noise from outdated and irrelevant segments, the job follows certain rules about segments based on reports, report sources, or indicator sources. Segments based on these records are active only if the records fit the following criteria:
    • Reports must meet the following criteria:
      • They must be shared.
      • They must be created by a user with an analytics manager role: admin, dashboard_admin, report_admin, pa_admin, or viz_admin.
      • They must have run recently, which by default is within 180 days.
    • Report sources must be included in a data visualization or must be used in a report that has run recently.
    • Indicator sources must be linked to indicators and the scores of those indicators must have recently changed.

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

    For indicator sources, the time span for "recently changed" depends on the indicator frequency, as follows:
    • 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 to them. You can’t change them individually. To apply a multiplier to these time spans, set it in the system property sn_query_gen.segments.indicator.inactivity_threshold_multiplier. The value must be an integer, meaning you can only lengthen the periods, not shorten them.