GUIDED TUTORIAL

The IncQL Book

Follow one small order dataset from typed intent to an observed, deliberately governed result. The book is organised into focused Parts, so later topics can deepen or branch from the core path without turning it into one endless sequence.

One project · expandable learning paths

Choose the part of the system you want to understand

Open one Part at a time. Every chapter names its owner, outcome, and primary artifact.

Part I Model the work Typed source → deferred plan 2 chapters

ChapterOutcomeOwnerPrimary artifact

1. 01Read a typed relation Bind a named CSV source and carry the intended row model. Author → Session Typed source
2. 02Build deferred work Describe a small relational operation without backend execution. LazyFrame → Prism Deferred plan

Part II Explain and execute it Inspection → observed attempt → coverage 3 chapters

ChapterOutcomeOwnerPrimary artifact

1. 03Inspect the plan Explain the Prism plan and lineage before execution. Prism inspection PlanInspection
2. 04Collect an observed result Materialise through DataFusion and retain attempt evidence. Session → adapter ObservedDataFrame
3. 05Check adapter coverage Separate execution success from capability evidence. Session Coverage records

Part III Decide what happens next Quality evidence → caller decision 2 chapters

ChapterOutcomeOwnerPrimary artifact

1. 06Observe data quality Compare passing and failing observations without inventing enforcement. Session → caller QualityObservation
2. 07Make the write decision Let caller-owned policy decide whether to attempt the write. Caller → adapter ObservedWrite

Part IV Query blocks SQL-familiar clauses → typed results 2 chapters

ChapterOutcomeOwnerPrimary artifact

1. 08Write your first query Filter, project, order, and collect without relational method chains. Author → IncQL Checked query
2. 09Summarize and order results Group rows, calculate measures, and reuse projected aliases. IncQL → Session Typed summary

What you will build

The project reads an included CSV through a Session, carries an intended Order row model, and builds a deferred LazyFrame. You will inspect that plan through Prism before asking the current DataFusion adapter to execute it. The later core chapters separate adapter coverage from data-quality observations, then make the write decision explicitly in application code.

Part IV is a direct-entry route for readers who prefer SQL-familiar clauses. It reuses the same project and typed source, but authors relational work with checked query { ... } blocks instead of method chains. You can begin there without completing Parts I–III first.

The core path ends with a deliberately modest result: a bounded three-row order review written to CSV. The query path collects a filtered row set and a grouped summary instead. Across both routes, the important part is that you can explain what IncQL knew before execution, what the backend reported afterwards, and which decisions still belonged to your code.

Before you begin

You need:

• an Incan toolchain compatible with this checkout
• a working Rust and CMake build toolchain for the local IncQL dependency; its protobuf sources are vendored, so a system protoc is not required
• a local IncQL checkout; the tutorial project uses a path dependency and does not claim a registry release

From the IncQL repository root, prepare the included project once:

cd examples/tutorial_book
incan lock

Each chapter gives one incan run command from that directory. Chapters 1–7 are cumulative checkpoints for the core system path. Chapters 8–9 are independent query-block checkpoints that share the same fixture, so you can enter Part IV directly.

How this book fits the site

This edition follows one bounded CSV-to-write path and one direct-entry query-language path. Later Parts can deepen the core language or introduce a separate execution path with its own prerequisites. Use Guides for independent tasks, Reference for exact signatures and record fields, and Architecture for the complete boundary and ownership story.