Get started with CyborgDB in minutes.

CyborgDB is offered as two packages: cyborgdb_core and cyborgdb_lite. This guide shows how to get started with either. For more details on the difference between both packages, read more here.
1

Install CyborgDB

Install CyborgDB on your machine:

# Ensure that Python 3.9 - 3.13 is installed
# Or create a virtual environment with Python 3.9 - 3.13:
conda create -n cyborg-env python=3.12

# Activate the virtual environment:
conda activate cyborg-env

# Install CyborgDB:
pip install cyborgdb-core -i https://dl.cloudsmith.io/<token>/cyborg/cyborgdb/python/simple/

# Or install CyborgDB Lite for evaluation/non-commercial use:
pip install cyborgdb-lite
You will need to replace <token> with your token provided by Cyborg.
2

Create a Client

Create a CyborgDB client:

# Import cyborgdb_core or cyborgdb_lite:
import cyborgdb_core as cyborgdb
import cyborgdb_lite as cyborgdb
import secrets

# Using `memory` storage for this example
# `redis` and `postgres` are also supported

index_location = cyborgdb.DBConfig("memory")  # Where encrypted index is stored (for queries)
config_location = cyborgdb.DBConfig("memory") # Where encrypted index config is stored (for config/loading)
items_location = cyborgdb.DBConfig("memory")  # Where item contents are stored (for upsert/get)

# Create a client
client = cyborgdb.Client(index_location, config_location, items_location)

For more info, refer to Create a Client.

3

Create an Encrypted Index

Create an encrypted index with CyborgDB:

# ... Continuing from the previous step

# Create an IVFFlat index config (can also be IVF/IVFPQ)
# Using an example vector dimension of 4, and number of lists of 1024
index_config = cyborgdb.IndexIVFFlat(dimension=4, n_lists=1024)

# Generate an encryption key for the index
index_key = secrets.token_bytes(32)

# Create an encrypted index
index = client.create_index("my_index", index_key, index_config)

For more info, refer to Create an Encrypted Index.

4

Add Items to Encrypted Index

Add data to the encrypted index via Upsert:

# ... Continuing from the previous step

# Add items to the encrypted index
items = [
    {"id": "item_1", "vector": [0.1, 0.2, 0.3, 0.4], "contents": "Hello!"},
    {"id": "item_2", "vector": [0.5, 0.6, 0.7, 0.8], "contents": "Bonjour!"},
    {"id": "item_3", "vector": [0.9, 0.10, 0.11, 0.12], "contents": "Hola!"}
]

index.upsert(items)

For more info, refer to Add Items.

5

Query Encrypted Index

Query the encrypted index for similar vectors.

# ... Continuing from the previous step

# Query the encrypted index
query_vector = [0.1, 0.2, 0.3, 0.4]
results = index.query(query_vector)

# Print the results
for result in results:
    print(f"ID: {result.id}, Distance: {result.distance}")

For more info, refer to Query an Encrypted Index.

6

Retrieve Items from Encrypted Index

Retrieve data from the encrypted index:

# ... Continuing from the previous step

# Retrieve items from the encrypted index
ids = ["item_1", "item_2", "item_3"]
items = index.get(ids)

# Print the items
for item in items:
    print(f"ID: {item.id}, Vector: {item.vector}, Contents: {item.contents}")

For more info, refer to Get Items.

7

Next Steps