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

# Types

## DBConfig

The `DBConfig` class specifies the storage location for the index, with options for in-memory storage, databases, or file-based storage.

### Parameters

| Parameter           | Type     | Default | Description                                  |
| ------------------- | -------- | ------- | -------------------------------------------- |
| `location`          | `string` | -       | DB location (`redis`, `postgres`, `memory`)  |
| `table_name`        | `string` | None    | *(Optional)* Table name (`postgres`-only)    |
| `connection_string` | `string` | None    | *(Optional)* Connection string to access DB. |

The supported `location` options are:

* `"redis"`: Use for high-speed, in-memory storage (recommended for `index_location`).
* `"postgres"`: Use for reliable, SQL-based storage (recommended for `config_location`).
* `"memory"` Use for temporary in-memory storage (for benchmarking and evaluation purposes).

### Example Usage

```python theme={null}
import cyborgdb_core as cyborgdb

index_location = cyborgdb.DBConfig(
    location="redis",
    connection_string="redis://localhost"
)

config_location = cyborgdb.DBConfig(
    location="postgres",
    table_name="config_table",
    connection_string="host=localhost dbname=postgres"
)
```

For more info, you can read about supported backing stores [here](../../intro/backing-stores).

***

## GPUConfig

The `GPUConfig` class configures which operations should use GPU acceleration. GPU acceleration requires CUDA support.

### Parameters

| Parameter | Type   | Default | Description                                     |
| --------- | ------ | ------- | ----------------------------------------------- |
| `upsert`  | `bool` | `False` | *(Optional)* Enable GPU for upsert operations   |
| `train`   | `bool` | `False` | *(Optional)* Enable GPU for training operations |

<Warning>The `query` parameter is not available in the constructor. To enable GPU for query operations, you must enable both `upsert=True` and `train=True`, or use the bitflag operations directly in C++.</Warning>

### Properties (Read-Only)

| Property | Type   | Description                                    |
| -------- | ------ | ---------------------------------------------- |
| `upsert` | `bool` | Whether GPU is enabled for upsert operations   |
| `train`  | `bool` | Whether GPU is enabled for training operations |
| `query`  | `bool` | Whether GPU is enabled for query operations    |
| `all`    | `bool` | Whether all GPU operations are enabled         |
| `none`   | `bool` | Whether no GPU operations are enabled          |

### Example Usage

```python theme={null}
import cyborgdb_core as cyborgdb

# Enable GPU for upsert and training (query will also be enabled via properties)
gpu_config1 = cyborgdb.GPUConfig(upsert=True, train=True)

# Enable GPU only for training
gpu_config2 = cyborgdb.GPUConfig(train=True)

# Disable GPU (default)
gpu_config3 = cyborgdb.GPUConfig()

# Check GPU configuration
if gpu_config1.all:
    print("All GPU operations enabled")

if gpu_config2.train and gpu_config2.query:
    print("GPU enabled for training and query")
```

***

## DistanceMetric

`DistanceMetric` is a string representing the distance metric used for the index. Options include:

* `"cosine"`: Cosine similarity.
* `"euclidean"`: Euclidean distance.
* `"squared_euclidean"`: Squared Euclidean distance.

***

## IndexConfig

The `IndexConfig` class defines the parameters for the type of index to be created. Each index type (e.g., `ivf`, `ivfflat`, `ivfpq`) has unique configuration options:

### IndexIVF

Ideal for large-scale datasets where fast retrieval is prioritized over high recall:

|  Speed  | Recall | Index Size |
| :-----: | :----: | :--------: |
| Fastest | Lowest |  Smallest  |

#### Parameters

| Parameter   | Type  | Default | Description                                                           |
| ----------- | ----- | ------- | --------------------------------------------------------------------- |
| `dimension` | `int` | `0`     | *(Optional)* Dimensionality of vector embeddings. Auto-detected if 0. |

#### Properties (Read-Only)

| Property     | Type  | Description                                                                              |
| ------------ | ----- | ---------------------------------------------------------------------------------------- |
| `n_lists`    | `int` | Number of inverted lists (coarse clusters). Set internally during training, initially 1. |
| `dimension`  | `int` | Dimensionality of vector embeddings.                                                     |
| `metric`     | `str` | Distance metric used.                                                                    |
| `index_type` | `str` | Returns "ivf".                                                                           |

