Database

The Python Nucleus client provides async access to all 14 data models using asyncpg.

Connection

from neutron.nucleus import NucleusClient

db = await NucleusClient.connect(
    "postgres://localhost:5432/mydb",
    min_size=5,
    max_size=25,
)

# Auto-detect features
print(db.features.is_nucleus)  # True
print(db.features.version)     # "0.1.0"

await db.close()

SQL

from pydantic import BaseModel

class User(BaseModel):
    id: int
    name: str
    email: str

# Query multiple rows
users = await db.sql.query(User, "SELECT * FROM users")

# Query one row
user = await db.sql.query_one(User, "SELECT * FROM users WHERE id = $1", 42)

# Query one or None
user = await db.sql.query_one_or_none(User, "SELECT * FROM users WHERE id = $1", 99)

# Execute (returns affected count)
count = await db.sql.execute(
    "INSERT INTO users (name, email) VALUES ($1, $2)", "Alice", "alice@example.com")

# Scalar value
total = await db.sql.fetchval("SELECT COUNT(*) FROM users")

Key-Value

kv = db.kv

await kv.set("session:1", "data", ttl=3600)
val = await kv.get("session:1")
await kv.delete("session:1")

# Typed get/set (JSON serialization)
await kv.set_typed("prefs:1", PrefsModel(theme="dark"), ttl=3600)
prefs = await kv.get_typed("prefs:1", PrefsModel)

# Lists
await kv.lpush("queue", "item")
item = await kv.rpop("queue")

# Hashes
await kv.hset("user:1", "name", "Alice")
name = await kv.hget("user:1", "name")
all_fields = await kv.hgetall("user:1")

# Sorted sets
await kv.zadd("leaderboard", 100, "alice")
top = await kv.zrange("leaderboard", 0, 9)

# HyperLogLog
await kv.pfadd("visitors", "user1")
count = await kv.pfcount("visitors")

Vector Search

results = await db.vector.search(
    "documents", query_embedding,
    k=10, metric="cosine",
    filter={"category": "tech"},
)

for r in results:
    print(f"ID: {r.id}, Score: {r.score:.4f}")

Document

doc_id = await db.document.insert("posts", {
    "title": "Hello", "body": "World", "tags": ["python"]
})

post = await db.document.find_one("posts", {"author": "alice"})
posts = await db.document.find("posts", {"author": "alice"}, limit=10)

# Typed queries
post = await db.document.find_one_typed("posts", {"author": "alice"}, BlogPost)

Graph

node_id = await db.graph.add_node(["Person"], {"name": "Alice", "age": 30})
await db.graph.add_edge("KNOWS", node_id, other_id, {"since": "2024"})

result = await db.graph.query(
    "MATCH (p:Person)-[:KNOWS]->(q) RETURN p.name, q.name")

Full-Text Search

results = await db.fts.search("articles", "machine learning",
    limit=10, fuzzy=2, highlight=True)

Time Series

from neutron.nucleus import TimeSeriesPoint
from datetime import datetime

points = [TimeSeriesPoint(timestamp=datetime.now(), value=72.5, tags={"host": "web-01"})]
await db.timeseries.write("cpu_usage", points)

latest = await db.timeseries.last("cpu_usage")
points = await db.timeseries.query("cpu_usage", start, end, buckets=60)

All 14 Models

| Model | Accessor | Key Methods | |-------|----------|-------------| | SQL | db.sql | query, execute, fetchval | | Key-Value | db.kv | get, set, hset, lpush, zadd | | Vector | db.vector | search | | TimeSeries | db.timeseries | write, query, last | | Document | db.document | insert, find, get | | Graph | db.graph | add_node, add_edge, query | | FTS | db.fts | search | | Geo | db.geo | distance, within_radius | | Blob | db.blob | put, get, delete | | Streams | db.streams | xadd, xrange, xreadgroup | | Columnar | db.columnar | insert, sum, avg | | Datalog | db.datalog | assert_rule, query | | CDC | db.cdc | subscribe | | PubSub | db.pubsub | publish, subscribe |