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. Generic tables are how Databaas stores Zarr arrays and plain files under the same grants — see files, blobs and Zarr arrays.
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. An instance can have several; one of them is the default that notebooks and pipelines use unless you name another.
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
iceberg, not the warehouse name:iceberg.<namespace>.<table>. Select the Lakehouse database and a schema in SQL Lab and you can leave the catalog off entirely.
Catalog
Catalog is used two ways here, 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 behind it: Lakekeeper, Databaas’s Iceberg REST catalog. Every engine — notebooks, SQL Lab, pipelines — asks it for a table’s location, schema and current snapshot before touching data, and it is where grants are checked too. Because grants live in this one service rather than in each engine separately, a grant you make once applies everywhere.
Engines
An engine is what actually runs your query. Which one to reach for depends on what you’re doing:
| Reach for | What it is | When |
|---|---|---|
| The preview in the Data Catalog | The portal fetching the first 20 rows through Trino, as you. | 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 outcomes: one gets rows, the other an error. Pipelines run the same way under their own application identity, which is granted data like a person.
The two things that can be missing
“Why can’t I see this?” is decided in two layers:
- Feature permissions — which features you can open.
- Data grants — 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.