Python Library¶

akasicdb is the official Python client library for AkasicDB. It provides a high-level SDK for vector search, Psycopg3 type registration, SQLAlchemy and Django integrations, vector index option helpers, and graph query utilities.

For runnable code paths, see Python Library Examples.

Requirements¶

Python 3.11 or later
A running AkasicDB instance
A database user that can create tables, and indexes when needed

Start AkasicDB first by following the Quick Start guide.

Installation¶

Install the package with the optional features you need.

pip install "akasicdb"
pip install "akasicdb[sdk]"
pip install "akasicdb[sqlalchemy]"
pip install "akasicdb[django]"
pip install "akasicdb[all]"

Use akasicdb[sdk] when you want the high-level AkasicDB client. Use akasicdb[all] when you want to install every supported integration.

The package version should match the AkasicDB server version.

AkasicDB version	Recommended `akasicdb` version
`0.1.*`	`0.1.*`
`0.2.*`	`0.2.*`
`1.0.*`	`1.0.*`

Connection URLs¶

The high-level SDK and SQLAlchemy integration use SQLAlchemy connection URLs.

postgresql+psycopg://postgres:mysecretpassword@localhost:5432/postgres

The Psycopg3 and graph helper APIs use Psycopg connection URLs.

postgresql://postgres:mysecretpassword@localhost:5432/postgres

Package Areas¶

Area	Import path	Purpose
High-level SDK	`akasicdb.sdk`	Store records and run vector search without writing SQL
Psycopg3 integration	`akasicdb.psycopg`	Register AkasicDB vector types for direct Psycopg3 usage
SQLAlchemy integration	`akasicdb.sqlalchemy`	Define vector columns and distance expressions in SQLAlchemy models
Django integration	`akasicdb.django`	Define vector fields, indexes, and distance functions in Django models
Vector and index types	`akasicdb.types`	Build vector values and index option strings
Graph utilities	`akasicdb.graph`	Execute Cypher queries through AkasicDB

Typical imports:

from akasicdb.sdk import AkasicDB, Record
from akasicdb.psycopg import register_vector
from akasicdb.sqlalchemy import VECTOR
from akasicdb.django import VectorField
from akasicdb.types import Hnsw, IndexOption
from akasicdb.graph import execute_cypher

High-Level SDK¶

The SDK stores text, metadata, and embeddings in an AkasicDB-backed collection. It creates a table named collection_<collection_name> and can create a vector index on the embedding column.

from akasicdb.sdk import AkasicDB, Record

client = AkasicDB(DB_URL, "docs", dimension=3, create_vector_index=True)
client.insert([Record.from_text("hello akasicdb", [1.0, 2.0, 3.0])])
results = client.search([1.0, 2.0, 3.5], top_k=3)

Primary objects:

Object	Description
`AkasicDB`	Client for one collection
`Record`	Text, metadata, UUID, and embedding container
`filters`	Helpers for metadata and text filters
`GraphQuery`	Fluent graph query builder
`SqlQuery`	Fluent SQL query builder
`ComposedQuery`	SQL/GQL query composer

Common client operations:

Operation	Method
Insert records	`insert()`
Similarity search	`search()`
Retrieve records	`get()`
Count records	`row_count()`
Delete records	`delete()`, `delete_by_ids()`, `delete_all()`
Drop the collection table	`drop()`
Release connections	`close()`

search() supports the <->, <=>, and <#> distance operators. Metadata filters can use $eq, $ne, $gt, $lt, $gte, $lte, $in, $nin, $and, and $or.

See High-Level SDK for a complete example.

Psycopg3 Integration¶

Use akasicdb.psycopg.register_vector() when working directly with Psycopg3. Registering vector types lets Psycopg convert AkasicDB vector values to Python objects and bind Python values in SQL parameters.

import psycopg

from akasicdb.psycopg import register_vector

with psycopg.connect(DB_URL) as conn:
    register_vector(conn)
    conn.execute("INSERT INTO documents (embedding) VALUES (%s)", ([1, 2, 3],))

See Psycopg3 for a complete example.

SQLAlchemy Integration¶

The SQLAlchemy integration provides AkasicDB vector column types and distance methods.

from sqlalchemy.orm import mapped_column

from akasicdb.sqlalchemy import VECTOR

class Document(Base):
    __tablename__ = "documents"
    embedding = mapped_column(VECTOR(3))

AkasicDB type	SQLAlchemy type
`vector`	`VECTOR`
`svector`	`SVECTOR`
`vecf16`	`VECF16`
`bvector`	`BVECTOR`

Distance methods include l2_distance, max_inner_product, cosine_distance, and jaccard_distance for binary vectors.

See SQLAlchemy for a complete example.

Django Integration¶

The Django integration provides model fields, migration helpers, vector indexes, and distance functions.

from django.db import models

from akasicdb.django import L2Distance, VectorField

class Document(models.Model):
    embedding = VectorField(dim=3)

Document.objects.order_by(L2Distance("embedding", [1.0, 2.0, 3.0]))

AkasicDB type	Django field
`vector`	`VectorField`
`svector`	`SparseVectorField`
`vecf16`	`Float16VectorField`
`bvector`	`BinaryVectorField`

Supported index classes include HnswIndex, IvfIndex, and VamanaIndex.

See Django for a complete example.

Vector Types and Index Options¶

akasicdb.types provides Python objects for AkasicDB vector values and index options.

from akasicdb.types import Hnsw, IndexOption, SparseVector

sparse = SparseVector({0: 1.0, 2: 3.0}, 4)
options = IndexOption(index=Hnsw(m=16), threads=1).dumps()

Common vector classes:

Class	Purpose
`Vector`	Dense vector value
`SparseVector`	Sparse vector value
`Float16Vector`	Half-precision vector value
`BinaryVector`	Binary vector value

Common index option classes:

Class	Purpose
`IndexOption`	Common options and index-specific options
`Flat`	Flat index options
`Hnsw`	HNSW index options
`Ivf`	IVF index options
`Vamana`	Vamana index options
`Quantization`	Quantization options

Graph Query Utilities¶

Use akasicdb.graph.execute_cypher() to execute Cypher through AkasicDB from Python. Use wrap_cypher_query() when you want to build the SQL/GQL string and execute it yourself.

from akasicdb.graph import execute_cypher

rows = execute_cypher(
    DB_URL,
    "retail_graph",
    "MATCH (n:v_item) RETURN n.name AS name",
)

See Graph Query for a complete example.