Core concepts
The core nouns, each in a paragraph.
The rest of the docs use these nouns. Each paragraph links to a page with more detail.
Tenant and roles
A tenant is one customer workspace, and everything else lives inside exactly one tenant. There are two roles. A TenantAdmin manages tenant-wide configuration: object stores, external sources, AI and dashboard settings, Connect packages and saved credentials. A TenantUser can do everything else, including connections, syncs, File Sets, datasets, pipelines, automations, apps, reports and API keys. Tenants and roles.
Object store
An object store is the S3-compatible bucket where Beetl writes a tenant's datasets. Every tenant starts with Beetl's hosted store. A TenantAdmin can add the tenant's own buckets too, and one store is the default that new datasets go to. Tenants and roles.
Connection
A Connection is your access to one provider: a webhook endpoint, or an account in a system reached through an integration. A Configured Sync is one stream of records on a connection, run on demand or on a schedule. A File Set is a folder of uploaded files. Each of these writes to exactly one dataset through an Output Link. Connection types, connections and syncs.
Connection type and integration
A Connection Type is the definition a connection is created from. Webhook is built in. Every
other type is a Connect package, called an integration in the app: TypeScript written against
the open-source @beetlio/connect SDK, uploaded by a TenantAdmin and run in an isolated sandbox. A package's
contract (the syncs and record schemas it declares) cannot change after installation.
Build integrations.
Dataset
A Dataset is a table you can query and use as a pipeline source. A materialized dataset is one Beetl writes, and an app-published dataset is one an app replaces on each run. A registered dataset points at files already in one of your object stores, and an external dataset points at a live PostgreSQL table; Beetl reads those two in place and never writes to them. Datasets and tiers.
Delta Lake and the tiers
Materialized datasets are Delta Lake tables, so every write is all-or-nothing, and Beetl maintains them automatically. Every dataset is labeled Bronze, Silver or Gold, a convention your team shares about how processed the data is. Datasets and tiers.
Pipeline
A Pipeline reads source datasets, runs an ordered list of SQL stages, and can write the result to a destination dataset. Working is the draft you edit and preview, and Deployed is the version that runs. Deploy promotes the draft and starts a first run. A pipeline without a destination is useful for exploring but cannot be deployed or run. Pipelines.
Run
A run is one execution of a sync, a pipeline, an automation, an app or a report. Each keeps its history next to the thing that ran: on Home for syncs, pipelines and apps, on the automation's page for automations, and on the report's page for reports. Runs.
Query result
Every query produces a saved result with its own URL. Only the person who ran the query can open it, and it expires after 7 days. Query results.
AI settings
A TenantAdmin chooses where the assistant's models come from: managed AI, with a monthly credit allowance, or the tenant's own API key. Every tenant starts on managed AI. Admins can also give the assistant standing instructions. AI settings.
The agent trust boundary
Beetl reads from your systems and does not write back to them. Inside Beetl, the assistant can edit
the page you are on and build pipelines, and deploying one writes its destination dataset. In chat
a deploy needs your confirmation; over MCP a write key deploys directly. Queries cannot change
data. The agent trust boundary.
In this section
| Page | What it covers |
|---|---|
| Tenants and roles | What a tenant contains, what each role can do, and where your data is stored. |
| Connection types, connections and syncs | How data is copied into Beetl: connection types, connections, syncs, file processors, and the output link that ties each one to a dataset. |
| Datasets and tiers | The four kinds of dataset, how they are stored, what happens when a schema changes, and the Bronze / Silver / Gold convention. |
| Pipelines | Sources, SQL stages and a destination, the Working and Deployed versions, and what starts a run. |
| Runs | The kinds of run, where each one's history lives, how long it is kept, and what you can cancel. |
| Query results | Saved results with their own URL, who can open them, and the 7-day clock on them. |
| AI in a tenant | Managed AI or your own key, monthly credits, choosing a model, and standing instructions. |
| The agent trust boundary | What the assistant and MCP clients can read and change, and how each change is gated. |
Last updated on