{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":35597,"path":"now-intelligence/manual-segment-data-model-sync.md","title":"Manual segment data model and sync behavior","bundle":null,"doc_type":null,"release":"australia","body":"\n# Manual segment data model and sync behavior\n\nManual segments use a two-table data model with automatic synchronization between the configuration table and the runtime table used for search operations.\n\n## Data model overview\n\nManual 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.\n\n-   **configuration table: `sn_query_gen_segment_table_config`**\n\n    This is where you define manual segments. Each record represents one segment configuration that administrators create and maintain.\n\n-   **Synced table: `sn_query_gen_segment`**\n\n    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.\n\n\n## Configuration table fields\n\nThe `sn_query_gen_segment_table_`configuration table contains the following fields for defining manual segments:\n\n|Field|Column Name|Max Length|Required|Purpose|\n|-----|-----------|----------|--------|-------|\n|Table Name|**table\\_name**|—|Yes|The table \\(entity\\) the segment applies to. Must have an active entity in the semantic layer.|\n|Name|**name**|255 chars|Yes|User-friendly name that the LLM matches against during semantic search.|\n|Description|**description**|4,000 chars|No|Optional clarification using commonly-used terms. Helps the LLM understand when to apply the segment.|\n|Filter|**filter**|4,000 chars|Yes|Encoded query defining the segment's filter conditions. Uses the condition builder \\(v2\\).|\n|Active|**active**|—|No|Defaults to **true**. When **false**, the segment is deactivated and excluded from search.|\n\n## Synced table fields\n\nThe `sn_query_gen_segment` table contains the runtime data used for search operations:\n\n|Field|Source|\n|-----|------|\n|**name**|Copied from manual segment config|\n|**description**|Copied from manual segment config|\n|**filter**|Copied from manual segment config|\n|**table**|From **table\\_name**|\n|**entity**|Resolved reference to `sn_query_gen_entity`|\n|**source\\_table**|Always `sn_query_gen_segment_table_config`|\n|**source\\_id**|Sys\\_id of the manual segment config record|\n|**active**|`manual_segment.active AND entity.active`|\n\n## Sync behavior\n\nManual segments are synced automatically between the configuration and runtime tables. You do not need to trigger synchronization manually.\n\n|Trigger|When|What Happens|\n|-------|----|------------|\n|Business rule on config|Insert or update on `sn_query_gen_segment_table_config`|Syncs the individual record into `sn_query_gen_segment` \\(async\\)|\n|Entity insert/update|When an entity is created or updated with **active=true**|Re-syncs all segments \\(including manual\\) for that entity|\n|Weekly scheduled job|Saturdays at midnight|Full sync of all 6 segment sources; cleanup of orphaned records|\n\nDuring sync, a manual segment is eligible if:\n\n1.  **active = true** on the config record\n2.  The referenced table has an active entity in `sn_query_gen_entity`\n\nIf either condition is not met, the synced segment is deactivated \\(not deleted\\).\n\n## Activation and deactivation\n\nA synced segment's active status is: `manual_segment.active AND entity.active`.\n\n|Event|Result|\n|-----|------|\n|Manual segment config **active** → **false**|Synced segment deactivated|\n|Manual segment config **active** → **true**|Synced segment reactivated \\(if entity is also active\\)|\n|Entity **active** → **false**|All segments for that entity deactivated|\n|Manual segment config deleted|Synced segment deleted|\n|Entity deleted|Orphaned segments cleaned up by scheduled job|\n\nDeactivated segments are excluded from search results.\n\n## ACL protections\n\nThe synced segment table has strict ACLs so that the configuration table remains the single source of truth:\n\n-   **Create:** Blocked \\(**admin\\_overrides = false**\\) — segments can only be created via sync\n-   **Write to __name__:** Blocked — must be changed on the config record\n-   **Write to __description__:** Blocked — must be changed on the config record\n\n## Filter length considerations\n\nWhile 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.\n\n**Tip:** Keep filters concise for best results. Consider splitting complex segments into multiple focused segments instead of creating one segment with many conditions.\n\n## Domain separation\n\nManual 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.\n\nIf domain separation is not enabled on your instance, this field is inactive and can be ignored.\n\n**Parent Topic:**[Segments in the Query Generation semantic layer](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/now-intelligence/querygen-segments.md)\n\n**Related topics**  \n\n\n[Create a manual segment](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/now-intelligence/querygen-create-segment-manually.md)\n\n[Guidelines for segments](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/now-intelligence/general-guidelines-segments.md)\n\n[Query Generation properties](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/now-intelligence/querygen-properties.md)\n\n"}}