Turso and libSQL enables vector search capability without an extension.

​

How it works

• Create a table with one or more vector columns (e.g. FLOAT32)
• Provide vector values in binary format or convert text representation to binary using the appropriate conversion function (e.g. vector32(...))
• Calculate vector similarity between vectors in the table or from the query itself using dedicated vector functions (e.g. vector_distance_cos)
• Create a special vector index to speed up nearest neighbors queries (use the libsql_vector_idx(column) expression in the CREATE INDEX statement to create vector index)
• Query the index with the special vector_top_k(idx_name, q_vector, k) table-valued function

​

Vectors

​

Types

LibSQL uses the native SQLite BLOB storage class for vector columns. To align with SQLite affinity rules, all type names have two alternatives: one that is easy to type and another with a _BLOB suffix that is consistent with affinity rules.

The table below lists six vector types currently supported by LibSQL. Types are listed from more precise and storage-heavy to more compact but less precise alternatives (the number of dimensions in vector $D$ is used to estimate storage requirements for a single vector).

​

Functions

To work with vectors, LibSQL provides several functions that operate in the vector domain. Each function understands vectors in binary format aligned with the six types described above or in text format as a single JSON array of numbers.

Currently, LibSQL supports the following functions:

​

Vectors usage

CREATE TABLE movies (
  title    TEXT,
  year     INT,
  full_emb F32_BLOB(4) -- 4-dimensional f32 vector
);

INSERT INTO movies (title, year, embedding)
VALUES
  ('Napoleon', 2023, vector32('[0.800, 0.579, 0.481, 0.229]')),
  ('Black Hawk Down', 2001, vector32('[0.406, 0.027, 0.378, 0.056]')),
  ('Gladiator', 2000, vector32('[0.698, 0.140, 0.073, 0.125]')),
  ('Blade Runner', 1982, vector32('[0.379, 0.637, 0.011, 0.647]'));

SELECT title,
       vector_extract(embedding),
       vector_distance_cos(embedding, vector32('[0.064, 0.777, 0.661, 0.687]'))
FROM movies
ORDER BY
       vector_distance_cos(embedding, vector32('[0.064, 0.777, 0.661, 0.687]'))
ASC;

​

Understanding Distance Results

The vector_distance_cos function calculates the cosine distance, which is defined at:

• Cosine Distance = 1 — Cosine Similarity

The cosine distance ranges from 0 to 2, where:

• A distance close to 0 indicates that the vectors are nearly identical or exactly matching.
• A distance close to 1 indicates that the vectors are orthogonal (perpendicular).
• A distance close to 2 indicates that the vectors are pointing in opposite directions.

SELECT vector_distance_cos('[1000]', '[1000]');
-- Output: -2.0479999918166e-09

​

Vector Limitations

• Euclidian distance is not supported for 1-bit FLOAT1BIT vectors
• LibSQL can only operate on vectors with no more than 65536 dimensions

​

Indexing

Nearest neighbors (NN) queries are popular for various AI-powered applications (RAG uses NN queries to extract relevant information, and recommendation engines can suggest items based on embedding similarity).

LibSQL implements DiskANN algorithm in order to speed up approximate neareast neighbors queries for tables with vector colums.

​

Vector Index

LibSQL introduces a custom index type that helps speed up nearest neighbors queries against a fixed distance function (cosine similarity by default).

From a syntax perspective, the vector index differs from ordinary application-defined B-Tree indices in that it must wrap the vector column into a libsql_vector_idx marker function like this

CREATE INDEX movies_idx ON movies (libsql_vector_idx(embedding));

The vector index is fully integrated into the LibSQL core, so it inherits all operations and most features from ordinary indices:

• An index created for a table with existing data will be automatically populated with this data
• All updates to the base table will be automatically reflected in the index
• You can rebuild index from scratch using REINDEX movies_idx command
• You can drop index with DROP INDEX movies_idx command
• You can create partial vector index with a custom filtering rule:

CREATE INDEX movies_idx ON movies (libsql_vector_idx(embedding))
WHERE year >= 2000;

​

Query

At the moment vector index must be queried explicitly with special vector_top_k(idx_name, q_vector, k) table-valued function. The function accepts index name, query vector and amount of neighbors to return. This function search for k approximate nearest neighbors and return ROWID of these rows or PRIMARY KEY if base index do not have ROWID.

In order for table-valued function to work query vector must have same vector type and same dimensionality.

​

Settings

LibSQL vector index optionally can accept settings which must be specified as a variadic parameters of the libsql_vector_idx function as a strings in the format key=value:

CREATE INDEX movies_idx
ON movies(libsql_vector_idx(embedding, 'metric=l2', 'compress_neighbors=float8'));

At the moment LibSQL supports following settings:

​

Index usage

CREATE TABLE movies (
  title    TEXT,
  year     INT,
  full_emb F32_BLOB(4), -- 4-dimensional f32 vector
);

INSERT INTO movies (title, year, embedding)
VALUES
  ('Napoleon', 2023, vector32('[0.800, 0.579, 0.481, 0.229]')),
  ('Black Hawk Down', 2001, vector32('[0.406, 0.027, 0.378, 0.056]')),
  ('Gladiator', 2000, vector32('[0.698, 0.140, 0.073, 0.125]')),
  ('Blade Runner', 1982, vector32('[0.379, 0.637, 0.011, 0.647]'));

CREATE INDEX movies_idx ON movies(libsql_vector_idx(embedding));

SELECT title, year
FROM vector_top_k('movies_idx', vector32('[0.064, 0.777, 0.661, 0.687]'), 3)
JOIN movies ON movies.rowid = id
WHERE year >= 2020;

​

Index limitations

• Vector index works only for tables with ROWID or with singular PRIMARY KEY. Composite PRIMARY KEY without ROWID is not supported