Rebuild an Offline AI Search Index

Direct answer

Rebuild a local search index as a derived-data migration tied to a specific source snapshot and transformation identity. A database row count alone does not prove that every source record has a corresponding indexed record, that the index uses the current parser or chunker, or that search results point back to the right source. Define an index manifest before rebuilding: source-set revision, parser or extraction version, normalization policy, chunking rule, embedding model and revision if embeddings are used, vector or term-index implementation, schema version, and build completion state. A change to any input that affects indexed text or vectors should produce a candidate index identity that can be tested separately from the active one. Keep this guide on index lifecycle, not on how to search PDFs or answer questions. A literal term index and an embedding index have different query behavior and consistency checks; do not pretend a rebuild makes them interchangeable. RAG-01 describes stages from ingestion through generation, which helps isolate where an index sits. PRIVACY-01 is also a boundary: a local retrieval path does not prove the app makes no other network requests. This article does not claim Cove currently ships RAG, embeddings, or an index rebuild feature. First inventory the authoritative source and its derivatives. Assign a stable source ID and revision to each local document or record. Record deletion, update, and parser failure events in a queue or change table only if the implementation supports it. A rebuild should read from a consistent source snapshot or use a versioned change cursor; otherwise updates arriving mid-run can be omitted or indexed twice. Record the policy for records that cannot be parsed, empty documents, deleted sources, and revoked file access. Do not convert an inaccessible source into an empty successful record, because that hides the difference between “no searchable text” and “could not read.” Choose a rebuild strategy that fits the installed index. An in-place refresh may be appropriate for a small index with a transaction boundary, while a separate candidate is easier to inspect when the old index must remain usable during work. If multiple schema versions share a database, use a documented migration path and test it against exported schemas. Room supports FTS-backed entities; SQLite FTS5 documents external-content synchronization and a rebuild command, but its commands and semantics do not automatically apply to Room FTS4, vector stores, or another library. Check the exact engine and version before using vendor-specific repair SQL. For an external-content table, the base table and index must remain aligned; rebuilding only the index cannot repair a stale or wrong source mapping. Build into an isolated candidate where practical. Track expected source count, accepted count, skipped count and categorized failures; chunk or vector counts; source revision; and a completion marker. Never expose an incomplete candidate as active. After generation, run integrity checks supported by the chosen engine, then compare representative source IDs, revisions, page or record locations, and normalized text against the authority. Use known queries to detect missing terms, stale terms after deletion, duplicate chunks, wrong-language filters, and mismatched vector revision. A plausible result is not proof that all sources were indexed. Switching must have a clear rollback boundary. Record the active index identity before the build. Activate the candidate only after integrity, coverage, provenance, and query checks pass. If the candidate fails, keep the old index or mark search unavailable with an explicit recovery state; do not merge mixed-version entries to improve apparent coverage. If a parser or embedding model changes, either rebuild all affected records or maintain explicit per-record versioning and a query policy that can safely handle it. When the source changes during the build, replay a bounded change set or restart against a fresh snapshot. Deletion and privacy are part of index correctness. When a source is removed, ensure linked chunks, vectors, snippets, caches, queued work, and index rows cannot reappear through a delayed worker or later rebuild. If the index contains a contentless or external-content representation, determine which component retains readable text and which operation actually deletes it. Do not claim forensic erasure based on removing search hits. Test that a unique synthetic canary is absent from queries and app-controlled diagnostics after deletion, and separately describe backups or user exports if they are in scope. The final record should state exact app build, source revision, transformation versions, engine, schema, manifest counts, rejected inputs, integrity result, query fixtures, active pointer before and after, and rollback outcome. Report only what was observed. A successful rebuild validates a particular index and source snapshot; it does not establish retrieval relevance, answer quality, language coverage, or offline behavior for every feature.

An updated parser leaves some local documents missing from search

An offline assistant has local source records and a term index. After a parser upgrade, some records have new normalized text while old index entries remain. A user also deleted one source while a background indexing task was queued.

Decision

Create a candidate index tied to the new parser and source snapshot, reconcile the deletion queue, and keep the prior active index until candidate checks pass.

Expected outcome

Search switches to one complete revision or reports recovery in progress; neither mixed parser versions nor the deleted source reappear.

Evidence to collect

The claim becomes reviewable only when the following evidence is attached to the same artifact and test run:

• Index manifest
• Rebuild fixtures
• Query and deletion verification

Task quality needs a versioned corpus and acceptance rules. Fluent sample output is not an accuracy result.

Implementation workflow

Record and compare the index manifest, rebuild fixtures, and query and deletion verification results, treating them as a connected set of artifacts. The note recommends capturing each item in a comparable form so reviewers can evaluate consistency across the rebuild evidence without inferring additional relationships.

1. Freeze source and transformation identity. Record authoritative source IDs and revisions plus parser, normalization, chunker, embedding model if used, index engine, schema, and build identifier. Define how the source snapshot stays consistent while work runs.
2. Classify failures before indexing. Separate unreadable or revoked sources, empty extracted text, unsupported formats, deletion events, and transform errors. Keep each outcome visible in the manifest instead of counting all as successful empty records.
3. Build a versioned candidate. Write into an isolated index or transaction strategy supported by the chosen engine. Track expected, indexed, skipped, and failed sources, and do not mark a partial candidate active.
4. Check integrity, coverage, and provenance. Use only repair commands documented for the exact engine/version. Compare source IDs, revisions, locations, term or vector fixtures, deleted canaries, and representative queries against the authoritative records.
5. Activate or roll back explicitly. Switch the active pointer after all gates pass. On failure, retain the prior compatible index or expose an honest unavailable state; replay source changes or restart rather than merging incompatible revisions.
6. Test deletion and privacy paths. Remove a synthetic source while indexing is queued, let pending work finish, rebuild if supported, and confirm its chunks, vectors, snippets, logs, and query results do not return.

Acceptance criteria

• Every index build is bound to a source snapshot and explicit transform, engine, and schema versions.
• A partial, failed, or mixed-version candidate cannot be reported as active or complete.
• After source deletion, queued work and later rebuilds do not restore app-owned derivatives or make a unique canary searchable.

Decision table

Failure patterns to prevent

• Mixing embedding revisions
• Serving partial rebuilds as complete

When rebuilding, avoid mixing embedding revisions within one index and do not serve partial rebuilds as complete. The note restricts release language to what is captured in the recorded artifacts and bounds discussion to the RAG-01 and PRIVACY-01 fact cards.

Minimum reproducibility record

Release checklist

• ☐ The primary query is answered without an unsupported number.
• ☐ Every artifact and runtime is pinned.
• ☐ The representative task and failure policy are explicit.
• ☐ Lifecycle, cancellation, cleanup, and fallback are tested.
• ☐ User-content and network boundaries are documented.
• ☐ Result wording applies only to the recorded configuration.
• ☐ The page links to raw method or evidence when results are added.

Sources and related evidence

• Android Developers — define data using Room entities and FTS
• SQLite — FTS5 external content, integrity, and rebuild commands
• Android Developers — migrate Room database versions

Chinese deployment and troubleshooting content is organized in the .奇连 AI 端侧专题.

Frequently asked questions