# Message Search Rollout (TiDB)

This page is for operators of an AgentTeam deployment backed by TiDB.

AgentTeam message search is available only after the workspace-global TiDB search projection for the target workspace is:

1. backfilled
2. finalized with a TiDB FULLTEXT artifact
3. explicitly promoted to read-ready

Until then, AgentTeam treats message search as unavailable for that workspace. Fresh message writes update `scope_message_search_docs` in the same transaction as the message; the admin commands backfill or repair historical projection gaps and manage the readiness state.

During upgrade, AgentTeam may migrate existing hot search documents into `scope_message_search_docs`, but it does not inherit the pre-scope search `read_ready` state. Search remains unavailable until the workspace-global projection is finalized and promoted with the admin commands below.

## Required Environment

All commands require:

- `AGENTTEAM_DATABASE_DSN`: DSN for the AgentTeam core TiDB database
- `AGENTTEAM_WORKSPACE_MESSAGE_SEARCH_WORKSPACE_ID`: workspace id for the low-level workspace-global readiness row

Optional knobs:

- `AGENTTEAM_DATABASE_CONNECT_TIMEOUT`: connection timeout (default `5s`)
- `AGENTTEAM_MESSAGE_SEARCH_BACKFILL_BATCH_SIZE`: backfill batch size (default `1000`)

## Rollout Flow

### 1) Backfill projection rows

Run:

```bash
agentteam-tidb-admin workspace-message-search-backfill
```

This backfills TiDB projection rows for historical hot scope messages. The command is resumable and safe to rerun.

### 2) Finalize projection readiness

Run:

```bash
agentteam-tidb-admin workspace-message-search-finalize
```

Finalize verifies that the workspace-global projection has no missing rows, creates or verifies the `MULTILINGUAL` TiDB FULLTEXT artifact for `scope_message_search_docs`, and records the finalized state. Search queries use TiDB FULLTEXT; do not promote a deployment that lacks the required TiDB FULLTEXT capability.

Finalize is idempotent. Re-running it after a projection is ready must not downgrade `read_ready`.

Finalize requires:

- `tidb_enable_fulltext_index = ON`
- a registered TiFlash / TiFlash Compute node

### 3) Promote read-ready

Run:

```bash
agentteam-tidb-admin workspace-message-search-promote-ready
```

This sets `read_ready = true` for the workspace-global projection only after migration, backfill, and finalize are complete, the FULLTEXT artifact is visible, and no projection rows are missing. After this, AgentTeam Web can expose message search for that workspace.

## Inspecting Status

For a machine-readable status snapshot, run:

```bash
agentteam-tidb-admin workspace-message-search-status
```

To ensure every workspace in the current database is ready in one pass, run:

```bash
agentteam-tidb-admin workspace-message-search-ensure-ready
```

This command enumerates workspaces in deterministic `created_at ASC, id ASC` order, writes phase logs to stderr, and prints the final machine-readable summary to stdout JSON.

## Common Troubleshooting

- `AGENTTEAM_DATABASE_DSN is required`
  Set `AGENTTEAM_DATABASE_DSN` to the same core TiDB DSN used by the server.

- `AGENTTEAM_WORKSPACE_MESSAGE_SEARCH_WORKSPACE_ID is required`
  Set the workspace id for the workspace-global projection you are operating.

- `scope search migration must be complete before backfill` / `scope search readiness not found`
  The schema or state row is not ready. Run the normal schema verification / migration flow and retry. After an upgrade, migrated documents still require workspace-global backfill/finalize/promote before search is available.

- `scope search backfill must be complete before finalize`
  Run `agentteam-tidb-admin workspace-message-search-backfill` until it reports `status=complete`.

- `scope search projection has missing rows; run scope search backfill`
  Run backfill again. Live message writes maintain the projection for new messages; backfill repairs historical gaps.

- `tidb_enable_fulltext_index is not enabled`
  Enable `tidb_enable_fulltext_index` and retry finalize.

- `no TiFlash node is registered; scope message search fulltext finalize requires TiFlash`
  Add/enable TiFlash in the TiDB cluster and retry finalize.

- AgentTeam Web still does not show search results for the workspace
  Check `workspace-message-search-status` and ensure migration, backfill, and finalize are all complete and `read_ready` is `true` (run `workspace-message-search-promote-ready` if needed).