/ 
SQLite-VecDB-0.001
/ SQLite::VecDB::Collection

NAME

SQLite::VecDB::Collection - A named vector collection in SQLite::VecDB

VERSION

version 0.001

SYNOPSIS

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

$coll->add(id => 'doc1', vector => [...], metadata => { title => 'Hi' });
$coll->add(id => 'doc2', vector => [...], content => 'Some text');

my @results = $coll->search(vector => [...], limit => 5);
my $result  = $coll->get(id => 'doc1');
my $count   = $coll->count;
$coll->delete(id => 'doc1');

DESCRIPTION

Represents a named vector collection backed by a sqlite-vec virtual table and a companion metadata table. Created via "collection" in SQLite::VecDB.

When the parent SQLite::VecDB has an embedding engine, SQLite::VecDB::Role::Embedding is applied automatically, adding add_text and search_text methods.

name

The collection name. Used as suffix for the underlying SQLite tables.

add

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

Store a vector with optional metadata and content. The vector ArrayRef must have exactly dimensions elements.

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

Perform a KNN (k-nearest neighbor) search. Returns a list of SQLite::VecDB::Result objects ordered by distance (closest first).

get

my $result = $coll->get(id => 'doc1');

Retrieve a stored entry by ID. Returns a SQLite::VecDB::Result or undef if not found.

delete

$coll->delete(id => 'doc1');

Delete a stored vector by ID. Returns 1 if deleted, 0 if not found.

count

my $n = $coll->count;

Returns the number of vectors in this collection.

add_batch

$coll->add_batch(
  { id => 'doc1', vector => [...] },
  { id => 'doc2', vector => [...], metadata => { ... } },
);

Add multiple vectors in a single transaction.

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.