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_atto 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 exampledefault.main.orders. A table is created on its first load.
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
defaultcatalog. - 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 asX-Database-Id. - Tokens are displayed once. If you lose one, issue a replacement.