Skip to main content

​
Vector Functions

Turso Extension: Vector functions are a Turso-specific feature for working with vector embeddings directly in SQL. These functions are not part of the SQLite standard.
Turso provides built-in functions for storing and querying vector embeddings. Vectors are stored as BLOBs in a compact binary format and can be compared using distance functions for similarity search.

​
Vector Creation

​
vector32

Creates a 32-bit floating-point vector from a JSON array of numbers. 
vector32(json_array)
ParameterTypeDescription
json_arrayTEXTA JSON array of numbers, e.g. '[1.0, 2.0, 3.0]'
Returns: BLOB — the vector in 32-bit float binary format. This is the most common vector format and offers a good balance of precision and storage efficiency. Each dimension uses 4 bytes. 
SELECT vector32('[1.0, 2.0, 3.0]');
-- (BLOB: 12 bytes)

-- Store embeddings in a table
CREATE TABLE documents (
    id INTEGER PRIMARY KEY,
    content TEXT,
    embedding BLOB
);

INSERT INTO documents VALUES (1, 'Introduction to databases', vector32('[0.1, 0.3, 0.5, 0.7]'));

​
vector64

Creates a 64-bit floating-point vector from a JSON array of numbers. 
vector64(json_array)
ParameterTypeDescription
json_arrayTEXTA JSON array of numbers, e.g. '[1.0, 2.0, 3.0]'
Returns: BLOB — the vector in 64-bit float binary format. Use this format when you need higher precision. Each dimension uses 8 bytes. 
SELECT vector64('[1.0, 2.0, 3.0]');
-- (BLOB: 24 bytes)

​
vector

Creates a vector using the default format (32-bit float). 
vector(json_array)
ParameterTypeDescription
json_arrayTEXTA JSON array of numbers
Returns: BLOB — the vector in default (32-bit float) binary format. 
SELECT vector('[1.0, 2.0, 3.0]');

​
vector8

Creates an 8-bit quantized vector from a JSON array of numbers. 
vector8(json_array)
ParameterTypeDescription
json_arrayTEXTA JSON array of integer values (0-255)
Returns: BLOB — the vector in 8-bit integer binary format. Use this format for storage-efficient approximate representations. Each dimension uses 1 byte. 
SELECT vector8('[128, 64, 255, 0]');

​
vector1bit

Creates a 1-bit binary vector from a JSON array. 
vector1bit(json_array)
ParameterTypeDescription
json_arrayTEXTA JSON array of 0s and 1s
Returns: BLOB — the vector in 1-bit binary format. Use this format for extremely compact representations. Eight dimensions are packed into a single byte. 
SELECT vector1bit('[1, 0, 1, 1, 0, 0, 1, 0]');

​
Distance Functions

Distance functions compute the distance between two vectors. Smaller values indicate more similar vectors.

​
vector_distance_cos

Computes the cosine distance between two vectors, defined as 1 - cosine_similarity. A result of 0 means the vectors are identical in direction; a result of 1 means they are orthogonal. 
vector_distance_cos(v1, v2)
ParameterTypeDescription
v1BLOBFirst vector
v2BLOBSecond vector (must have the same number of dimensions as v1)
Returns: REAL — the cosine distance between the two vectors. 
SELECT vector_distance_cos(
    vector32('[1.0, 0.0, 0.0]'),
    vector32('[0.0, 1.0, 0.0]')
);
-- 1.0 (orthogonal vectors)

SELECT vector_distance_cos(
    vector32('[1.0, 0.0]'),
    vector32('[1.0, 0.0]')
);
-- 0.0 (identical vectors)

​
vector_distance_l2

Computes the Euclidean (L2) distance between two vectors. A result of 0 means the vectors are identical. 
vector_distance_l2(v1, v2)
ParameterTypeDescription
v1BLOBFirst vector
v2BLOBSecond vector (must have the same number of dimensions as v1)
Returns: REAL — the Euclidean distance between the two vectors. 
SELECT vector_distance_l2(
    vector32('[1.0, 0.0, 0.0]'),
    vector32('[0.0, 1.0, 0.0]')
);
-- 1.4142135623730951

SELECT vector_distance_l2(
    vector32('[3.0, 4.0]'),
    vector32('[0.0, 0.0]')
);
-- 5.0

​
vector_distance_dot

Computes the negative dot product distance between two vectors. The result is the negation of the dot product, so smaller (more negative) values indicate higher similarity. 
vector_distance_dot(v1, v2)
ParameterTypeDescription
v1BLOBFirst vector
v2BLOBSecond vector (must have the same number of dimensions as v1)
Returns: REAL — the negative dot product of the two vectors. 
SELECT vector_distance_dot(
    vector32('[1.0, 2.0, 3.0]'),
    vector32('[4.0, 5.0, 6.0]')
);
-- -32.0 (dot product is 32)

