> For the complete documentation index, see [llms.txt](https://docs.envector.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.envector.io/1.4.x/sdk-user-guide/advanced-user-guide/index-operation-lifecycle.md).

# Index Operation Lifecycle

`Index.insert()` and `Index.delete()` are asynchronous on the server. The SDK exposes helpers to wait for or directly poll the underlying state machine — useful when you need progress tracking, parallel pipelines, or timeout recovery. Most users can rely on `await_completion=True` and skip this page.

***

## State Sequence

```
SPLITTING → SPLIT_COMPLETED → MERGING → MERGED_SAVED → SEARCHABLE   (or FAILED)
```

* `SPLIT_COMPLETED` — data durable, not yet merged into the searchable index.
* `MERGED_SAVED` — merge persisted, compute memory not yet reloaded.
* `SEARCHABLE` — operation complete; affected rows are reflected in subsequent searches. `done=true`.
* `FAILED` — terminal failure; the `request_id` will not advance.

***

## Insert: Mapping the Stages

```python
request_ids: list[str] = []
index.insert(
    data=vecs,
    metadata=metadata,
    request_ids=request_ids,         # filled with one ID per split RPC
    execute_until="segmentation",    # default; "flush" stops earlier
    await_completion=True,
)
```

| `execute_until`  | `await_completion` | Returns when…                              |
| ---------------- | ------------------ | ------------------------------------------ |
| `"flush"`        | `False`            | split RPCs are submitted (no wait)         |
| `"flush"`        | `True`             | server reaches `SPLIT_COMPLETED`           |
| `"segmentation"` | `False`            | split + merge RPCs are submitted (no wait) |
| `"segmentation"` | `True`             | server reaches `MERGED_SAVED` (default)    |

* `"flush"` durably stores the vectors but **skips the indexing step** — search results do not yet reflect this data until indexing runs ([manually via `Index.indexing()`](#indexing-manually), or via a follow-up `"segmentation"` call).
* No mode waits for `SEARCHABLE` automatically. Capture `request_ids` and poll `wait_for_insert_searchable` (below) for that guarantee.
* `await_completion=True` is silently skipped if `request_ids=[]` is not also passed — the SDK has no IDs to poll.

***

## Indexing Manually

`execute_until="flush"` is a fast path: it stores the vectors durably but defers the work of organizing them into the search-optimized form. While data is in this state, search results do not reflect it yet. Call `Index.indexing()` later to index the captured `request_ids` and make them search-ready:

```python
request_ids: list[str] = []
index.insert(
    data=vecs,
    metadata=metadata,
    request_ids=request_ids,        # filled with split request IDs
    execute_until="flush",
    await_completion=True,          # wait until data is durably persisted
)

# ... do other work, batch additional flushed inserts, etc. ...

index.indexing(request_ids=request_ids)   # build the search index for those IDs

index.indexer.wait_for_inserts_searchable(
    index_name=index.index_config.index_name,
    request_ids=request_ids,
)                                          # optional: block until search-ready
```

* `request_ids` **must be non-empty and unique**. Passing `None`, `[]`, or duplicates raises `EnvectorValidationError`. Use the list captured from one or more prior `Index.insert(execute_until="flush", ...)` calls — you may concatenate IDs from several flushes to index them all in one call.
* `Index.indexing()` returns as soon as the indexing job is submitted. Track completion via `wait_for_inserts_searchable` (or `get_index_operation_status`) on the same split `request_ids`.
* Use this pattern when you want to decouple ingestion from search-readiness — e.g., flush many batches in parallel during high-throughput ingest, then trigger indexing once during a low-traffic window for predictable, optimized search performance.

***

## Delete

`Index.delete()` runs the lifecycle internally and waits for `SEARCHABLE` by default. See [Deleting by Item ID](/1.4.x/sdk-user-guide/delete/deleting-by-item-id.md).

***

## Polling Manually

```python
status = index.indexer.get_index_operation_status(
    index_name=index.index_config.index_name,
    request_id=request_id,
    operation_type="INSERT",   # or "DELETE"
)
print(status.searchable_row_count, status.total_row_count, status.done)
```

Convenience wait helpers on `index.indexer`:

* `wait_for_insert_searchable` — polls until `SEARCHABLE`.
* `wait_for_insert_persist_completed` — polls until `SPLIT_COMPLETED`.
* `wait_for_delete_completion` — polls until delete reaches `SEARCHABLE`.

On `EnvectorTimeoutError`, the operation is still progressing on the server — re-poll with the same `request_id`.


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.envector.io/1.4.x/sdk-user-guide/advanced-user-guide/index-operation-lifecycle.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.