asopi tech
asopi techIndie Developer

Alopex DB · Core features

Try it (quickstart)

Create a table and run a vector query with the CLI and Python. The data is stored in a single .alopex file.

Updated: Oct 11, 2026

This walkthrough creates a table and runs a vector query with the CLI and with Python. The database is created as the single file ./data.alopex.

With the CLI

alopex --data-dir ./data.alopex sql "CREATE TABLE docs (id INTEGER PRIMARY KEY, title TEXT NOT NULL, tag TEXT, emb VECTOR(3))"
alopex --data-dir ./data.alopex sql "INSERT INTO docs (id,title,tag,emb) VALUES (1,'raft','db',[0.9,0.1,0.0]),(2,'sqlite','db',[0.1,0.9,0.0]),(3,'cake','food',[0.0,0.1,0.9])"
alopex --data-dir ./data.alopex sql "CREATE INDEX docs_emb ON docs (emb) USING HNSW"
alopex --data-dir ./data.alopex sql "SELECT id,title, vector_similarity(emb,[1.0,0.0,0.0],'cosine') AS score FROM docs WHERE tag='db' ORDER BY score DESC LIMIT 2"
┌────┬────────┬──────────┐
│ id ┆ title  ┆ score    │
╞════╪════════╪══════════╡
│ 1  ┆ raft   ┆ 0.993884 │
├╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌┤
│ 2  ┆ sqlite ┆ 0.110432 │
└────┴────────┴──────────┘

Your data is stored in the single file data.alopex. Copy it as is to take it anywhere.

Writing SQL

Foreign keys, ON CONFLICT, and window functions work as you would expect.

CREATE TABLE customers (id INTEGER PRIMARY KEY, name TEXT);
CREATE TABLE orders (
  id INTEGER PRIMARY KEY,
  customer_id INTEGER NOT NULL REFERENCES customers(id),
  amount INTEGER
);

INSERT INTO orders VALUES (1, 10, 500)
  ON CONFLICT (id) DO UPDATE SET amount = 500 RETURNING id;

SELECT customer_id, SUM(amount) AS total,
       ROW_NUMBER() OVER (ORDER BY SUM(amount) DESC) AS rank
FROM orders GROUP BY customer_id;

With Python

After pip install alopex:

import alopex
db = alopex.Database.open("pydata.alopex")
db.execute_sql("CREATE TABLE t (id INTEGER PRIMARY KEY, n INTEGER)")
db.execute_sql("INSERT INTO t VALUES (1, 10)")
print(db.execute_sql("SELECT id, n FROM t"))   # [{'id': 1, 'n': 10}]

Your data is stored in the single file pydata.alopex.