Obelisk urQL

urQL is the scripting/query language of Obelisk, an Urbit-native RDBMS Gall agent. It is derived from SQL but differs deliberately for readability, composability, and set/relational theory. When this skill conflicts with desk/doc/usr/reference/ or desk/doc/usr/users-guide.md, the docs win.

First, the differences that bite

• Clause order is evaluation order: FROM .. WHERE .. SELECT .., never SELECT-first.
• SCALARS placement: in a query it sits after the joins and before WHERE; in UPDATE/DELETE it sits before the verb.
• Results are always sets (no dup rows, no DISTINCT). No nulls — columns are non-nullable typed atoms.
• Auras, not SQL types. Literals follow hoon aura notation ('cord', ~2024.1.1, --20, .~3.14, Y/N). @rd floats need the .~ prefix.
• No inlined sub-queries — use CTEs (WITH) / joins, referenced by alias.
• INNER keyword does not exist (JOIN is inner). DELETE requires WHERE. SQL "schema" → NAMESPACE.
• Comments are :: and /* */ (delimiters in columns 1–2), not --.
• Object names are hoon terms (@tas: lower-case, hyphens, leading letter); aliases may be mixed case and are case-agnostic.
• AND has precedence over OR; use parentheses for clarity.
• Scripts (;-separated) are atomic and share one timestamp; once a query appears, no later command may mutate.

Workflow

Writing / generating: confirm clause order (syntax.md → Clause ordering), qualify objects (<db>.<ns>.<obj>, dbo/current-db defaults), use aura-correct literals, list columns explicitly (avoid SELECT * in saved scripts), end arithmetic scalars with END.

Reviewing: check for SQL-isms that are invalid urQL — SELECT-first order, -- comments, INNER JOIN, DISTINCT, nulls, NULL, inlined sub-selects, DELETE with no WHERE, qualified table names inside predicates (only unqualified names or aliases allowed), bare 3.14 where @rd is meant. Verify joins actually share a name+aura column (natural join crashes otherwise).

Debugging: parser errors are terse — inspect the script structurally (clause order, parentheses, END on arithmetic, comma vs. no-comma in VALUES rows). Use the %parse action to inspect the AST without executing (system-views-and-api.md). Confirm a feature is actually executed and not parse-only (see status tables).

Reference map

Topic	File
Clause order, qualification, naming, literals, comments, scripts/atomicity	references/syntax.md
CREATE/ALTER/DROP DATABASE·NAMESPACE·TABLE, foreign keys	references/ddl.md
INSERT, UPSERT, UPDATE, DELETE, TRUNCATE TABLE	references/dml.md
SELECT, joins, CTEs, predicates, set operations, status tables	references/queries.md
Scalar functions (control flow, arithmetic, datetime, math, string)	references/scalars.md
AS OF / time-travel rules and warnings	references/time-travel.md
System views, cmd-result/vector molds, Hoon %obelisk-action API	references/system-views-and-api.md

Canonical worked examples: examples/sample.md.

Implementation status (frequent traps)

Parsed but not yet executed: LEFT/RIGHT/OUTER JOIN, GROUP BY, HAVING, ORDER BY, TOP, aggregates, DIVIDED BY, EQUIV, EXISTS, ALL, ANY, INSERT from SELECT, CREATE/ALTER/DROP INDEX, CREATE/DROP VIEW. Executed: DDL on databases/namespaces/tables, INSERT/UPSERT/UPDATE/DELETE/TRUNCATE, JOIN/JOIN ON/CROSS JOIN, UNION/EXCEPT/INTERSECT, scalar functions, AS OF.