Keep Up With AI by Building Your First Vector Database with ChromaDB

Hello, I'm Rijul. I'm building git-lrc, a micro AI code reviewer that runs on every commit. It's free and source-available on GitHub. Star git-lrc to help more developers discover the project. Do give it a try and share your feedback

ChromaDB is a term you might have heard being mentioned quite often when working with AI applications.

ChromaDB is a vector database.

It is the kind of database you will often see being used in AI applications such as chatbots, RAG systems, and other applications that need to search for information based on semantic meaning.

What Is a Vector Database?

Let's say we have two sentences:

How can I get my money back?

and

What is your refund policy?

The words are different, but the meaning is similar.

To allow a computer to work with this kind of semantic similarity, we can convert text into numbers called embeddings.

An embedding is a numerical representation of the meaning of a piece of text.

A vector database allows us to store these embeddings and later search for information based on their semantic similarity.

ChromaDB is one such vector database.

Installing ChromaDB

Let's start by installing ChromaDB:

pip install chromadb

Once installed, we can import it and create a client:

import chromadb

chroma_client = chromadb.Client()

Now we can create a collection:

collection = chroma_client.create_collection(name="my_collection")

You can think of a collection as a place where we store related pieces of data.

Adding Documents

Now let's add some documents to our collection:

collection.add(
    ids=["id1", "id2"],
    documents=[
        "This is a document about pineapple",
        "This is a document about oranges"
    ]
)

We use collection.add() to add the text to the database.

One useful thing here is that we don't have to manually generate the embeddings ourselves for this basic example.

ChromaDB can generate embeddings for the documents for us.

When you run this for the first time, ChromaDB will download the embedding model it uses to generate these embeddings.

Once the documents and their embeddings are stored, we can search the collection.

Querying the Database

Let's query the database:

results = collection.query(
    query_texts=["This is a query document about hawaii"],
    n_results=2
)

print(results)

Here:

• query_texts contains the text we want to search for.
• n_results specifies how many results we want to retrieve.

ChromaDB will generate an embedding for the query and compare it with the embeddings stored in the collection.

It then returns the most relevant results.

The output might look something like this:

{
    'ids': [['id1', 'id2']],
    'embeddings': None,
    'documents': [
        [
            'This is a document about pineapple',
            'This is a document about oranges'
        ]
    ],
    'uris': None,
    'included': ['metadatas', 'documents', 'distances'],
    'data': None,
    'metadatas': [[None, None]],
    'distances': [[1.0404, 1.2431]]
}

Notice the distances field.

These values represent how far the results are from the query in the embedding space. The exact interpretation depends on the distance function being used.

In this example, the pineapple document has a smaller distance than the oranges document, meaning ChromaDB considers it more similar to the query.

Getting the Embeddings

By default, the embeddings aren't included in the query result.

If we want to see them, we can explicitly request them:

results = collection.query(
    query_texts=["This is a query document about hawaii"],
    n_results=2,
    include=[
        "distances",
        "metadatas",
        "embeddings",
        "documents"
    ]
)

print(results)

Now the output will include the actual embedding vectors:

{
    'ids': [['id1', 'id2']],
    'embeddings': [
        array([
            [-0.0071,  0.0655, -0.0116, ...,  0.0897,  0.0134],
            [-0.0265,  0.0688, -0.0377, ...,  0.0654,  0.0778]
        ])
    ],
    'documents': [
        [
            'This is a document about pineapple',
            'This is a document about oranges'
        ]
    ],
    'uris': None,
    'included': [
        'distances',
        'metadatas',
        'embeddings',
        'documents'
    ],
    'data': None,
    'metadatas': [[None, None]],
    'distances': [[1.0404, 1.2431]]
}

The actual embedding contains many numbers, so I've shortened the output with ....

The important thing to understand is the flow:

Document
    ↓
Embedding
    ↓
Stored in ChromaDB
    ↓
Query
    ↓
Query embedding
    ↓
Similarity search
    ↓
Relevant documents

And that's the basic idea behind using ChromaDB as a vector database.

Wrapping Up

In this article, we looked at the basics of ChromaDB:

This is only the basic usage.

The more interesting part is seeing how we can use ChromaDB in a real application, such as a RAG system, where we can store documents, search for relevant information, and provide those results to an LLM.

We can explore that in another article.

AI agents write code fast. They also silently remove logic, change behavior, and introduce bugs -- without telling you. You often find out in production.

git-lrc fixes this. It hooks into git commit and reviews every diff before it lands. 60-second setup. Completely free.

Any feedback or contributors are welcome! It's online, source-available, and ready for anyone to use.

Give it a ⭐ star on Github