> 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/insert/insert-capacity.md).

# Insert Capacity

Each index has a finite capacity for additional inserts, derived from the compute node's free memory. `Index.insert()` checks the remaining headroom before submitting and raises `ValueError` if the request exceeds it. Use the values below to plan batch sizes or to surface friendly errors before calling `insert`.

***

## Capacity Fields

`Index.summary()` returns a dict whose capacity-related keys are:

| Key                                        | Meaning                                                                                                         |
| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
| `can_load_now`                             | `True` if the index is already loaded, or there is enough free server memory to load it now.                    |
| `remaining_insertable_shards`              | Number of additional shards the index can accept. Each shard holds up to 4096 vectors as default.               |
| `remaining_insertable_vectors_guaranteed`  | Hard lower bound on additional vectors that fit. Equals `remaining_insertable_shards × 4096`.                   |
| `remaining_insertable_vectors_best_effort` | Best-effort estimate, intended to be ≥ `_guaranteed`. **Currently identical** to `_guaranteed` in this release. |

Convenience properties on `Index`:

* `index.remaining_insertable_vectors` → `remaining_insertable_vectors_guaranteed`
* `index.remaining_insertable_shards` → `remaining_insertable_shards`
* `index.loadable` → `can_load_now`

***

## Usage

```python
# Full summary (capacity + identity + state fields)
summary = index.summary()
print(summary["remaining_insertable_vectors_guaranteed"])

# Quick capacity checks
print(index.remaining_insertable_vectors)
print(index.remaining_insertable_shards)
```

***

## Pre-Insert Check

```python
if len(vecs) > index.remaining_insertable_vectors:
    raise RuntimeError(
        f"Insert would exceed capacity: {len(vecs)} vectors, "
        f"{index.remaining_insertable_vectors} available"
    )

index.insert(vecs)
```

For pre-encrypted batches (`CipherBlock`), check `remaining_insertable_shards` instead — each `CipherBlock` consumes one shard regardless of vector count.

***

## Notes

* Capacity is **shared across all loaded indexes on the same compute node**: free memory ≈ `compute_max_memory − sum(currently loaded shards) − reserved`. Unloading or dropping other indexes raises the reported capacity for this index.
* The capacity feature requires `compute_max_memory` to be configured server-side. When unconfigured, all four fields are reported as 0/false.


---

# 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/insert/insert-capacity.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.