Vector DB extension

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:
        dimensions: 768 # Required - set number of dimensions to use
        max_vectors: 10 # Optional — max results returned per query (default: 10)
        store_batch_size: 300 # Optional — number of vectors stored per internal batch

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:
  vector_db:
    registry: https://gitlab.com/chromaway/core/vector-db-extension.git
    path: rell/src/lib/
    tagOrBranch: 0.5.1
    rid: x"1BC324D42A9622146FBCFECFBF16F1857144BA3266040BB9611634837003C484" # Update to match version
    insecure: false

tagOrBranch can be found here.
Once installed, chr will print the correct rid to use in your config.

Run:

chr install

Minimal implementation example

Here is a simple dapp to store and remove vectors:

import lib.vector_db.*;

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

operation delete_vector(context: integer, id: integer) {
    delete_vector(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:

chromia.yaml

deployments:
  testnet: # Deployment Target name
    brid: x"6F1B061C633A992BF195850BF5AA1B6F887AEE01BB3F51251C230930FB792A92" # Blockchain RID for Testnet Directory Chain
    url: https://node0.testnet.chromia.com:7740 # 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:7740

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
context	integer	true		Context used by the dapp. Use different contexts to separate unrelated vectors.
q_vector	text	true		The query vector as a string (e.g. "[1.0, 2.0, 3.0]")
max_distance	decimal	true		Maximum allowed cosine distance between the query and stored vectors
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 context=0 q_vector="[1.0, 2.0, 3.0]" max_distance=1.0 max_vectors=2

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

Using a query_template to return the text messages

chr query -brid $vector_brid --api-url $url query_closest_objects 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 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 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