bqsqlparse 0.1.0__py3-none-any.whl

bqsqlparse/parser.py

@@ -0,0 +1,1715 @@
+"""Recursive-descent parser for the BigQuery (GoogleSQL) dialect.
+
+Supported statements:
+  SELECT (incl. WITH / RECURSIVE, set operations, ORDER BY, LIMIT/OFFSET)
+  CREATE [OR REPLACE] [TEMP] TABLE / VIEW / MATERIALIZED VIEW ... AS SELECT
+  INSERT, UPDATE, DELETE, MERGE
+
+Supported constructs include: STRUCT & ARRAY literals and types, UNNEST
+(WITH OFFSET), PIVOT / UNPIVOT, TABLESAMPLE, FOR SYSTEM_TIME AS OF, QUALIFY,
+named windows, GROUP BY ROLLUP/CUBE/GROUPING SETS/ALL, SELECT * EXCEPT /
+REPLACE, aggregate modifiers (DISTINCT / IGNORE NULLS / ORDER BY / LIMIT /
+HAVING MAX), CAST FORMAT, EXTRACT, INTERVAL, typed literals, JSON subscripts,
+array subscripts with OFFSET/ORDINAL/SAFE_OFFSET/SAFE_ORDINAL, named function
+arguments (=>), query parameters, LIKE ANY/ALL, IS [NOT] DISTINCT FROM.
+"""
+
+from __future__ import annotations
+
+from typing import List, Optional
+
+from .errors import ParseError, UnsupportedStatementError
+from .lexer import (
+    BYTES, EOF, IDENT, KEYWORD, NUMBER, OP, PARAM, QIDENT, STRING,
+    Token, tokenize,
+)
+from .nodes import (
+    ArrayExpr, ArraySubquery, AssertStmt, Assignment, Between, BinaryOp,
+    BreakContinueStmt, CallStmt, Case, Cast, ColumnDef, ColumnRef,
+    CreateFunction, CreateProcedure, CreateTableAsSelect, CTE, DeclareStmt,
+    DeleteStmt, DropStmt, ExecuteImmediate, ExistsSubquery, Extract,
+    FieldAccess, ForInStmt, FrameBound, FuncCall, GroupBy, HavingModifier,
+    IfBranch, IfStmt, InExpr, InsertStmt, IntervalExpr, IsExpr, Join,
+    LikeExpr, Literal, LoopStmt, MergeStmt, MergeWhen, NamedArg, NamedWindow,
+    Node, OrderItem, Param, PivotAgg, PivotRef, PivotValue, Query, RaiseStmt,
+    RepeatStmt, ReplaceItem, ReturnStmt, RoutineParam, ScalarSubquery,
+    ScriptBlock, Select, SelectItem, SetOp, SetStmt, Star, StructExpr,
+    StructFieldType, StructFieldValue, SubqueryRef, Subscript, TableFuncRef,
+    TableRef, TableSample, TransactionStmt, TruncateStmt, TypedLiteral,
+    TypeNode, UnaryOp, UnnestRef, UnpivotGroup, UnpivotRef, UpdateStmt,
+    WhenClause, WhileStmt, WindowFrame, WindowSpec,
+)
+
+_COMPARISON_OPS = ("=", "!=", "<>", "<", "<=", ">", ">=")
+_TYPED_LITERAL_NAMES = {
+    "DATE", "DATETIME", "TIME", "TIMESTAMP", "NUMERIC", "BIGNUMERIC", "JSON",
+}
+_CALLABLE_KEYWORDS = {"IF", "LEFT", "RIGHT", "GROUPING", "COLLATE", "RANGE"}
+_NILADIC_FUNCTIONS = {
+    "CURRENT_DATE", "CURRENT_DATETIME", "CURRENT_TIME", "CURRENT_TIMESTAMP",
+}
+_CLAUSE_STARTERS = {
+    "FROM", "WHERE", "GROUP", "HAVING", "QUALIFY", "WINDOW", "ORDER",
+    "LIMIT", "UNION", "INTERSECT", "EXCEPT", "INTO",
+}
+_SUBSCRIPT_MODES = {"OFFSET", "ORDINAL", "SAFE_OFFSET", "SAFE_ORDINAL"}
+
+
+class Parser:
+    def __init__(self, sql: str):
+        self.sql = sql
+        self.tokens = tokenize(sql)
+        self.i = 0
+
+    # ------------------------------------------------------------------ utils
+
+    def peek(self, k: int = 0) -> Token:
+        j = min(self.i + k, len(self.tokens) - 1)
+        return self.tokens[j]
+
+    def advance(self) -> Token:
+        tok = self.tokens[self.i]
+        if tok.type != EOF:
+            self.i += 1
+        return tok
+
+    def error(self, msg: str, tok: Optional[Token] = None):
+        tok = tok or self.peek()
+        got = tok.value if tok.type != EOF else "<end of input>"
+        raise ParseError(f"{msg} (got {got!r})", tok.line, tok.col)
+
+    def at_op(self, *ops: str, k: int = 0) -> bool:
+        tok = self.peek(k)
+        return tok.type == OP and tok.value in ops
+
+    def accept_op(self, *ops: str) -> Optional[Token]:
+        if self.at_op(*ops):
+            return self.advance()
+        return None
+
+    def expect_op(self, op: str) -> Token:
+        if not self.at_op(op):
+            self.error(f"Expected {op!r}")
+        return self.advance()
+
+    def at_kw(self, *words: str, k: int = 0) -> bool:
+        tok = self.peek(k)
+        return tok.type in (KEYWORD, IDENT) and tok.value.upper() in words
+
+    def accept_kw(self, *words: str) -> Optional[Token]:
+        if self.at_kw(*words):
+            return self.advance()
+        return None
+
+    def expect_kw(self, *words: str) -> Token:
+        if not self.at_kw(*words):
+            self.error(f"Expected {' or '.join(words)}")
+        return self.advance()
+
+    def _is_ident(self, k: int = 0) -> bool:
+        return self.peek(k).type in (IDENT, QIDENT)
+
+    def parse_ident(self) -> str:
+        tok = self.peek()
+        if tok.type in (IDENT, QIDENT):
+            return self.advance().value
+        self.error("Expected identifier")
+
+    def _parse_name_after_dot(self) -> str:
+        tok = self.peek()
+        if tok.type in (IDENT, QIDENT, KEYWORD):
+            return self.advance().value
+        self.error("Expected name after '.'")
+
+    def _expect_gt(self):
+        """Consume one '>' — splits a '>>' token for nested generic types."""
+        tok = self.peek()
+        if tok.type == OP and tok.value == ">":
+            self.advance()
+        elif tok.type == OP and tok.value == ">>":
+            tok.value = ">"  # consume one of the two
+        else:
+            self.error("Expected '>'")
+
+    def _starts_query(self, k: int = 0) -> bool:
+        while self.at_op("(", k=k):
+            k += 1
+        return self.at_kw("SELECT", "WITH", k=k)
+
+    # ------------------------------------------------------------- statements
+
+    def parse_statements(self) -> List[Node]:
+        stmts: List[Node] = []
+        while True:
+            while self.accept_op(";"):
+                pass
+            if self.peek().type == EOF:
+                break
+            stmts.append(self.parse_statement())
+        return stmts
+
+    def parse_statement(self) -> Node:
+        if self._starts_query():
+            return self.parse_query()
+        if self.at_kw("CREATE"):
+            return self.parse_create()
+        if self.at_kw("INSERT"):
+            return self.parse_insert()
+        if self.at_kw("UPDATE"):
+            return self.parse_update()
+        if self.at_kw("DELETE"):
+            return self.parse_delete()
+        if self.at_kw("MERGE"):
+            return self.parse_merge()
+        # ------------------------- scripting (procedural language) ----------
+        if self._is_ident() and self.at_op(":", k=1):  # label: LOOP/WHILE/...
+            label = self.advance().value
+            self.advance()
+            return self._parse_labeled(label)
+        if self.at_kw("DECLARE"):
+            return self.parse_declare()
+        if self.at_kw("SET"):
+            return self.parse_set_stmt()
+        if self.at_kw("BEGIN"):
+            return self.parse_begin()
+        if self.at_kw("IF"):
+            return self.parse_if()
+        if self.at_kw("LOOP"):
+            return self.parse_loop()
+        if self.at_kw("WHILE"):
+            return self.parse_while()
+        if self.at_kw("REPEAT"):
+            return self.parse_repeat()
+        if self.at_kw("FOR"):
+            return self.parse_for_in()
+        if self.at_kw("BREAK", "LEAVE", "CONTINUE", "ITERATE"):
+            kind = self.advance().value.upper()
+            label = self.advance().value if self._is_ident() else None
+            return BreakContinueStmt(kind, label)
+        if self.at_kw("CALL"):
+            self.advance()
+            name = self._split_path(self._parse_dotted_path())
+            args = self._paren_expr_list() if self.at_op("(") else []
+            return CallStmt(name, args)
+        if self.at_kw("RETURN"):
+            self.advance()
+            return ReturnStmt()
+        if self.at_kw("RAISE"):
+            self.advance()
+            message = None
+            if self.accept_kw("USING"):
+                self.expect_kw("MESSAGE")
+                self.expect_op("=")
+                message = self.parse_expr()
+            return RaiseStmt(message)
+        if self.at_kw("EXECUTE") and self.at_kw("IMMEDIATE", k=1):
+            return self.parse_execute_immediate()
+        if self.at_kw("ASSERT"):
+            self.advance()
+            cond = self.parse_expr()
+            message = None
+            if self.accept_kw("AS"):
+                message = self.parse_expr()
+            return AssertStmt(cond, message)
+        if self.at_kw("COMMIT", "ROLLBACK"):
+            kind = self.advance().value.upper()
+            self.accept_kw("TRANSACTION")
+            return TransactionStmt(kind)
+        if self.at_kw("TRUNCATE"):
+            self.advance()
+            self.expect_kw("TABLE")
+            return TruncateStmt(self._split_path(self._parse_dotted_path()))
+        if self.at_kw("DROP"):
+            return self.parse_drop()
+        tok = self.peek()
+        raise UnsupportedStatementError(
+            f"Unsupported statement starting with {tok.value!r}", tok.line, tok.col
+        )
+
+    # ------------------------------------------------------------------ query
+
+    def parse_query(self) -> Query:
+        ctes: List[CTE] = []
+        recursive = False
+        if self.accept_kw("WITH"):
+            recursive = bool(self.accept_kw("RECURSIVE"))
+            while True:
+                name = self.parse_ident()
+                self.expect_kw("AS")
+                self.expect_op("(")
+                q = self.parse_query()
+                self.expect_op(")")
+                ctes.append(CTE(name, q))
+                if not self.accept_op(","):
+                    break
+        body = self.parse_set_expr()
+        order_by = self.parse_order_by_opt()
+        limit = offset = None
+        if self.accept_kw("LIMIT"):
+            limit = self.parse_expr()
+            if self.accept_kw("OFFSET"):
+                offset = self.parse_expr()
+        return Query(body=body, ctes=ctes, recursive=recursive,
+                     order_by=order_by, limit=limit, offset=offset)
+
+    def parse_order_by_opt(self) -> List[OrderItem]:
+        if not self.at_kw("ORDER"):
+            return []
+        self.advance()
+        self.expect_kw("BY")
+        return self.parse_order_items()
+
+    def parse_order_items(self) -> List[OrderItem]:
+        items = []
+        while True:
+            expr = self.parse_expr()
+            desc = None
+            if self.accept_kw("ASC"):
+                desc = False
+            elif self.accept_kw("DESC"):
+                desc = True
+            nulls = None
+            if self.accept_kw("NULLS"):
+                nulls = self.expect_kw("FIRST", "LAST").value.upper()
+            items.append(OrderItem(expr, desc, nulls))
+            if not self.accept_op(","):
+                break
+        return items
+
+    def parse_set_expr(self) -> Node:
+        left = self.parse_query_primary()
+        while True:
+            if self.at_kw("UNION") or self.at_kw("INTERSECT"):
+                op = self.advance().value.upper()
+            elif self.at_kw("EXCEPT") and self.at_kw("ALL", "DISTINCT", k=1):
+                op = self.advance().value.upper()
+            else:
+                break
+            all_ = self.expect_kw("ALL", "DISTINCT").value.upper() == "ALL"
+            right = self.parse_query_primary()
+            left = SetOp(op, all_, left, right)
+        return left
+
+    def parse_query_primary(self) -> Node:
+        if self.at_kw("SELECT"):
+            return self.parse_select()
+        if self.at_op("("):
+            self.advance()
+            q = self.parse_query()
+            self.expect_op(")")
+            return q
+        self.error("Expected SELECT or '('")
+
+    def parse_select(self) -> Select:
+        self.expect_kw("SELECT")
+        distinct = False
+        if self.accept_kw("DISTINCT"):
+            distinct = True
+        else:
+            self.accept_kw("ALL")
+        as_mode = None
+        if self.accept_kw("AS"):
+            as_mode = self.expect_kw("STRUCT", "VALUE").value.upper()
+
+        items: List[Node] = []
+        while True:
+            items.append(self.parse_select_item())
+            if not self.accept_op(","):
+                break
+            # tolerate BigQuery trailing commas
+            if self._at_clause_boundary():
+                break
+
+        from_ = where = group_by = having = qualify = None
+        windows: List[NamedWindow] = []
+        if self.accept_kw("FROM"):
+            from_ = self.parse_from()
+        if self.accept_kw("WHERE"):
+            where = self.parse_expr()
+        if self.at_kw("GROUP"):
+            self.advance()
+            self.expect_kw("BY")
+            group_by = self.parse_group_by()
+        if self.accept_kw("HAVING"):
+            having = self.parse_expr()
+        if self.accept_kw("QUALIFY"):
+            qualify = self.parse_expr()
+        if self.accept_kw("WINDOW"):
+            while True:
+                wname = self.parse_ident()
+                self.expect_kw("AS")
+                self.expect_op("(")
+                spec = self.parse_window_spec_body()
+                self.expect_op(")")
+                windows.append(NamedWindow(wname, spec))
+                if not self.accept_op(","):
+                    break
+        return Select(items=items, distinct=distinct, as_mode=as_mode,
+                      from_=from_, where=where, group_by=group_by,
+                      having=having, qualify=qualify, windows=windows)
+
+    def _at_clause_boundary(self) -> bool:
+        tok = self.peek()
+        if tok.type == EOF or (tok.type == OP and tok.value in (")", ";")):
+            return True
+        return tok.type == KEYWORD and tok.value in _CLAUSE_STARTERS
+
+    def parse_select_item(self) -> Node:
+        if self.at_op("*"):
+            self.advance()
+            return self._parse_star_modifiers([])
+        expr = self.parse_expr()
+        if self.at_op(".") and self.at_op("*", k=1):
+            if not isinstance(expr, ColumnRef):
+                self.error("Expected path before '.*'")
+            self.advance()
+            self.advance()
+            return self._parse_star_modifiers(expr.path)
+        alias = None
+        if self.accept_kw("AS"):
+            alias = self.parse_ident()
+        elif self._is_ident():
+            alias = self.advance().value
+        return SelectItem(expr, alias)
+
+    def _parse_star_modifiers(self, prefix: List[str]) -> Star:
+        except_: List[str] = []
+        replace: List[ReplaceItem] = []
+        if self.at_kw("EXCEPT") and self.at_op("(", k=1):
+            self.advance()
+            self.advance()
+            while True:
+                except_.append(self.parse_ident())
+                if not self.accept_op(","):
+                    break
+            self.expect_op(")")
+        if self.at_kw("REPLACE") and self.at_op("(", k=1):
+            self.advance()
+            self.advance()
+            while True:
+                e = self.parse_expr()
+                self.expect_kw("AS")
+                name = self.parse_ident()
+                replace.append(ReplaceItem(e, name))
+                if not self.accept_op(","):
+                    break
+            self.expect_op(")")
+        return Star(prefix=prefix, except_=except_, replace=replace)
+
+    def parse_group_by(self) -> GroupBy:
+        if self.accept_kw("ALL"):
+            return GroupBy("all")
+        if self.at_kw("ROLLUP") and self.at_op("(", k=1):
+            self.advance()
+            return GroupBy("rollup", exprs=self._paren_expr_list())
+        if self.at_kw("CUBE") and self.at_op("(", k=1):
+            self.advance()
+            return GroupBy("cube", exprs=self._paren_expr_list())
+        if self.at_kw("GROUPING") and self.at_kw("SETS", k=1):
+            self.advance()
+            self.advance()
+            self.expect_op("(")
+            sets: List[List[Node]] = []
+            while True:
+                if self.at_kw("ROLLUP", "CUBE") and self.at_op("(", k=1):
+                    self.advance()
+                    sets.append(self._paren_expr_list())
+                elif self.accept_op("("):
+                    inner: List[Node] = []
+                    if not self.at_op(")"):
+                        while True:
+                            inner.append(self.parse_expr())
+                            if not self.accept_op(","):
+                                break
+                    self.expect_op(")")
+                    sets.append(inner)
+                else:
+                    sets.append([self.parse_expr()])
+                if not self.accept_op(","):
+                    break
+            self.expect_op(")")
+            return GroupBy("sets", sets=sets)
+        exprs = []
+        while True:
+            exprs.append(self.parse_expr())
+            if not self.accept_op(","):
+                break
+        return GroupBy("exprs", exprs=exprs)
+
+    def _paren_expr_list(self) -> List[Node]:
+        self.expect_op("(")
+        exprs = []
+        if not self.at_op(")"):
+            while True:
+                exprs.append(self.parse_expr())
+                if not self.accept_op(","):
+                    break
+        self.expect_op(")")
+        return exprs
+
+    # ------------------------------------------------------------------- FROM
+
+    def parse_from(self) -> Node:
+        left = self.parse_join_expr()
+        while self.accept_op(","):
+            right = self.parse_join_expr()
+            left = Join("CROSS", left, right)
+        return left
+
+    def parse_join_expr(self) -> Node:
+        left = self.parse_table_primary()
+        while True:
+            kind = None
+            if self.at_kw("CROSS") and self.at_kw("JOIN", k=1):
+                self.advance()
+                self.advance()
+                kind = "CROSS"
+            elif self.at_kw("INNER"):
+                self.advance()
+                self.expect_kw("JOIN")
+                kind = "INNER"
+            elif self.at_kw("LEFT", "RIGHT", "FULL") and self.at_kw("OUTER", "JOIN", k=1):
+                kind = self.advance().value.upper()
+                self.accept_kw("OUTER")
+                self.expect_kw("JOIN")
+            elif self.at_kw("JOIN"):
+                self.advance()
+                kind = "INNER"
+            else:
+                break
+            right = self.parse_table_primary()
+            on = None
+            using: List[str] = []
+            if kind != "CROSS":
+                if self.accept_kw("ON"):
+                    on = self.parse_expr()
+                elif self.accept_kw("USING"):
+                    self.expect_op("(")
+                    while True:
+                        using.append(self.parse_ident())
+                        if not self.accept_op(","):
+                            break
+                    self.expect_op(")")
+            left = Join(kind, left, right, on=on, using=using)
+        return left
+
+    def parse_table_primary(self) -> Node:
+        node = self._parse_table_primary_base()
+        while True:
+            if self.at_kw("PIVOT") and self.at_op("(", k=1):
+                node = self._parse_pivot(node)
+            elif self.at_kw("UNPIVOT") and (
+                self.at_op("(", k=1) or self.at_kw("INCLUDE", "EXCLUDE", k=1)
+            ):
+                node = self._parse_unpivot(node)
+            elif self.at_kw("TABLESAMPLE"):
+                self.advance()
+                method = self.expect_kw("SYSTEM", "BERNOULLI", "RESERVOIR").value.upper()
+                self.expect_op("(")
+                value = self.parse_expr()
+                unit = "PERCENT"
+                if self.at_kw("PERCENT", "ROWS"):
+                    unit = self.advance().value.upper()
+                self.expect_op(")")
+                if isinstance(node, TableRef):
+                    node.sample = TableSample(method, value, unit)
+            else:
+                break
+        return node
+
+    def _parse_table_alias(self) -> Optional[str]:
+        if self.accept_kw("AS"):
+            return self.parse_ident()
+        if self._is_ident():
+            up = self.peek().value.upper()
+            if up in ("PIVOT", "UNPIVOT") and self.at_op("(", k=1):
+                return None
+            if up in ("TABLESAMPLE",):
+                return None
+            return self.advance().value
+        return None
+
+    def _parse_table_primary_base(self) -> Node:
+        if self.at_op("("):
+            if self._starts_query():
+                self.advance()
+                q = self.parse_query()
+                self.expect_op(")")
+                alias = self._parse_table_alias()
+                return SubqueryRef(q, alias)
+            self.advance()
+            inner = self.parse_from()
+            self.expect_op(")")
+            return inner
+        if self.at_kw("UNNEST"):
+            self.advance()
+            self.expect_op("(")
+            expr = self.parse_expr()
+            self.expect_op(")")
+            alias = self._parse_table_alias()
+            with_offset = False
+            offset_alias = None
+            if self.at_kw("WITH") and self.at_kw("OFFSET", k=1):
+                self.advance()
+                self.advance()
+                with_offset = True
+                if self.accept_kw("AS"):
+                    offset_alias = self.parse_ident()
+                elif self._is_ident():
+                    offset_alias = self.advance().value
+            return UnnestRef(expr, alias, with_offset, offset_alias)
+        # table path (possibly a table-valued function)
+        path = [self.parse_ident()]
+        while self.at_op(".") and not self.at_op("*", k=1):
+            self.advance()
+            path.append(self._parse_name_after_dot())
+        if self.at_op("("):
+            args = self._paren_expr_list()
+            alias = self._parse_table_alias()
+            return TableFuncRef(path, args, alias)
+        # a quoted `project.dataset.table` arrives as a single token — split it
+        parts: List[str] = []
+        for p in path:
+            parts.extend(p.split(".") if "." in p else [p])
+        system_time = None
+        if self.at_kw("FOR") and self.at_kw("SYSTEM_TIME", k=1):
+            self.advance()
+            self.advance()
+            self.expect_kw("AS")
+            self.expect_kw("OF")
+            system_time = self.parse_expr()
+        alias = self._parse_table_alias()
+        return TableRef(parts, alias, system_time)
+
+    def _parse_pivot(self, input_: Node) -> PivotRef:
+        self.advance()  # PIVOT
+        self.expect_op("(")
+        aggs: List[PivotAgg] = []
+        while True:
+            expr = self.parse_expr()
+            if not isinstance(expr, FuncCall):
+                self.error("PIVOT expects aggregate function calls")
+            agg_alias = None
+            if self.accept_kw("AS"):
+                agg_alias = self.parse_ident()
+            elif self._is_ident() and not self.at_kw("FOR"):
+                agg_alias = self.advance().value
+            aggs.append(PivotAgg(expr, agg_alias))
+            if not self.accept_op(","):
+                break
+        self.expect_kw("FOR")
+        for_col = ColumnRef(self._parse_dotted_path())
+        self.expect_kw("IN")
+        self.expect_op("(")
+        in_values: List[PivotValue] = []
+        while True:
+            v = self.parse_expr()
+            v_alias = None
+            if self.accept_kw("AS"):
+                v_alias = self.parse_ident()
+            elif self._is_ident():
+                v_alias = self.advance().value
+            in_values.append(PivotValue(v, v_alias))
+            if not self.accept_op(","):
+                break
+        self.expect_op(")")
+        self.expect_op(")")
+        alias = self._parse_table_alias()
+        return PivotRef(input_, aggs, for_col, in_values, alias)
+
+    def _parse_unpivot(self, input_: Node) -> UnpivotRef:
+        self.advance()  # UNPIVOT
+        include_nulls = None
+        if self.accept_kw("INCLUDE"):
+            self.expect_kw("NULLS")
+            include_nulls = True
+        elif self.accept_kw("EXCLUDE"):
+            self.expect_kw("NULLS")
+            include_nulls = False
+        self.expect_op("(")
+        value_columns: List[str] = []
+        multi = False
+        if self.accept_op("("):
+            multi = True
+            while True:
+                value_columns.append(self.parse_ident())
+                if not self.accept_op(","):
+                    break
+            self.expect_op(")")
+        else:
+            value_columns.append(self.parse_ident())
+        self.expect_kw("FOR")
+        name_column = self.parse_ident()
+        self.expect_kw("IN")
+        self.expect_op("(")
+        groups: List[UnpivotGroup] = []
+        while True:
+            cols: List[List[str]] = []
+            if multi:
+                self.expect_op("(")
+                while True:
+                    cols.append(self._parse_dotted_path())
+                    if not self.accept_op(","):
+                        break
+                self.expect_op(")")
+            else:
+                cols.append(self._parse_dotted_path())
+            label = None
+            if self.accept_kw("AS"):
+                label = self.parse_expr()
+            elif self.peek().type in (STRING, NUMBER):
+                label = self.parse_expr()
+            groups.append(UnpivotGroup(cols, label))
+            if not self.accept_op(","):
+                break
+        self.expect_op(")")
+        self.expect_op(")")
+        alias = self._parse_table_alias()
+        return UnpivotRef(input_, value_columns, name_column, groups,
+                          include_nulls, alias)
+
+    def _parse_dotted_path(self) -> List[str]:
+        path = [self.parse_ident()]
+        while self.at_op(".") and not self.at_op("*", k=1):
+            self.advance()
+            path.append(self._parse_name_after_dot())
+        return path
+
+    # ------------------------------------------------------------ expressions
+
+    def parse_expr(self) -> Node:
+        return self.parse_or()
+
+    def parse_or(self) -> Node:
+        left = self.parse_and()
+        while self.at_kw("OR") and self.peek().type == KEYWORD:
+            self.advance()
+            left = BinaryOp("OR", left, self.parse_and())
+        return left
+
+    def parse_and(self) -> Node:
+        left = self.parse_not()
+        while self.at_kw("AND") and self.peek().type == KEYWORD:
+            self.advance()
+            left = BinaryOp("AND", left, self.parse_not())
+        return left
+
+    def parse_not(self) -> Node:
+        if self.peek().type == KEYWORD and self.peek().value == "NOT" \
+                and not self.at_kw("LIKE", "BETWEEN", "IN", k=1):
+            self.advance()
+            return UnaryOp("NOT", self.parse_not())
+        return self.parse_comparison()
+
+    def parse_comparison(self) -> Node:
+        left = self.parse_bitor()
+        while True:
+            negated = False
+            if self.peek().type == KEYWORD and self.peek().value == "NOT" \
+                    and self.at_kw("LIKE", "BETWEEN", "IN", k=1):
+                self.advance()
+                negated = True
+            tok = self.peek()
+            if tok.type == OP and tok.value in _COMPARISON_OPS:
+                self.advance()
+                left = BinaryOp(tok.value, left, self.parse_bitor())
+            elif self.at_kw("LIKE"):
+                self.advance()
+                quantifier = None
+                if self.at_kw("ANY", "ALL", "SOME"):
+                    quantifier = self.advance().value.upper()
+                    patterns = self._paren_expr_list()
+                else:
+                    patterns = [self.parse_bitor()]
+                left = LikeExpr(left, patterns, quantifier, negated)
+            elif self.at_kw("BETWEEN"):
+                self.advance()
+                low = self.parse_bitor()
+                self.expect_kw("AND")
+                high = self.parse_bitor()
+                left = Between(left, low, high, negated)
+            elif self.at_kw("IN"):
+                self.advance()
+                if self.at_kw("UNNEST"):
+                    self.advance()
+                    self.expect_op("(")
+                    arr = self.parse_expr()
+                    self.expect_op(")")
+                    left = InExpr(left, unnest=arr, negated=negated)
+                else:
+                    self.expect_op("(")
+                    if self._starts_query():
+                        q = self.parse_query()
+                        self.expect_op(")")
+                        left = InExpr(left, query=q, negated=negated)
+                    else:
+                        values = [self.parse_expr()]
+                        while self.accept_op(","):
+                            values.append(self.parse_expr())
+                        self.expect_op(")")
+                        left = InExpr(left, values=values, negated=negated)
+            elif self.at_kw("IS"):
+                self.advance()
+                neg = bool(self.accept_kw("NOT"))
+                if self.accept_kw("DISTINCT"):
+                    self.expect_kw("FROM")
+                    op = "IS NOT DISTINCT FROM" if neg else "IS DISTINCT FROM"
+                    left = BinaryOp(op, left, self.parse_bitor())
+                else:
+                    val = self.expect_kw("NULL", "TRUE", "FALSE", "UNKNOWN")
+                    left = IsExpr(left, val.value.upper(), neg)
+            else:
+                break
+        return left
+
+    def parse_bitor(self) -> Node:
+        left = self.parse_bitxor()
+        while self.at_op("|"):
+            self.advance()
+            left = BinaryOp("|", left, self.parse_bitxor())
+        return left
+
+    def parse_bitxor(self) -> Node:
+        left = self.parse_bitand()
+        while self.at_op("^"):
+            self.advance()
+            left = BinaryOp("^", left, self.parse_bitand())
+        return left
+
+    def parse_bitand(self) -> Node:
+        left = self.parse_shift()
+        while self.at_op("&"):
+            self.advance()
+            left = BinaryOp("&", left, self.parse_shift())
+        return left
+
+    def parse_shift(self) -> Node:
+        left = self.parse_additive()
+        while self.at_op("<<", ">>"):
+            op = self.advance().value
+            left = BinaryOp(op, left, self.parse_additive())
+        return left
+
+    def parse_additive(self) -> Node:
+        left = self.parse_multiplicative()
+        while self.at_op("+", "-"):
+            op = self.advance().value
+            left = BinaryOp(op, left, self.parse_multiplicative())
+        return left
+
+    def parse_multiplicative(self) -> Node:
+        left = self.parse_unary()
+        while self.at_op("*", "/", "||"):
+            op = self.advance().value
+            left = BinaryOp(op, left, self.parse_unary())
+        return left
+
+    def parse_unary(self) -> Node:
+        if self.at_op("-", "+", "~"):
+            op = self.advance().value
+            return UnaryOp(op, self.parse_unary())
+        return self.parse_postfix()
+
+    def parse_postfix(self) -> Node:
+        expr = self.parse_primary()
+        while True:
+            if self.at_op(".") and not self.at_op("*", k=1):
+                self.advance()
+                name = self._parse_name_after_dot()
+                if isinstance(expr, ColumnRef):
+                    expr = ColumnRef(expr.path + [name])
+                else:
+                    expr = FieldAccess(expr, name)
+            elif self.at_op("["):
+                self.advance()
+                mode = None
+                if self.at_kw(*_SUBSCRIPT_MODES) and self.at_op("(", k=1):
+                    mode = self.advance().value.upper()
+                    self.expect_op("(")
+                    index = self.parse_expr()
+                    self.expect_op(")")
+                else:
+                    index = self.parse_expr()
+                self.expect_op("]")
+                expr = Subscript(expr, index, mode)
+            else:
+                break
+        return expr
+
+    def parse_primary(self) -> Node:
+        tok = self.peek()
+
+        if tok.type == NUMBER:
+            self.advance()
+            return Literal(tok.value, "number")
+        if tok.type == STRING:
+            self.advance()
+            return Literal(tok.value, "string")
+        if tok.type == BYTES:
+            self.advance()
+            return Literal(tok.value, "bytes")
+        if tok.type == PARAM:
+            self.advance()
+            return Param(tok.value)
+
+        if tok.type == KEYWORD:
+            v = tok.value
+            if v in ("TRUE", "FALSE"):
+                self.advance()
+                return Literal(v == "TRUE", "bool")
+            if v == "NULL":
+                self.advance()
+                return Literal(None, "null")
+            if v == "DEFAULT":
+                self.advance()
+                return Literal(None, "default")
+            if v == "CASE":
+                return self.parse_case()
+            if v == "CAST":
+                return self.parse_cast(safe=False)
+            if v == "EXTRACT":
+                return self.parse_extract()
+            if v == "EXISTS" and self.at_op("(", k=1):
+                self.advance()
+                self.expect_op("(")
+                q = self.parse_query()
+                self.expect_op(")")
+                return ExistsSubquery(q)
+            if v == "ARRAY":
+                return self.parse_array()
+            if v == "STRUCT":
+                return self.parse_struct()
+            if v == "INTERVAL":
+                return self.parse_interval()
+            if v == "NOT":
+                self.advance()
+                return UnaryOp("NOT", self.parse_not())
+            if v in _CALLABLE_KEYWORDS and self.at_op("(", k=1):
+                self.advance()
+                return self.parse_func_call([v])
+
+        if self.at_op("["):  # bare array literal: [1, 2, 3]
+            self.advance()
+            elements: List[Node] = []
+            if not self.at_op("]"):
+                while True:
+                    elements.append(self.parse_expr())
+                    if not self.accept_op(","):
+                        break
+            self.expect_op("]")
+            return ArrayExpr(elements)
+
+        if self.at_op("("):
+            if self._starts_query():
+                self.advance()
+                q = self.parse_query()
+                self.expect_op(")")
+                return ScalarSubquery(q)
+            self.advance()
+            expr = self.parse_expr()
+            if self.at_op(","):
+                fields = [StructFieldValue(expr)]
+                while self.accept_op(","):
+                    fields.append(StructFieldValue(self.parse_expr()))
+                self.expect_op(")")
+                return StructExpr(fields)
+            self.expect_op(")")
+            return expr
+
+        # typed literals: DATE '...', JSON '...', etc.
+        if tok.type == IDENT and tok.value.upper() in _TYPED_LITERAL_NAMES \
+                and self.peek(1).type == STRING:
+            self.advance()
+            lit = self.advance()
+            return TypedLiteral(tok.value.upper(), lit.value)
+
+        if tok.type in (IDENT, QIDENT):
+            path = [self.advance().value]
+            while self.at_op(".") and not self.at_op("*", k=1) \
+                    and self.peek(1).type in (IDENT, QIDENT, KEYWORD):
+                self.advance()
+                path.append(self._parse_name_after_dot())
+            if self.at_op("("):
+                if path[-1].upper() == "SAFE_CAST" and len(path) == 1:
+                    return self.parse_cast(safe=True, consumed_name=True)
+                return self.parse_func_call(path)
+            if len(path) == 1 and path[0].upper() in _NILADIC_FUNCTIONS:
+                return FuncCall([path[0].upper()])
+            return ColumnRef(path)
+
+        self.error("Unexpected token in expression")
+
+    def parse_case(self) -> Case:
+        self.expect_kw("CASE")
+        operand = None
+        if not self.at_kw("WHEN"):
+            operand = self.parse_expr()
+        whens: List[WhenClause] = []
+        while self.accept_kw("WHEN"):
+            cond = self.parse_expr()
+            self.expect_kw("THEN")
+            whens.append(WhenClause(cond, self.parse_expr()))
+        else_ = None
+        if self.accept_kw("ELSE"):
+            else_ = self.parse_expr()
+        self.expect_kw("END")
+        return Case(operand, whens, else_)
+
+    def parse_cast(self, safe: bool, consumed_name: bool = False) -> Cast:
+        if not consumed_name:
+            self.advance()  # CAST
+        self.expect_op("(")
+        expr = self.parse_expr()
+        self.expect_kw("AS")
+        to_type = self.parse_type()
+        fmt = None
+        if self.accept_kw("FORMAT"):
+            fmt = self.parse_expr()
+        self.expect_op(")")
+        return Cast(expr, to_type, safe, fmt)
+
+    def parse_extract(self) -> Extract:
+        self.expect_kw("EXTRACT")
+        self.expect_op("(")
+        part_tok = self.advance()
+        part = part_tok.value.upper()
+        if self.at_op("("):  # WEEK(MONDAY)
+            self.advance()
+            day = self.advance().value.upper()
+            self.expect_op(")")
+            part = f"{part}({day})"
+        self.expect_kw("FROM")
+        expr = self.parse_expr()
+        tz = None
+        if self.accept_kw("AT"):
+            self.expect_kw("TIME")
+            self.expect_kw("ZONE")
+            tz = self.parse_expr()
+        self.expect_op(")")
+        return Extract(part, expr, tz)
+
+    def parse_array(self) -> Node:
+        self.expect_kw("ARRAY")
+        elem_type = None
+        if self.at_op("<"):
+            self.advance()
+            elem_type = self.parse_type()
+            self._expect_gt()
+        if self.at_op("("):
+            self.advance()
+            q = self.parse_query()
+            self.expect_op(")")
+            return ArraySubquery(q)
+        self.expect_op("[")
+        elements: List[Node] = []
+        if not self.at_op("]"):
+            while True:
+                elements.append(self.parse_expr())
+                if not self.accept_op(","):
+                    break
+        self.expect_op("]")
+        return ArrayExpr(elements, elem_type)
+
+    def parse_struct(self) -> StructExpr:
+        self.expect_kw("STRUCT")
+        type_fields = None
+        if self.at_op("<"):
+            self.advance()
+            type_fields = self._parse_struct_type_fields()
+        self.expect_op("(")
+        fields: List[StructFieldValue] = []
+        if not self.at_op(")"):
+            while True:
+                e = self.parse_expr()
+                name = None
+                if self.accept_kw("AS"):
+                    name = self.parse_ident()
+                fields.append(StructFieldValue(e, name))
+                if not self.accept_op(","):
+                    break
+        self.expect_op(")")
+        return StructExpr(fields, type_fields)
+
+    def parse_interval(self) -> IntervalExpr:
+        self.expect_kw("INTERVAL")
+        value = self.parse_additive()
+        unit = self.advance().value.upper()
+        to_unit = None
+        if self.accept_kw("TO"):
+            to_unit = self.advance().value.upper()
+        return IntervalExpr(value, unit, to_unit)
+
+    def parse_func_call(self, path: List[str]) -> FuncCall:
+        self.expect_op("(")
+        distinct = bool(self.accept_kw("DISTINCT"))
+        args: List[Node] = []
+        nulls = None
+        order_by: List[OrderItem] = []
+        limit = None
+        having = None
+        if not self.at_op(")"):
+            if self.at_op("*"):
+                self.advance()
+                args.append(Star())
+            else:
+                while True:
+                    if self._is_ident() and self.at_op("=>", k=1):
+                        name = self.advance().value
+                        self.advance()
+                        args.append(NamedArg(name, self.parse_expr()))
+                    else:
+                        args.append(self.parse_expr())
+                    if not self.accept_op(","):
+                        break
+            # aggregate modifiers, in any order, before ')'
+            while True:
+                if self.at_kw("IGNORE", "RESPECT") and self.at_kw("NULLS", k=1):
+                    nulls = self.advance().value.upper()
+                    self.advance()
+                elif self.at_kw("HAVING") and self.at_kw("MAX", "MIN", k=1):
+                    self.advance()
+                    kind = self.advance().value.upper()
+                    having = HavingModifier(kind, self.parse_expr())
+                elif self.at_kw("ORDER"):
+                    self.advance()
+                    self.expect_kw("BY")
+                    order_by = self.parse_order_items()
+                elif self.at_kw("LIMIT"):
+                    self.advance()
+                    limit = self.parse_expr()
+                else:
+                    break
+        self.expect_op(")")
+        over = None
+        if self.at_kw("OVER"):
+            self.advance()
+            if self.at_op("("):
+                self.advance()
+                over = self.parse_window_spec_body()
+                self.expect_op(")")
+            else:
+                over = WindowSpec(name=self.parse_ident(), is_ref=True)
+        return FuncCall(path, args, distinct, nulls, order_by, limit, having, over)
+
+    def parse_window_spec_body(self) -> WindowSpec:
+        name = None
+        if self._is_ident() and not self.at_kw("PARTITION", "ORDER", "ROWS", "RANGE", "GROUPS"):
+            name = self.advance().value
+        partition_by: List[Node] = []
+        if self.at_kw("PARTITION"):
+            self.advance()
+            self.expect_kw("BY")
+            while True:
+                partition_by.append(self.parse_expr())
+                if not self.accept_op(","):
+                    break
+        order_by = self.parse_order_by_opt()
+        frame = None
+        if self.at_kw("ROWS", "RANGE", "GROUPS"):
+            unit = self.advance().value.upper()
+            if self.accept_kw("BETWEEN"):
+                start = self.parse_frame_bound()
+                self.expect_kw("AND")
+                end = self.parse_frame_bound()
+                frame = WindowFrame(unit, start, end)
+            else:
+                frame = WindowFrame(unit, self.parse_frame_bound())
+        return WindowSpec(name, partition_by, order_by, frame)
+
+    def parse_frame_bound(self) -> FrameBound:
+        if self.accept_kw("UNBOUNDED"):
+            kind = self.expect_kw("PRECEDING", "FOLLOWING").value.upper()
+            return FrameBound(f"UNBOUNDED {kind}")
+        if self.accept_kw("CURRENT"):
+            self.expect_kw("ROW")
+            return FrameBound("CURRENT ROW")
+        value = self.parse_expr()
+        kind = self.expect_kw("PRECEDING", "FOLLOWING").value.upper()
+        return FrameBound(kind, value)
+
+    # ------------------------------------------------------------------ types
+
+    def parse_type(self) -> TypeNode:
+        if self.at_kw("ARRAY"):
+            self.advance()
+            self.expect_op("<")
+            elem = self.parse_type()
+            self._expect_gt()
+            return TypeNode("ARRAY", element=elem)
+        if self.at_kw("STRUCT"):
+            self.advance()
+            fields: List[StructFieldType] = []
+            if self.at_op("<"):
+                self.advance()
+                fields = self._parse_struct_type_fields()
+            return TypeNode("STRUCT", fields_=fields)
+        if self.at_kw("RANGE"):
+            self.advance()
+            self.expect_op("<")
+            elem = self.parse_type()
+            self._expect_gt()
+            return TypeNode("RANGE", element=elem)
+        if self.at_kw("INTERVAL"):
+            self.advance()
+            return TypeNode("INTERVAL")
+        if self.at_kw("ANY"):
+            self.advance()
+            self.expect_kw("TYPE")
+            return TypeNode("ANY TYPE")
+        tok = self.peek()
+        if tok.type not in (IDENT, QIDENT):
+            self.error("Expected type name")
+        name = self.advance().value.upper()
+        params: List[str] = []
+        if self.at_op("("):
+            self.advance()
+            while True:
+                p = self.advance()
+                params.append(p.value)
+                if not self.accept_op(","):
+                    break
+            self.expect_op(")")
+        return TypeNode(name, params=params)
+
+    def _parse_struct_type_fields(self) -> List[StructFieldType]:
+        fields: List[StructFieldType] = []
+        while True:
+            fname: Optional[str] = None
+            tok = self.peek()
+            if tok.type in (IDENT, QIDENT) and (
+                self.peek(1).type in (IDENT, QIDENT)
+                or self.at_kw("ARRAY", "STRUCT", "RANGE", "INTERVAL", k=1)
+                or self.at_op("<", k=1)
+            ):
+                # "name type" — but "name <" only if name isn't itself generic
+                fname = self.advance().value
+            fields.append(StructFieldType(fname, self.parse_type()))
+            if not self.accept_op(","):
+                break
+        self._expect_gt()
+        return fields
+
+    # ------------------------------------------------------------- scripting
+
+    _SCRIPT_TERMINATORS = ("END", "ELSEIF", "ELSE", "EXCEPTION", "UNTIL", "WHEN")
+
+    def parse_statement_list(self) -> List[Node]:
+        stmts: List[Node] = []
+        while True:
+            while self.accept_op(";"):
+                pass
+            if self.peek().type == EOF or self.at_kw(*self._SCRIPT_TERMINATORS):
+                break
+            stmts.append(self.parse_statement())
+        return stmts
+
+    def _parse_labeled(self, label: str) -> Node:
+        if self.at_kw("LOOP"):
+            stmt = self.parse_loop()
+        elif self.at_kw("WHILE"):
+            stmt = self.parse_while()
+        elif self.at_kw("REPEAT"):
+            stmt = self.parse_repeat()
+        elif self.at_kw("FOR"):
+            stmt = self.parse_for_in()
+        elif self.at_kw("BEGIN"):
+            stmt = self.parse_begin()
+        else:
+            self.error("Expected LOOP, WHILE, REPEAT, FOR or BEGIN after label")
+        stmt.label = label
+        self._accept_trailing_label(stmt)
+        return stmt
+
+    def _accept_trailing_label(self, label_holder: Node):
+        if getattr(label_holder, "label", None) and self._is_ident() \
+                and self.peek().value.lower() == label_holder.label.lower():
+            self.advance()
+
+    def parse_declare(self) -> DeclareStmt:
+        self.expect_kw("DECLARE")
+        names = [self.parse_ident()]
+        while self.accept_op(","):
+            names.append(self.parse_ident())
+        var_type = None
+        default = None
+        if self.accept_kw("DEFAULT"):
+            default = self.parse_expr()
+        elif not self.at_op(";") and self.peek().type != EOF:
+            var_type = self.parse_type()
+            if self.accept_kw("DEFAULT"):
+                default = self.parse_expr()
+        return DeclareStmt(names, var_type, default)
+
+    def parse_set_stmt(self) -> SetStmt:
+        self.expect_kw("SET")
+        targets: List[str] = []
+        if self.accept_op("("):
+            while True:
+                targets.append(self.parse_ident())
+                if not self.accept_op(","):
+                    break
+            self.expect_op(")")
+        elif self.peek().type == PARAM:
+            targets.append(self.advance().value)
+        else:
+            targets.append(self.parse_ident())
+        self.expect_op("=")
+        return SetStmt(targets, self.parse_expr())
+
+    def parse_begin(self) -> Node:
+        self.expect_kw("BEGIN")
+        if self.accept_kw("TRANSACTION"):
+            return TransactionStmt("BEGIN")
+        if self.at_op(";") or self.peek().type == EOF:
+            return TransactionStmt("BEGIN")
+        statements = self.parse_statement_list()
+        exception_statements: List[Node] = []
+        has_handler = False
+        if self.accept_kw("EXCEPTION"):
+            self.expect_kw("WHEN")
+            self.expect_kw("ERROR")
+            self.expect_kw("THEN")
+            has_handler = True
+            exception_statements = self.parse_statement_list()
+        self.expect_kw("END")
+        block = ScriptBlock(statements, exception_statements, has_handler)
+        self._accept_trailing_label(block)
+        return block
+
+    def parse_if(self) -> IfStmt:
+        self.expect_kw("IF")
+        cond = self.parse_expr()
+        self.expect_kw("THEN")
+        branches = [IfBranch(cond, self.parse_statement_list())]
+        while self.at_kw("ELSEIF"):
+            self.advance()
+            cond = self.parse_expr()
+            self.expect_kw("THEN")
+            branches.append(IfBranch(cond, self.parse_statement_list()))
+        else_statements: List[Node] = []
+        if self.accept_kw("ELSE"):
+            else_statements = self.parse_statement_list()
+        self.expect_kw("END")
+        self.expect_kw("IF")
+        return IfStmt(branches, else_statements)
+
+    def parse_loop(self) -> LoopStmt:
+        self.expect_kw("LOOP")
+        stmts = self.parse_statement_list()
+        self.expect_kw("END")
+        self.expect_kw("LOOP")
+        loop = LoopStmt(stmts)
+        self._accept_trailing_label(loop)
+        return loop
+
+    def parse_while(self) -> WhileStmt:
+        self.expect_kw("WHILE")
+        cond = self.parse_expr()
+        self.expect_kw("DO")
+        stmts = self.parse_statement_list()
+        self.expect_kw("END")
+        self.expect_kw("WHILE")
+        loop = WhileStmt(cond, stmts)
+        self._accept_trailing_label(loop)
+        return loop
+
+    def parse_repeat(self) -> RepeatStmt:
+        self.expect_kw("REPEAT")
+        stmts = self.parse_statement_list()
+        self.expect_kw("UNTIL")
+        until = self.parse_expr()
+        self.expect_kw("END")
+        self.expect_kw("REPEAT")
+        loop = RepeatStmt(stmts, until)
+        self._accept_trailing_label(loop)
+        return loop
+
+    def parse_for_in(self) -> ForInStmt:
+        self.expect_kw("FOR")
+        var = self.parse_ident()
+        self.expect_kw("IN")
+        self.expect_op("(")
+        query = self.parse_query()
+        self.expect_op(")")
+        self.expect_kw("DO")
+        stmts = self.parse_statement_list()
+        self.expect_kw("END")
+        self.expect_kw("FOR")
+        loop = ForInStmt(var, query, stmts)
+        self._accept_trailing_label(loop)
+        return loop
+
+    def parse_execute_immediate(self) -> ExecuteImmediate:
+        self.expect_kw("EXECUTE")
+        self.expect_kw("IMMEDIATE")
+        sql_expr = self.parse_expr()
+        into: List[str] = []
+        using: List = []
+        if self.accept_kw("INTO"):
+            while True:
+                into.append(self.parse_ident())
+                if not self.accept_op(","):
+                    break
+        if self.accept_kw("USING"):
+            while True:
+                e = self.parse_expr()
+                alias = None
+                if self.accept_kw("AS"):
+                    alias = self.parse_ident()
+                using.append((e, alias))
+                if not self.accept_op(","):
+                    break
+        return ExecuteImmediate(sql_expr, into, using)
+
+    def parse_drop(self) -> DropStmt:
+        self.expect_kw("DROP")
+        kind = self.advance().value.upper()
+        if kind in ("MATERIALIZED", "EXTERNAL", "SNAPSHOT", "SEARCH", "VECTOR"):
+            kind += " " + self.advance().value.upper()
+        elif kind == "TABLE" and self.at_kw("FUNCTION"):
+            kind += " " + self.advance().value.upper()
+        if_exists = False
+        if self.at_kw("IF") and self.at_kw("EXISTS", k=1):
+            self.advance()
+            self.advance()
+            if_exists = True
+        return DropStmt(kind, self._split_path(self._parse_dotted_path()), if_exists)
+
+    # ------------------------------------------------------------- DDL / DML
+
+    def _skip_balanced_parens(self) -> str:
+        start_tok = self.expect_op("(")
+        depth = 1
+        start = start_tok.pos
+        while depth > 0:
+            tok = self.advance()
+            if tok.type == EOF:
+                self.error("Unbalanced parentheses")
+            if tok.type == OP and tok.value == "(":
+                depth += 1
+            elif tok.type == OP and tok.value == ")":
+                depth -= 1
+                end = tok.pos + 1
+        return self.sql[start:end]
+
+    def parse_create(self) -> Node:
+        self.expect_kw("CREATE")
+        replace = False
+        if self.accept_kw("OR"):
+            self.expect_kw("REPLACE")
+            replace = True
+        temp = bool(self.accept_kw("TEMP", "TEMPORARY"))
+        if self.at_kw("PROCEDURE"):
+            return self._parse_create_procedure(replace)
+        if self.at_kw("AGGREGATE") and self.at_kw("FUNCTION", k=1):
+            self.advance()
+            self.advance()
+            return self._parse_create_function(replace, temp, aggregate=True)
+        if self.at_kw("FUNCTION"):
+            self.advance()
+            return self._parse_create_function(replace, temp)
+        if self.at_kw("TABLE") and self.at_kw("FUNCTION", k=1):
+            self.advance()
+            self.advance()
+            return self._parse_create_function(replace, temp, table_function=True)
+        kind = "TABLE"
+        if self.accept_kw("MATERIALIZED"):
+            self.expect_kw("VIEW")
+            kind = "MATERIALIZED VIEW"
+        elif self.accept_kw("VIEW"):
+            kind = "VIEW"
+        else:
+            self.expect_kw("TABLE")
+        if_not_exists = False
+        if self.at_kw("IF") and self.at_kw("NOT", k=1):
+            self.advance()
+            self.advance()
+            self.expect_kw("EXISTS")
+            if_not_exists = True
+        name = self._parse_dotted_path()
+        parts: List[str] = []
+        for p in name:
+            parts.extend(p.split(".") if "." in p else [p])
+
+        columns: List[ColumnDef] = []
+        if self.at_op("("):
+            self.advance()
+            while True:
+                cname = self.parse_ident()
+                ctype = None
+                if kind == "TABLE" or self.peek().type in (IDENT, QIDENT) \
+                        or self.at_kw("ARRAY", "STRUCT", "RANGE", "INTERVAL"):
+                    if not self.at_op(",", ")"):
+                        ctype = self.parse_type()
+                # skip column attributes (NOT NULL, OPTIONS(...), DEFAULT ...)
+                depth = 0
+                while not (depth == 0 and self.at_op(",", ")")):
+                    tok = self.advance()
+                    if tok.type == EOF:
+                        self.error("Unterminated column definition list")
+                    if tok.type == OP and tok.value in "([":
+                        depth += 1
+                    elif tok.type == OP and tok.value in ")]":
+                        depth -= 1
+                columns.append(ColumnDef(cname, ctype))
+                if not self.accept_op(","):
+                    break
+            self.expect_op(")")
+
+        partition_by = None
+        cluster_by: List[Node] = []
+        options_sql = None
+        while True:
+            if self.at_kw("PARTITION"):
+                self.advance()
+                self.expect_kw("BY")
+                partition_by = self.parse_expr()
+            elif self.at_kw("CLUSTER"):
+                self.advance()
+                self.expect_kw("BY")
+                while True:
+                    cluster_by.append(self.parse_expr())
+                    if not self.accept_op(","):
+                        break
+            elif self.at_kw("OPTIONS"):
+                self.advance()
+                options_sql = self._skip_balanced_parens()
+            else:
+                break
+        query = None
+        if self.accept_kw("AS"):
+            query = self.parse_query()
+        return CreateTableAsSelect(kind, parts, query, replace, temp,
+                                   if_not_exists, columns, partition_by,
+                                   cluster_by, options_sql)
+
+    def _parse_if_not_exists(self) -> bool:
+        if self.at_kw("IF") and self.at_kw("NOT", k=1):
+            self.advance()
+            self.advance()
+            self.expect_kw("EXISTS")
+            return True
+        return False
+
+    def _parse_routine_params(self, allow_modes: bool) -> List[RoutineParam]:
+        params: List[RoutineParam] = []
+        self.expect_op("(")
+        if not self.at_op(")"):
+            while True:
+                mode = None
+                if allow_modes and self.at_kw("IN", "OUT", "INOUT") \
+                        and self._is_ident(k=1) and not self.at_op(",", ")", k=2):
+                    mode = self.advance().value.upper()
+                pname = self.parse_ident()
+                ptype = None
+                if not self.at_op(",", ")"):
+                    ptype = self.parse_type()
+                params.append(RoutineParam(pname, ptype, mode))
+                if not self.accept_op(","):
+                    break
+        self.expect_op(")")
+        return params
+
+    def _parse_create_procedure(self, replace: bool) -> CreateProcedure:
+        self.expect_kw("PROCEDURE")
+        if_not_exists = self._parse_if_not_exists()
+        name = self._split_path(self._parse_dotted_path())
+        params = self._parse_routine_params(allow_modes=True)
+        options_sql = None
+        if self.at_kw("OPTIONS"):
+            self.advance()
+            options_sql = self._skip_balanced_parens()
+        body = self.parse_begin()
+        if not isinstance(body, ScriptBlock):
+            self.error("Expected BEGIN ... END procedure body")
+        return CreateProcedure(name, params, body, replace, if_not_exists,
+                               options_sql)
+
+    def _parse_create_function(self, replace: bool, temp: bool,
+                               table_function: bool = False,
+                               aggregate: bool = False) -> CreateFunction:
+        if_not_exists = self._parse_if_not_exists()
+        name = self._split_path(self._parse_dotted_path())
+        params = self._parse_routine_params(allow_modes=False)
+        fn = CreateFunction(name, params, replace=replace, temp=temp,
+                            if_not_exists=if_not_exists,
+                            table_function=table_function, aggregate=aggregate)
+        while True:
+            if self.accept_kw("RETURNS"):
+                if self.at_kw("TABLE"):
+                    self.advance()
+                    self.expect_op("<")
+                    fn.returns_table = self._parse_struct_type_fields()
+                else:
+                    fn.returns = self.parse_type()
+            elif self.at_kw("DETERMINISTIC"):
+                self.advance()
+                fn.deterministic = True
+            elif self.at_kw("NOT") and self.at_kw("DETERMINISTIC", k=1):
+                self.advance()
+                self.advance()
+                fn.deterministic = False
+            elif self.accept_kw("LANGUAGE"):
+                fn.language = self.parse_ident()
+            elif self.at_kw("OPTIONS"):
+                self.advance()
+                fn.options_sql = self._skip_balanced_parens()
+            elif self.accept_kw("AS"):
+                if self.at_op("("):
+                    self.advance()
+                    if self._starts_query():
+                        fn.body_query = self.parse_query()
+                    else:
+                        fn.body_expr = self.parse_expr()
+                    self.expect_op(")")
+                else:
+                    tok = self.peek()
+                    if tok.type not in (STRING, BYTES):
+                        self.error("Expected function body")
+                    fn.body_string = self.advance().value
+            else:
+                break
+        return fn
+
+    def parse_insert(self) -> InsertStmt:
+        self.expect_kw("INSERT")
+        self.accept_kw("INTO")
+        table = self._split_path(self._parse_dotted_path())
+        columns: List[str] = []
+        if self.at_op("(") and not self._starts_query():
+            self.advance()
+            while True:
+                columns.append(self.parse_ident())
+                if not self.accept_op(","):
+                    break
+            self.expect_op(")")
+        if self.at_kw("VALUES"):
+            self.advance()
+            values: List[List[Node]] = []
+            while True:
+                row = self._paren_expr_list()
+                values.append(row)
+                if not self.accept_op(","):
+                    break
+            return InsertStmt(table, columns, values=values)
+        query = self.parse_query()
+        return InsertStmt(table, columns, query=query)
+
+    def parse_update(self) -> UpdateStmt:
+        self.expect_kw("UPDATE")
+        table = self._split_path(self._parse_dotted_path())
+        alias = None
+        if self.accept_kw("AS"):
+            alias = self.parse_ident()
+        elif self._is_ident() and not self.at_kw("SET"):
+            alias = self.advance().value
+        self.expect_kw("SET")
+        assignments = self._parse_assignments()
+        from_ = None
+        if self.accept_kw("FROM"):
+            from_ = self.parse_from()
+        where = None
+        if self.accept_kw("WHERE"):
+            where = self.parse_expr()
+        return UpdateStmt(table, assignments, alias, from_, where)
+
+    def _parse_assignments(self) -> List[Assignment]:
+        assignments: List[Assignment] = []
+        while True:
+            target = self._parse_dotted_path()
+            self.expect_op("=")
+            assignments.append(Assignment(target, self.parse_expr()))
+            if not self.accept_op(","):
+                break
+        return assignments
+
+    def parse_delete(self) -> DeleteStmt:
+        self.expect_kw("DELETE")
+        self.accept_kw("FROM")
+        table = self._split_path(self._parse_dotted_path())
+        alias = None
+        if self.accept_kw("AS"):
+            alias = self.parse_ident()
+        elif self._is_ident() and not self.at_kw("WHERE"):
+            alias = self.advance().value
+        where = None
+        if self.accept_kw("WHERE"):
+            where = self.parse_expr()
+        return DeleteStmt(table, alias, where)
+
+    def parse_merge(self) -> MergeStmt:
+        self.expect_kw("MERGE")
+        self.accept_kw("INTO")
+        target = self._split_path(self._parse_dotted_path())
+        alias = None
+        if self.accept_kw("AS"):
+            alias = self.parse_ident()
+        elif self._is_ident() and not self.at_kw("USING"):
+            alias = self.advance().value
+        self.expect_kw("USING")
+        source = self.parse_table_primary()
+        self.expect_kw("ON")
+        on = self.parse_expr()
+        whens: List[MergeWhen] = []
+        while self.at_kw("WHEN"):
+            self.advance()
+            if self.accept_kw("MATCHED"):
+                match_kind = "MATCHED"
+            else:
+                self.expect_kw("NOT")
+                self.expect_kw("MATCHED")
+                match_kind = "NOT_MATCHED"
+                if self.accept_kw("BY"):
+                    which = self.expect_kw("TARGET", "SOURCE").value.upper()
+                    if which == "SOURCE":
+                        match_kind = "NOT_MATCHED_BY_SOURCE"
+            condition = None
+            if self.accept_kw("AND"):
+                condition = self.parse_expr()
+            self.expect_kw("THEN")
+            if self.accept_kw("UPDATE"):
+                self.expect_kw("SET")
+                whens.append(MergeWhen(match_kind, "UPDATE", condition,
+                                       assignments=self._parse_assignments()))
+            elif self.accept_kw("DELETE"):
+                whens.append(MergeWhen(match_kind, "DELETE", condition))
+            else:
+                self.expect_kw("INSERT")
+                if self.accept_kw("ROW"):
+                    whens.append(MergeWhen(match_kind, "INSERT_ROW", condition))
+                else:
+                    cols: List[str] = []
+                    if self.at_op("("):
+                        self.advance()
+                        while True:
+                            cols.append(self.parse_ident())
+                            if not self.accept_op(","):
+                                break
+                        self.expect_op(")")
+                    self.expect_kw("VALUES")
+                    vals = self._paren_expr_list()
+                    whens.append(MergeWhen(match_kind, "INSERT", condition,
+                                           columns=cols, values=vals))
+        return MergeStmt(target, source, on, whens, alias)
+
+    @staticmethod
+    def _split_path(path: List[str]) -> List[str]:
+        parts: List[str] = []
+        for p in path:
+            parts.extend(p.split(".") if "." in p else [p])
+        return parts
+
+
+def parse(sql: str) -> List[Node]:
+    """Parse one or more ``;``-separated statements into AST nodes."""
+    return Parser(sql).parse_statements()
+
+
+def parse_one(sql: str) -> Node:
+    """Parse exactly one statement and return its AST."""
+    stmts = parse(sql)
+    if not stmts:
+        raise ParseError("No statement found")
+    if len(stmts) > 1:
+        raise ParseError(f"Expected a single statement, found {len(stmts)}")
+    return stmts[0]