> ## 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 Embedded Quickstart

Get started with CyborgDB in minutes.

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

    <CodeGroup>
      ```bash Python theme={null}
      # Install CyborgDB:
      pip install cyborgdb-core

      # For automatic embedding generation, install with:
      pip install cyborgdb-core[embeddings]

      # For LangChain integration, install with:
      pip install cyborgdb-core[langchain]

      # Or with all extras:
      pip install cyborgdb-core[all]
      ```

      ```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 icon="python" theme={null}
      import cyborgdb_core as cyborgdb
      import secrets

      # Backing store: disk (local, RocksDB-backed) for simple persistent storage.
      # Use .memory() for ephemeral storage or .s3("bucket") for cloud persistence.
      client = cyborgdb.Client(storage_config=cyborgdb.StorageConfig.disk("/tmp/cyborgdb"))
      ```

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

      // Backing store: disk (local, RocksDB-backed) for simple persistent storage.
      // Use StorageConfig::Memory() for ephemeral storage or ::S3("bucket") for cloud persistence.
      // Pass "" for api_key to run in free-tier mode.
      cyborg::Client client("", cyborg::StorageConfig::Disk("/tmp/cyborgdb"), 0, cyborg::kNone);
      ```
    </CodeGroup>

    <Note>
      Without an API key the client runs in free-tier mode, capped at 1,000,000 items per index. Pass a key from the [CyborgDB Admin Dashboard](https://cyborgdb.co) as the first argument (`cyborgdb.Client(api_key, storage_config=...)`) for unlimited usage. See [Get an API Key](../../../intro/get-api-key).
    </Note>

    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 icon="python" theme={null}
      # ... Continuing from the previous step

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

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

      ```cpp C++ icon="brackets-curly" theme={null}
      /// ... Continuing from the previous step

      // 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
      auto index = client.CreateIndex("my_index", index_key);
      ```
    </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 icon="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_key must be supplied on every data operation
      index.upsert(items, index_key=index_key)
      ```

      ```cpp C++ icon="brackets-curly" 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<float> 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}};
      std::vector<std::vector<uint8_t>> contents = {
          std::vector<uint8_t>{'H', 'e', 'l', 'l', 'o', '!'},
          std::vector<uint8_t>{'B', 'o', 'n', 'j', 'o', 'u', 'r', '!'},
          std::vector<uint8_t>{'H', 'o', 'l', 'a', '!'}
      };

      index->Upsert(ids, vectors, contents, /*metadata=*/{}, index_key);
      ```
    </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 icon="python" theme={null}
      # ... Continuing from the previous step

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

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

      ```cpp C++ icon="brackets-curly" theme={null}
      // ... Continuing from the previous step
      cyborg::Array2D<float> query_vectors{{0.1, 0.2, 0.3, 0.4}};

      // Query using the standard params
      cyborg::QueryResults results = index->Query(query_vectors, cyborg::QueryParams{}, index_key);

      // Print the results
      auto view = results[0];
      for (uint32_t i = 0; i < view.num_results; ++i) {
          std::cout << "ID: " << view.ids[i] << ", Distance: " << view.distances[i] << 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 icon="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, index_key=index_key)

      # Print the items (contents are returned as bytes)
      for item in items:
          print(f"ID: {item['id']}, Vector: {item['vector']}, Contents: {item['contents']}")
      ```

      ```cpp C++ icon="brackets-curly" theme={null}
      // ... Continuing from the previous step

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

      // Print the items
      for (const auto& item : items) {
          std::cout << "ID: " << item.id << ", Contents: " << std::string(item.contents.begin(), item.contents.end()) << 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="Python API Reference" href="../../python/introduction" icon="python">
        Explore the Python API reference to learn how to use CyborgDB in your applications.
      </Card>

      <Card title="C++ API Reference" href="../../cpp/introduction" icon="brackets-curly">
        Explore the C++ API reference to learn how to use CyborgDB in your applications.
      </Card>
    </CardGroup>
  </Step>
</Steps>