Getting Started›Core Concepts

Core Concepts

How Hotdata organizes data and how requests authenticate. Next, read Push Data or Pull Data.

The object model

Four nested objects cover nearly every resource in the API. Two request headers select which ones a request addresses.

Workspacework…

An isolated environment. Workspaces share no compute, cache or credentials. Most integrations use one. Header: X-Workspace-Id.

Databasedbid…

A query scope inside a workspace. Create one for a job, load data, query it, and delete it. Set expires_at to delete it automatically. Header: X-Database-Id.

Catalog

A named group of schemas and tables. Every database has one called default, where pushed data lands.

Table

Holds the rows. Addressed in SQL as catalog.schema.table, for example default.main.orders. A table is created on its first load.

Organizationyour credentials live hereWorkspaceX-Workspace-IdDatabaseX-Database-IdCatalogdefaultmainorderscustomersCatalogwarehousepublicinvoicesregionsattach moreown · writable · attachable elsewhereattached · read-onlySELECT * FROM default.main.orders
Two headers and a qualified name address everything. X-Workspace-Id selects the workspace. X-Database-Id selects the database. The three-part SQL name selects the table. Pushed data lands in default.main.

Sharing a catalog

Attach a database's default catalog to another database to query both in one statement. A catalog can be attached to many databases at once.

To attach, call POST /v1/databases/{database_id}/catalogs with the source's default_connection_id as the connection_id.

Pass an alias to name the catalog. Without one, the catalog keeps the source's name. A source that kept the name default needs an alias, because default is reserved.

An attached catalog is:

  • Read-only. Loads always target a database's own default catalog.
  • Not transitive. A database sees the catalog it attached, not the catalogs that one has attached in turn.
  • Pinned until it expires. The source cannot be deleted while it is attached. Detach it first.

After the source's expires_at, it can be deleted. Its tables then disappear from the attaching database, and queries there keep working.

Detaching hides the catalog; it does not delete data. Deleting a database removes its attachments but not the catalogs they point to.

Authentication

All calls go to https://api.hotdata.dev under /v1. Issue an API token from the dashboard and send it on every request.

# the two headers on every request
Authorization: Bearer <api_token>
X-Workspace-Id: workm4lz2mp899l2i7h9lk9u84azg3

# create a database, get an id back
curl -X POST https://api.hotdata.dev/v1/databases \
  -H "Authorization: Bearer $HOTDATA_API_KEY" \
  -H "X-Workspace-Id: $HOTDATA_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{"name": "nightly-rollup", "expires_at": "24h"}'

# => { "id": "dbid6lguax1dxn9y1xj5gxnameyywl", "default_catalog": "default",
#      "default_connection_id": "connu6ho8mseuv8rvsk15anzkmpdsm", … }
  • Keep the returned id. Loads use it in the path. Queries send it as X-Database-Id.
  • Tokens are displayed once. If you lose one, issue a replacement.