> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cyborg.co/llms.txt
> Use this file to discover all available pages before exploring further.

# CyborgDB Quickstart

Get started with CyborgDB in minutes.

<Tip>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](./about#cyborgdb-lite).</Tip>

<Steps>
  <Step title="Install CyborgDB">
    Install CyborgDB on your machine:

    <CodeGroup>
      ```bash Python theme={null}
      # 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
      ```

      ```bash C++ theme={null}
      # Ensure that Conan is installed

      # Add the repository to your Conan remotes:
      conan remote add cyborgdb https://dl.cloudsmith.io/<token>/cyborg/cyborgdb/conan
      conan remote login cyborgdb -p <token> cyborg

      # Install CyborgDB:
      conan install cyborgdb_core -r cyborgdb
      ```
    </CodeGroup>

    <Note>You will need to replace `<token>` with your token provided by Cyborg.</Note>
  </Step>

  <Step title="Create a Client">
    Create a CyborgDB client:

    <CodeGroup>
      ```python Python theme={null}
      # 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)
      ```

      ```cpp C++ theme={null}
      #include "cyborgdb_core/client.hpp"
      #include "cyborgdb_core/encrypted_index.hpp"
      #include <array>
      #include <string>
      #include <openssl/rand.h>

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

      cyborg::DBConfig index_location(cyborg::Location::kMemory);  // Where encrypted index is stored (for queries)
      cyborg::DBConfig config_location(cyborg::Location::kMemory); // Where encrypted index config is stored (for config/loading)
      cyborg::DBConfig items_location(cyborg::Location::kMemory);  // Where item contents are stored (for upsert/get)

      // Create a client
      cyborg::Client client(index_location, config_location, items_location);
      ```
    </CodeGroup>

    For more info, refer to [Create a Client](../encrypted-indexes/create-client).
  </Step>

  <Step title="Create an Encrypted Index">
    Create an encrypted index with CyborgDB:

    <CodeGroup>
      ```python Python theme={null}
      # ... 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)
      ```

      ```cpp C++ theme={null}
      /// ... 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
      cyborg::IndexIVFFlat index_config(4, 1024);

      // Generate a 32-byte random encryption key
      std::array<uint8_t, 32> index_key;
      if (RAND_bytes(index_key.data(), index_key.size()) != 1) {
          throw std::runtime_error("Failed to generate secure random key");
      }

      // Create an encrypted index
      cyborg::EncryptedIndex index = client.CreateIndex("my_index", index_key, index_config);
      ```
    </CodeGroup>

    For more info, refer to [Create an Encrypted Index](../encrypted-indexes/create-index).
  </Step>

  <Step title="Add Items to Encrypted Index">
    Add data to the encrypted index via Upsert:

    <CodeGroup>
      ```python Python theme={null}
      # ... 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)
      ```

      ```cpp C++ theme={null}
      // ... Continuing from the previous step

      // Add items to the encrypted index
      std::vector<std::string> ids = {"item_1", "item_2", "item_3"};
      cyborg::Array2D vectors = {{0.1, 0.2, 0.3, 0.4}, {0.5, 0.6, 0.7, 0.8}, {0.9, 0.10, 0.11, 0.12}};

      index.Upsert(vectors, ids);
      ```
    </CodeGroup>

    For more info, refer to [Add Items](../data-operations/add-items).
  </Step>

  <Step title="Query Encrypted Index">
    Query the encrypted index for similar vectors.

    <CodeGroup>
      ```python Python theme={null}
      # ... 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}")
      ```

      ```cpp C++ theme={null}
      // ... Continuing from the previous step
      std::vector<float> query_vector = {0.1, 0.2, 0.3, 0.4};
      cyborg::QueryResults results = index.Query(query_vector);

      // Print the results
      for (const auto& result : results) {
          std::cout << "ID: " << result.id << ", Distance: " << result.distance << std::endl;
      }
      ```
    </CodeGroup>

    For more info, refer to [Query an Encrypted Index](../data-operations/query).
  </Step>

  <Step title="Retrieve Items from Encrypted Index">
    Retrieve data from the encrypted index:

    <CodeGroup>
      ```python Python theme={null}
      # ... 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}")
      ```

      ```cpp C++ theme={null}
      // ... Continuing from the previous step

      // Retrieve items from the encrypted index
      std::vector<std::string> ids = {"item_1", "item_2", "item_3"};
      cyborg::Array2D<cyborg::Item> items = index.Get(ids, {kContents});

      // Print the items
      for (size_t i = 0; i < ids.size(); i++) {
          std::cout << "ID: " << ids[i] << ", Contents: " << items[i].contents << std::endl;
      }
      ```
    </CodeGroup>

    For more info, refer to [Get Items](../data-operations/get-items).
  </Step>

  <Step title="Next Steps">
    Learn more about CyborgDB:

    <CardGroup>
      <Card title="About CyborgDB" href="./about" icon="book-open-cover">
        Learn about the architecture, design and deployment of CyborgDB.
      </Card>

      <Card title="API Docs" href="../../api-reference" icon="code">
        Explore the API reference to learn how to use CyborgDB in your applications.
      </Card>
    </CardGroup>
  </Step>
</Steps>