Skip to content

Learn HQL

This is a book about HQL, read from the first page to the last. It starts with a number and ends with an agent whose run is a value, and every chapter builds on the ones before it. Every program in it prints what the book shows. Chapters 1 to 12 run with the current release; chapters 13 to 15 cover the io, io.logging and ai modules, which ship in the next one.

HQL is a statically typed language for querying, transforming, connecting and computing over data, knowledge and AI workflows. A program is checked before it runs, and values flow through pipelines of typed steps: over records and lists, as jq works over JSON; over tables, as SQL does; over files, standard input and streams that do not end; over a vault of Markdown documents, their links and their meaning; and through the context, prompts and runs of a language model.

Following along

Install hql, clone the repository for the tutorial vault, and run each program with hql eval:

git clone https://github.com/ewiger/hql && cd hql
hql --vault examples/tutorial eval 'cards | size'

The tutorial vault, examples/tutorial/, is a small reading club: seven books, five authors, the links between them, and one claim about which book inspired which.

Chapters

  1. Hello world — the first program, running it, and the check before a program runs.
  2. Data types — Int, Float, String and Bool in the REPL, Data and its JSON-shaped trees, Option for a value that may be missing, and how sets, Data and maps differ.
  3. Collections — lists, sets and maps, and the steps they share.
  4. Functions — lambdas, declared and generic functions, aliases, and partial application.
  5. Asking questions — where, order by, group by and the aggregates.
  6. A vault of documents — cards, their metadata, and a reading list nobody maintains.
  7. Links and graphs — following links, building graphs, drawing them.
  8. Finding cards by meaning — rankings, hits, and the evidence behind a score.
  9. Streams that do not end — generators, laziness, and batches.
  10. Writing results out — presentation formats and who chooses them.
  11. Queries inside documents — cells, and documents built from them.
  12. Working with hql — the commands, the reports, and what to do when something is wrong.
  13. Reading and writing data — endpoints, source, tap, target and sink, and hql as a command-line data tool.
  14. Channels and logs — values passed through channels, and structured logging.
  15. Agents and runs — agents as cards, context and prompts, tools, and runs kept as values.
  16. Types, traits and modules — records, unions, results, receiver calls, traits and operators, and modules of your own.