Indexing data

The vocabulary service

Most of Copilot's "understand a name" ability is powered by the Vocab service. It keeps a compact, searchable index of your store's entities — agents and groups, activities, verbs, activity types, profiles, and document/MIME types — mapping their human labels and names to their identifiers. When Copilot resolves "completed" to a verb IRI, or "Sébastien" to an actor identifier, it is querying this index. Keeping resolution in one dedicated service means it is fast, store-scoped, and consistent whether TRAX runs as a monolith or as distributed services.

This index is maintained automatically: as statements are recorded, the vocabulary is kept up to date in the background. In normal operation you don't have to do anything.

How the data is layered (why order matters)

The searchable indexes are not built directly from the statements — they sit on top of two intermediate tables that are themselves derived from the statements at ingestion:

statements ──► agents      ──► agent IDs registry
           └─► activities  ──► activity IDs registry + activity types
           └────────────────► verbs
documents ──────────────────► document IDs

• The agents and activities tables (the "definitions") are projected from the statements.
• The agent and activity IDs registries and the activity types are built from those tables.
• Verbs come straight from the statements.
• Document IDs come from the state/profile documents.

So an index can only be as complete as the table beneath it. If a store was recorded with the agents/activities projections turned off, those tables are empty and the indexes built on them are empty too — you must rebuild the definitions first.

The Indexing task

Under Tasks → Indexing (requires the manager role), the + Job button offers five operations. For each, pick the store (or all stores), and for the multi-selects choose which indexes to rebuild. Each rebuild clears and repopulates its target from the source; there is a brief window where autocomplete/resolution for that index is degraded while it runs.

Operation	Rebuilds	Source	When
Rebuild the activity definitions	activities table	statements	First build only, if activities were never projected. ⚠ Long-running.
Rebuild the agent definitions	agents table	statements	First build only. ⛔ Destructive (see below) · ⚠ Long-running.
Rebuild the activity IDs registry	activity IDs (incl. profiles + statement categories)	activities table	After the activity definitions if those may be stale.
Rebuild the agent IDs registry	agent IDs	agents table	After the agent definitions if those may be stale.
Rebuild the vocabulary	verbs, activity types, document IDs	statements / activities / documents	Anytime — but activity types read the activities table, so rebuild those first if stale.

Typical case. If your stores were recorded normally, the agents/activities tables are already populated — you only ever need the last three (the registries and the vocabulary). The two definitions rebuilds are a first-build recovery for stores that were ingested with those projections disabled, not a routine maintenance step.

Order for a full first build: activity/agent definitions → then the corresponding registries; the vocabulary can run at any point. The operations are split precisely so you can run them in that order.

⛔ The agent definitions rebuild is destructive. It clears the agents table first, so manual person groupings and pseudonymization state are lost (neither can be reconstructed from the statements). This is acceptable for a genuine first build — a store that never projected agents has no such links to lose — but do not use it as a repair tool on a store that has them.