< HQL >
^{HIVE QUERY LANGUAGE}

HQL is a modern, high-performance, app-focused query language designed for HiveDB. It replaces SQL with a cleaner, verb-first syntax that is easier to read, write, and parse — while being strict enough to prevent the ambiguity and implicit behavior that make SQL error-prone at scale.

---

Why HQL

• Verb-first structure — every statement starts with its intent: FIND, INSERT, UPDATE, DELETE, UPSERT, TXN
• Fixed clause ordering — no ambiguous grammar, no backtracking, single-token lookahead parsing
• Reduced round trips — TXN blocks with IF/ELSE, REQUIRE, and RETURNING INTO handle multi-step flows in a single query
• Strict null handling — no implicit coercions, ordering comparisons with null are rejected outright
• Built-in safety limits — token count, nesting depth, literal size, and join count are all bounded to prevent resource exhaustion

---

Quick Example

A login flow as a single atomic transaction — one round trip instead of three:

TXN {
  UPDATE users
    SET last_login_at = now(), failed_logins = 0
    WHERE users.email == @email
      AND verify_hash(@password, users.password_hash)
    RETURNING id, role INTO @uid, @user_role;

  REQUIRE affected_rows() == 1 ELSE "AUTH_INVALID";

  INSERT sessions
    VALUES user_id = @uid, token = @token, expires_at = @expires
}

---

Specification

The full language specification is in SPEC.md. Detailed reference documents:

Document	Contents
Lexical structure	Tokens, keywords, operators, comments, security limits
Statements	All 11 statement types, clause ordering, transaction semantics
Expressions	Operators, functions, null handling, precedence table
Overview	Design philosophy and goals

---

Statement Set

Statement	Purpose
FIND	Query with JOIN, WHERE, SELECT DISTINCT, GROUP BY, HAVING, ORDER BY, LIMIT, OFFSET
INSERT	Single-row VALUES or multi-row BATCH
UPDATE	SET with optional WHERE and RETURNING
DELETE	Optional WHERE and RETURNING
UPSERT	Insert-or-update on KEY conflict
TXN	Atomic transaction block
REQUIRE	Guard clause with error code
IF/ELSE	Conditional execution (TXN only)
DEFINE	Schema definition with types and constraints
ALTER	Field and index management
EXPLAIN	Query plan inspection
PING	Health check (micro-query)
GET	Single-record read by parameter (micro-query)
DEL	Single-record delete by parameter (micro-query)

---

Parser

The reference parser implementation is at HiveQL/hql-parser-rs.

---

Status

v1 — Implementation phase. The grammar is stable, the parser is operational, and the spec is being finalized.

---

License

This specification is provided for reference and implementation purposes by the HiveDB project.