# Core concepts (/getting-started/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](https://iceberg.apache.org) 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](/notebooks/files-and-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](/catalog/browsing) | 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](/notebooks/querying-data) | 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](/dashboards/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](/dashboards/building-dashboards) 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/monitoring) 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](/access/how-access-works) covers
both layers; the terms are collected in the [glossary](/reference/glossary).