Skip to main content
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.

​
Defining a database

Extend AbstractVectorDatabase<DataType> and implement three getters. The type parameter must have a metadata object — it carries your custom fields through records, filters, and results. 
import { AbstractVectorDatabase } from "@ooneex/rag";
import type {
  EmbeddingModelType,
  EmbeddingProviderType,
  FieldValueType,
} from "@ooneex/rag";
import { Utf8 } from "apache-arrow";

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

class ArticleVectorDatabase extends AbstractVectorDatabase<ArticleData> {
  public getDatabaseUri = (): string => "./data/articles.lance";

  public getEmbeddingModel = (): {
    provider: EmbeddingProviderType;
    model: EmbeddingModelType["model"];
  } => ({ provider: "openai", model: "text-embedding-3-small" });

  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.

​
getEmbeddingModel()

Returns the embedding provider and model. The provider is openai; the model is one of the OpenAI embedding models. See Embeddings for the full list.

​
getSchema()

Returns the schema for your custom columns, using Apache Arrow data types. The id, text, and vector columns are added automatically — 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 search is fast immediately:
ColumnIndexPurpose
idbtreeFast lookups by identifier.
textfull-text (FTS)Keyword half of hybrid search.
vectorIVF-PQApproximate nearest-neighbor (semantic) search.

​
Options

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

​
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 "@ooneex/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 "@ooneex/container";

@decorator.vectorDatabase(EContainerScope.Transient)
class ArticleVectorDatabase extends AbstractVectorDatabase<ArticleData> {
  // ...
}
Resolve it from the container: 
import { container } from "@ooneex/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 "@ooneex/rag";

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