Types

StorageConfig

The StorageConfig class specifies the backing store for an index’s keystores. It is immutable and is built via static factory methods. A single StorageConfig is shared across all per-index keystores and is passed to the Client constructor. CyborgDB supports two backing stores: disk and s3.

Factories

StorageConfig.disk(path: str,
                   *,
                   cache_vectors: bool = False,
                   cache_metadata: bool = False,
                   cache_ids: bool = False,
                   cache_metadata_index: bool = False)
# Local persistent storage on disk.

StorageConfig.s3(bucket: str,
                 *,
                 region: str | None = None,
                 endpoint: str | None = None,
                 prefix: str = "",
                 credentials: S3Credentials | None = None)
# AWS S3 / S3-compatible (MinIO, Ceph, R2, etc.).

Factory	Description
`disk(path, ...)`	Local persistent store on disk. Optional `cache_*` flags keep vectors / metadata / IDs / the metadata index in memory for faster reads.
`s3(bucket, ...)`	S3 or S3-compatible object store. Set `endpoint` for non-AWS providers (path-style addressing is auto-selected). Omit `credentials` to use the AWS default credential provider chain.

Properties (Read-Only)

Property	Type	Description
`cache_vectors`	`bool`	Whether the vectors store is served from the in-RAM cache.
`cache_metadata`	`bool`	Whether the metadata store is served from the in-RAM cache.
`cache_ids`	`bool`	Whether the ids store is served from the in-RAM cache.
`cache_metadata_index`	`bool`	Whether the encrypted metadata index store is served from the in-RAM cache.

Example Usage

import cyborgdb_core as cyborgdb

# Local disk, caching vectors in memory
disk_store = cyborgdb.StorageConfig.disk("/tmp/cyborgdb", cache_vectors=True)

# AWS S3 with explicit credentials
s3_store = cyborgdb.StorageConfig.s3(
    "my-bucket",
    region="us-east-1",
    credentials=cyborgdb.S3Credentials(access_key="...", secret_key="..."),
)

# S3-compatible (e.g. MinIO) with default credential chain
minio_store = cyborgdb.StorageConfig.s3(
    "my-bucket",
    endpoint="http://localhost:9000",
)

For more info, you can read about supported backing stores here.

S3Credentials

Explicit credentials for the StorageConfig.s3(...) factory. Omit credentials= on .s3() to use the AWS default credential provider chain (environment variables, ~/.aws/credentials, EC2 instance profile, EKS IRSA).

S3Credentials(access_key: str,
              secret_key: str,
              session_token: str | None = None)

Parameters

Parameter	Type	Default	Description
`access_key`	`str`	-	S3 access key ID.
`secret_key`	`str`	-	S3 secret access key.
`session_token`	`str` \| `None`	`None`	(Optional) Temporary session token (for STS / assumed roles).

Example Usage

import cyborgdb_core as cyborgdb

creds = cyborgdb.S3Credentials(access_key="AKIA...", secret_key="...")
store = cyborgdb.StorageConfig.s3("my-bucket", region="us-east-1", credentials=creds)

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

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

import cyborgdb_core as cyborgdb

# Enable GPU for upsert and training
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:
    print("GPU enabled for training")

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.

StoragePrecision

StoragePrecision is a str enum naming the on-disk rerank-vector format, chosen at create time and immutable. Each member’s value is its lowercase string, so the raw strings (and np.float32 / np.float16) are also accepted wherever storage_precision is.

class StoragePrecision(str, Enum):
    FLOAT32 = "float32"
    FLOAT16 = "float16"
    TQ12 = "tq12"
    TQ8 = "tq8"
    TQ6 = "tq6"
    TQ4 = "tq4"

KMSBlob

KMSBlob describes a per-index envelope recording how the index KEK is wrapped by an external KMS. It is used with the module-level KMS functions (create_index_kms, push_index_kms, get_index_kms, delete_index_kms). This is an advanced, optional surface primarily for the service layer; embedded SDK users supplying their own KEK can ignore it or use provider="none".

KMSBlob(kms_name: str = "",
        provider: str = "",
        key_id: str = "",
        region: str = "",
        wrapped_kek: bytes = b"",
        version: int = 1,
        created_at: int = 0)

Fields

Field	Type	Description
`kms_name`	`str`	Human-readable name of the KMS configuration.
`provider`	`str`	KMS provider: `"aws"`, `"aws-kms"`, or `"none"`.
`key_id`	`str`	Identifier of the wrapping key within the KMS.
`region`	`str`	Region of the KMS / key.
`wrapped_kek`	`bytes`	The wrapped index KEK.
`version`	`int`	Envelope version.
`created_at`	`int`	Creation timestamp (unix epoch seconds).

Example Usage

import cyborgdb_core as cyborgdb

blob = cyborgdb.KMSBlob(
    kms_name="prod",
    provider="aws-kms",
    key_id="arn:aws:kms:us-east-1:111122223333:key/abcd",
    region="us-east-1",
    wrapped_kek=wrapped_bytes,
)

Introduction

Client

Encrypted Index

Types & Getters

StorageConfig

Factories

Properties (Read-Only)

Example Usage

S3Credentials

Parameters

Example Usage

GPUConfig

Parameters

Properties (Read-Only)

Example Usage

DistanceMetric

StoragePrecision

KMSBlob

Fields

Example Usage

​StorageConfig

​Factories

​Properties (Read-Only)

​Example Usage

​S3Credentials

​Parameters

​Example Usage

​GPUConfig

​Parameters

​Properties (Read-Only)

​Example Usage

​DistanceMetric

​StoragePrecision

​KMSBlob

​Fields

​Example Usage

StorageConfig

Factories

Properties (Read-Only)

Example Usage

S3Credentials

Parameters

Example Usage

GPUConfig

Parameters

Properties (Read-Only)

Example Usage

DistanceMetric

StoragePrecision

KMSBlob

Fields

Example Usage