Manual segment data model and sync behavior
Manual segments use a two-table data model with automatic synchronization between the configuration table and the runtime table used for search operations.
Data model overview
Manual segments use a two-table architecture that separates configuration from runtime data. This design ensures that the configuration table remains the single source of truth while the runtime table is optimized for search performance.
configuration table:
sn_query_gen_segment_table_configThis is where you define manual segments. Each record represents one segment configuration that administrators create and maintain.
Synced table:
sn_query_gen_segmentYou do not write to this table directly. When a manual segment config is created or updated, a business rule automatically syncs it into this table, which is queried at search time.
Configuration table fields
The sn_query_gen_segment_table_configuration table contains the following fields for defining manual segments:
| Field | Column Name | Max Length | Required | Purpose |
|---|---|---|---|---|
| Table Name | table_name | — | Yes | The table (entity) the segment applies to. Must have an active entity in the semantic layer. |
| Name | name | 255 chars | Yes | User-friendly name that the LLM matches against during semantic search. |
| Description | description | 4,000 chars | No | Optional clarification using commonly-used terms. Helps the LLM understand when to apply the segment. |
| Filter | filter | 4,000 chars | Yes | Encoded query defining the segment's filter conditions. Uses the condition builder (v2). |
| Active | active | — | No | Defaults to true. When false, the segment is deactivated and excluded from search. |
Synced table fields
The sn_query_gen_segment table contains the runtime data used for search operations:
| Field | Source |
|---|---|
| name | Copied from manual segment config |
| description | Copied from manual segment config |
| filter | Copied from manual segment config |
| table | From table_name |
| entity | Resolved reference to sn_query_gen_entity |
| source_table | Always sn_query_gen_segment_table_config |
| source_id | Sys_id of the manual segment config record |
| active | manual_segment.active AND entity.active |
Sync behavior
Manual segments are synced automatically between the configuration and runtime tables. You do not need to trigger synchronization manually.
| Trigger | When | What Happens |
|---|---|---|
| Business rule on config | Insert or update on sn_query_gen_segment_table_config | Syncs the individual record into sn_query_gen_segment (async) |
| Entity insert/update | When an entity is created or updated with active=true | Re-syncs all segments (including manual) for that entity |
| Weekly scheduled job | Saturdays at midnight | Full sync of all 6 segment sources; cleanup of orphaned records |
During sync, a manual segment is eligible if:
- active = true on the config record
- The referenced table has an active entity in
sn_query_gen_entity
If either condition is not met, the synced segment is deactivated (not deleted).
Activation and deactivation
A synced segment's active status is: manual_segment.active AND entity.active.
| Event | Result |
|---|---|
| Manual segment config active → false | Synced segment deactivated |
| Manual segment config active → true | Synced segment reactivated (if entity is also active) |
| Entity active → false | All segments for that entity deactivated |
| Manual segment config deleted | Synced segment deleted |
| Entity deleted | Orphaned segments cleaned up by scheduled job |
Deactivated segments are excluded from search results.
ACL protections
The synced segment table has strict ACLs so that the configuration table remains the single source of truth:
- Create: Blocked (admin_overrides = false) — segments can only be created via sync
- Write to name: Blocked — must be changed on the config record
- Write to description: Blocked — must be changed on the config record
Filter length considerations
While the filter field supports up to 4,000 characters, the system property sn_query_gen.segments.max_filter_length defaults to 2,000. Filters longer than this threshold are truncated when included in the LLM prompt.
Tip: Keep filters concise for best results. Consider splitting complex segments into multiple focused segments instead of creating one segment with many conditions.
Domain separation
Manual segments support domain separation. When creating a segment config record with a specific sys_domain, the synced segment inherits that domain. At search time, segments are filtered by the user's domain context.
If domain separation is not enabled on your instance, this field is inactive and can be ignored.
Parent Topic:Segments in the Query Generation semantic layer
Related topics