Vector Database

A vector database describes where your data lives, which embedding model turns text into vectors, and what the schema looks like. You define one by extending AbstractVectorDatabase, then connect to it and open tables.

Don’t need custom fields beyond metadata? Use the ready-made VectorDatabase class instead of writing your own subclass — see Using the default database.

Defining a database

Extend AbstractVectorDatabase<DataType> and implement two getters. The type parameter must have a metadata object, which carries your custom fields through records, filters, and results.

import { AbstractVectorDatabase } from "@talosjs/rag";
import type { EmbeddingModelType, FieldValueType } from "@talosjs/rag";
import { Utf8 } from "apache-arrow";

type ArticleData = {
  metadata: {
    title: string;
    category: string;
  };
};

class ArticleVectorDatabase extends AbstractVectorDatabase<ArticleData> {
  public constructor(embeddingModel: EmbeddingModelType = { model: "qwen3-embedding-8b" }) {
    super(embeddingModel);
  }

  public getDatabaseUri = (): string => "./data/articles.lance";

  public getSchema = (): { [K in keyof ArticleData]: FieldValueType } => ({
    metadata: new Utf8(),
  });
}

`getDatabaseUri()`

Returns the URI where LanceDB stores its data: a local directory path (./data/articles.lance) or a remote/object-store URI supported by LanceDB.

The constructor

The base class constructor takes the EmbeddingModelType to use and exposes it through getEmbeddingModel(). Every model is served through OpenRouter — see Embeddings for the full list and how to pick one.

`getSchema()`

Returns the schema for your custom columns, using Apache Arrow data types. The id, text, and vector columns are added automatically, so you only declare the rest. The accepted types are listed in FieldValueType.

Connecting

Call connect() before any table operation. It opens the LanceDB connection at the database URI.

const db = new ArticleVectorDatabase();
await db.connect();

getDatabase() returns the underlying LanceDB Connection. It throws a VectorDatabaseException if you call it before connect().

const connection = db.getDatabase(); // throws if not connected

Opening a table

open() returns a VectorTable. If the table already exists it is opened as-is; if it does not exist, it is created with the schema and indexed automatically.

const table = await db.open("articles");

On creation, three indexes are built so the first searches are already fast:

Column	Index	Purpose
`id`	btree	Fast lookups by identifier.
`text`	full-text (FTS)	Keyword half of hybrid search.
`vector`	IVF-PQ	Approximate nearest-neighbor (semantic) search.

Options

Option	Type	Default	Description
`mode`	`"create" \| "overwrite"`	`"overwrite"`	How to create the table when it does not yet exist. `"create"` fails if it exists at the storage layer; `"overwrite"` replaces it.

const table = await db.open("articles", { mode: "create" });

The mode option only applies when the table is being created. If a table with that name already exists, open() returns the existing table and ignores mode.

The `VectorDatabase` starting point

VectorDatabase is a minimal, ready-to-extend AbstractVectorDatabase with an untyped Record<string, unknown> metadata schema, defaulting to the qwen3-embedding-8b embedding model. It’s what talos vector-database:create scaffolds for you — override getDatabaseUri() (and getSchema(), if you need typed fields) rather than writing AbstractVectorDatabase boilerplate from scratch.

import { VectorDatabase } from "@talosjs/rag";

class NotesVectorDatabase extends VectorDatabase {
  public override getDatabaseUri = (): string => "./data/notes.lance";
}

Pass a different embedding model through the constructor if you don’t want the default:

const db = new NotesVectorDatabase({ model: "text-embedding-3-small" });

Registering with the container

Use the decorator.vectorDatabase() decorator to register your database class with the DI container, then resolve it anywhere.

import { decorator } from "@talosjs/rag";

@decorator.vectorDatabase()
class ArticleVectorDatabase extends AbstractVectorDatabase<ArticleData> {
  // ...
}

By default the class is registered as a singleton. Pass a scope to change that:

import { EContainerScope } from "@talosjs/container";

@decorator.vectorDatabase(EContainerScope.Transient)
class ArticleVectorDatabase extends AbstractVectorDatabase<ArticleData> {
  // ...
}

Resolve it from the container:

import { container } from "@talosjs/container";

const db = container.get(ArticleVectorDatabase);
await db.connect();

`FieldValueType`

Schema fields accept these Apache Arrow types: Null, Bool, Int8–Int64, Uint8–Uint64, Float16–Float64, Utf8, LargeUtf8, Binary, LargeBinary, Decimal, DateDay, DateMillisecond, and EmbeddingFunction.

Exceptions

VectorDatabaseException is thrown when a database operation fails, most commonly calling getDatabase() (directly or via open()) before connect(). It carries a machine-readable key (for example VECTOR_DB_NOT_CONNECTED) and a human-readable message.

import { VectorDatabaseException } from "@talosjs/rag";

try {
  db.getDatabase();
} catch (error) {
  if (error instanceof VectorDatabaseException) {
    console.error(`[${error.key}] ${error.message}`);
  }
}

Getting Started

AI

Framework

Command Line

Vector Database

Defining a database

`getDatabaseUri()`

The constructor

`getSchema()`

Connecting

Opening a table

Options

The `VectorDatabase` starting point

Registering with the container

`FieldValueType`

Exceptions

​Defining a database

​getDatabaseUri()

​The constructor

​getSchema()

​Connecting

​Opening a table

​Options

​The VectorDatabase starting point

​Registering with the container

​FieldValueType

​Exceptions

Defining a database

`getDatabaseUri()`

The constructor

`getSchema()`

Connecting

Opening a table

Options

The `VectorDatabase` starting point

Registering with the container

`FieldValueType`

Exceptions