/ 
SQLite-VecDB-0.001
/ SQLite::VecDB

NAME

SQLite::VecDB - SQLite as a vector database using sqlite-vec

VERSION

version 0.001

SYNOPSIS

use SQLite::VecDB;

my $vdb = SQLite::VecDB->new(
  db_file    => 'vectors.db',   # or ':memory:'
  dimensions => 768,
);

my $coll = $vdb->collection('documents');

# Store a vector
$coll->add(
  id       => 'doc1',
  vector   => [0.1, 0.2, ...],
  metadata => { title => 'Hello World' },
  content  => 'Original text content',
);

# KNN search
my @results = $coll->search(
  vector => [0.1, 0.2, ...],
  limit  => 5,
);

for my $r (@results) {
  say $r->id;        # 'doc1'
  say $r->distance;  # 0.042
  say $r->metadata;  # { title => 'Hello World' }
  say $r->content;   # 'Original text content'
}

DESCRIPTION

SQLite::VecDB turns SQLite into a vector database using the sqlite-vec extension. It supports storing vectors with metadata, KNN (k-nearest neighbor) search, and optional automatic embedding generation via Langertha.

db_file

Path to the SQLite database file. Use :memory: for an in-memory database.

dimensions

The number of dimensions for vectors in this database. Must match the embedding model you are using (e.g. 768 for nomic-embed-text, 1536 for OpenAI text-embedding-3-small).

distance_metric

Distance metric for vector search. Default is cosine. Supported by sqlite-vec: cosine, l2, l1.

embedding

Optional. A Langertha engine instance that supports the Langertha::Role::Embedding role. When set, collections gain add_text and search_text methods that automatically generate embeddings.

sqlite_vec_path

Path to the sqlite-vec shared library. Auto-detected from $ENV{SQLITE_VEC_PATH} or Alien::sqlite_vec if not specified.

collection

my $coll = $vdb->collection('documents');
my $coll = $vdb->collection;  # uses '_default'

Returns a SQLite::VecDB::Collection for the given name. Creates the underlying tables on first use.

collections

my @names = $vdb->collections;

Returns the names of all existing collections.

WITH LANGERTHA — AUTOMATIC EMBEDDINGS

use SQLite::VecDB;
use Langertha::Engine::OpenAI;

my $engine = Langertha::Engine::OpenAI->new(
  api_key => $ENV{OPENAI_API_KEY},
);

my $vdb = SQLite::VecDB->new(
  db_file    => 'vectors.db',
  dimensions => 1536,
  embedding  => $engine,
);

my $coll = $vdb->collection('docs');

# Text is automatically embedded
$coll->add_text(
  id   => 'doc1',
  text => 'Kubernetes is a container orchestration platform.',
);

# Query is automatically embedded
my @results = $coll->search_text(
  text  => 'container management',
  limit => 5,
);

EMBEDDING SETUP

SQLite::VecDB stores and searches raw vectors. To generate embeddings from text, pass any Langertha engine that supports Langertha::Role::Embedding as the embedding attribute.

Local Embeddings with Ollama (Recommended for Getting Started)

The easiest way to run embeddings locally — no API key, no cloud, free:

# Start Ollama in Docker
docker run -d -p 11434:11434 --name ollama ollama/ollama

# Pull an embedding model (768 dimensions, ~270MB)
docker exec ollama ollama pull nomic-embed-text

Then in Perl:

use SQLite::VecDB;
use Langertha::Engine::Ollama;

my $engine = Langertha::Engine::Ollama->new(
  url             => 'http://localhost:11434',
  embedding_model => 'nomic-embed-text',
);

my $vdb = SQLite::VecDB->new(
  db_file    => 'my_vectors.db',
  dimensions => 768,
  embedding  => $engine,
);
Model                            Dimensions  Provider
─────────────────────────────────────────────────────
nomic-embed-text (Ollama)        768         Local
all-minilm (Ollama)              384         Local
mxbai-embed-large (Ollama)       1024        Local
text-embedding-3-small (OpenAI)  1536        Cloud
text-embedding-3-large (OpenAI)  3072        Cloud

Cloud Embeddings with OpenAI

use Langertha::Engine::OpenAI;

my $engine = Langertha::Engine::OpenAI->new(
  api_key => $ENV{OPENAI_API_KEY},
);

my $vdb = SQLite::VecDB->new(
  db_file    => 'vectors.db',
  dimensions => 1536,   # text-embedding-3-small default
  embedding  => $engine,
);

SQLITE-VEC EXTENSION

The sqlite-vec extension must be available as a shared library. SQLite::VecDB finds it in this order:

1. The sqlite_vec_path attribute (explicit path)
2. $ENV{SQLITE_VEC_PATH} environment variable
3. Alien::sqlite_vec (installs and compiles it automatically)

SEE ALSO

SUPPORT

Issues

Please report bugs and feature requests on GitHub at https://github.com/Getty/p5-sqlite-vecdb/issues.

CONTRIBUTING

Contributions are welcome! Please fork the repository and submit a pull request.

AUTHOR

Torsten Raudssus <torsten@raudssus.us>

COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Torsten Raudssus.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.