Python SDK

Python client for the HeliosDB-Lite REST API.

Installation

The SDKs are Apache-2.0 and developed in the public HeliosDatabase/HeliosDB-SDKs repository. They are not published to package registries yet, so install from source as shown. See SDKs & Integrations and the SDK README for the full client API.

pip install "git+https://github.com/HeliosDatabase/HeliosDB-SDKs#subdirectory=sdks/python"

The installed Python package is heliosdb.

Quick Start

Every Lite /v1 route needs a JWT signed with the server’s HELIOSDB_JWT_SECRET; see Authentication for how to mint one.

import os
from heliosdb import HeliosDB

db = HeliosDB.connect("http://localhost:8080", jwt_token=os.environ["HELIOSDB_TOKEN"])

# Query the main branch (POST /v1/branches/main/query)
result = db.query("SELECT * FROM users WHERE id = $1", [1])
for row in result.to_dicts():
    print(row)

db.close()

Async Client

import asyncio, os
from heliosdb import HeliosDB

async def main():
    async with HeliosDB.connect("http://localhost:8080",
                                jwt_token=os.environ["HELIOSDB_TOKEN"]) as db:
        result = await db.aquery("SELECT count(*) FROM users")
        print(result.to_dicts())

asyncio.run(main())

Branching

# POST /v1/branches
db.create_branch("dev", from_branch="main")

# Query a branch
db.query("SELECT count(*) FROM users", branch="dev")

Branches can also be managed in SQL: CREATE DATABASE BRANCH dev FROM main AS OF NOW.

Vector Search, Agent Memory and Natural-Language Query

The SDK has vector-store, agent-memory and natural-language-query methods. The matching Lite REST endpoint groups are planned, so these methods return a not-implemented error against Lite today. Run vector search in SQL instead; see Vector Search.

See the REST API Reference for the routes Lite serves.