Get started with CyborgDB in minutes.
CyborgDB’s embedded library 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

Get an API Key

To use CyborgDB, you need an API key. You can get an API key from the CyborgDB Admin Dashboard. For more info, follow this guide.Make sure to keep your API key secure and do not share it publicly.
2

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.
3

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)

# Get your API key
api_key = "your_api_key_here"  # Replace with your actual API key

# Create a client
client = cyborgdb.Client(api_key, index_location, config_location, items_location)
For more info, refer to Create a Client.
4

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.
5

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.
6

Query Encrypted Index

Query the encrypted index for similar vectors.
# ... Continuing from the previous step

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

# Print the results
for result in results:
    print(f"ID: {result.id}, Distance: {result.distance}")
For more info, refer to Query an Encrypted Index.
7

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.
8

Next Steps

Learn more about CyborgDB:

Python API Reference

Explore the Python API reference to learn how to use CyborgDB in your applications.

C++ API Reference

Explore the C++ API reference to learn how to use CyborgDB in your applications.