#### Example Usage

```python theme={null}
import cyborgdb_core as cyborgdb

# Basic configuration with auto-detection
index_config = cyborgdb.IndexIVF()

# Explicit dimension configuration
index_config = cyborgdb.IndexIVF(dimension=128)

# Access read-only properties
print(f"n_lists: {index_config.n_lists}")  # Will show 1 (default)
print(f"dimension: {index_config.dimension}")  # Will show 128
```

### IndexIVFFlat

Suitable for applications requiring high recall with less concern for memory usage:

| Speed |  Recall | Index Size |
| :---: | :-----: | :--------: |
|  Fast | Highest |   Biggest  |

#### Parameters

| Parameter   | Type  | Default | Description                                                           |
| ----------- | ----- | ------- | --------------------------------------------------------------------- |
| `dimension` | `int` | `0`     | *(Optional)* Dimensionality of vector embeddings. Auto-detected if 0. |

#### Properties (Read-Only)

| Property     | Type  | Description                                                                              |
| ------------ | ----- | ---------------------------------------------------------------------------------------- |
| `n_lists`    | `int` | Number of inverted lists (coarse clusters). Set internally during training, initially 1. |
| `dimension`  | `int` | Dimensionality of vector embeddings.                                                     |
| `metric`     | `str` | Distance metric used.                                                                    |
| `index_type` | `str` | Returns "ivfflat".                                                                       |

#### Example Usage

```python theme={null}
import cyborgdb_core as cyborgdb

# Basic configuration with auto-detection
index_config = cyborgdb.IndexIVFFlat()

# Explicit dimension configuration
index_config = cyborgdb.IndexIVFFlat(dimension=128)

# Access read-only properties
print(f"n_lists: {index_config.n_lists}")  # Will show 1 (default)
print(f"dimension: {index_config.dimension}")  # Will show 128
```

<Tip>`IndexIVFFlat` is the default index configuration and is suitable for most use cases.</Tip>

### IndexIVFPQ

Product Quantization compresses embeddings, making it suitable for balancing memory use and recall:

| Speed | Recall | Index Size |
| :---: | :----: | :--------: |
|  Fast |  High  |   Medium   |

#### Parameters

| Parameter   | Type  | Default | Description                                                                      |
| ----------- | ----- | ------- | -------------------------------------------------------------------------------- |
| `dimension` | `int` | `None`  | *(Optional)* Dimensionality of vector embeddings. Auto-detected if not provided. |
| `pq_dim`    | `int` | -       | *(Required)* Dimensionality of PQ codes after quantization.                      |
| `pq_bits`   | `int` | -       | *(Required)* Number of bits per quantizer (between 1 and 16).                    |

#### Properties (Read-Only)

| Property     | Type  | Description                                                                              |
| ------------ | ----- | ---------------------------------------------------------------------------------------- |
| `n_lists`    | `int` | Number of inverted lists (coarse clusters). Set internally during training, initially 1. |
| `dimension`  | `int` | Dimensionality of vector embeddings.                                                     |
| `metric`     | `str` | Distance metric used.                                                                    |
| `index_type` | `str` | Returns "ivfpq".                                                                         |
| `pq_dim`     | `int` | Dimensionality of PQ codes after quantization.                                           |
| `pq_bits`    | `int` | Number of bits per quantizer.                                                            |

#### Example Usage

```python theme={null}
import cyborgdb_core as cyborgdb

# Basic configuration (dimension auto-detected)
index_config = cyborgdb.IndexIVFPQ(pq_dim=64, pq_bits=8)

# Explicit configuration
index_config = cyborgdb.IndexIVFPQ(
    dimension=128,
    pq_dim=64, 
    pq_bits=8
)

# Access read-only properties
print(f"n_lists: {index_config.n_lists}")  # Will show 1 (default)
print(f"pq_dim: {index_config.pq_dim}")    # Will show 64
print(f"pq_bits: {index_config.pq_bits}")  # Will show 8
```

<Tip>If `dimension` is not provided, it will be auto-determined based on the first vector embedding added to the index.</Tip>