CyborgDB Quickstart

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:

   Python

   # 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:

   Python

   # 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:

   Python

   # ... 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:

   Python

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

   Python

   # ... 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:

   Python

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

   Learn more about CyborgDB:

   About CyborgDB

   Learn about the architecture, design and deployment of CyborgDB.

   API Docs

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