# ibis-project/ibis architecture

> Architecture diagram of the GitHub repository ibis-project/ibis, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ibis-project/ibis
- Repository: https://github.com/ibis-project/ibis

## Overview

Ibis is a portable Python dataframe library: users build lazy expressions, select a backend, and execute against a local or remote engine to obtain dataframe results. SQL backends compile expressions to backend-native SQL; DataFrame backends use their native execution model. The graph preserves major documented capabilities, including Python/SQL composition, interactive exploration, and user-defined functions. Several backend internals are unsampled, so only documented relationships are shown; the format adapters represent conversion support, not a claimed execution sequence.

Main entry points: [`ibis/expr/schema.py`](https://github.com/ibis-project/ibis/blob/main/ibis/expr/schema.py) (Schemas), [`ibis/backends/__init__.py`](https://github.com/ibis-project/ibis/blob/main/ibis/backends/__init__.py) (Backend interface), [`ibis/backends`](https://github.com/ibis-project/ibis/tree/main/ibis/backends) (SQL backends), [`ibis/expr/api.py`](https://github.com/ibis-project/ibis/blob/main/ibis/expr/api.py) (Public API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_expression["Expression API"]
  node_public_api["Public API<br/>[api.py]"]
  node_relational_expr["Relational expressions<br/>[relations.py]"]
  node_operations["Expression operations"]
end

subgraph group_execution["Execution backends"]
  node_sql_compilers["SQL compilers"]
  node_backend_api["Backend interface<br/>[__init__.py]"]
  node_backend_loading["Backend loading<br/>[__init__.py]"]
  node_sql_backends["SQL backends"]
  node_dataframe_backends["DataFrame backends"]
end

subgraph group_types["Types and formats"]
  node_datatypes["Data types<br/>[core.py]"]
  node_schema["Schemas<br/>[schema.py]"]
  node_pandas["Pandas adapter<br/>[pandas.py]"]
  node_polars["Polars adapter<br/>[polars.py]"]
  node_pyarrow["PyArrow adapter<br/>[pyarrow.py]"]
end

subgraph group_support["Shared capabilities"]
  node_config["Configuration<br/>[config.py]"]
  node_udfs["User-defined functions<br/>[udf.py]"]
  node_interactive["Interactive mode<br/>[interactive.py]"]
  node_common["Expression utilities"]
end

node_user(("Python user"))
node_engine[("Database or engine")]
node_dataframe_engine["DataFrame engine"]
node_result["Dataframe result"]

node_user -->|"builds expressions"| node_public_api
node_public_api -->|"creates expressions"| node_relational_expr
node_relational_expr -->|"represents operations"| node_operations
node_user -->|"selects backend"| node_backend_loading
node_backend_loading -->|"loads backend"| node_backend_api
node_backend_api -->|"provides interface"| node_sql_backends
node_backend_api -.->|"provides interface"| node_dataframe_backends
node_sql_backends -->|"compiles to SQL"| node_sql_compilers
node_sql_backends -->|"executes queries"| node_engine
node_sql_compilers -->|"targets native SQL"| node_engine
node_dataframe_backends -->|"uses native model"| node_dataframe_engine
node_dataframe_engine -.->|"returns dataframe"| node_result
node_engine -.->|"returns results"| node_result
node_schema -->|"describes columns"| node_datatypes
node_pandas -->|"maps schema"| node_schema
node_polars -->|"maps schema"| node_schema
node_pyarrow -->|"maps schema"| node_schema
node_user -->|"defines functions"| node_udfs
node_user -->|"explores results"| node_interactive
node_user -->|"sets options"| node_config
node_operations -->|"uses utilities"| node_common

click node_public_api "https://github.com/ibis-project/ibis/blob/main/ibis/expr/api.py"
click node_relational_expr "https://github.com/ibis-project/ibis/blob/main/ibis/expr/types/relations.py"
click node_operations "https://github.com/ibis-project/ibis/tree/main/ibis/expr/operations"
click node_sql_compilers "https://github.com/ibis-project/ibis/tree/main/ibis/backends/sql/compilers"
click node_backend_api "https://github.com/ibis-project/ibis/blob/main/ibis/backends/__init__.py"
click node_backend_loading "https://github.com/ibis-project/ibis/blob/main/ibis/__init__.py"
click node_sql_backends "https://github.com/ibis-project/ibis/tree/main/ibis/backends"
click node_dataframe_backends "https://github.com/ibis-project/ibis/tree/main/ibis/backends"
click node_datatypes "https://github.com/ibis-project/ibis/blob/main/ibis/expr/datatypes/core.py"
click node_schema "https://github.com/ibis-project/ibis/blob/main/ibis/expr/schema.py"
click node_pandas "https://github.com/ibis-project/ibis/blob/main/ibis/formats/pandas.py"
click node_polars "https://github.com/ibis-project/ibis/blob/main/ibis/formats/polars.py"
click node_pyarrow "https://github.com/ibis-project/ibis/blob/main/ibis/formats/pyarrow.py"
click node_config "https://github.com/ibis-project/ibis/blob/main/ibis/config.py"
click node_udfs "https://github.com/ibis-project/ibis/blob/main/ibis/expr/operations/udf.py"
click node_interactive "https://github.com/ibis-project/ibis/blob/main/ibis/interactive.py"
click node_common "https://github.com/ibis-project/ibis/tree/main/ibis/common"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_public_api,node_relational_expr,node_operations,node_user toneBlue
class node_sql_compilers,node_backend_api,node_backend_loading,node_sql_backends,node_dataframe_backends,node_engine toneAmber
class node_datatypes,node_schema,node_pandas,node_polars,node_pyarrow toneMint
class node_config,node_udfs,node_interactive,node_common toneRose
class node_dataframe_engine,node_result toneIndigo
```

## Components

### Expression API

- [Public API](https://github.com/ibis-project/ibis/blob/main/ibis/expr/api.py): `ibis/expr/api.py`
- [Relational expressions](https://github.com/ibis-project/ibis/blob/main/ibis/expr/types/relations.py): `ibis/expr/types/relations.py`
- [Expression operations](https://github.com/ibis-project/ibis/tree/main/ibis/expr/operations): `ibis/expr/operations`

### Execution backends

- [SQL compilers](https://github.com/ibis-project/ibis/tree/main/ibis/backends/sql/compilers): `ibis/backends/sql/compilers`
- [Backend interface](https://github.com/ibis-project/ibis/blob/main/ibis/backends/__init__.py): `ibis/backends/__init__.py`
- [Backend loading](https://github.com/ibis-project/ibis/blob/main/ibis/__init__.py): `ibis/__init__.py`
- [SQL backends](https://github.com/ibis-project/ibis/tree/main/ibis/backends): `ibis/backends`
- [DataFrame backends](https://github.com/ibis-project/ibis/tree/main/ibis/backends): `ibis/backends`

### Types and formats

- [Data types](https://github.com/ibis-project/ibis/blob/main/ibis/expr/datatypes/core.py): `ibis/expr/datatypes/core.py`
- [Schemas](https://github.com/ibis-project/ibis/blob/main/ibis/expr/schema.py): `ibis/expr/schema.py`
- [Pandas adapter](https://github.com/ibis-project/ibis/blob/main/ibis/formats/pandas.py): `ibis/formats/pandas.py`
- [Polars adapter](https://github.com/ibis-project/ibis/blob/main/ibis/formats/polars.py): `ibis/formats/polars.py`
- [PyArrow adapter](https://github.com/ibis-project/ibis/blob/main/ibis/formats/pyarrow.py): `ibis/formats/pyarrow.py`

### Shared capabilities

- [Configuration](https://github.com/ibis-project/ibis/blob/main/ibis/config.py): `ibis/config.py`
- [User-defined functions](https://github.com/ibis-project/ibis/blob/main/ibis/expr/operations/udf.py): `ibis/expr/operations/udf.py`
- [Interactive mode](https://github.com/ibis-project/ibis/blob/main/ibis/interactive.py): `ibis/interactive.py`
- [Expression utilities](https://github.com/ibis-project/ibis/tree/main/ibis/common): `ibis/common`

### Other components

- **Python user**
- **Database or engine**
- **DataFrame engine**
- **Dataframe result**

## Connections

- Python user → Public API: builds expressions
- Public API → Relational expressions: creates expressions (evidence: `ibis/expr/api.py`)
- Relational expressions → Expression operations: represents operations (evidence: `ibis/expr/types/relations.py`)
- Python user → Backend loading: selects backend
- Backend loading → Backend interface: loads backend (evidence: `ibis/__init__.py`)
- Backend interface → SQL backends: provides interface (evidence: `ibis/backends/__init__.py`)
- Backend interface → DataFrame backends: provides interface (evidence: `ibis/backends/duckdb/__init__.py`)
- SQL backends → SQL compilers: compiles to SQL (evidence: `ibis/backends/materialize/__init__.py`)
- SQL backends → Database or engine: executes queries
- SQL compilers → Database or engine: targets native SQL
- DataFrame backends → DataFrame engine: uses native model
- DataFrame engine → Dataframe result: returns dataframe
- Database or engine → Dataframe result: returns results
- Schemas → Data types: describes columns (evidence: `ibis/expr/schema.py`)
- Pandas adapter → Schemas: maps schema (evidence: `ibis/formats/pandas.py`)
- Polars adapter → Schemas: maps schema (evidence: `ibis/formats/polars.py`)
- PyArrow adapter → Schemas: maps schema (evidence: `ibis/formats/pyarrow.py`)
- Python user → User-defined functions: defines functions
- Python user → Interactive mode: explores results
- Python user → Configuration: sets options
- Expression operations → Expression utilities: uses utilities (evidence: `ibis/common/patterns.py`)
