Altertable Lakehouse Python SDK

Official Python SDK for the Altertable Lakehouse API.

Installation

pip install altertable-lakehouse

Ibis

pip install 'altertable-lakehouse[ibis]'

import ibis

con = ibis.altertable.connect(
    username="your_username", password="your_password",
    catalog="my_catalog", database="my_schema",
)
orders = con.table("orders")
totals = orders.group_by("customer_id").aggregate(total=orders.amount.sum())
print(totals.execute())
con.disconnect()

database means schema. Queries run remotely; results are buffered in memory. Writes use the SDK directly. See the runnable example.

marimo

Use the Ibis connection with mo.sql(query, engine=con). Try the notebook with ALTERTABLE_USERNAME and ALTERTABLE_PASSWORD set:

pip install -e '.[ibis]' marimo
marimo edit examples/marimo_notebook.py

Use marimo's Datasources panel to add SQL cells for your own tables.

Usage

Initialization

from altertable_lakehouse import Client

client = Client(username="your_username", password="your_password")

# Disable TLS certificate verification for development only
client = Client(username="your_username", password="your_password", verify=False)

Querying

from altertable_lakehouse.models import QueryRequest

# Stream rows (good for large datasets)
req = QueryRequest(statement="SELECT * FROM my_table")
metadata, columns, row_iterator = client.query(req)
print(metadata.values)
print(columns)
for row in row_iterator:
    print(row)

# Accumulate all rows in memory
result = client.query_all(req)
print(result.metadata.values)
print(result.columns)
print(result.rows)

Append

res = client.append(
    catalog="my_cat",
    schema="my_schema",
    table="my_table",
    data={"col1": "val1"},
    sync=False,
)
print(res.ok)

if res.task_id:
    task = client.get_task(res.task_id)
    print(task.status)

Upsert

with open("data.csv", "rb") as f:
    client.upsert(
        catalog="my_cat",
        schema="my_schema",
        table="my_table",
        primary_key="id",
        content=f.read(),
    )

Upload

from altertable_lakehouse.models import UploadMode

with open("data.csv", "rb") as f:
    client.upload(
        catalog="my_cat",
        schema="my_schema",
        table="my_table",
        mode=UploadMode.CREATE,
        content=f,
        content_type="text/csv",
    )

Validate Query

from altertable_lakehouse.models import ValidateRequest

res = client.validate(ValidateRequest(statement="SELECT * FROM non_existent"))
print(res.valid)
print(res.connections_errors)

Query Log & Cancellation

# Get query status
log_res = client.get_query("query_uuid_here")
print(log_res.progress)

# Cancel a query
cancel_res = client.cancel_query("query_uuid_here", "session_id_here")
print(cancel_res.cancelled)

Autocomplete

from altertable_lakehouse.models import AutocompleteRequest

res = client.autocomplete(AutocompleteRequest(statement="SEL", max_suggestions=5))
print(res.statement)
print([suggestion.suggestion for suggestion in res.suggestions])