SDK quickstart

The Klarety Python SDK gives your code one object, Nexus, that reaches everything in your workspace: SQL, tables, files and folders, connections, agents and jobs. This page gets you to a first query in about five minutes.

Before you startCopy Anchor Link

• Python 3.11 or newer. Check with python3 --version.
• An API key. Only workspace admins create keys; otherwise ask one (see Members).
• Credits on the workspace. A key spends the workspace's credits, so queries run only while there are some.

Install the SDKCopy Anchor Link

Copy Text

pip install klarety

Use a virtual environment if you work on more than one project:

Copy Text

python3 -m venv .venv
source .venv/bin/activate
pip install klarety

Create an API keyCopy Anchor Link

Open SettingsSDK & API, select Create key and verify it is you. Give the key a Name (for example "Laptop" or "Production server"), choose its Access, and set when it Expires. Leave Browser origins empty; it is only for keys used from a web page.

Copy the key now. It is shown only once.

Put the key in your environmentCopy Anchor Link

The SDK reads the key from KLARETY_API_KEY, so it never has to appear in your code.

Copy Text

export KLARETY_API_KEY="paste-your-key-here"

On a laptop you can store it in your system keychain instead, with the CLI: see Authentication.

Connect and check your accountCopy Anchor Link

Copy Text

from klarety import AuthError, Nexus

try:
    nexus = Nexus.connect()
except AuthError as refused:
    raise SystemExit(f"Sign-in failed: {refused}")

with nexus:
    account = nexus.account()
    print("Workspace:", account.org_id)
    print("Plan:", account.plan)
    print("Credits:", account.credits)

Nexus.connect() exchanges your key for a one-hour token and renews it. account() returns an Account with org_id, user_id, roles, plan and credits. plan and credits are None when unreadable, so a missing balance is distinct from zero.

Run your first queryCopy Anchor Link

Add this inside the with nexus: block:

Copy Text

    result = nexus.sql("SELECT 1 AS ok")
    print(result.rows)

Run it:

Copy Text

python first_query.py

Check that it workedCopy Anchor Link

You see your workspace ID, your plan, your credit balance and the row of the query:

Workspace: <your workspace ID>
Plan: <your plan>
Credits: <your balance>
[{'ok': 1}]

nexus.sql() returns a ResultSet. Its rows are dictionaries keyed by column name, bytes_scanned says how much data the query read, and truncated is True when there were more rows than came back. Run SQL explains each field.

A complete first scriptCopy Anchor Link

This script lists your tables and queries one, with real error handling.

from klarety import (
    AuthError,
    InsufficientCreditsError,
    Nexus,
    RefusedError,
    ServiceError,
)

try:
    with Nexus.connect() as nexus:
        tables = nexus.tables.list()
        for table in tables:
            print(table["name"])

        if tables:
            first = tables[0]["name"]
            result = nexus.sql(f"SELECT * FROM {first} LIMIT 5")
            for row in result.rows:
                print(row)
except AuthError:
    print("The key was not accepted. Check KLARETY_API_KEY, or create a new key.")
except InsufficientCreditsError:
    print("The workspace is out of credits. Add credits in the app.")
except RefusedError as refused:
    print(f"Not allowed: {refused}")
except ServiceError as failed:
    print(f"Klarety could not answer, try again shortly: {failed}")

Connect without the environment variableCopy Anchor Link

You can pass the key directly, for example when you read it from your own secret store:

nexus = Nexus.connect(api_key=my_secret_store.get("klarety"))

connect() also takes timeout (seconds per request, 30 by default). Close the connection when you are done, with nexus.close() or by using with.

If something goes wrongCopy Anchor Link

Next stepsCopy Anchor Link

• Authentication: tokens, key rotation and the keychain.
• Run SQL: parameters, estimates and large results.
• Ingest data: load your files into tables.
• CLI: the same SDK from your terminal.