The KQuery Project
This book is accompanied by a fully functional query engine called KQuery (for Kotlin Query). The source code is available on GitHub:
https://github.com/andygrove/how-query-engines-work
Each chapter references specific modules in this repository. Reading the book alongside the code will deepen your understanding. The book explains the design decisions, while the code shows the complete implementation.
Why Kotlin?
The examples use Kotlin because it is concise and readable. If you know Java, Python, or any C-family language, you will follow along easily. Kotlin runs on the JVM and interoperates seamlessly with Java libraries like Apache Arrow.
Query engine concepts are language-agnostic. The Apache Arrow DataFusion project implements similar ideas in Rust, and you could apply these patterns in any language.
Repository Structure
The repository is organized into Gradle modules, each corresponding to a layer of the query engine:
| Module | Description |
|---|---|
datatypes | Type system built on Apache Arrow |
datasource | Data source abstractions and CSV/Parquet readers |
logical-plan | Logical plans and expressions |
physical-plan | Physical plans and expression evaluation |
query-planner | Translation from logical to physical plans |
optimizer | Query optimization rules |
sql | SQL tokenizer, parser, and planner |
execution | Query execution engine |
examples | Example queries and benchmarks |
Building the Project
Prerequisites:
- JDK 11 or later
- Gradle (or use the included Gradle wrapper)
To build and run tests:
cd jvm
./gradlew build
To run a specific test:
./gradlew :sql:test --tests "SqlParserTest"
Running Examples
The examples module contains sample queries you can run:
./gradlew :examples:run
See the README in the repository for the latest instructions and any additional setup required.
This book is also available for purchase in ePub, MOBI, and PDF format from https://leanpub.com/how-query-engines-work
Copyright © 2020-2025 Andy Grove. All rights reserved.