# peimu/aqphub architecture

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

- Interactive diagram: https://gitdiagram.com/peimu/aqphub
- Repository: https://github.com/peimu/aqphub

## Overview

AQPHub is a command-line approximate-query-processing middleware: it accepts a SQL query and configuration, converts the query into an intermediate representation, repeatedly extracts and executes subqueries, then returns the final result. Users can select FK-based relationship-center, entity-center, or min-subquery strategies, or node-based splitting, and choose among DuckDB, PostgreSQL, MariaDB, OpenGauss, and Umbra. The README also documents SQL printing, combined sub-plans, cardinality updates, and correctness/error checking. The graph follows the sampled entry point and splitter; unsampled adapter and strategy internals are represented only where paths and documented behavior support them.

Main entry points: [`include/adapters/db_adapter.h`](https://github.com/peimu/aqphub/blob/master/include/adapters/db_adapter.h) (Engine adapter API), [`src/split/ir_query_splitter.cpp`](https://github.com/peimu/aqphub/blob/master/src/split/ir_query_splitter.cpp) (Split orchestrator), [`src/split/fk_based_splitter.cpp`](https://github.com/peimu/aqphub/blob/master/src/split/fk_based_splitter.cpp) (FK-based strategies), [`src/aqp_middleware.cpp`](https://github.com/peimu/aqphub/blob/master/src/aqp_middleware.cpp) (Middleware entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Command-line entry"]
  node_config["Configuration<br/>[param_config.cpp]"]
  node_middleware["Middleware entry<br/>[aqp_middleware.cpp]"]
end

subgraph group_planning["Query planning"]
  node_ir_converter["IR converter"]
  node_fk_extractor["Foreign-key extraction"]
end

subgraph group_splitting["Query splitting"]
  node_ir_splitter["Split orchestrator"]
  node_fk_strategies["FK-based strategies"]
  node_node_strategy["Node-based strategy"]
  node_topdown_strategy["Top-down strategy"]
  node_sub_ir["Subquery selection<br/>[select_sub_ir.cpp]"]
  node_ir_utils["IR utilities<br/>[ir_utils.cpp]"]
end

subgraph group_engines["Database engines"]
  node_adapter_api["Engine adapter API<br/>[db_adapter.h]"]
  node_duckdb_adapter["DuckDB adapter<br/>[duckdb_adapter.cpp]"]
  node_postgres_adapter["PostgreSQL adapter"]
  node_mariadb_adapter["MariaDB adapter"]
  node_opengauss_adapter["OpenGauss adapter"]
  node_umbra_adapter["Umbra adapter<br/>[umbra_adapter.cpp]"]
end

node_user(("Query user"))
node_sql_input["SQL input"]
node_database[("Configured database")]
node_helper_estimator[("Optional estimator")]
node_temp_tables[("Intermediate tables")]
node_query_result["Query result"]

node_user -->|"sets options"| node_config
node_user -->|"provides SQL"| node_sql_input
node_sql_input -->|"supplies query"| node_middleware
node_config -->|"configures run"| node_middleware
node_middleware -->|"creates adapter"| node_adapter_api
node_middleware -->|"runs split query"| node_ir_splitter
node_ir_splitter -->|"parses and executes"| node_adapter_api
node_adapter_api -->|"converts plan"| node_ir_converter
node_ir_splitter -->|"dispatches strategy"| node_fk_strategies
node_ir_splitter -->|"dispatches strategy"| node_node_strategy
node_ir_splitter -->|"dispatches strategy"| node_topdown_strategy
node_fk_strategies -->|"reads key metadata"| node_fk_extractor
node_fk_strategies -->|"selects cluster IR"| node_sub_ir
node_fk_strategies -->|"uses IR operations"| node_ir_utils
node_node_strategy -->|"uses IR operations"| node_ir_utils
node_topdown_strategy -->|"uses IR operations"| node_ir_utils
node_adapter_api -->|"implemented by"| node_duckdb_adapter
node_adapter_api -->|"implemented by"| node_postgres_adapter
node_adapter_api -->|"implemented by"| node_mariadb_adapter
node_adapter_api -->|"implemented by"| node_opengauss_adapter
node_adapter_api -->|"implemented by"| node_umbra_adapter
node_duckdb_adapter -->|"executes SQL"| node_database
node_postgres_adapter -->|"executes SQL"| node_database
node_mariadb_adapter -->|"executes SQL"| node_database
node_opengauss_adapter -->|"executes SQL"| node_database
node_umbra_adapter -->|"executes SQL"| node_database
node_ir_splitter -->|"tracks intermediates"| node_temp_tables
node_adapter_api -->|"creates and reads"| node_temp_tables
node_mariadb_adapter -.->|"may estimate with"| node_helper_estimator
node_ir_splitter -->|"returns final result"| node_query_result
node_query_result -->|"displays rows"| node_user

click node_config "https://github.com/peimu/aqphub/blob/master/src/util/param_config.cpp"
click node_middleware "https://github.com/peimu/aqphub/blob/master/src/aqp_middleware.cpp"
click node_ir_converter "https://github.com/peimu/aqphub/tree/master/third_party/IR_SQL_Converter"
click node_fk_extractor "https://github.com/peimu/aqphub/blob/master/src/split/foreign_key_extractor.cpp"
click node_ir_splitter "https://github.com/peimu/aqphub/blob/master/src/split/ir_query_splitter.cpp"
click node_fk_strategies "https://github.com/peimu/aqphub/blob/master/src/split/fk_based_splitter.cpp"
click node_node_strategy "https://github.com/peimu/aqphub/blob/master/src/split/node_based_splitter.cpp"
click node_topdown_strategy "https://github.com/peimu/aqphub/blob/master/src/split/topdown_splitter.cpp"
click node_sub_ir "https://github.com/peimu/aqphub/blob/master/src/split/select_sub_ir.cpp"
click node_ir_utils "https://github.com/peimu/aqphub/blob/master/src/split/ir_utils.cpp"
click node_adapter_api "https://github.com/peimu/aqphub/blob/master/include/adapters/db_adapter.h"
click node_duckdb_adapter "https://github.com/peimu/aqphub/blob/master/src/adapters/duckdb_adapter.cpp"
click node_postgres_adapter "https://github.com/peimu/aqphub/blob/master/src/adapters/postgres_adapter.cpp"
click node_mariadb_adapter "https://github.com/peimu/aqphub/blob/master/src/adapters/mariadb_adapter.cpp"
click node_opengauss_adapter "https://github.com/peimu/aqphub/blob/master/src/adapters/opengauss_adapter.cpp"
click node_umbra_adapter "https://github.com/peimu/aqphub/blob/master/src/adapters/umbra_adapter.cpp"

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_config,node_middleware,node_user toneBlue
class node_ir_converter,node_fk_extractor,node_database,node_helper_estimator,node_temp_tables toneAmber
class node_ir_splitter,node_fk_strategies,node_node_strategy,node_topdown_strategy,node_sub_ir,node_ir_utils toneMint
class node_adapter_api,node_duckdb_adapter,node_postgres_adapter,node_mariadb_adapter,node_opengauss_adapter,node_umbra_adapter toneRose
class node_sql_input,node_query_result toneIndigo
```

## Components

### Command-line entry

- [Configuration](https://github.com/peimu/aqphub/blob/master/src/util/param_config.cpp): `src/util/param_config.cpp`
- [Middleware entry](https://github.com/peimu/aqphub/blob/master/src/aqp_middleware.cpp): `src/aqp_middleware.cpp`

### Query planning

- [IR converter](https://github.com/peimu/aqphub/tree/master/third_party/IR_SQL_Converter): `third_party/IR_SQL_Converter`
- [Foreign-key extraction](https://github.com/peimu/aqphub/blob/master/src/split/foreign_key_extractor.cpp): `src/split/foreign_key_extractor.cpp`

### Query splitting

- [Split orchestrator](https://github.com/peimu/aqphub/blob/master/src/split/ir_query_splitter.cpp): `src/split/ir_query_splitter.cpp`
- [FK-based strategies](https://github.com/peimu/aqphub/blob/master/src/split/fk_based_splitter.cpp): `src/split/fk_based_splitter.cpp`
- [Node-based strategy](https://github.com/peimu/aqphub/blob/master/src/split/node_based_splitter.cpp): `src/split/node_based_splitter.cpp`
- [Top-down strategy](https://github.com/peimu/aqphub/blob/master/src/split/topdown_splitter.cpp): `src/split/topdown_splitter.cpp`
- [Subquery selection](https://github.com/peimu/aqphub/blob/master/src/split/select_sub_ir.cpp): `src/split/select_sub_ir.cpp`
- [IR utilities](https://github.com/peimu/aqphub/blob/master/src/split/ir_utils.cpp): `src/split/ir_utils.cpp`

### Database engines

- [Engine adapter API](https://github.com/peimu/aqphub/blob/master/include/adapters/db_adapter.h): `include/adapters/db_adapter.h`
- [DuckDB adapter](https://github.com/peimu/aqphub/blob/master/src/adapters/duckdb_adapter.cpp): `src/adapters/duckdb_adapter.cpp`
- [PostgreSQL adapter](https://github.com/peimu/aqphub/blob/master/src/adapters/postgres_adapter.cpp): `src/adapters/postgres_adapter.cpp`
- [MariaDB adapter](https://github.com/peimu/aqphub/blob/master/src/adapters/mariadb_adapter.cpp): `src/adapters/mariadb_adapter.cpp`
- [OpenGauss adapter](https://github.com/peimu/aqphub/blob/master/src/adapters/opengauss_adapter.cpp): `src/adapters/opengauss_adapter.cpp`
- [Umbra adapter](https://github.com/peimu/aqphub/blob/master/src/adapters/umbra_adapter.cpp): `src/adapters/umbra_adapter.cpp`

### Other components

- **Query user**
- **SQL input**
- **Configured database**
- **Optional estimator**
- **Intermediate tables**
- **Query result**

## Connections

- Query user → Configuration: sets options
- Query user → SQL input: provides SQL
- SQL input → Middleware entry: supplies query
- Configuration → Middleware entry: configures run
- Middleware entry → Engine adapter API: creates adapter
- Middleware entry → Split orchestrator: runs split query
- Split orchestrator → Engine adapter API: parses and executes
- Engine adapter API → IR converter: converts plan
- Split orchestrator → FK-based strategies: dispatches strategy
- Split orchestrator → Node-based strategy: dispatches strategy
- Split orchestrator → Top-down strategy: dispatches strategy
- FK-based strategies → Foreign-key extraction: reads key metadata
- FK-based strategies → Subquery selection: selects cluster IR
- FK-based strategies → IR utilities: uses IR operations
- Node-based strategy → IR utilities: uses IR operations
- Top-down strategy → IR utilities: uses IR operations
- Engine adapter API → DuckDB adapter: implemented by
- Engine adapter API → PostgreSQL adapter: implemented by
- Engine adapter API → MariaDB adapter: implemented by
- Engine adapter API → OpenGauss adapter: implemented by
- Engine adapter API → Umbra adapter: implemented by
- DuckDB adapter → Configured database: executes SQL
- PostgreSQL adapter → Configured database: executes SQL
- MariaDB adapter → Configured database: executes SQL
- OpenGauss adapter → Configured database: executes SQL
- Umbra adapter → Configured database: executes SQL
- Split orchestrator → Intermediate tables: tracks intermediates
- Engine adapter API → Intermediate tables: creates and reads
- MariaDB adapter → Optional estimator: may estimate with
- Split orchestrator → Query result: returns final result
- Query result → Query user: displays rows