Core concepts
The vocabulary Databaas uses: warehouses, namespaces, tables, engines, and permissions.
The words the rest of the docs use without stopping to explain them.
Lakehouse
Your data lives as files in object storage. A lakehouse puts a table layer over those files, so you work with tables — columns, types, versions — instead of a folder of files: storage priced like a data lake, behaviour like a database.
Iceberg table
Databaas uses Apache Iceberg for that table layer. An Iceberg table is a set of data files plus metadata describing its schema and history. That gets you:
- Snapshots. Every write creates a new snapshot. The current one is in the catalog’s Properties tab; older ones are kept, which is what makes time travel possible — reading the table as it was at an earlier snapshot.
- Real schemas. Columns have types, and the schema can change without rewriting the data.
- One table, many engines. A notebook, a SQL query and a pipeline read the same table through the catalog; none owns it.
The catalog can also list generic tables — entries registered in the catalog but not Iceberg. They carry a format badge; only Iceberg tables get a preview and a schema.
Warehouse
A warehouse is the top-level container: a named storage area tables live in. It is the first level of the Data Catalog tree, and the first level at which access is granted. A deployment can have several.
Namespace
Inside a warehouse, tables are grouped into namespaces — the equivalent of a schema or database
elsewhere. Namespaces nest, written with dots: sales.eu.raw. A table’s full identity is its
warehouse, namespace path and name. How you spell that out depends on where you are:
- In a notebook, name the warehouse once when you load the catalog, then address the table as
namespace.table. - In SQL, the namespace is the schema and the table is the table. The catalog name in front of them is not the warehouse name: it is a fixed name your deployment configures for the lakehouse connection. Select the database and schema in SQL Lab and you can leave it off entirely.
Catalog
The catalog is the registry that knows every table: where its files are, its current schema and snapshot, and who may read it. Databaas runs Lakekeeper, an Iceberg REST catalog, and every engine asks it before touching data. The word is used two ways, both correct:
- The Data Catalog in the portal — the screen where you browse warehouses, namespaces and tables, preview rows and see grants.
- The catalog service those engines connect to. It also stores data permissions, which is why a grant applies everywhere at once.
Engines
An engine is what actually runs your query. Pick by the shape of the work.
| Reach for | What it is | When |
|---|---|---|
| The preview in the Data Catalog | The portal reading a few rows straight from the table’s files. | You want to see whether a table holds what you think it does. |
| pyiceberg and DuckDB in a notebook | pyiceberg is the Python library that talks to the catalog and pulls table data into your session; DuckDB is the in-process SQL engine that then queries it there. | Python, exploration, joins and aggregations you iterate on, charts in the notebook. |
| Trino, through SQL Lab | The shared SQL engine that runs your query next to the data and returns only the result. SQL Lab is the query editor inside Superset. | SQL over the lakehouse, queries that back charts, data too large to pull into a notebook. |
| Superset charts and dashboards | The dashboard tool: charts built on saved queries and datasets, arranged on a page. | Publishing a result to people who will not write a query. |
| Airflow pipelines | The scheduler that runs the jobs loading data into the tables. | Getting data into tables on a schedule, and keeping it fresh. |
The rule: notebooks pull data to your code, Trino pushes your query to the data. Small and exploratory goes in a notebook; large and repeated goes in SQL.
Single sign-on and identity
You have one Databaas identity, and every feature trusts it. It travels with your queries, so a query from SQL Lab or a notebook is authorised as you, not a shared service account. Two people running the same query on the same table can legitimately get different results — or one gets rows and the other an error.
The three things that can be missing
“Why can’t I see this?” is decided in two layers: feature permissions (which features you can open) and data permissions (which warehouses, namespaces and tables you can read). Pipelines are not a third layer — seeing and operating them is a feature permission like any other, all or none. You can hold every feature permission and see an empty catalog, or hold wide data grants and have no feature to read them with. How access works covers both layers; the terms are collected in the glossary.