Vector DB

Chromia’s Vector DB extension allows for the efficient storage and querying of complex multi-dimensional data in a decentralized approach. It integrates relational database principles to support high-performance indexing and similarity searches, making it ideal for AI-driven applications such as recommendation systems, natural language processing, and image recognition.

You can easily use Chromia’s Rell language and the Chromia CLI to define vector-based schemas, execute operations and queries, and perform similarity searches. The integration with Chromia’s decentralized network ensures high availability, scalability, and tamper-proof data management. This combination of blockchain technology, relational indexing, and vector search opens up new possibilities for decentralized AI, gaming, and large-scale data analytics.

Leasing a container

If you are unfamiliar with the process of leasing a container, follow these steps.

info

Ensure that the Vector DB extension is selected when leasing the container.

Configuring blockchain in the dapp

When leasing your container, ensure that you select the Vector DB extension. Configure your blockchain to use operations and queries to start utilizing this extension. Below is a sample configuration:

chromia.yml

blockchains:
  my_chain:
    module: my_chain_module
    config:
      gtx:
        modules:
          - "net.postchain.gtx.extensions.vectordb.VectorDbGTXModule"
      vector_db_extension:
        my_vector_collection: # Name of the collection. Multiple collections can be defined.
          dimensions: 768 # Required - set number of dimensions to use
          index: hnsw_cosine # Optional - available distance indices: hnsw_cosine, hnsw_l1, hnsw_l2, hnsw_ip (default: hnsw_cosine)
          query_max_vectors: 10 # Optional — max results returned per query (default: 10)
          store_batch_size: 300 # Optional — number of vectors stored per internal batch (default: 300)

Vectors are stored and grouped by collections and contexts. A collection is defined in the blockchain configuration to separate different types of vectors (e.g. dimensions, index, etc.). A context is used to separate vectors within a collection, and is set by the dApp.

A dApp can also dynamically manage collections. More information about this can be found in the repository documentation.

info

dimensions must match the length of the vectors you store — for example, 384, 768, or 1024 when using text embeddings.

Integrating with Rell

Integrating the Vector DB Extension library into your Rell project is optional but recommended. To do this, add it to your configuration as follows:

chromia.yml

libs:
  com.chromia.vector_db:
    version: 2.2.0 # Set to version you want to use

Available versions can be found by running chr library versions com.chromia.vector_db.

Run:

chr install

Minimal implementation example

Here is a simple dapp to store and remove vectors in the defined collection my_vector_collection:

import lib.vector_db.*;

operation add_vector(context: integer, vector: text, id: integer) {
    store_vector("my_vector_collection", context, vector, id);
}

operation delete_vector(context: integer, id: integer) {
    delete_vector("my_vector_collection", context, id);
}

Deployment to Testnet

Deployment steps. BRID for Testnet Directory Chain can be found in the explorer.

Expected output on successful deployment:

Deployment of blockchain vector_example was successful
Add the following to your project settings file:
deployments:
  testnet:
    chains:
      my_chain: x"CEC6A318C873...0A32C85429706" # you will get your own BRID

Add the deployed chain into chromia.yml:

deployments:
testnet: # Deployment Target name
  brid: x"6F1B061C633A992BF195850BF5AA1B6F887AEE01BB3F51251C230930FB792A92" # Blockchain RID for Testnet Directory Chain
  url: https://node0.testnet.chromia.com # Target URL for one of the nodes in Testnet
  container: 4d7890243fe710...08c724700cbd385ecd17d6f # Replace with your container ID (Example - container: 15ddfcb25dcb43577ab311fe78aedab14fda25757c72a787420454728fb80304)
  chains:
    my_chain: x"CEC6A318C873...0A32C85429706" # Replace with the actual BRID after the dapp gets deployed. It can be found in the terminal during deployment.

Save the BRID from deployment into environment variables.

vector_brid=CEC6A318C873B3013DB9476C084BEDE0EA3D03D5C686A2FACD50A32C85429706

Save the URL of the test node into environment variables.

url=https://node0.testnet.chromia.com

note

The following operation examples are based on the vector_example application from the Vector DB extension repository. You can reference this example to see the complete implementation.

Operation examples:

chr tx -brid $vector_brid --api-url $url add_message hej "[1.0, 2.0, 3.0]"
chr tx -brid $vector_brid --api-url $url add_message hello "[1.0, 2.5, 3.0]"
chr tx -brid $vector_brid --api-url $url add_message hei "[1.0, 2.0, 3.1]"
chr tx -brid $vector_brid --api-url $url add_message "guten tag" "[1.0, 1.5, 3.5]"

Querying vectors

The extension introduces a query function named query_closest_objects, which allows you to search for vectors. It returns the closest vectors based on cosine similarity:

Name	Type	Required	Default	Description
collection	text	true		Collection used by the dapp. Use different collections to separate different type of vectors.
context	integer	true		Context used by the dapp. Use different contexts to separate unrelated vectors. Use -1 to disable and query all vectors in all contexts.
q_vector	text	true		The query vector as a string (e.g. "[1.0, 2.0, 3.0]")
max_distance	decimal	true		Maximum allowed distance between the query and stored vectors
query_max_vectors	integer	false	10	Maximum number of results to return
query_template	text or dict	false	–	Apply a Rell query to enrich/filter/transform the results (see examples below)

tip

Use different context values to keep vector sets isolated — for example, one for product descriptions, and one for support tickets. This allows you to run similarity searches independently across each domain.

Query examples

Plain query with no query_template

chr query -brid $vector_brid --api-url $url query_closest_objects collection=my_vector_collection context=0 q_vector="[1.0, 2.0, 3.0]" max_distance=1.0 max_vectors=2

[
  {
    "distance": "0",
    "id": 1,
    "context": 0,
  },
  {
    "distance": "0.0001212999220387978",
    "id": 3,
    "context": 0,
  }
]

Using a query_template to return the text messages

chr query -brid $vector_brid --api-url $url query_closest_objects collection=my_vector_collection context=0 q_vector="[1.0, 2.5, 3.0]" max_distance=1.0 max_vectors=2 'query_template=["type":"get_messages"]'

[
  "hello",
  "hej"
]

Using a query_template to return distance and text

chr query -brid $vector_brid --api-url $url query_closest_objects collection=my_vector_collection context=0 q_vector="[1.0, 2.5, 3.0]" max_distance=1.0 max_vectors=2 'query_template=["type":"get_messages_with_distance"]'

[
  {
    "distance": "0",
    "text": "hello"
  },
  {
    "distance": "0.005509683802306209",
    "text": "hej"
  }
]

Passing arguments to filter results

chr query -brid $vector_brid --api-url $url query_closest_objects collection=my_vector_collection context=0 q_vector="[1.0, 2.5, 3.0]" max_distance=1.0 max_vectors=2 'query_template=["type":"get_messages_with_filter", "args":["text_filter": "j"]]'

[
  "hej"
]

---

You can find the source code and additional details about the Vector DB extension in the
👉 official repository