Quickstart

Get Data Island running locally and execute your first query in under five minutes. This guide walks you through installation, platform startup, configuration, and basic data operations.

Prerequisites

Python 3.10 or later
Docker & Docker Compose (for the full platform stack)
4 GB of free RAM minimum

Install the Python SDK

Install the supertable package from PyPI. This gives you the CLI and the Python client library.

pip install supertable

For cloud storage support, install with extras:

# Amazon S3 support
pip install supertable[s3]

# Azure Blob Storage support
pip install supertable[azure]

# All storage backends
pip install supertable[all]

Start the Platform

Use Docker Compose to launch the full Data Island infrastructure including the storage engine, API gateway, and web UI.

docker compose --profile infra --profile webui up -d

This starts the following services:

Core Engine — storage engine and query processor
Gatekeeper — API gateway with RBAC and rate limiting
Web UI — browser-based management interface

Tip: Run docker compose ps to verify all services are healthy before continuing.

Configure Environment

Set the required environment variables. Create a .env file or export them in your shell.

# Required
export SUPERTABLE_ORGANIZATION=my-org
export SUPERTABLE_SUPERUSER_TOKEN=your-secret-token

# Storage backend (local, s3, azure, gcs)
export STORAGE_TYPE=local
export STORAGE_PATH=/data/supertable

# Optional: API endpoint (defaults to localhost)
export SUPERTABLE_API_URL=http://localhost:8050

Create Your First Table

Use the Python SDK to create a table and write some data. Data Island works natively with Polars DataFrames.

from supertable import SuperTable
import polars as pl

# Connect to the platform
st = SuperTable(organization="my-org")

# Create a new table
st.create_table(
    table_name="sensors",
    comment="IoT sensor readings"
)

# Prepare sample data
df = pl.DataFrame({
    "sensor_id": ["s-001", "s-002", "s-003", "s-001"],
    "temperature": [22.5, 19.8, 25.1, 23.0],
    "humidity": [45.2, 62.1, 38.7, 44.8],
    "timestamp": [
        "2026-01-15T10:00:00",
        "2026-01-15T10:00:00",
        "2026-01-15T10:00:00",
        "2026-01-15T10:05:00",
    ]
})

# Write data to the table
writer = st.data_writer(table_name="sensors")
writer.write(df)
writer.commit()

print("Data written successfully!")

Query with SQL

Run SQL queries against your table. The engine returns Polars DataFrames by default.

# Simple query
result = st.execute_query("SELECT * FROM sensors WHERE temperature > 20")
print(result)

# Aggregation
stats = st.execute_query("""
    SELECT
        sensor_id,
        AVG(temperature) AS avg_temp,
        MAX(humidity)     AS max_humidity,
        COUNT(*)          AS readings
    FROM sensors
    GROUP BY sensor_id
    ORDER BY avg_temp DESC
""")
print(stats)

# Time travel: query data as of a specific point in time
historical = st.execute_query(
    "SELECT * FROM sensors",
    as_of="2026-01-15T10:00:00"
)
print(historical)

Connect BI Tools

Data Island exposes an OData 4.0 endpoint so you can connect Power BI, Excel, Tableau, and other analytics tools directly to your tables.

http://localhost:8052/odata/v4/sensors

In Power BI, use Get Data → OData Feed and paste the URL above. Authenticate with your OData bearer token (prefix st_od_).

Tip: See the OData Integration guide for detailed connection instructions for each BI tool.

Next Steps

You are up and running. Explore the rest of the developer documentation to go deeper.

REST API Reference Python SDK MCP Server OData Integration