Home › API › Vector Embeddings

Vector Embeddings

Store and search vector embeddings in SQLite. Useful for semantic search, recommendations, and AI applications.

Classes

SIMPLE_SQL_VECTOR - Vector data structure
SIMPLE_SQL_VECTOR_STORE - Storage and retrieval
SIMPLE_SQL_SIMILARITY - Distance metrics

SIMPLE_SQL_VECTOR

View Source

Creation

make (a_dimensions: INTEGER)

Create zero vector with specified dimensions.

make_from_array (a_values: ARRAY [REAL_64])

Create vector from array of values.

make_from_blob (a_blob: MANAGED_POINTER)

Deserialize vector from BLOB.

Operations

add (other: SIMPLE_SQL_VECTOR): SIMPLE_SQL_VECTOR

Add two vectors element-wise.

subtract (other: SIMPLE_SQL_VECTOR): SIMPLE_SQL_VECTOR

Subtract vectors element-wise.

scale (a_factor: REAL_64): SIMPLE_SQL_VECTOR

Multiply all elements by factor.

normalize: SIMPLE_SQL_VECTOR

Return unit vector (magnitude = 1).

dot_product (other: SIMPLE_SQL_VECTOR): REAL_64

Compute dot product.

magnitude: REAL_64

Compute Euclidean length.

SIMPLE_SQL_VECTOR_STORE

View Source

Setup

make (a_db: SIMPLE_SQL_DATABASE; a_table: READABLE_STRING_8; a_dimensions: INTEGER)

Create vector store with specified dimensions.

create_table

Create storage table if not exists.

Storage

insert (a_id: READABLE_STRING_GENERAL; a_vector: SIMPLE_SQL_VECTOR)

Store vector with string ID.

insert_with_metadata (a_id: READABLE_STRING_GENERAL; a_vector: SIMPLE_SQL_VECTOR; a_metadata: READABLE_STRING_GENERAL)

Store vector with JSON metadata.

get (a_id: READABLE_STRING_GENERAL): detachable SIMPLE_SQL_VECTOR

Retrieve vector by ID.

delete (a_id: READABLE_STRING_GENERAL)

Remove vector by ID.

Search

knn_search (a_query: SIMPLE_SQL_VECTOR; k: INTEGER): ARRAYED_LIST [TUPLE [id: STRING_32; distance: REAL_64]]

Find k nearest neighbors using Euclidean distance.

cosine_search (a_query: SIMPLE_SQL_VECTOR; k: INTEGER): ARRAYED_LIST [TUPLE [id: STRING_32; similarity: REAL_64]]

Find k most similar vectors using cosine similarity.

SIMPLE_SQL_SIMILARITY

View Source

Distance Metrics

euclidean_distance (a, b: SIMPLE_SQL_VECTOR): REAL_64

L2 distance (shorter = more similar).

cosine_similarity (a, b: SIMPLE_SQL_VECTOR): REAL_64

Cosine of angle between vectors (1.0 = identical, 0.0 = orthogonal).

manhattan_distance (a, b: SIMPLE_SQL_VECTOR): REAL_64

L1 distance (sum of absolute differences).

Examples

Store Document Embeddings

local
    store: SIMPLE_SQL_VECTOR_STORE
    embedding: SIMPLE_SQL_VECTOR
do
    -- Create store for 384-dimensional embeddings
    create store.make (db, "document_vectors", 384)
    store.create_table

    -- Store embeddings (e.g., from a sentence transformer)
    create embedding.make_from_array (get_embedding ("Hello world"))
    store.insert_with_metadata ("doc1", embedding, "{%"title%":%"Greeting%"}")
end

Semantic Search

local
    query_vec: SIMPLE_SQL_VECTOR
    results: ARRAYED_LIST [TUPLE [id: STRING_32; similarity: REAL_64]]
do
    -- Get embedding for search query
    create query_vec.make_from_array (get_embedding ("How to say hello"))

    -- Find 5 most similar documents
    results := store.cosine_search (query_vec, 5)

    across results as r loop
        print (r.id + ": similarity = " + r.similarity.out + "%N")
    end
end

Vector Math

local
    v1, v2, avg: SIMPLE_SQL_VECTOR
    sim: SIMPLE_SQL_SIMILARITY
do
    create v1.make_from_array (<<1.0, 2.0, 3.0>>)
    create v2.make_from_array (<<4.0, 5.0, 6.0>>)

    -- Average of two vectors
    avg := v1.add (v2).scale (0.5)

    -- Similarity
    create sim
    print ("Cosine similarity: " + sim.cosine_similarity (v1, v2).out + "%N")
    print ("Euclidean distance: " + sim.euclidean_distance (v1, v2).out + "%N")
end

Performance Note

Vector search scans all rows. For large datasets (100k+ vectors), consider approximate nearest neighbor solutions or batch queries.