Skip to content

Reference

Commands at a glance

Command What it does
hql eval <program> check and evaluate a program given as an argument
hql run <file> check and evaluate a program from a file
hql check <file> check a program and print its type, without evaluating it
hql repl read, evaluate and print, one input at a time, keeping bindings
hql plan <file> print each pipeline's steps and the stage the planner gives each, without evaluating
hql boundary <file> <id> print a configured endpoint's boundary: each field, its external name and type, and where each setting came from
hql render <file>… run the HQL cells in a document and write each cell's output
hql help <name> the declarations of a function, type, trait or module, with their doc strings
hql builtins list the steps a pipeline can use
hql config the reporting settings in force and where each came from; list, show and select named contexts
hql context [file] the execution context: the mode, the project, the vault, and where each came from
hql doctor check the semantic-search chain and name the first missing part
hql package <command> install, search, update, list, rebuild and remove packages; chapter 36

hql '<program>' is hql eval '<program>'. - reads standard input wherever a file is taken. Success is exit 0, a language or I/O failure 1, a usage error 2.

Doc strings

A block of /// lines opened after an empty line is the doc string of the declarations below it, up to the next empty line. hql help <name> and :help <name> in hql repl print each declaration of a name with its module and doc string; :type <name> prints the first sentence. The pages below are the standard library's doc strings, one page per function, type and trait.

The standard library

  • std/core — The types every other module is written in: the scalars, the collection types, the open tree Data, absence, failure, value order, the format category and the core traits.
  • std/doc — Documents: a header of everything known about one and a body someone wrote, and the card, a document a vault holds.
  • std/retrieval — Retrieval: a corpus ranked against a query.
  • std/graph — Graphs: nodes and the edges among them, structural only; what a node or an edge means is the knowledge module's.
  • std/knowledge — Knowledge: the semantic domain, where everything is a claim.
  • std/collections — The operations over the collection types core declares: membership, filtering, mapping, order, grouping, joins and reductions.
  • std/string — The functions of a String, in the prelude.
  • std/seq — The sequence, set and map operations beyond the core's membership, order and lookup, in the prelude.
  • std/math — Numbers, in the prelude.
  • std/stats — Descriptive statistics over a collection of numbers: the mean, the sample and population variance and standard deviation, the median, quantiles, the mode, covariance and correlation.
  • std/time — Time: zones, the units a value truncates to, and the operations over the time scalars of core: conversion from text, parts, arithmetic, truncation, rendering, and the evaluation clock.
  • std/random — Randomness: samples, shuffles, choices, numbers and UUIDs.
  • std/option — The ways out of an Option<T>, in the prelude, each stating what absence gives.
  • std/result — The ways out of a Result<T, E>, in the prelude, each stating what a failure gives.
  • std/regex — Text matched against a regular expression.
  • std/format — The formats, how bytes are read as values and how values are written as text, and the codec contracts over them.
  • std/io — Input and output: endpoints, the data sources read from them, and the data targets written to them.
  • std/io/fs — The file system as data: folders, globs over paths, and the entries a folder holds, with their kinds, sizes and modification times.
  • std/io/env — What a program reads from the invocation that runs it: environment variables and named arguments.
  • std/io/net — Network endpoints: transports, read and written by source, tap, target and sink like any other endpoint (module io).
  • std/io/logging — Logging: structured events written to a destination, apart from the result.
  • std/io/db/sqlite — SQLite: one table of a database file, as a transport read by source and tap and written by target like any other endpoint (module io).
  • std/io/db/postgres — PostgreSQL: one table of a database, as a transport read by source and tap and written by target like any other endpoint (module io).
  • std/io/db/spark — Spark SQL: one table behind a Spark SQL endpoint, a Databricks SQL warehouse or a Spark Thrift Server, as a transport read by source and tap and written by target like any other endpoint (module io).
  • std/io/transaction — The control calls of a transaction scope's handle, tx, bound by with transaction tx on participants { … } (module io): each ends the attempt and gives no value, so it stands where any type is expected and nothing after it runs.
  • std/io/msg/nats — Core NATS: one subject, as a transport read by tap and written by sink and target like any other endpoint (module io).
  • std/io/msg/nats_jetstream — NATS JetStream: one subject of a stream, as a transport read by tap and written by sink and target like any other endpoint (module io).
  • std/crypto/digest — Cryptographic digests of text and of Data trees.
  • std/encoding — Text-safe encodings of a text's UTF-8 octets.
  • std/bytes — The functions of a Bytes value, in the prelude.
  • std/crypto — Keys, signatures, MACs, password hashes and encryption.
  • hmd — HyperMarkdown in HQL: the builtin package hmd, beside std.
  • hmd/vault — The current vault: the HyperMarkdown vault a program reads (HQL-0059).
  • hmd/search — Retrieval over a vault's cards: hmd.search.lexical ranks by the words a card shares with a query, hmd.search.semantic by vectors from the vault's index.
  • hmd/search/lexical — Lexical retrieval: a corpus ranked by the words it shares with a query, a hashed bag of words compared by cosine.
  • hmd/search/semantic — Semantic retrieval: a corpus ranked against a query by vectors a language model made ahead of time, read from the index that [semantics] index in the vault's .hmd/config.toml names.
  • std/validators — Validators: the standard validator traits, imported where they are used, import validators, and never by the prelude, so a program's own Email is its own.