Create Client

The Client class provides an interface to initialize, create, load and list Encrypted Indexes. Encrypted Indexes, in turn, expose data-related functionality such as upserting, querying, and deleting.

Creating the Client

To create the client, supply a backing store (StorageConfig) which it will use to persist all encrypted index data. No API key is required — without one the client runs in free-tier mode, capped at 1,000,000 items per index. The simplest backing store is an in-memory store, which is ephemeral and ideal for development and tests:

import cyborgdb_core as cyborgdb

# In-memory backing store (ephemeral, for development/tests)
client = cyborgdb.Client(storage_config=cyborgdb.StorageConfig.memory())

#include "cyborgdb_core/client.hpp"
#include "cyborgdb_core/encrypted_index.hpp"
#include <array>

// In-memory backing store (ephemeral, for development/tests).
// Pass "" for api_key to run in free-tier mode.
cyborg::Client client("", cyborg::StorageConfig::Memory(), 0, cyborg::kNone);

To lift the free-tier cap, pass an API key as the first argument (cyborgdb.Client(api_key, storage_config=...)). Get a key from the CyborgDB Admin Dashboard; for more info, follow this guide. Bear in mind that all contents stored in the backing store are end-to-end encrypted, meaning that no index contents are stored in plaintext.

The C++ cyborg::Client is non-copyable and non-movable (it owns the keystore handles). Construct it in place, or hold it via std::unique_ptr<cyborg::Client> if you need to move ownership.

Persistent Backing Stores

For persistence, use a disk-backed or S3 backing store instead of memory. StorageConfig exposes three static factories: memory(), disk(path) (local, RocksDB-backed), and s3(bucket) (AWS S3 or S3-compatible).

import cyborgdb_core as cyborgdb

# Local, RocksDB-backed persistent storage
client = cyborgdb.Client(storage_config=cyborgdb.StorageConfig.disk("/tmp/cyborgdb"))

# Or AWS S3 / S3-compatible (MinIO, etc.)
client = cyborgdb.Client(storage_config=cyborgdb.StorageConfig.s3(
    "my-bucket",
    region="us-east-1",
    credentials=cyborgdb.S3Credentials(access_key="...", secret_key="..."),  # omit for the default credential chain
))

#include "cyborgdb_core/client.hpp"

// Local, RocksDB-backed persistent storage (pass "" for api_key to run in free-tier mode)
cyborg::Client disk_client("", cyborg::StorageConfig::Disk("/tmp/cyborgdb"), 0, cyborg::kNone);

// Or AWS S3 / S3-compatible (MinIO, etc.)
cyborg::S3Options s3_opts;
s3_opts.region = "us-east-1";
cyborg::Client s3_client("", cyborg::StorageConfig::S3("my-bucket", s3_opts), 0, cyborg::kNone);

Omit credentials= (Python) / leave credentials unset in S3Options (C++) to use the AWS default credential provider chain (environment variables, ~/.aws/credentials, EC2 instance profile, EKS IRSA). The disk store also accepts cache options (cache_vectors, cache_metadata, cache_ids) to keep hot data in memory.

Setting Device Configurations

CyborgDB can be accelerated in two ways:

CPU Multithreading (via OpenMP) -> can scale with the number of CPU cores available
GPU Acceleration (via CUDA & cuVS) -> can increase the speed of certain operations (e.g., ingestion) by an order of magnitude.

You can control either of these with the optional cpu_threads and gpu_config parameters:

# ... existing setup

# Enable GPU for specific operations (upsert and train)
gpu_config = cyborgdb.GPUConfig(upsert=True, train=True)

client = cyborgdb.Client(
    storage_config=cyborgdb.StorageConfig.disk("/tmp/cyborgdb"),
    cpu_threads=4,
    gpu_config=gpu_config
)

// ... existing setup

// Enable GPU for specific operations (upsert and train)
cyborg::GPUConfig gpu_config = cyborg::kUpsert | cyborg::kTrain;

cyborg::Client client("", cyborg::StorageConfig::Disk("/tmp/cyborgdb"), 4, gpu_config);

gpu_config can only be set if running on a CUDA-enabled system with the CUDA driver installed. Use GPUConfig to specify which operations (upsert, train, query) should use GPU acceleration.

By default, cpu_threads will use all available cores, and gpu_config will be None (no GPU acceleration).

API Reference

For more information on the Client class, refer to the API Reference:

Python API Reference

API reference for Client in Python

C++ API Reference

API reference for cyborg::Client in C++

Intro

Encrypted Indexes

Data Operations

Advanced

Creating the Client

Persistent Backing Stores

Setting Device Configurations

API Reference

Python API Reference

C++ API Reference

​Creating the Client

​Persistent Backing Stores

​Setting Device Configurations

​API Reference

Python API Reference

C++ API Reference

Creating the Client

Persistent Backing Stores

Setting Device Configurations

API Reference