Embeddings

GalaxDB computes text embeddings locally — no external API, no data leaving your machine. Embeddings are computed automatically when you insert rows into a table with an EMBEDDING MODEL column.

How It Works

When you declare a column with EMBEDDING MODEL 'model-id' DIM n, GalaxDB registers that column as an embedding source. On every INSERT, the text value is sent to the sidecar process, which returns a float32 vector of dimension n. That vector is stored alongside the row and indexed in the HNSW graph.

INSERT INTO docs (id, body) VALUES (1, 'machine learning')
         ↓
  galaxdb-server receives INSERT
         ↓
  sends 'machine learning' to galaxdb-sidecar
         ↓
  sidecar returns float32[384]
         ↓
  row stored + HNSW index updated

Sidecar Process

The sidecar (galaxdb-sidecar) is a separate process that loads the HuggingFace model and serves embedding requests over a local socket. This isolation means:

The main database process never loads Python or ML frameworks
A sidecar crash doesn't crash the database — writes are queued and drained on recovery
The sidecar can be updated independently of the database binary

Start the server with sidecar support:

bash

galaxdb-server \
  --data-dir ./data \
  --sidecar /usr/local/bin/galaxdb-sidecar \
  --model sentence-transformers/all-MiniLM-L6-v2

On first run, the sidecar downloads the model from HuggingFace Hub (~90 MB for all-MiniLM-L6-v2). Subsequent starts use the local cache at ~/.cache/huggingface.

Warning

If the sidecar is unavailable (not started, crashed, or model failed to load), INSERT into embedding columns returns a SidecarUnavailable error. GalaxDB never silently stores zero vectors or falls back to mock embeddings.

Supported Models

Any BERT-style sentence-transformer from HuggingFace Hub is supported. The model ID is passed to the sidecar at startup via --model.

Model	Dim	Size	Use case
sentence-transformers/all-MiniLM-L6-v2	384	90 MB	General purpose, fast
sentence-transformers/all-mpnet-base-v2	768	420 MB	Higher quality
BAAI/bge-small-en-v1.5	384	130 MB	Retrieval-optimized

Note

No model is hard-coded. Any model ID that works with the sentence-transformers library can be used. The DIM value in the CREATE TABLE statement must match the model's output dimension.

Embedding Column Syntax

SQL

CREATE TABLE table_name (
    -- Regular columns
    id   INT PRIMARY KEY,
    title TEXT,

    -- Embedding column: TEXT with automatic vectorization
    body TEXT EMBEDDING MODEL 'sentence-transformers/all-MiniLM-L6-v2' DIM 384
);

The EMBEDDING MODEL clause is an AuroraSQL extension. The column stores the original text value (accessible via SELECT) and the computed vector (used by SEMANTIC_MATCH and the HNSW index).

You can have multiple embedding columns in one table, each with a different model:

SQL

CREATE TABLE multilingual (
    id      INT PRIMARY KEY,
    en_text TEXT EMBEDDING MODEL 'sentence-transformers/all-MiniLM-L6-v2' DIM 384,
    de_text TEXT EMBEDDING MODEL 'sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2' DIM 384
);

Health Check

Check the sidecar status with SHOW EMBEDDING HEALTH:

SQL

-- Global sidecar status
SHOW EMBEDDING HEALTH;

-- Status for a specific table
SHOW EMBEDDING HEALTH FOR docs;

Or via the HTTP observability endpoint:

bash

curl http://localhost:9090/health
# {"status":"ok","version":"1.0.0-beta.1","subsystems":{"disk_full":false,"sidecar_healthy":true,"connections_active":2}}

The Prometheus metrics endpoint also exposes embedding queue depth and backlog:

bash

curl http://localhost:9090/metrics | grep embedding
# galaxdb_embedding_queue_depth 0
# galaxdb_embedding_backlog_depth 0
# galaxdb_sidecar_status 1

Storage Engine

Vector Search