Skip to content

1. Hello world

HQL is a statically typed expression and query language. You use it to read data, transform it and write it out: records from a JSON file, rows of a table, events from a stream, the notes in a folder of Markdown documents. Where a shell pipeline would combine jq, grep and a script, an HQL program is one expression that hql checks and runs.

Most of the data a query language handles was written by someone else, and its shape is not guaranteed. HQL deals with this through types. Every value has a type, and a type is a contract: it states what the value must look like. hql checks a program against these contracts before running it, and checks data against them when the data is read. A mistake in the program is reported before anything runs. A mistake in the data is reported where the data comes in, not three steps later.

A program goes through the same stages every time:

d2 diagram

Hello, world

The smallest program that says hello is the text itself:

"Hello, world!"
"Hello, world!"

A program is an expression, and hql writes its value. A string prints in quotes, the way it is written in a program. fmt builds a string from a template, filling each {} with the next argument:

fmt("Hello, {}!", "world")
"Hello, world!"

Running a program

hql eval runs a program given on the command line:

$ hql eval 'fmt("Hello, {}!", "world")'
"Hello, world!"

hql run runs a program from a file. A file holds the same thing an argument does:

$ cat hello.hql
title = "Dune"
pages = 412
fmt("{} has {} pages", title, pages)
$ hql run hello.hql
"Dune has 412 pages"

hql repl reads one program at a time and prints each value, which is useful for trying things out. Chapter 2 starts there.

This book shows each program in a block, followed by what hql writes for it. Most programs run against a small example vault, a reading club of books and authors in examples/reading-club/. To follow along, clone the repository and pass the vault to hql:

$ hql --vault examples/reading-club eval 'cards | size'
15

Values and pipelines

Every value has a type. 412 is an Int, "Dune" is a String, and [412, 280, 310] is a List<Int>. Operators and functions combine values into new ones:

412 / 100
4

Both operands are Int, so / divides whole numbers and drops the remainder.

Most HQL programs are pipelines. | passes the value on its left to the step on its right, and each step returns a new value for the next one:

[412, 280, 310] | filter(n => n > 300) | size
2

filter keeps the elements for which a function returns true. Here the function is n => n > 300, a lambda: a function written in place, with its parameter before => and its result after it. size counts what is left. Chapter 3 covers the steps, and chapter 4 covers functions.

Bindings

name = expression binds a value to a name. The name can be used in the statements after it, and the value of the program is its last expression:

pages = 280
chapters = 24
pages / chapters
11

A binding can state its type. The checker then rejects a value of any other type:

rating : Int = "five"
rating
check error[type-mismatch]: `rating` is declared Int but its value is String
 --> <expression>:1:16
  |
1 | rating : Int = "five"
  |                ^^^^^^

Without the declaration, the checker infers the type from the value. A declaration is useful where you want the program to state its intent, and for values whose type cannot be inferred, such as an empty list.

Checked before it runs

hql checks the whole program before it evaluates any of it. A check error names the problem and points at the expression:

1 + "two"
check error[type-mismatch]: addition requires two Int, two Float or two Decimal operands
 --> <expression>:1:5
  |
1 | 1 + "two"
  |     ^^^^^

Nothing was evaluated. There is no value, only the report, and hql exits with status 1. A name that was never bound is a check error too:

pages + 1
check error[unknown-name]: `pages` is not bound
 --> <expression>:1:1
  |
1 | pages + 1
  | ^^^^^

hql check runs only the checker. It prints the type of the program and evaluates nothing:

$ hql check - <<< '412 / 100'
Int

Errors while it runs

Some problems depend on values, and the checker cannot see values. Dividing by zero passes the check and fails when the program runs:

pages = 412
pages / 0
execute failure[division-by-zero]: division by zero
 --> <expression>:2:1
  |
2 | pages / 0
  | ^^^^^^^^^

The report starts with the phase in which the problem was found: check before the program runs, execute while it runs. Data that does not match its type is also found in the execute phase, when the data is read. Chapter 2 shows how, and chapter 12 covers errors in full.

Choosing a value

a given condition otherwise b is a when the condition is true, and b when it is false:

pages = 412
"long" given pages > 300 otherwise "short"
"long"

It is an expression, so it has a value and a type. Both branches must have the same type.

match compares a value with a list of patterns in order. The first pattern that fits gives the result:

status = "reading"
match status {
    "done" => "finished",
    "reading" => "on the nightstand",
    _ => "on the shelf",
}
"on the nightstand"

_ fits any value. A match must cover every possible value, and the checker rejects one that does not:

match 3 { 1 => "one", 2 => "two" }
check error[non-exhaustive-match]: this match does not cover every Int: add a `_` arm
 --> <expression>:1:1
  |
1 | match 3 { 1 => "one", 2 => "two" }
  | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

What is next

Chapter 2 covers types as contracts, and the types values are built from: numbers, text, dates and times, and Data, the tree that JSON and YAML documents are read into.