Specification
What an implementation of q must provide
This specification states what a q implementation must do. Each chapter defines a required surface; each rule carries an ID; each rule is pinned by executable tests. An implementation is conformant for a chapter when it passes the tests tagged with that chapter's rules.
kdb+ is the reference implementation. Where this text and the reference disagree, the reference is correct and this text is in error.
Not affiliated with, endorsed by, or a product of KX Systems. "kdb+" and "q" name the reference implementation and the language it implements.
1. What must be implemented
| Chapter | Status | Covers |
|---|---|---|
| core | Required | Right-to-left evaluation with no precedence. The lexical grammar: literals, temporals, symbols, glyph verbs, adverbs, vector runs. The type system and its codes. Verb monad/dyad overloads. The six adverbs. Lambdas, projection, amend, control flow. Lists, dictionaries, tables, keyed tables, enums. |
| q | Required | The keyword layer over that core, the parse-time keyword rewrites that make keywords unshadowable, q 4.1 pattern matching, namespaces, system commands. |
| qsql | Required | select / exec / update / delete over tables, the by and where clauses, column naming, the row-limit form, insert and upsert, the join family, and the functional forms of each. |
| ipc | Required | The wire format: 8-byte frame header, handshake, and the byte encoding of every value. Required for interoperability with any other q process, and the same encoding -8! and -9! expose to the language. |
| storage | Required | On-disk formats: serialized values, column files, splayed tables, symbol enumeration, partitioned databases, compression. Required to read or write a database another implementation produced. |
| runtime | Annex | .z, .Q, .j, system commands. Documented, NOT required — see section 3. |
Read order: core.txt, then q.txt, then qsql.txt. ipc.txt and storage.txt are independent of each other and of the query layer.
2. Conformance
The specification is descriptive. If the reference does it, it is specified, including behaviour that looks accidental: integer infinity wraps on overflow, select of a constant signals while update of a constant broadcasts, match is type-strict but float-tolerant. Implement the behaviour, not the tidier behaviour you expect.
Two things are deliberately not asserted:
- ERROR MESSAGE WORDING. Errors are asserted by CLASS only. An implementation must signal 'length where the reference signals 'length; the text that follows the class is free.
- DISPLAY, except where it is the subject. The -3! rendered form is specified (core.txt 11) and tested in one place. Everywhere else the tests compare VALUES, so an implementation is never required to render a value the way the reference renders it in order to be correct about it.
Partial conformance is the normal state. There is no single pass/fail badge for the language; conformance is reported per chapter.
3. The annex
runtime.txt is documented but not required. Its surface cannot be pinned without naming a host, a machine, or a release: local timezone, workspace limits, timer granularity, thread counts, and the exact membership of .Q.
An implementation that provides none of it is still a conformant q implementation for the language; it is simply not a q process host. Nothing in the annex marked IMPLEMENTATION-DEFINED is asserted by any test.
4. Rule IDs
Every specified unit carries an ID at the end of its heading:
3.6 Temporal literals [CORE-0009]Prefixes are per chapter: CORE, Q, QSQL, IPC, STOR, RT. Numbers are a running counter, assigned once and never reused or renumbered. A rule that is deleted leaves a hole; a rule that moves or is retitled keeps its ID. Cite rules by ID, not by section number.
5. Verifying an implementation
The conformance suite is executable and ships with this specification. Every test is a single-line assertion that must evaluate to 1b:
(1+2)~3
(0W+0W)~-2
(@[value;"1 2+1 2 3";{x}]) like "length*"Run it against any q binary:
oqspec run --q "/path/to/your-q"Tests are tagged with the rule IDs they pin, so oqspec coverage reports which rules a test covers and which rules have no test yet.
To run the suite an implementation needs only: read0, value, @[;;] trap, -1, .z.x with .Q.opt, script arguments, and — for the k categories — loading .k files as k source. Everything else is under test. There is no float-precision requirement: assertions compare values, not rendered text.