mdcms/neuraldb-docs/pages/sdk-python.md

title	sort	section-id	keywords	description	language
Python SDK	100	client-sdks	Python, SDK, client, connection, CRUD, vector operations, psycopg	Installing and using the NeuralDB Python SDK — connection, CRUD, and vector operations	en

Python SDK

Built on psycopg3 with NeuralDB-specific helpers for vector operations and batch ingestion.

Installation

pip install neuraldb
pip install neuraldb[asyncio]  # async support

Connecting

from neuraldb import NeuralDB

client = NeuralDB("postgresql://neuraldb:password@localhost:5432/mydb")

# Async
from neuraldb import AsyncNeuralDB
async with AsyncNeuralDB("postgresql://...") as client:
    result = await client.query("SELECT 1")

# Pool
from neuraldb import NeuralDBPool
pool = NeuralDBPool("postgresql://...", min_size=5, max_size=20)
with pool.acquire() as client:
    result = client.query("SELECT COUNT(*) FROM documents")

CRUD Operations

from neuraldb import Vector

client.execute(
    "INSERT INTO documents (content, source, embedding) VALUES (%s, %s, %s)",
    ("My document content", "web-scraper", Vector([0.023, -0.187, 0.412]))
)

rows = client.query("SELECT id, content FROM documents WHERE source = %s", ("web-scraper",))
for row in rows:
    print(row["id"], row["content"])

client.execute("UPDATE documents SET content = %s, embedding = %s WHERE id = %s",
    ("Updated", Vector(new_embedding), doc_id))
client.execute("DELETE FROM documents WHERE id = %s", (doc_id,))

Vector Search

results = client.query("""
    SELECT id, content, 1 - (embedding <=> %s) AS similarity
    FROM documents WHERE embedding IS NOT NULL
    ORDER BY embedding <=> %s LIMIT 10
""", (Vector(query_embedding), Vector(query_embedding)))

Transactions

with client.transaction():
    client.execute("INSERT INTO documents (content, embedding) VALUES (%s, %s)", (content, Vector(embedding)))
    client.execute("UPDATE stats SET count = count + 1")

Bulk Ingestion

from neuraldb import BulkIngestor

ingestor = BulkIngestor(client, table="documents",
    columns=["content", "source", "embedding"], batch_size=1000,
    embedding_model="openai/text-embedding-3-small", embedding_column="embedding", text_column="content")

with ingestor as ing:
    for doc in docs:
        ing.add(doc)
print(f"Ingested {ingestor.total_inserted} documents")