Skip to main content

Getting started

This walk-through takes you from nothing to a pandas DataFrame in five steps. You need a Honeyframe account, access to at least one project, and Python 3.9 or newer.

1. Install the SDK with pandas​

pip install "honeyframeapi[pandas]"

2. Mint a Personal Access Token​

Open the platform, then avatar menu → Personal access tokens, and create a token. Copy the hf_… value when it is shown: it is displayed once and cannot be retrieved later. See Authentication for lifetimes and narrowing a token.

Put the token and the platform URL in your environment rather than in your script:

export HONEYFRAME_URL=https://platform.your-domain.com
export HONEYFRAME_TOKEN=hf_xxxxxxxxxxxxxxxxxxxx

3. Build a client and check who you are​

from honeyframeapi import HoneyframeClient

client = HoneyframeClient.from_env()     # reads HONEYFRAME_URL and HONEYFRAME_TOKEN
print(client.get_auth_info())            # your user profile
print(client.get_instance_info())        # the platform version

from_env() builds the client from environment variables; any keyword you pass (for example project_id=1) wins over the environment.

4. Pick a project​

for p in client.list_projects():
    print(p["project_id"], p.get("slug"), p.get("name"))

project = client.get_project("sales")    # a numeric id, or a slug / name

get_project accepts an id or a slug. A slug is looked up in list_projects(); an unknown one raises HoneyframeNotFoundError.

5. Run SQL and get a DataFrame​

df = project.sql("""
    SELECT store_key, COUNT(*) AS orders, SUM(amount) AS revenue
    FROM marts.fact_orders
    GROUP BY store_key
    ORDER BY revenue DESC
""")
print(df.head())

project.sql runs through the platform's governed SQL endpoint: it accepts read-only statements only, sees only what your project can see, and applies the same data policies and masking as the UI. It returns at most 10,000 rows unless you raise row_limit; see SQL and DataFrames.

To read a whole dataset instead of a query result:

orders = project.get_dataset("fact_orders").get_dataframe()

The complete script​

"""first_script.py — top stores by revenue."""
from honeyframeapi import HoneyframeClient, HoneyframeError

with HoneyframeClient.from_env() as client:          # closes the HTTP connection on exit
    project = client.get_project("sales")
    try:
        df = project.sql(
            "SELECT store_key, SUM(amount) AS revenue FROM marts.fact_orders "
            "GROUP BY store_key ORDER BY revenue DESC",
            row_limit=20,
        )
    except HoneyframeError as exc:
        raise SystemExit(f"query failed: {exc}")
    print(df)

Next steps​

  • Keep the project on the client so client-level shortcuts work: HoneyframeClient.from_env(project_id=1) or client.using(project_id=1), then client.sql(...) and client.get_dataset(...).
  • Projects and datasets: upload a DataFrame, materialize it, export a dataset to CSV or Parquet.
  • Dashboards and webapps: turn the query into a dashboard card and share it.
  • Errors and retries: what each exception means and what is retried for you.

Verified against honeyframeapi 0.1.8.