---
title: "Python SDK"
description: "Use the Apache-2.0 HeliosDB Python SDK against the HeliosDB Lite REST API: install from source, authenticate with a JWT, run SQL and manage branches."
---

# 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](https://github.com/HeliosDatabase/HeliosDB-SDKs) repository. They are not published to package registries yet, so install from source as shown. See [SDKs & Integrations](https://www.heliosdb.com/docs/lite/api/sdks/) and the SDK README for the full client API.

```bash
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](https://www.heliosdb.com/docs/lite/website/getting-started/authentication/) for how to mint one.

```python
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

```python
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

```python
# 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](https://www.heliosdb.com/docs/lite/features/vector-search/).

See the [REST API Reference](https://www.heliosdb.com/docs/lite/website/api/readme/) for the routes Lite serves.