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_config

  This is where you define manual segments. Each record represents one segment configuration that administrators create and maintain.

• Synced table: sn_query_gen_segment

  You 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:

1. active = true on the config record

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

Create a manual segment

Guidelines for segments

Query Generation properties