> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cyborg.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Index

Creates and returns an `EncryptedIndex` instance backed by a new encrypted DiskIVF index on the server.

<Note>v0.17 introduces a single **DiskIVF** index type and removes the polymorphic `index_config` argument. The previous `IndexIVFFlat`, `IndexIVFPQ`, and `IndexIVFSQ` types are gone — index configuration is now expressed as flat keyword arguments (`dimension`, `metric`, `storage_precision`).</Note>

```python theme={null}
client.create_index(
    index_name,
    index_key = None,
    kms_name = None,
    dimension = None,
    embedding_model = None,
    metric = None,
    storage_precision = None,
)
```

### Parameters

| Parameter           | Type    | Default | Description                                                                                                                                                                                |
| ------------------- | ------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `index_name`        | `str`   | -       | Unique name for the index                                                                                                                                                                  |
| `index_key`         | `bytes` | `None`  | *(Optional)* 32-byte encryption key. Required when `kms_name` is omitted (SDK-supplied KEK). Must be omitted when `kms_name` references a real KMS provider.                               |
| `kms_name`          | `str`   | `None`  | *(Optional)* Name of a `kms.registry` entry in the service YAML. When supplied, the service generates the KEK and wraps it under the named provider; the SDK never sees the plaintext key. |
| `dimension`         | `int`   | `None`  | *(Optional)* Vector dimensionality. If omitted, the server auto-detects from the first upsert.                                                                                             |
| `embedding_model`   | `str`   | `None`  | *(Optional)* sentence-transformers model name for automatic embedding generation. When set, `dimension` is inferred from the model.                                                        |
| `metric`            | `str`   | `None`  | *(Optional)* Distance metric (`"euclidean"`, `"squared_euclidean"`, or `"cosine"`). When `None`, the server applies its default.                                                           |
| `storage_precision` | `str`   | `None`  | *(Optional)* On-disk rerank-vector dtype: `"float32"` (default) or `"float16"`.                                                                                                            |

### Key Management Modes

At least one of `index_key` / `kms_name` must be supplied; supplying both against a real-KMS slot is rejected by the server with 400:

* **SDK-supplied KEK** — pass `index_key`, omit `kms_name`. The server records the index with `provider: none`; you must re-supply the same key on every subsequent call (`load_index`, `query`, `upsert`, etc.).
* **KMS-backed** — pass `kms_name`, omit `index_key`. The server generates the DEK, wraps it under the named registry slot, and persists the envelope. Subsequent calls omit `index_key` entirely.

### Returns

An instance of `EncryptedIndex` bound to the newly created index. For KMS-backed indexes the returned handle holds no plaintext key.

### Exceptions

<AccordionGroup>
  <Accordion title="ValueError">
    * Raised if neither `index_key` nor `kms_name` is provided.
    * Raised if `index_key` is provided but is not exactly 32 bytes.
    * Raised by the server (re-wrapped as `ValueError`) if both `index_key` and `kms_name` are provided against a real-KMS slot.
    * Raised by the server if the index name already exists, the embedding model is unsupported, or the KMS slot lookup fails.
  </Accordion>

  <Accordion title="Service Errors">
    * Raised if the CyborgDB service is unavailable, unreachable, or returns 5xx (including KMS-wrap failures as 502).
  </Accordion>
</AccordionGroup>

### Example Usage

#### SDK-supplied key (basic)

```python theme={null}
from cyborgdb import Client

# Initialize client
client = Client(base_url='http://localhost:8000', api_key='your-api-key')

# Generate a secure encryption key
index_key = client.generate_key(save=True)

# Create a basic index — dimension is auto-detected from the first upsert
index = client.create_index('documents', index_key=index_key)
```

<Note>For more info on `generate_key`, refer to [Generate Key](./generate-key).</Note>

#### SDK-supplied key with explicit dimension

```python theme={null}
# Pin the dimension and metric explicitly
index = client.create_index(
    'documents',
    index_key=index_key,
    dimension=384,
    metric='cosine',
)
```

#### KMS-backed index

```python theme={null}
# The service generates the KEK, wraps it via the 'prod-aws' registry slot,
# and persists the envelope. The SDK never sees the plaintext key.
index = client.create_index(
    'kms_documents',
    kms_name='prod-aws',
    dimension=384,
)
# Subsequent calls — including load_index — omit index_key entirely.
```

#### Auto-embedding

```python theme={null}
# When embedding_model is set, the server infers `dimension` from the model.
index = client.create_index(
    'semantic_docs',
    index_key=index_key,
    embedding_model='all-MiniLM-L6-v2',
)
```

#### Float16 storage for reduced footprint

```python theme={null}
# Halves on-disk rerank-vector storage at the cost of small recall
index = client.create_index(
    'compact_docs',
    index_key=index_key,
    dimension=768,
    storage_precision='float16',
)
```

<Note>For more info on auto-generating embeddings, refer to [Auto-Generate Embeddings](../../guides/data-operations/add-items#automatic-embedding-generation).</Note>