# Vector DB · Chromia Docs (concept)

> Chromia’s Vector DB extension allows for the efficient storage and querying of complex multi-dimensional data in a decentralized approach.

Source: https://docs.chromia.com/ecosystem/extensions/vector-db/

# Vector DB

On this page

* [Leasing a container](#leasing-a-container)
* [Configuring blockchain in the dapp](#configuring-blockchain-in-the-dapp)
* [Integrating with Rell](#integrating-with-rell)
* [Minimal implementation example](#minimal-implementation-example)
* [Deployment to Testnet](#deployment-to-testnet)
* [Operation examples:](#operation-examples)
* [Querying vectors](#querying-vectors)
* [Query examples](#query-examples)
* [Plain query with no query\_template](#plain-query-with-no-query_template)
* [Using a query\_template to return the text messages](#using-a-query_template-to-return-the-text-messages)
* [Using a query\_template to return distance and text](#using-a-query_template-to-return-distance-and-text)
* [Passing arguments to filter results](#passing-arguments-to-filter-results)

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](https://docs.chromia.com/build/deployment/testnet-tokens/get-tchr-chromia/).

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

```
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](https://gitlab.com/chromaway/core/vector-db-extension#blockchain-configuration).

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

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

Terminal

```
chr install
```

## Minimal implementation example

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

Rell

```
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.](https://docs.chromia.com/get-started/create-dapp/deploy-to-testnet/) BRID for Testnet Directory Chain can be found in the
[explorer](https://explorer.chromia.com/testnet/cluster/system).

Expected output on successful deployment:

YAML

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

YAML

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

Terminal

```
vector_brid=CEC6A318C873B3013DB9476C084BEDE0EA3D03D5C686A2FACD50A32C85429706
```

Save the `URL` of the test node into environment variables.

Terminal

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

note

The following operation examples are based on the `vector_example` application from the
[Vector DB extension repository](https://gitlab.com/chromaway/core/vector-db-extension). You can reference this example
to see the complete implementation.

## Operation examples:

Terminal

```
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`

Terminal

```
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

Terminal

```
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

Terminal

```
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

Terminal

```
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](https://gitlab.com/chromaway/core/vector-db-extension)

[View this page on docs.chromia.com](https://docs.chromia.com/ecosystem/extensions/vector-db/)Content mirrored from the live docs