​
vector_distance_jaccard

Computes the Jaccard distance between two binary vectors. Best suited for use with vector1bit vectors. 
vector_distance_jaccard(v1, v2)
ParameterTypeDescription
v1BLOBFirst vector
v2BLOBSecond vector (must have the same number of dimensions as v1)
Returns: REAL — the Jaccard distance between the two vectors.

​
Utility Functions

​
vector_extract

Converts a vector BLOB back to a JSON text representation. 
vector_extract(vector_blob)
ParameterTypeDescription
vector_blobBLOBA vector created by vector32, vector64, or another vector function
Returns: TEXT — a JSON array string of the vector’s components. 
SELECT vector_extract(vector32('[1.5, 2.5, 3.5]'));
-- [1.500000,2.500000,3.500000]

​
vector_concat

Concatenates two or more vectors into a single vector. 
vector_concat(v1, v2, ...)
ParameterTypeDescription
v1, v2, ...BLOBTwo or more vectors to concatenate. All vectors must be the same type.
Returns: BLOB — a new vector containing the dimensions of all input vectors in order. 
SELECT vector_extract(
    vector_concat(
        vector32('[1.0, 2.0]'),
        vector32('[3.0, 4.0]')
    )
);
-- [1.000000,2.000000,3.000000,4.000000]

​
vector_slice

Extracts a contiguous portion of a vector. 
vector_slice(vector_blob, start, end)
ParameterTypeDescription
vector_blobBLOBThe source vector
startINTEGERStart index (zero-based, inclusive)
endINTEGEREnd index (exclusive)
Returns: BLOB — a new vector containing dimensions from start to end - 1. 
SELECT vector_extract(
    vector_slice(vector32('[10.0, 20.0, 30.0, 40.0, 50.0]'), 1, 4)
);
-- [20.000000,30.000000,40.000000]

​
Examples

​
Creating a table with vector embeddings

CREATE TABLE articles (
    id INTEGER PRIMARY KEY,
    title TEXT NOT NULL,
    content TEXT,
    embedding BLOB
);

INSERT INTO articles VALUES (
    1,
    'Introduction to Machine Learning',
    'Machine learning is a subset of artificial intelligence...',
    vector32('[0.12, -0.34, 0.56, 0.78, -0.11, 0.45, -0.23, 0.67]')
);

INSERT INTO articles VALUES (
    2,
    'Database Design Patterns',
    'Relational databases organize data into tables...',
    vector32('[0.82, 0.15, -0.44, 0.23, 0.61, -0.33, 0.09, 0.77]')
);

INSERT INTO articles VALUES (
    3,
    'Neural Networks Explained',
    'Neural networks are computing systems inspired by biological neural networks...',
    vector32('[0.14, -0.28, 0.62, 0.71, -0.09, 0.51, -0.18, 0.59]')
);

​
Similarity search with ORDER BY distance

-- Find articles most similar to a query embedding using cosine distance
SELECT
    id,
    title,
    vector_distance_cos(embedding, vector32('[0.1, -0.3, 0.5, 0.8, -0.1, 0.4, -0.2, 0.6]')) AS distance
FROM articles
ORDER BY distance ASC
LIMIT 5;

​
Cosine distance vs. L2 distance

Cosine distance measures the angle between two vectors, ignoring magnitude. L2 distance measures the absolute distance in space. 
-- Cosine distance: direction matters, not magnitude
SELECT vector_distance_cos(
    vector32('[1.0, 0.0]'),
    vector32('[100.0, 0.0]')
);
-- 0.0 (same direction, cosine distance is 0)

-- L2 distance: magnitude matters
SELECT vector_distance_l2(
    vector32('[1.0, 0.0]'),
    vector32('[100.0, 0.0]')
);
-- 99.0 (very far apart in absolute terms)
Use cosine distance when you care about the direction of the vector (e.g., semantic similarity of text embeddings). Use L2 distance when absolute position matters (e.g., geospatial coordinates or image feature vectors).

​
Working with vector data

-- Inspect the contents of a stored vector
SELECT vector_extract(embedding) FROM articles WHERE id = 1;

-- Concatenate vectors from two different models
SELECT vector_extract(
    vector_concat(
        (SELECT embedding FROM articles WHERE id = 1),
        (SELECT embedding FROM articles WHERE id = 2)
    )
);

-- Extract the first 4 dimensions of an embedding
SELECT vector_extract(
    vector_slice(embedding, 0, 4)
) FROM articles WHERE id = 1;
-- [0.120000,-0.340000,0.560000,0.780000]
Vector indexes are not yet supported. All similarity searches use a linear scan over the table. For large datasets, consider limiting search to a subset of rows with a WHERE clause.

​
See Also