sqlite-vec/site/api-reference.md

API Reference

::: warning sqlite-vec is pre-v1, so expect breaking changes. :::

toc

Meta

TODO

vec_version()

Returns a version string of the current sqlite-vec installation.

select vec_version();
-- 'v0.0.1-alpha.33'

vec_debug()

Returns debugging information of the current sqlite-vec installation.

select vec_debug();
/*
'Version: v0.0.1-alpha.33
Date: 2024-07-14T14:24:27Z-0700
Commit: 18e33edf143cafd881643965a559cd0259ab0666
Build flags: avx '
*/

Constructors

TODO

vec_f32(vector)

Creates a float vector from a BLOB or JSON text. If a BLOB is provided, the length must be divisible by 4, as a float takes up 4 bytes of space each.

The returned value is a BLOB with 4 bytes per element, with a special subtype of 223.

select vec_f32('[.1, .2, .3, 4]');
-- X'CDCCCC3DCDCC4C3E9A99993E008040'

select subtype(vec_f32('[.1, .2, .3, 4]'));
-- 223

select vec_f32(X'AABBCCDD');
-- X'AABBCCDD'

select vec_to_json(vec_f32(X'AABBCCDD'));
-- '[-1844071490169864000.000000]'

select vec_f32(X'AA');
-- ❌ invalid float32 vector BLOB length. Must be divisible by 4, found 1

vec_int8(vector)

Creates a 8-bit integer vector from a BLOB or JSON text. If a BLOB is provided, the length must be divisible by 4, as a float takes up 4 bytes of space each. If JSON text is provided, each element must be an integer between -128 and 127 inclusive.

The returned value is a BLOB with 1 byte per element, with a special subtype of 225.

select vec_int8('[1, 2, 3, 4]');
-- X'1234'

select subtype(vec_int8('[1, 2, 3, 4]'));
-- 225

select vec_int8(X'AABBCCDD');
-- X'AABBCCDD'

select vec_to_json(vec_int8(X'AABBCCDD'));
-- '[-86,-69,-52,-35]'

select vec_int8('[999]');
-- ❌ JSON parsing error: value out of range for int8

vec_bit(vector)

Creates a binary vector from a BLOB.

The returned value is a BLOB with 4 bytes per element, with a special subtype of 224.

select vec_bit(X'F0');
-- X'F0'

select subtype(vec_bit(X'F0'));
-- 224

select vec_to_json(vec_bit(X'F0'));
-- '[0,0,0,0,1,1,1,1]'

Operations

TODO

vec_length(vector)

Returns the number of elements in the given vector. The vector can be JSON, BLOB, or the result of a constructor function.

This function will return an error if vector is invalid.

select vec_length('[.1, .2]');
-- 2

select vec_length(X'AABBCCDD');
-- 1

select vec_length(vec_int8(X'AABBCCDD'));
-- 4

select vec_length(vec_bit(X'AABBCCDD'));
-- 32

select vec_length(X'CCDD');
-- ❌ invalid float32 vector BLOB length. Must be divisible by 4, found 2

vec_add(a, b)

Adds every element in vector a with vector b, returning a new vector c. Both vectors must be of the same type and same length. Only float32 and int8 vectors are supported.

An error is raised if either a or b are invalid, or if they are not the same type or same length.

select vec_add(
  '[.1, .2, .3]',
  '[.4, .5, .6]'
);
-- X'0003F3333333F6766663F'

select vec_to_json(
  vec_add(
    '[.1, .2, .3]',
    '[.4, .5, .6]'
  )
);
-- '[0.500000,0.700000,0.900000]'

select vec_to_json(
  vec_add(
    vec_int8('[1, 2, 3]'),
    vec_int8('[4, 5, 6]')
  )
);
-- '[5,7,9]'

select vec_add('[.1]', vec_int8('[1]'));
-- ❌ Vector type mistmatch. First vector has type float32, while the second has type int8.

select vec_add(vec_bit(X'AA'), vec_bit(X'BB'));
-- ❌ Cannot add two bitvectors together.

vec_sub(a, b)

x

select vec_sub(
  '[.1, .2, .3]',
  '[.4, .5, .6]'
);
-- X'9A9999BE9A9999BE9A9999BE'

select vec_to_json(
  vec_sub(
    '[.1, .2, .3]',
    '[.4, .5, .6]'
  )
);
-- '[-0.300000,-0.300000,-0.300000]'

select vec_to_json(
  vec_sub(
    vec_int8('[1, 2, 3]'),
    vec_int8('[4, 5, 6]')
  )
);
-- '[-3,-3,-3]'

select vec_sub('[.1]', vec_int8('[1]'));
-- ❌ Vector type mistmatch. First vector has type float32, while the second has type int8.

select vec_sub(vec_bit(X'AA'), vec_bit(X'BB'));
-- ❌ Cannot subtract two bitvectors together.

vec_normalize(vector)

x

select 'todo';
-- 'todo'

vec_slice(vector, start, end)

x

select 'todo';
-- 'todo'

vec_to_json(vector)

x

select 'todo';
-- 'todo'

Distance functions

TODO

vec_distance_cosine(a, b)

x

select 'todo';
-- 'todo'

vec_distance_hamming(a, b)

x

select 'todo';
-- 'todo'

vec_distance_l2(a, b)

x

select 'todo';
-- 'todo'

Quantization

TODO

vec_quantize_binary(vector)

x

select 'todo';
-- 'todo'

vec_quantize_i8(vector, [start], [end])

x

select 'todo';
-- 'todo'