Client

Client is the main class exposed by CyborgDB. It exposes the functionality necessary to create, load, list and delete indexes. Operations within encrypted indexes (such as upsert and query) are contained within the EncryptedIndex class returned by create_index and load_index.

Constructor

Client(api_key: str = "",
       storage_config: StorageConfig,
       cpu_threads: int = 0,
       gpu_config: GPUConfig | None = None)

Initializes a new CyborgDB Client instance.

Parameters

Parameter	Type	Default	Description
`api_key`	`str`	`""`	(Optional) API key for your CyborgDB account. If omitted or empty, the client runs in free-tier mode, capped at 1,000,000 items per index. Pass a key from the Admin Dashboard for unlimited usage. When omitted, pass `storage_config` as a keyword argument.
`storage_config`	`StorageConfig`	-	Backing store for all index keystores. Built via the static factories `StorageConfig.memory()`, `StorageConfig.disk(path)`, or `StorageConfig.s3(bucket)`.
`cpu_threads`	`int`	`0`	(Optional) Number of CPU threads to use for computations (defaults to `0` = all cores).
`gpu_config`	`GPUConfig` \| `None`	`None`	(Optional) GPU operations configuration. Specify which operations use GPU acceleration (defaults to `None`, no GPU).

A single storage_config replaces the former index_location / config_location / items_location trio. The store is shared across all per-index keystores.

Exceptions

ValueError

Throws if the cpu_threads parameter is less than 0.
Throws if the StorageConfig is invalid.
Throws if the GPU is not available when gpu_config is set.

RuntimeError

Throws if the backing store is not available.
Throws if the Client could not be initialized.

Example Usage

import cyborgdb_core as cyborgdb

# Example 1: In-memory backing store, free-tier (no API key)
client1 = cyborgdb.Client(
    storage_config=cyborgdb.StorageConfig.memory(),
    cpu_threads=4
)

# Example 2: With an API key for unlimited usage, GPU on upsert and train
api_key = "your_api_key_here"  # Replace with your CyborgDB API key
gpu_config = cyborgdb.GPUConfig(upsert=True, train=True)
client2 = cyborgdb.Client(
    api_key=api_key,
    storage_config=cyborgdb.StorageConfig.disk("/tmp/cyborgdb"),
    cpu_threads=4,
    gpu_config=gpu_config
)

# Proceed with further operations

Use StorageConfig.memory() for ephemeral testing, StorageConfig.disk("/path") for local persistence, or StorageConfig.s3("bucket") for S3-backed persistence. See StorageConfig.

Methods

get_cpu_threads()

Returns the number of CPU threads configured for this client.

def get_cpu_threads(self) -> int

Returns

int: The number of CPU threads.

Example Usage

threads = client.get_cpu_threads()
print(f"Using {threads} CPU threads")

is_gpu_enabled()

Checks if GPU acceleration is enabled for this client.

def is_gpu_enabled(self) -> bool

Returns

bool: True if GPU acceleration is enabled, False otherwise.

Example Usage

gpu_enabled = client.is_gpu_enabled()
print(f"GPU acceleration is {'enabled' if gpu_enabled else 'disabled'}")

get_gpu_config()

Returns the GPU operations configuration for this client.

def get_gpu_config(self) -> GPUConfig

Returns

GPUConfig: The GPU operations configuration.

Example Usage

gpu_config = client.get_gpu_config()
print(f"GPU operations: upsert={gpu_config.upsert}, train={gpu_config.train}, query={gpu_config.query}")

Introduction

Encrypted Index

Types & Getters

Client

Constructor

Parameters

Exceptions

Example Usage

Methods

get_cpu_threads()

Returns

Example Usage

is_gpu_enabled()

Returns

Example Usage

get_gpu_config()

Returns

Example Usage

​Constructor

​Parameters

​Exceptions

​Example Usage

​Methods

​get_cpu_threads()

​Returns

​Example Usage

​is_gpu_enabled()

​Returns

​Example Usage

​get_gpu_config()

​Returns

​Example Usage

Constructor

Parameters

Exceptions

Example Usage

Methods

get_cpu_threads()

Returns

Example Usage

is_gpu_enabled()

Returns

Example Usage

get_gpu_config()

Returns

Example Usage