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)

Parameter	Type	Description
`json_array`	TEXT	A 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)

Parameter	Type	Description
`json_array`	TEXT	A 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)

Parameter	Type	Description
`json_array`	TEXT	A 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)

Parameter	Type	Description
`json_array`	TEXT	A 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)

Parameter	Type	Description
`json_array`	TEXT	A 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]');

vector32_sparse

Creates a 32-bit floating-point sparse vector from a JSON array. Only non-zero components are stored, which is efficient for high-dimensional vectors that are mostly zero.

vector32_sparse(json_array)

Parameter	Type	Description
`json_array`	TEXT	A JSON array of numbers, typically with many zeros

Returns: BLOB — the vector in 32-bit float sparse binary format.

SELECT vector32_sparse('[0.0, 0.0, 1.5, 0.0, 0.0, 2.5]');

Sparse vectors can be indexed with the experimental sparse vector index method (enable --experimental-index-method). See CREATE INDEX.

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)

Parameter	Type	Description
`v1`	BLOB	First vector
`v2`	BLOB	Second 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)

Parameter	Type	Description
`v1`	BLOB	First vector
`v2`	BLOB	Second 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)

Parameter	Type	Description
`v1`	BLOB	First vector
`v2`	BLOB	Second 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)

Parameter	Type	Description
`v1`	BLOB	First vector
`v2`	BLOB	Second 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)

Parameter	Type	Description
`vector_blob`	BLOB	A 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, ...)

Parameter	Type	Description
`v1, v2, ...`	BLOB	Two 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)

Parameter	Type	Description
`vector_blob`	BLOB	The source vector
`start`	INTEGER	Start index (zero-based, inclusive)
`end`	INTEGER	End 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]

By default, similarity searches use a linear scan over the table. An experimental sparse vector index method is available behind the --experimental-index-method flag; without it, consider limiting search to a subset of rows with a WHERE clause for large datasets.

Getting Started

Fundamentals

AI and Agents

CLI Reference

SQL Reference

Changelog

Vector Functions

Vector Functions

Vector Creation

vector32

vector64

vector

vector8

vector1bit

vector32_sparse

Distance Functions

vector_distance_cos

vector_distance_l2

vector_distance_dot

vector_distance_jaccard

Utility Functions

vector_extract

vector_concat

vector_slice

Examples

Creating a table with vector embeddings

Similarity search with ORDER BY distance

Cosine distance vs. L2 distance

Working with vector data

See Also

​Vector Functions

​Vector Creation

​vector32

​vector64

​vector

​vector8

​vector1bit

​vector32_sparse

​Distance Functions

​vector_distance_cos

​vector_distance_l2

​vector_distance_dot

​vector_distance_jaccard

​Utility Functions

​vector_extract

​vector_concat

​vector_slice

​Examples

​Creating a table with vector embeddings

​Similarity search with ORDER BY distance

​Cosine distance vs. L2 distance

​Working with vector data

​See Also

Vector Functions

Vector Creation

vector32

vector64

vector

vector8

vector1bit

vector32_sparse

Distance Functions

vector_distance_cos

vector_distance_l2

vector_distance_dot

vector_distance_jaccard

Utility Functions

vector_extract

vector_concat

vector_slice

Examples

Creating a table with vector embeddings

Similarity search with ORDER BY distance

Cosine distance vs. L2 distance

Working with vector data

See Also