> For the complete documentation index, see [llms.txt](https://docs.contextual.io/documentation-and-resources/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.contextual.io/documentation-and-resources/components-and-data/ai-search/keep-search-up-to-date.md).

# Keep Search Up to Date

Indexing is asynchronous. Saving a record or profile does not mean every affected search result changes immediately. Check processing status and query known records when freshness matters.

## Read Index Status

| Status      | Meaning                                                                                           |
| ----------- | ------------------------------------------------------------------------------------------------- |
| Not indexed | No serving namespace is available and no build is reported.                                       |
| Indexing    | A build is queuing or processing source records. An earlier index, if any, keeps serving queries. |
| Ready       | A serving namespace exists and no build is reported. A repair may still be processing records.    |

The list and details page show the same reported index status, and the list's **Status** column can be filtered. Repair progress, reported record errors, and unconfirmed build completion appear separately on the details page.

If no matching build or repair progress has been reported for at least 15 minutes, the details page can show a warning. This warning does not change the index status, mark the operation as stuck or stalled, or establish that it stopped or failed. Check progress and record-level errors before deciding whether to retry. Ready also does not prove that the most recent source change has been processed.

## Source Changes and Deletions

The indexing pipeline processes source changes and checks profile membership. Eligible records need their searchable text and projections updated. Records that are deleted or no longer eligible need their indexed membership removed.

Verify this with a known record: change a distinctive phrase, wait for processing, and search for the new evidence. Test deletion and eligibility changes separately. Avoid using a successful request alone as proof that background work completed.

## Repair and Rebuild

**Repair index** checks matching and previously associated records in the active and building indexes. It can retry missing or failed work and reuse unchanged embeddings: only text that changed or has no stored embedding is sent to the embedding model. Inspect progress and failure details after requesting repair.

**Rebuild index** creates a new generation and processes source records for it. An existing active index continues serving queries while the rebuild runs. For an initial build, there may be no complete active generation yet.

A build finishes when the indexer processes its completion check, which follows every record the build queued. If that check is lost, the details page shows **Indexing hasn't confirmed completion** even when the processed count matches. **Repair index** resends the check along with the repair, and the build finishes once the indexer processes it. The repair's own records continue separately.

**Drain queued work** drops this profile's repair and rebuild work that was queued before you drain, for a limited time (30 minutes by default). A repair that is still queuing records stops. A rebuild keeps queuing the records it has not reached, and record changes made after the drain still index. Dropped records are reported as skipped and stay out of search results until a repair checks them.

Use repair when the configuration is appropriate but records appear missing or stale. Review rebuild options when indexed text or the embedding configuration changes. A dimension change requires a new vector configuration. Named index changes save without a rebuild, and projection-only changes repair the existing index in place. See [Change an Existing Profile](https://docs.contextual.io/documentation-and-resources/components-and-data/ai-search/manage-search-profiles.md#change-an-existing-profile).

## Skipped Records

The indexer skips a record, rather than stopping, when the record itself cannot be indexed. Two causes qualify:

* a projection value the stored column type cannot hold, such as a fraction for an `integer` projection or for a column an older index holds as integers, and
* a record whose template, projection expression, or chunks fail for that record alone.

For a value the column cannot hold, the indexer first makes one more attempt. It rereads the profile configuration and the index's stored column types, and writes again only if the result changed and now fits. It never clears or rounds the rejected value to make the record fit.

A skipped record is acknowledged so later records keep flowing, but it is not indexed. The **Stored columns** summary near the top of the Search Profile page shows one alert for the profile with how many records were skipped, what the last one produced, and **Run repair**. The alert carries through when a build takes over. Build progress counts a skipped record as processed, not as indexed.

Other failures still stop processing until they are fixed: an unavailable search store or embedding service, an authorization or configuration problem, a request the search store rejects for another reason, and any failure deleting or cleaning up records. The indexer retries those records once the cause is resolved.

To recover skipped records:

1. Use the reported projection and value kind to find the cause. Change the projection type or alias, or correct the source records.
2. Save the profile, or request **Repair index** if only source data changed.
3. Wait for the repair to finish. The skipped-record warning clears once a repair that started after the last skip completes.

Skipped work no longer sits in a queue, and logs are not replayable. A repair is what reprocesses those records.

## Investigate Failures

1. Confirm the tenant, profile, source Object Type, and index ID.
2. Inspect build or repair progress and record-level failure details.
3. Check the affected record's template output and projection values.
4. Check model availability and input limits if embedding fails.
5. Correct the cause, then request the appropriate repair or rebuild.
6. Wait for processing and rerun the known query.

If a repair request reports an immediate API error, capture the status, response, and request correlation information for support. An error in the client does not by itself prove that the server queued no work.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.contextual.io/documentation-and-resources/components-and-data/ai-search/keep-search-up-to-date.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
