1"""
   2## Expressions
   3
   4Every AST node in SQLGlot is represented by a subclass of `Expression`.
   5
   6This module contains the implementation of all supported `Expression` types. Additionally,
   7it exposes a number of helper functions, which are mainly used to programmatically build
   8SQL expressions, such as `sqlglot.expressions.select`.
   9
  10----
  11"""
  12
  13from __future__ import annotations
  14
  15import datetime
  16import math
  17import numbers
  18import re
  19import textwrap
  20import typing as t
  21from collections import deque
  22from copy import deepcopy
  23from decimal import Decimal
  24from enum import auto
  25from functools import reduce
  26
  27from sqlglot.errors import ErrorLevel, ParseError
  28from sqlglot.helper import (
  29    AutoName,
  30    camel_to_snake_case,
  31    ensure_collection,
  32    ensure_list,
  33    seq_get,
  34    split_num_words,
  35    subclasses,
  36    to_bool,
  37)
  38from sqlglot.tokens import Token, TokenError
  39
  40if t.TYPE_CHECKING:
  41    from typing_extensions import Self
  42
  43    from sqlglot._typing import E, Lit
  44    from sqlglot.dialects.dialect import DialectType
  45
  46    Q = t.TypeVar("Q", bound="Query")
  47    S = t.TypeVar("S", bound="SetOperation")
  48
  49
  50class _Expression(type):
  51    def __new__(cls, clsname, bases, attrs):
  52        klass = super().__new__(cls, clsname, bases, attrs)
  53
  54        # When an Expression class is created, its key is automatically set
  55        # to be the lowercase version of the class' name.
  56        klass.key = clsname.lower()
  57
  58        # This is so that docstrings are not inherited in pdoc
  59        klass.__doc__ = klass.__doc__ or ""
  60
  61        return klass
  62
  63
  64SQLGLOT_META = "sqlglot.meta"
  65SQLGLOT_ANONYMOUS = "sqlglot.anonymous"
  66TABLE_PARTS = ("this", "db", "catalog")
  67COLUMN_PARTS = ("this", "table", "db", "catalog")
  68POSITION_META_KEYS = ("line", "col", "start", "end")
  69
  70
  71class Expression(metaclass=_Expression):
  72    """
  73    The base class for all expressions in a syntax tree. Each Expression encapsulates any necessary
  74    context, such as its child expressions, their names (arg keys), and whether a given child expression
  75    is optional or not.
  76
  77    Attributes:
  78        key: a unique key for each class in the Expression hierarchy. This is useful for hashing
  79            and representing expressions as strings.
  80        arg_types: determines the arguments (child nodes) supported by an expression. It maps
  81            arg keys to booleans that indicate whether the corresponding args are optional.
  82        parent: a reference to the parent expression (or None, in case of root expressions).
  83        arg_key: the arg key an expression is associated with, i.e. the name its parent expression
  84            uses to refer to it.
  85        index: the index of an expression if it is inside of a list argument in its parent.
  86        comments: a list of comments that are associated with a given expression. This is used in
  87            order to preserve comments when transpiling SQL code.
  88        type: the `sqlglot.expressions.DataType` type of an expression. This is inferred by the
  89            optimizer, in order to enable some transformations that require type information.
  90        meta: a dictionary that can be used to store useful metadata for a given expression.
  91
  92    Example:
  93        >>> class Foo(Expression):
  94        ...     arg_types = {"this": True, "expression": False}
  95
  96        The above definition informs us that Foo is an Expression that requires an argument called
  97        "this" and may also optionally receive an argument called "expression".
  98
  99    Args:
 100        args: a mapping used for retrieving the arguments of an expression, given their arg keys.
 101    """
 102
 103    key = "expression"
 104    arg_types = {"this": True}
 105    __slots__ = ("args", "parent", "arg_key", "index", "comments", "_type", "_meta", "_hash")
 106
 107    def __init__(self, **args: t.Any):
 108        self.args: t.Dict[str, t.Any] = args
 109        self.parent: t.Optional[Expression] = None
 110        self.arg_key: t.Optional[str] = None
 111        self.index: t.Optional[int] = None
 112        self.comments: t.Optional[t.List[str]] = None
 113        self._type: t.Optional[DataType] = None
 114        self._meta: t.Optional[t.Dict[str, t.Any]] = None
 115        self._hash: t.Optional[int] = None
 116
 117        for arg_key, value in self.args.items():
 118            self._set_parent(arg_key, value)
 119
 120    def __eq__(self, other) -> bool:
 121        return type(self) is type(other) and hash(self) == hash(other)
 122
 123    @property
 124    def hashable_args(self) -> t.Any:
 125        return frozenset(
 126            (k, tuple(_norm_arg(a) for a in v) if type(v) is list else _norm_arg(v))
 127            for k, v in self.args.items()
 128            if not (v is None or v is False or (type(v) is list and not v))
 129        )
 130
 131    def __hash__(self) -> int:
 132        if self._hash is not None:
 133            return self._hash
 134
 135        return hash((self.__class__, self.hashable_args))
 136
 137    @property
 138    def this(self) -> t.Any:
 139        """
 140        Retrieves the argument with key "this".
 141        """
 142        return self.args.get("this")
 143
 144    @property
 145    def expression(self) -> t.Any:
 146        """
 147        Retrieves the argument with key "expression".
 148        """
 149        return self.args.get("expression")
 150
 151    @property
 152    def expressions(self) -> t.List[t.Any]:
 153        """
 154        Retrieves the argument with key "expressions".
 155        """
 156        return self.args.get("expressions") or []
 157
 158    def text(self, key) -> str:
 159        """
 160        Returns a textual representation of the argument corresponding to "key". This can only be used
 161        for args that are strings or leaf Expression instances, such as identifiers and literals.
 162        """
 163        field = self.args.get(key)
 164        if isinstance(field, str):
 165            return field
 166        if isinstance(field, (Identifier, Literal, Var)):
 167            return field.this
 168        if isinstance(field, (Star, Null)):
 169            return field.name
 170        return ""
 171
 172    @property
 173    def is_string(self) -> bool:
 174        """
 175        Checks whether a Literal expression is a string.
 176        """
 177        return isinstance(self, Literal) and self.args["is_string"]
 178
 179    @property
 180    def is_number(self) -> bool:
 181        """
 182        Checks whether a Literal expression is a number.
 183        """
 184        return (isinstance(self, Literal) and not self.args["is_string"]) or (
 185            isinstance(self, Neg) and self.this.is_number
 186        )
 187
 188    def to_py(self) -> t.Any:
 189        """
 190        Returns a Python object equivalent of the SQL node.
 191        """
 192        raise ValueError(f"{self} cannot be converted to a Python object.")
 193
 194    @property
 195    def is_int(self) -> bool:
 196        """
 197        Checks whether an expression is an integer.
 198        """
 199        return self.is_number and isinstance(self.to_py(), int)
 200
 201    @property
 202    def is_star(self) -> bool:
 203        """Checks whether an expression is a star."""
 204        return isinstance(self, Star) or (isinstance(self, Column) and isinstance(self.this, Star))
 205
 206    @property
 207    def alias(self) -> str:
 208        """
 209        Returns the alias of the expression, or an empty string if it's not aliased.
 210        """
 211        if isinstance(self.args.get("alias"), TableAlias):
 212            return self.args["alias"].name
 213        return self.text("alias")
 214
 215    @property
 216    def alias_column_names(self) -> t.List[str]:
 217        table_alias = self.args.get("alias")
 218        if not table_alias:
 219            return []
 220        return [c.name for c in table_alias.args.get("columns") or []]
 221
 222    @property
 223    def name(self) -> str:
 224        return self.text("this")
 225
 226    @property
 227    def alias_or_name(self) -> str:
 228        return self.alias or self.name
 229
 230    @property
 231    def output_name(self) -> str:
 232        """
 233        Name of the output column if this expression is a selection.
 234
 235        If the Expression has no output name, an empty string is returned.
 236
 237        Example:
 238            >>> from sqlglot import parse_one
 239            >>> parse_one("SELECT a").expressions[0].output_name
 240            'a'
 241            >>> parse_one("SELECT b AS c").expressions[0].output_name
 242            'c'
 243            >>> parse_one("SELECT 1 + 2").expressions[0].output_name
 244            ''
 245        """
 246        return ""
 247
 248    @property
 249    def type(self) -> t.Optional[DataType]:
 250        return self._type
 251
 252    @type.setter
 253    def type(self, dtype: t.Optional[DataType | DataType.Type | str]) -> None:
 254        if dtype and not isinstance(dtype, DataType):
 255            dtype = DataType.build(dtype)
 256        self._type = dtype  # type: ignore
 257
 258    def is_type(self, *dtypes) -> bool:
 259        return self.type is not None and self.type.is_type(*dtypes)
 260
 261    def is_leaf(self) -> bool:
 262        return not any(isinstance(v, (Expression, list)) for v in self.args.values())
 263
 264    @property
 265    def meta(self) -> t.Dict[str, t.Any]:
 266        if self._meta is None:
 267            self._meta = {}
 268        return self._meta
 269
 270    def __deepcopy__(self, memo):
 271        root = self.__class__()
 272        stack = [(self, root)]
 273
 274        while stack:
 275            node, copy = stack.pop()
 276
 277            if node.comments is not None:
 278                copy.comments = deepcopy(node.comments)
 279            if node._type is not None:
 280                copy._type = deepcopy(node._type)
 281            if node._meta is not None:
 282                copy._meta = deepcopy(node._meta)
 283            if node._hash is not None:
 284                copy._hash = node._hash
 285
 286            for k, vs in node.args.items():
 287                if hasattr(vs, "parent"):
 288                    stack.append((vs, vs.__class__()))
 289                    copy.set(k, stack[-1][-1])
 290                elif type(vs) is list:
 291                    copy.args[k] = []
 292
 293                    for v in vs:
 294                        if hasattr(v, "parent"):
 295                            stack.append((v, v.__class__()))
 296                            copy.append(k, stack[-1][-1])
 297                        else:
 298                            copy.append(k, v)
 299                else:
 300                    copy.args[k] = vs
 301
 302        return root
 303
 304    def copy(self) -> Self:
 305        """
 306        Returns a deep copy of the expression.
 307        """
 308        return deepcopy(self)
 309
 310    def add_comments(self, comments: t.Optional[t.List[str]] = None, prepend: bool = False) -> None:
 311        if self.comments is None:
 312            self.comments = []
 313
 314        if comments:
 315            for comment in comments:
 316                _, *meta = comment.split(SQLGLOT_META)
 317                if meta:
 318                    for kv in "".join(meta).split(","):
 319                        k, *v = kv.split("=")
 320                        value = v[0].strip() if v else True
 321                        self.meta[k.strip()] = to_bool(value)
 322
 323                if not prepend:
 324                    self.comments.append(comment)
 325
 326            if prepend:
 327                self.comments = comments + self.comments
 328
 329    def pop_comments(self) -> t.List[str]:
 330        comments = self.comments or []
 331        self.comments = None
 332        return comments
 333
 334    def append(self, arg_key: str, value: t.Any) -> None:
 335        """
 336        Appends value to arg_key if it's a list or sets it as a new list.
 337
 338        Args:
 339            arg_key (str): name of the list expression arg
 340            value (Any): value to append to the list
 341        """
 342        if type(self.args.get(arg_key)) is not list:
 343            self.args[arg_key] = []
 344        self._set_parent(arg_key, value)
 345        values = self.args[arg_key]
 346        if hasattr(value, "parent"):
 347            value.index = len(values)
 348        values.append(value)
 349
 350    def set(
 351        self,
 352        arg_key: str,
 353        value: t.Any,
 354        index: t.Optional[int] = None,
 355        overwrite: bool = True,
 356    ) -> None:
 357        """
 358        Sets arg_key to value.
 359
 360        Args:
 361            arg_key: name of the expression arg.
 362            value: value to set the arg to.
 363            index: if the arg is a list, this specifies what position to add the value in it.
 364            overwrite: assuming an index is given, this determines whether to overwrite the
 365                list entry instead of only inserting a new value (i.e., like list.insert).
 366        """
 367        if index is not None:
 368            expressions = self.args.get(arg_key) or []
 369
 370            if seq_get(expressions, index) is None:
 371                return
 372            if value is None:
 373                expressions.pop(index)
 374                for v in expressions[index:]:
 375                    v.index = v.index - 1
 376                return
 377
 378            if isinstance(value, list):
 379                expressions.pop(index)
 380                expressions[index:index] = value
 381            elif overwrite:
 382                expressions[index] = value
 383            else:
 384                expressions.insert(index, value)
 385
 386            value = expressions
 387        elif value is None:
 388            self.args.pop(arg_key, None)
 389            return
 390
 391        self.args[arg_key] = value
 392        self._set_parent(arg_key, value, index)
 393
 394    def _set_parent(self, arg_key: str, value: t.Any, index: t.Optional[int] = None) -> None:
 395        if hasattr(value, "parent"):
 396            value.parent = self
 397            value.arg_key = arg_key
 398            value.index = index
 399        elif type(value) is list:
 400            for index, v in enumerate(value):
 401                if hasattr(v, "parent"):
 402                    v.parent = self
 403                    v.arg_key = arg_key
 404                    v.index = index
 405
 406    @property
 407    def depth(self) -> int:
 408        """
 409        Returns the depth of this tree.
 410        """
 411        if self.parent:
 412            return self.parent.depth + 1
 413        return 0
 414
 415    def iter_expressions(self, reverse: bool = False) -> t.Iterator[Expression]:
 416        """Yields the key and expression for all arguments, exploding list args."""
 417        for vs in reversed(self.args.values()) if reverse else self.args.values():  # type: ignore
 418            if type(vs) is list:
 419                for v in reversed(vs) if reverse else vs:  # type: ignore
 420                    if hasattr(v, "parent"):
 421                        yield v
 422            else:
 423                if hasattr(vs, "parent"):
 424                    yield vs
 425
 426    def find(self, *expression_types: t.Type[E], bfs: bool = True) -> t.Optional[E]:
 427        """
 428        Returns the first node in this tree which matches at least one of
 429        the specified types.
 430
 431        Args:
 432            expression_types: the expression type(s) to match.
 433            bfs: whether to search the AST using the BFS algorithm (DFS is used if false).
 434
 435        Returns:
 436            The node which matches the criteria or None if no such node was found.
 437        """
 438        return next(self.find_all(*expression_types, bfs=bfs), None)
 439
 440    def find_all(self, *expression_types: t.Type[E], bfs: bool = True) -> t.Iterator[E]:
 441        """
 442        Returns a generator object which visits all nodes in this tree and only
 443        yields those that match at least one of the specified expression types.
 444
 445        Args:
 446            expression_types: the expression type(s) to match.
 447            bfs: whether to search the AST using the BFS algorithm (DFS is used if false).
 448
 449        Returns:
 450            The generator object.
 451        """
 452        for expression in self.walk(bfs=bfs):
 453            if isinstance(expression, expression_types):
 454                yield expression
 455
 456    def find_ancestor(self, *expression_types: t.Type[E]) -> t.Optional[E]:
 457        """
 458        Returns a nearest parent matching expression_types.
 459
 460        Args:
 461            expression_types: the expression type(s) to match.
 462
 463        Returns:
 464            The parent node.
 465        """
 466        ancestor = self.parent
 467        while ancestor and not isinstance(ancestor, expression_types):
 468            ancestor = ancestor.parent
 469        return ancestor  # type: ignore
 470
 471    @property
 472    def parent_select(self) -> t.Optional[Select]:
 473        """
 474        Returns the parent select statement.
 475        """
 476        return self.find_ancestor(Select)
 477
 478    @property
 479    def same_parent(self) -> bool:
 480        """Returns if the parent is the same class as itself."""
 481        return type(self.parent) is self.__class__
 482
 483    def root(self) -> Expression:
 484        """
 485        Returns the root expression of this tree.
 486        """
 487        expression = self
 488        while expression.parent:
 489            expression = expression.parent
 490        return expression
 491
 492    def walk(
 493        self, bfs: bool = True, prune: t.Optional[t.Callable[[Expression], bool]] = None
 494    ) -> t.Iterator[Expression]:
 495        """
 496        Returns a generator object which visits all nodes in this tree.
 497
 498        Args:
 499            bfs: if set to True the BFS traversal order will be applied,
 500                otherwise the DFS traversal will be used instead.
 501            prune: callable that returns True if the generator should stop traversing
 502                this branch of the tree.
 503
 504        Returns:
 505            the generator object.
 506        """
 507        if bfs:
 508            yield from self.bfs(prune=prune)
 509        else:
 510            yield from self.dfs(prune=prune)
 511
 512    def dfs(
 513        self, prune: t.Optional[t.Callable[[Expression], bool]] = None
 514    ) -> t.Iterator[Expression]:
 515        """
 516        Returns a generator object which visits all nodes in this tree in
 517        the DFS (Depth-first) order.
 518
 519        Returns:
 520            The generator object.
 521        """
 522        stack = [self]
 523
 524        while stack:
 525            node = stack.pop()
 526
 527            yield node
 528
 529            if prune and prune(node):
 530                continue
 531
 532            for v in node.iter_expressions(reverse=True):
 533                stack.append(v)
 534
 535    def bfs(
 536        self, prune: t.Optional[t.Callable[[Expression], bool]] = None
 537    ) -> t.Iterator[Expression]:
 538        """
 539        Returns a generator object which visits all nodes in this tree in
 540        the BFS (Breadth-first) order.
 541
 542        Returns:
 543            The generator object.
 544        """
 545        queue = deque([self])
 546
 547        while queue:
 548            node = queue.popleft()
 549
 550            yield node
 551
 552            if prune and prune(node):
 553                continue
 554
 555            for v in node.iter_expressions():
 556                queue.append(v)
 557
 558    def unnest(self):
 559        """
 560        Returns the first non parenthesis child or self.
 561        """
 562        expression = self
 563        while type(expression) is Paren:
 564            expression = expression.this
 565        return expression
 566
 567    def unalias(self):
 568        """
 569        Returns the inner expression if this is an Alias.
 570        """
 571        if isinstance(self, Alias):
 572            return self.this
 573        return self
 574
 575    def unnest_operands(self):
 576        """
 577        Returns unnested operands as a tuple.
 578        """
 579        return tuple(arg.unnest() for arg in self.iter_expressions())
 580
 581    def flatten(self, unnest=True):
 582        """
 583        Returns a generator which yields child nodes whose parents are the same class.
 584
 585        A AND B AND C -> [A, B, C]
 586        """
 587        for node in self.dfs(prune=lambda n: n.parent and type(n) is not self.__class__):
 588            if type(node) is not self.__class__:
 589                yield node.unnest() if unnest and not isinstance(node, Subquery) else node
 590
 591    def __str__(self) -> str:
 592        return self.sql()
 593
 594    def __repr__(self) -> str:
 595        return _to_s(self)
 596
 597    def to_s(self) -> str:
 598        """
 599        Same as __repr__, but includes additional information which can be useful
 600        for debugging, like empty or missing args and the AST nodes' object IDs.
 601        """
 602        return _to_s(self, verbose=True)
 603
 604    def sql(self, dialect: DialectType = None, **opts) -> str:
 605        """
 606        Returns SQL string representation of this tree.
 607
 608        Args:
 609            dialect: the dialect of the output SQL string (eg. "spark", "hive", "presto", "mysql").
 610            opts: other `sqlglot.generator.Generator` options.
 611
 612        Returns:
 613            The SQL string.
 614        """
 615        from sqlglot.dialects import Dialect
 616
 617        return Dialect.get_or_raise(dialect).generate(self, **opts)
 618
 619    def transform(self, fun: t.Callable, *args: t.Any, copy: bool = True, **kwargs) -> Expression:
 620        """
 621        Visits all tree nodes (excluding already transformed ones)
 622        and applies the given transformation function to each node.
 623
 624        Args:
 625            fun: a function which takes a node as an argument and returns a
 626                new transformed node or the same node without modifications. If the function
 627                returns None, then the corresponding node will be removed from the syntax tree.
 628            copy: if set to True a new tree instance is constructed, otherwise the tree is
 629                modified in place.
 630
 631        Returns:
 632            The transformed tree.
 633        """
 634        root = None
 635        new_node = None
 636
 637        for node in (self.copy() if copy else self).dfs(prune=lambda n: n is not new_node):
 638            parent, arg_key, index = node.parent, node.arg_key, node.index
 639            new_node = fun(node, *args, **kwargs)
 640
 641            if not root:
 642                root = new_node
 643            elif parent and arg_key and new_node is not node:
 644                parent.set(arg_key, new_node, index)
 645
 646        assert root
 647        return root.assert_is(Expression)
 648
 649    @t.overload
 650    def replace(self, expression: E) -> E: ...
 651
 652    @t.overload
 653    def replace(self, expression: None) -> None: ...
 654
 655    def replace(self, expression):
 656        """
 657        Swap out this expression with a new expression.
 658
 659        For example::
 660
 661            >>> tree = Select().select("x").from_("tbl")
 662            >>> tree.find(Column).replace(column("y"))
 663            Column(
 664              this=Identifier(this=y, quoted=False))
 665            >>> tree.sql()
 666            'SELECT y FROM tbl'
 667
 668        Args:
 669            expression: new node
 670
 671        Returns:
 672            The new expression or expressions.
 673        """
 674        parent = self.parent
 675
 676        if not parent or parent is expression:
 677            return expression
 678
 679        key = self.arg_key
 680        value = parent.args.get(key)
 681
 682        if type(expression) is list and isinstance(value, Expression):
 683            # We are trying to replace an Expression with a list, so it's assumed that
 684            # the intention was to really replace the parent of this expression.
 685            value.parent.replace(expression)
 686        else:
 687            parent.set(key, expression, self.index)
 688
 689        if expression is not self:
 690            self.parent = None
 691            self.arg_key = None
 692            self.index = None
 693
 694        return expression
 695
 696    def pop(self: E) -> E:
 697        """
 698        Remove this expression from its AST.
 699
 700        Returns:
 701            The popped expression.
 702        """
 703        self.replace(None)
 704        return self
 705
 706    def assert_is(self, type_: t.Type[E]) -> E:
 707        """
 708        Assert that this `Expression` is an instance of `type_`.
 709
 710        If it is NOT an instance of `type_`, this raises an assertion error.
 711        Otherwise, this returns this expression.
 712
 713        Examples:
 714            This is useful for type security in chained expressions:
 715
 716            >>> import sqlglot
 717            >>> sqlglot.parse_one("SELECT x from y").assert_is(Select).select("z").sql()
 718            'SELECT x, z FROM y'
 719        """
 720        if not isinstance(self, type_):
 721            raise AssertionError(f"{self} is not {type_}.")
 722        return self
 723
 724    def error_messages(self, args: t.Optional[t.Sequence] = None) -> t.List[str]:
 725        """
 726        Checks if this expression is valid (e.g. all mandatory args are set).
 727
 728        Args:
 729            args: a sequence of values that were used to instantiate a Func expression. This is used
 730                to check that the provided arguments don't exceed the function argument limit.
 731
 732        Returns:
 733            A list of error messages for all possible errors that were found.
 734        """
 735        errors: t.List[str] = []
 736
 737        for k in self.args:
 738            if k not in self.arg_types:
 739                errors.append(f"Unexpected keyword: '{k}' for {self.__class__}")
 740        for k, mandatory in self.arg_types.items():
 741            v = self.args.get(k)
 742            if mandatory and (v is None or (isinstance(v, list) and not v)):
 743                errors.append(f"Required keyword: '{k}' missing for {self.__class__}")
 744
 745        if (
 746            args
 747            and isinstance(self, Func)
 748            and len(args) > len(self.arg_types)
 749            and not self.is_var_len_args
 750        ):
 751            errors.append(
 752                f"The number of provided arguments ({len(args)}) is greater than "
 753                f"the maximum number of supported arguments ({len(self.arg_types)})"
 754            )
 755
 756        return errors
 757
 758    def dump(self):
 759        """
 760        Dump this Expression to a JSON-serializable dict.
 761        """
 762        from sqlglot.serde import dump
 763
 764        return dump(self)
 765
 766    @classmethod
 767    def load(cls, obj):
 768        """
 769        Load a dict (as returned by `Expression.dump`) into an Expression instance.
 770        """
 771        from sqlglot.serde import load
 772
 773        return load(obj)
 774
 775    def and_(
 776        self,
 777        *expressions: t.Optional[ExpOrStr],
 778        dialect: DialectType = None,
 779        copy: bool = True,
 780        wrap: bool = True,
 781        **opts,
 782    ) -> Condition:
 783        """
 784        AND this condition with one or multiple expressions.
 785
 786        Example:
 787            >>> condition("x=1").and_("y=1").sql()
 788            'x = 1 AND y = 1'
 789
 790        Args:
 791            *expressions: the SQL code strings to parse.
 792                If an `Expression` instance is passed, it will be used as-is.
 793            dialect: the dialect used to parse the input expression.
 794            copy: whether to copy the involved expressions (only applies to Expressions).
 795            wrap: whether to wrap the operands in `Paren`s. This is true by default to avoid
 796                precedence issues, but can be turned off when the produced AST is too deep and
 797                causes recursion-related issues.
 798            opts: other options to use to parse the input expressions.
 799
 800        Returns:
 801            The new And condition.
 802        """
 803        return and_(self, *expressions, dialect=dialect, copy=copy, wrap=wrap, **opts)
 804
 805    def or_(
 806        self,
 807        *expressions: t.Optional[ExpOrStr],
 808        dialect: DialectType = None,
 809        copy: bool = True,
 810        wrap: bool = True,
 811        **opts,
 812    ) -> Condition:
 813        """
 814        OR this condition with one or multiple expressions.
 815
 816        Example:
 817            >>> condition("x=1").or_("y=1").sql()
 818            'x = 1 OR y = 1'
 819
 820        Args:
 821            *expressions: the SQL code strings to parse.
 822                If an `Expression` instance is passed, it will be used as-is.
 823            dialect: the dialect used to parse the input expression.
 824            copy: whether to copy the involved expressions (only applies to Expressions).
 825            wrap: whether to wrap the operands in `Paren`s. This is true by default to avoid
 826                precedence issues, but can be turned off when the produced AST is too deep and
 827                causes recursion-related issues.
 828            opts: other options to use to parse the input expressions.
 829
 830        Returns:
 831            The new Or condition.
 832        """
 833        return or_(self, *expressions, dialect=dialect, copy=copy, wrap=wrap, **opts)
 834
 835    def not_(self, copy: bool = True):
 836        """
 837        Wrap this condition with NOT.
 838
 839        Example:
 840            >>> condition("x=1").not_().sql()
 841            'NOT x = 1'
 842
 843        Args:
 844            copy: whether to copy this object.
 845
 846        Returns:
 847            The new Not instance.
 848        """
 849        return not_(self, copy=copy)
 850
 851    def update_positions(
 852        self: E, other: t.Optional[Token | Expression] = None, **kwargs: t.Any
 853    ) -> E:
 854        """
 855        Update this expression with positions from a token or other expression.
 856
 857        Args:
 858            other: a token or expression to update this expression with.
 859
 860        Returns:
 861            The updated expression.
 862        """
 863        if isinstance(other, Expression):
 864            self.meta.update({k: v for k, v in other.meta.items() if k in POSITION_META_KEYS})
 865        elif other is not None:
 866            self.meta.update(
 867                {
 868                    "line": other.line,
 869                    "col": other.col,
 870                    "start": other.start,
 871                    "end": other.end,
 872                }
 873            )
 874        self.meta.update({k: v for k, v in kwargs.items() if k in POSITION_META_KEYS})
 875        return self
 876
 877    def as_(
 878        self,
 879        alias: str | Identifier,
 880        quoted: t.Optional[bool] = None,
 881        dialect: DialectType = None,
 882        copy: bool = True,
 883        **opts,
 884    ) -> Alias:
 885        return alias_(self, alias, quoted=quoted, dialect=dialect, copy=copy, **opts)
 886
 887    def _binop(self, klass: t.Type[E], other: t.Any, reverse: bool = False) -> E:
 888        this = self.copy()
 889        other = convert(other, copy=True)
 890        if not isinstance(this, klass) and not isinstance(other, klass):
 891            this = _wrap(this, Binary)
 892            other = _wrap(other, Binary)
 893        if reverse:
 894            return klass(this=other, expression=this)
 895        return klass(this=this, expression=other)
 896
 897    def __getitem__(self, other: ExpOrStr | t.Tuple[ExpOrStr]) -> Bracket:
 898        return Bracket(
 899            this=self.copy(), expressions=[convert(e, copy=True) for e in ensure_list(other)]
 900        )
 901
 902    def __iter__(self) -> t.Iterator:
 903        if "expressions" in self.arg_types:
 904            return iter(self.args.get("expressions") or [])
 905        # We define this because __getitem__ converts Expression into an iterable, which is
 906        # problematic because one can hit infinite loops if they do "for x in some_expr: ..."
 907        # See: https://peps.python.org/pep-0234/
 908        raise TypeError(f"'{self.__class__.__name__}' object is not iterable")
 909
 910    def isin(
 911        self,
 912        *expressions: t.Any,
 913        query: t.Optional[ExpOrStr] = None,
 914        unnest: t.Optional[ExpOrStr] | t.Collection[ExpOrStr] = None,
 915        copy: bool = True,
 916        **opts,
 917    ) -> In:
 918        subquery = maybe_parse(query, copy=copy, **opts) if query else None
 919        if subquery and not isinstance(subquery, Subquery):
 920            subquery = subquery.subquery(copy=False)
 921
 922        return In(
 923            this=maybe_copy(self, copy),
 924            expressions=[convert(e, copy=copy) for e in expressions],
 925            query=subquery,
 926            unnest=(
 927                Unnest(
 928                    expressions=[
 929                        maybe_parse(t.cast(ExpOrStr, e), copy=copy, **opts)
 930                        for e in ensure_list(unnest)
 931                    ]
 932                )
 933                if unnest
 934                else None
 935            ),
 936        )
 937
 938    def between(
 939        self,
 940        low: t.Any,
 941        high: t.Any,
 942        copy: bool = True,
 943        symmetric: t.Optional[bool] = False,
 944        **opts,
 945    ) -> Between:
 946        return Between(
 947            this=maybe_copy(self, copy),
 948            low=convert(low, copy=copy, **opts),
 949            high=convert(high, copy=copy, **opts),
 950            symmetric=symmetric,
 951        )
 952
 953    def is_(self, other: ExpOrStr) -> Is:
 954        return self._binop(Is, other)
 955
 956    def like(self, other: ExpOrStr) -> Like:
 957        return self._binop(Like, other)
 958
 959    def ilike(self, other: ExpOrStr) -> ILike:
 960        return self._binop(ILike, other)
 961
 962    def eq(self, other: t.Any) -> EQ:
 963        return self._binop(EQ, other)
 964
 965    def neq(self, other: t.Any) -> NEQ:
 966        return self._binop(NEQ, other)
 967
 968    def rlike(self, other: ExpOrStr) -> RegexpLike:
 969        return self._binop(RegexpLike, other)
 970
 971    def div(self, other: ExpOrStr, typed: bool = False, safe: bool = False) -> Div:
 972        div = self._binop(Div, other)
 973        div.args["typed"] = typed
 974        div.args["safe"] = safe
 975        return div
 976
 977    def asc(self, nulls_first: bool = True) -> Ordered:
 978        return Ordered(this=self.copy(), nulls_first=nulls_first)
 979
 980    def desc(self, nulls_first: bool = False) -> Ordered:
 981        return Ordered(this=self.copy(), desc=True, nulls_first=nulls_first)
 982
 983    def __lt__(self, other: t.Any) -> LT:
 984        return self._binop(LT, other)
 985
 986    def __le__(self, other: t.Any) -> LTE:
 987        return self._binop(LTE, other)
 988
 989    def __gt__(self, other: t.Any) -> GT:
 990        return self._binop(GT, other)
 991
 992    def __ge__(self, other: t.Any) -> GTE:
 993        return self._binop(GTE, other)
 994
 995    def __add__(self, other: t.Any) -> Add:
 996        return self._binop(Add, other)
 997
 998    def __radd__(self, other: t.Any) -> Add:
 999        return self._binop(Add, other, reverse=True)
1000
1001    def __sub__(self, other: t.Any) -> Sub:
1002        return self._binop(Sub, other)
1003
1004    def __rsub__(self, other: t.Any) -> Sub:
1005        return self._binop(Sub, other, reverse=True)
1006
1007    def __mul__(self, other: t.Any) -> Mul:
1008        return self._binop(Mul, other)
1009
1010    def __rmul__(self, other: t.Any) -> Mul:
1011        return self._binop(Mul, other, reverse=True)
1012
1013    def __truediv__(self, other: t.Any) -> Div:
1014        return self._binop(Div, other)
1015
1016    def __rtruediv__(self, other: t.Any) -> Div:
1017        return self._binop(Div, other, reverse=True)
1018
1019    def __floordiv__(self, other: t.Any) -> IntDiv:
1020        return self._binop(IntDiv, other)
1021
1022    def __rfloordiv__(self, other: t.Any) -> IntDiv:
1023        return self._binop(IntDiv, other, reverse=True)
1024
1025    def __mod__(self, other: t.Any) -> Mod:
1026        return self._binop(Mod, other)
1027
1028    def __rmod__(self, other: t.Any) -> Mod:
1029        return self._binop(Mod, other, reverse=True)
1030
1031    def __pow__(self, other: t.Any) -> Pow:
1032        return self._binop(Pow, other)
1033
1034    def __rpow__(self, other: t.Any) -> Pow:
1035        return self._binop(Pow, other, reverse=True)
1036
1037    def __and__(self, other: t.Any) -> And:
1038        return self._binop(And, other)
1039
1040    def __rand__(self, other: t.Any) -> And:
1041        return self._binop(And, other, reverse=True)
1042
1043    def __or__(self, other: t.Any) -> Or:
1044        return self._binop(Or, other)
1045
1046    def __ror__(self, other: t.Any) -> Or:
1047        return self._binop(Or, other, reverse=True)
1048
1049    def __neg__(self) -> Neg:
1050        return Neg(this=_wrap(self.copy(), Binary))
1051
1052    def __invert__(self) -> Not:
1053        return not_(self.copy())
1054
1055
1056IntoType = t.Union[
1057    str,
1058    t.Type[Expression],
1059    t.Collection[t.Union[str, t.Type[Expression]]],
1060]
1061ExpOrStr = t.Union[str, Expression]
1062
1063
1064class Condition(Expression):
1065    """Logical conditions like x AND y, or simply x"""
1066
1067
1068class Predicate(Condition):
1069    """Relationships like x = y, x > 1, x >= y."""
1070
1071
1072class DerivedTable(Expression):
1073    @property
1074    def selects(self) -> t.List[Expression]:
1075        return self.this.selects if isinstance(self.this, Query) else []
1076
1077    @property
1078    def named_selects(self) -> t.List[str]:
1079        return [select.output_name for select in self.selects]
1080
1081
1082class Query(Expression):
1083    def subquery(self, alias: t.Optional[ExpOrStr] = None, copy: bool = True) -> Subquery:
1084        """
1085        Returns a `Subquery` that wraps around this query.
1086
1087        Example:
1088            >>> subquery = Select().select("x").from_("tbl").subquery()
1089            >>> Select().select("x").from_(subquery).sql()
1090            'SELECT x FROM (SELECT x FROM tbl)'
1091
1092        Args:
1093            alias: an optional alias for the subquery.
1094            copy: if `False`, modify this expression instance in-place.
1095        """
1096        instance = maybe_copy(self, copy)
1097        if not isinstance(alias, Expression):
1098            alias = TableAlias(this=to_identifier(alias)) if alias else None
1099
1100        return Subquery(this=instance, alias=alias)
1101
1102    def limit(
1103        self: Q, expression: ExpOrStr | int, dialect: DialectType = None, copy: bool = True, **opts
1104    ) -> Q:
1105        """
1106        Adds a LIMIT clause to this query.
1107
1108        Example:
1109            >>> select("1").union(select("1")).limit(1).sql()
1110            'SELECT 1 UNION SELECT 1 LIMIT 1'
1111
1112        Args:
1113            expression: the SQL code string to parse.
1114                This can also be an integer.
1115                If a `Limit` instance is passed, it will be used as-is.
1116                If another `Expression` instance is passed, it will be wrapped in a `Limit`.
1117            dialect: the dialect used to parse the input expression.
1118            copy: if `False`, modify this expression instance in-place.
1119            opts: other options to use to parse the input expressions.
1120
1121        Returns:
1122            A limited Select expression.
1123        """
1124        return _apply_builder(
1125            expression=expression,
1126            instance=self,
1127            arg="limit",
1128            into=Limit,
1129            prefix="LIMIT",
1130            dialect=dialect,
1131            copy=copy,
1132            into_arg="expression",
1133            **opts,
1134        )
1135
1136    def offset(
1137        self: Q, expression: ExpOrStr | int, dialect: DialectType = None, copy: bool = True, **opts
1138    ) -> Q:
1139        """
1140        Set the OFFSET expression.
1141
1142        Example:
1143            >>> Select().from_("tbl").select("x").offset(10).sql()
1144            'SELECT x FROM tbl OFFSET 10'
1145
1146        Args:
1147            expression: the SQL code string to parse.
1148                This can also be an integer.
1149                If a `Offset` instance is passed, this is used as-is.
1150                If another `Expression` instance is passed, it will be wrapped in a `Offset`.
1151            dialect: the dialect used to parse the input expression.
1152            copy: if `False`, modify this expression instance in-place.
1153            opts: other options to use to parse the input expressions.
1154
1155        Returns:
1156            The modified Select expression.
1157        """
1158        return _apply_builder(
1159            expression=expression,
1160            instance=self,
1161            arg="offset",
1162            into=Offset,
1163            prefix="OFFSET",
1164            dialect=dialect,
1165            copy=copy,
1166            into_arg="expression",
1167            **opts,
1168        )
1169
1170    def order_by(
1171        self: Q,
1172        *expressions: t.Optional[ExpOrStr],
1173        append: bool = True,
1174        dialect: DialectType = None,
1175        copy: bool = True,
1176        **opts,
1177    ) -> Q:
1178        """
1179        Set the ORDER BY expression.
1180
1181        Example:
1182            >>> Select().from_("tbl").select("x").order_by("x DESC").sql()
1183            'SELECT x FROM tbl ORDER BY x DESC'
1184
1185        Args:
1186            *expressions: the SQL code strings to parse.
1187                If a `Group` instance is passed, this is used as-is.
1188                If another `Expression` instance is passed, it will be wrapped in a `Order`.
1189            append: if `True`, add to any existing expressions.
1190                Otherwise, this flattens all the `Order` expression into a single expression.
1191            dialect: the dialect used to parse the input expression.
1192            copy: if `False`, modify this expression instance in-place.
1193            opts: other options to use to parse the input expressions.
1194
1195        Returns:
1196            The modified Select expression.
1197        """
1198        return _apply_child_list_builder(
1199            *expressions,
1200            instance=self,
1201            arg="order",
1202            append=append,
1203            copy=copy,
1204            prefix="ORDER BY",
1205            into=Order,
1206            dialect=dialect,
1207            **opts,
1208        )
1209
1210    @property
1211    def ctes(self) -> t.List[CTE]:
1212        """Returns a list of all the CTEs attached to this query."""
1213        with_ = self.args.get("with")
1214        return with_.expressions if with_ else []
1215
1216    @property
1217    def selects(self) -> t.List[Expression]:
1218        """Returns the query's projections."""
1219        raise NotImplementedError("Query objects must implement `selects`")
1220
1221    @property
1222    def named_selects(self) -> t.List[str]:
1223        """Returns the output names of the query's projections."""
1224        raise NotImplementedError("Query objects must implement `named_selects`")
1225
1226    def select(
1227        self: Q,
1228        *expressions: t.Optional[ExpOrStr],
1229        append: bool = True,
1230        dialect: DialectType = None,
1231        copy: bool = True,
1232        **opts,
1233    ) -> Q:
1234        """
1235        Append to or set the SELECT expressions.
1236
1237        Example:
1238            >>> Select().select("x", "y").sql()
1239            'SELECT x, y'
1240
1241        Args:
1242            *expressions: the SQL code strings to parse.
1243                If an `Expression` instance is passed, it will be used as-is.
1244            append: if `True`, add to any existing expressions.
1245                Otherwise, this resets the expressions.
1246            dialect: the dialect used to parse the input expressions.
1247            copy: if `False`, modify this expression instance in-place.
1248            opts: other options to use to parse the input expressions.
1249
1250        Returns:
1251            The modified Query expression.
1252        """
1253        raise NotImplementedError("Query objects must implement `select`")
1254
1255    def where(
1256        self: Q,
1257        *expressions: t.Optional[ExpOrStr],
1258        append: bool = True,
1259        dialect: DialectType = None,
1260        copy: bool = True,
1261        **opts,
1262    ) -> Q:
1263        """
1264        Append to or set the WHERE expressions.
1265
1266        Examples:
1267            >>> Select().select("x").from_("tbl").where("x = 'a' OR x < 'b'").sql()
1268            "SELECT x FROM tbl WHERE x = 'a' OR x < 'b'"
1269
1270        Args:
1271            *expressions: the SQL code strings to parse.
1272                If an `Expression` instance is passed, it will be used as-is.
1273                Multiple expressions are combined with an AND operator.
1274            append: if `True`, AND the new expressions to any existing expression.
1275                Otherwise, this resets the expression.
1276            dialect: the dialect used to parse the input expressions.
1277            copy: if `False`, modify this expression instance in-place.
1278            opts: other options to use to parse the input expressions.
1279
1280        Returns:
1281            The modified expression.
1282        """
1283        return _apply_conjunction_builder(
1284            *[expr.this if isinstance(expr, Where) else expr for expr in expressions],
1285            instance=self,
1286            arg="where",
1287            append=append,
1288            into=Where,
1289            dialect=dialect,
1290            copy=copy,
1291            **opts,
1292        )
1293
1294    def with_(
1295        self: Q,
1296        alias: ExpOrStr,
1297        as_: ExpOrStr,
1298        recursive: t.Optional[bool] = None,
1299        materialized: t.Optional[bool] = None,
1300        append: bool = True,
1301        dialect: DialectType = None,
1302        copy: bool = True,
1303        scalar: bool = False,
1304        **opts,
1305    ) -> Q:
1306        """
1307        Append to or set the common table expressions.
1308
1309        Example:
1310            >>> Select().with_("tbl2", as_="SELECT * FROM tbl").select("x").from_("tbl2").sql()
1311            'WITH tbl2 AS (SELECT * FROM tbl) SELECT x FROM tbl2'
1312
1313        Args:
1314            alias: the SQL code string to parse as the table name.
1315                If an `Expression` instance is passed, this is used as-is.
1316            as_: the SQL code string to parse as the table expression.
1317                If an `Expression` instance is passed, it will be used as-is.
1318            recursive: set the RECURSIVE part of the expression. Defaults to `False`.
1319            materialized: set the MATERIALIZED part of the expression.
1320            append: if `True`, add to any existing expressions.
1321                Otherwise, this resets the expressions.
1322            dialect: the dialect used to parse the input expression.
1323            copy: if `False`, modify this expression instance in-place.
1324            scalar: if `True`, this is a scalar common table expression.
1325            opts: other options to use to parse the input expressions.
1326
1327        Returns:
1328            The modified expression.
1329        """
1330        return _apply_cte_builder(
1331            self,
1332            alias,
1333            as_,
1334            recursive=recursive,
1335            materialized=materialized,
1336            append=append,
1337            dialect=dialect,
1338            copy=copy,
1339            scalar=scalar,
1340            **opts,
1341        )
1342
1343    def union(
1344        self, *expressions: ExpOrStr, distinct: bool = True, dialect: DialectType = None, **opts
1345    ) -> Union:
1346        """
1347        Builds a UNION expression.
1348
1349        Example:
1350            >>> import sqlglot
1351            >>> sqlglot.parse_one("SELECT * FROM foo").union("SELECT * FROM bla").sql()
1352            'SELECT * FROM foo UNION SELECT * FROM bla'
1353
1354        Args:
1355            expressions: the SQL code strings.
1356                If `Expression` instances are passed, they will be used as-is.
1357            distinct: set the DISTINCT flag if and only if this is true.
1358            dialect: the dialect used to parse the input expression.
1359            opts: other options to use to parse the input expressions.
1360
1361        Returns:
1362            The new Union expression.
1363        """
1364        return union(self, *expressions, distinct=distinct, dialect=dialect, **opts)
1365
1366    def intersect(
1367        self, *expressions: ExpOrStr, distinct: bool = True, dialect: DialectType = None, **opts
1368    ) -> Intersect:
1369        """
1370        Builds an INTERSECT expression.
1371
1372        Example:
1373            >>> import sqlglot
1374            >>> sqlglot.parse_one("SELECT * FROM foo").intersect("SELECT * FROM bla").sql()
1375            'SELECT * FROM foo INTERSECT SELECT * FROM bla'
1376
1377        Args:
1378            expressions: the SQL code strings.
1379                If `Expression` instances are passed, they will be used as-is.
1380            distinct: set the DISTINCT flag if and only if this is true.
1381            dialect: the dialect used to parse the input expression.
1382            opts: other options to use to parse the input expressions.
1383
1384        Returns:
1385            The new Intersect expression.
1386        """
1387        return intersect(self, *expressions, distinct=distinct, dialect=dialect, **opts)
1388
1389    def except_(
1390        self, *expressions: ExpOrStr, distinct: bool = True, dialect: DialectType = None, **opts
1391    ) -> Except:
1392        """
1393        Builds an EXCEPT expression.
1394
1395        Example:
1396            >>> import sqlglot
1397            >>> sqlglot.parse_one("SELECT * FROM foo").except_("SELECT * FROM bla").sql()
1398            'SELECT * FROM foo EXCEPT SELECT * FROM bla'
1399
1400        Args:
1401            expressions: the SQL code strings.
1402                If `Expression` instance are passed, they will be used as-is.
1403            distinct: set the DISTINCT flag if and only if this is true.
1404            dialect: the dialect used to parse the input expression.
1405            opts: other options to use to parse the input expressions.
1406
1407        Returns:
1408            The new Except expression.
1409        """
1410        return except_(self, *expressions, distinct=distinct, dialect=dialect, **opts)
1411
1412
1413class UDTF(DerivedTable):
1414    @property
1415    def selects(self) -> t.List[Expression]:
1416        alias = self.args.get("alias")
1417        return alias.columns if alias else []
1418
1419
1420class Cache(Expression):
1421    arg_types = {
1422        "this": True,
1423        "lazy": False,
1424        "options": False,
1425        "expression": False,
1426    }
1427
1428
1429class Uncache(Expression):
1430    arg_types = {"this": True, "exists": False}
1431
1432
1433class Refresh(Expression):
1434    pass
1435
1436
1437class DDL(Expression):
1438    @property
1439    def ctes(self) -> t.List[CTE]:
1440        """Returns a list of all the CTEs attached to this statement."""
1441        with_ = self.args.get("with")
1442        return with_.expressions if with_ else []
1443
1444    @property
1445    def selects(self) -> t.List[Expression]:
1446        """If this statement contains a query (e.g. a CTAS), this returns the query's projections."""
1447        return self.expression.selects if isinstance(self.expression, Query) else []
1448
1449    @property
1450    def named_selects(self) -> t.List[str]:
1451        """
1452        If this statement contains a query (e.g. a CTAS), this returns the output
1453        names of the query's projections.
1454        """
1455        return self.expression.named_selects if isinstance(self.expression, Query) else []
1456
1457
1458class DML(Expression):
1459    def returning(
1460        self,
1461        expression: ExpOrStr,
1462        dialect: DialectType = None,
1463        copy: bool = True,
1464        **opts,
1465    ) -> "Self":
1466        """
1467        Set the RETURNING expression. Not supported by all dialects.
1468
1469        Example:
1470            >>> delete("tbl").returning("*", dialect="postgres").sql()
1471            'DELETE FROM tbl RETURNING *'
1472
1473        Args:
1474            expression: the SQL code strings to parse.
1475                If an `Expression` instance is passed, it will be used as-is.
1476            dialect: the dialect used to parse the input expressions.
1477            copy: if `False`, modify this expression instance in-place.
1478            opts: other options to use to parse the input expressions.
1479
1480        Returns:
1481            Delete: the modified expression.
1482        """
1483        return _apply_builder(
1484            expression=expression,
1485            instance=self,
1486            arg="returning",
1487            prefix="RETURNING",
1488            dialect=dialect,
1489            copy=copy,
1490            into=Returning,
1491            **opts,
1492        )
1493
1494
1495class Create(DDL):
1496    arg_types = {
1497        "with": False,
1498        "this": True,
1499        "kind": True,
1500        "expression": False,
1501        "exists": False,
1502        "properties": False,
1503        "replace": False,
1504        "refresh": False,
1505        "unique": False,
1506        "indexes": False,
1507        "no_schema_binding": False,
1508        "begin": False,
1509        "end": False,
1510        "clone": False,
1511        "concurrently": False,
1512        "clustered": False,
1513    }
1514
1515    @property
1516    def kind(self) -> t.Optional[str]:
1517        kind = self.args.get("kind")
1518        return kind and kind.upper()
1519
1520
1521class SequenceProperties(Expression):
1522    arg_types = {
1523        "increment": False,
1524        "minvalue": False,
1525        "maxvalue": False,
1526        "cache": False,
1527        "start": False,
1528        "owned": False,
1529        "options": False,
1530    }
1531
1532
1533class TruncateTable(Expression):
1534    arg_types = {
1535        "expressions": True,
1536        "is_database": False,
1537        "exists": False,
1538        "only": False,
1539        "cluster": False,
1540        "identity": False,
1541        "option": False,
1542        "partition": False,
1543    }
1544
1545
1546# https://docs.snowflake.com/en/sql-reference/sql/create-clone
1547# https://cloud.google.com/bigquery/docs/reference/standard-sql/data-definition-language#create_table_clone_statement
1548# https://cloud.google.com/bigquery/docs/reference/standard-sql/data-definition-language#create_table_copy
1549class Clone(Expression):
1550    arg_types = {"this": True, "shallow": False, "copy": False}
1551
1552
1553class Describe(Expression):
1554    arg_types = {
1555        "this": True,
1556        "style": False,
1557        "kind": False,
1558        "expressions": False,
1559        "partition": False,
1560        "format": False,
1561    }
1562
1563
1564# https://duckdb.org/docs/sql/statements/attach.html#attach
1565class Attach(Expression):
1566    arg_types = {"this": True, "exists": False, "expressions": False}
1567
1568
1569# https://duckdb.org/docs/sql/statements/attach.html#detach
1570class Detach(Expression):
1571    arg_types = {"this": True, "exists": False}
1572
1573
1574# https://duckdb.org/docs/guides/meta/summarize.html
1575class Summarize(Expression):
1576    arg_types = {"this": True, "table": False}
1577
1578
1579class Kill(Expression):
1580    arg_types = {"this": True, "kind": False}
1581
1582
1583class Pragma(Expression):
1584    pass
1585
1586
1587class Declare(Expression):
1588    arg_types = {"expressions": True}
1589
1590
1591class DeclareItem(Expression):
1592    arg_types = {"this": True, "kind": False, "default": False}
1593
1594
1595class Set(Expression):
1596    arg_types = {"expressions": False, "unset": False, "tag": False}
1597
1598
1599class Heredoc(Expression):
1600    arg_types = {"this": True, "tag": False}
1601
1602
1603class SetItem(Expression):
1604    arg_types = {
1605        "this": False,
1606        "expressions": False,
1607        "kind": False,
1608        "collate": False,  # MySQL SET NAMES statement
1609        "global": False,
1610    }
1611
1612
1613class Show(Expression):
1614    arg_types = {
1615        "this": True,
1616        "history": False,
1617        "terse": False,
1618        "target": False,
1619        "offset": False,
1620        "starts_with": False,
1621        "limit": False,
1622        "from": False,
1623        "like": False,
1624        "where": False,
1625        "db": False,
1626        "scope": False,
1627        "scope_kind": False,
1628        "full": False,
1629        "mutex": False,
1630        "query": False,
1631        "channel": False,
1632        "global": False,
1633        "log": False,
1634        "position": False,
1635        "types": False,
1636        "privileges": False,
1637    }
1638
1639
1640class UserDefinedFunction(Expression):
1641    arg_types = {"this": True, "expressions": False, "wrapped": False}
1642
1643
1644class CharacterSet(Expression):
1645    arg_types = {"this": True, "default": False}
1646
1647
1648class RecursiveWithSearch(Expression):
1649    arg_types = {"kind": True, "this": True, "expression": True, "using": False}
1650
1651
1652class With(Expression):
1653    arg_types = {"expressions": True, "recursive": False, "search": False}
1654
1655    @property
1656    def recursive(self) -> bool:
1657        return bool(self.args.get("recursive"))
1658
1659
1660class WithinGroup(Expression):
1661    arg_types = {"this": True, "expression": False}
1662
1663
1664# clickhouse supports scalar ctes
1665# https://clickhouse.com/docs/en/sql-reference/statements/select/with
1666class CTE(DerivedTable):
1667    arg_types = {
1668        "this": True,
1669        "alias": True,
1670        "scalar": False,
1671        "materialized": False,
1672    }
1673
1674
1675class ProjectionDef(Expression):
1676    arg_types = {"this": True, "expression": True}
1677
1678
1679class TableAlias(Expression):
1680    arg_types = {"this": False, "columns": False, "column_only": False}
1681
1682    @property
1683    def columns(self):
1684        return self.args.get("columns") or []
1685
1686
1687class BitString(Condition):
1688    pass
1689
1690
1691class HexString(Condition):
1692    arg_types = {"this": True, "is_integer": False}
1693
1694
1695class ByteString(Condition):
1696    pass
1697
1698
1699class RawString(Condition):
1700    pass
1701
1702
1703class UnicodeString(Condition):
1704    arg_types = {"this": True, "escape": False}
1705
1706
1707class Column(Condition):
1708    arg_types = {"this": True, "table": False, "db": False, "catalog": False, "join_mark": False}
1709
1710    @property
1711    def table(self) -> str:
1712        return self.text("table")
1713
1714    @property
1715    def db(self) -> str:
1716        return self.text("db")
1717
1718    @property
1719    def catalog(self) -> str:
1720        return self.text("catalog")
1721
1722    @property
1723    def output_name(self) -> str:
1724        return self.name
1725
1726    @property
1727    def parts(self) -> t.List[Identifier]:
1728        """Return the parts of a column in order catalog, db, table, name."""
1729        return [
1730            t.cast(Identifier, self.args[part])
1731            for part in ("catalog", "db", "table", "this")
1732            if self.args.get(part)
1733        ]
1734
1735    def to_dot(self, include_dots: bool = True) -> Dot | Identifier:
1736        """Converts the column into a dot expression."""
1737        parts = self.parts
1738        parent = self.parent
1739
1740        if include_dots:
1741            while isinstance(parent, Dot):
1742                parts.append(parent.expression)
1743                parent = parent.parent
1744
1745        return Dot.build(deepcopy(parts)) if len(parts) > 1 else parts[0]
1746
1747
1748class ColumnPosition(Expression):
1749    arg_types = {"this": False, "position": True}
1750
1751
1752class ColumnDef(Expression):
1753    arg_types = {
1754        "this": True,
1755        "kind": False,
1756        "constraints": False,
1757        "exists": False,
1758        "position": False,
1759        "default": False,
1760        "output": False,
1761    }
1762
1763    @property
1764    def constraints(self) -> t.List[ColumnConstraint]:
1765        return self.args.get("constraints") or []
1766
1767    @property
1768    def kind(self) -> t.Optional[DataType]:
1769        return self.args.get("kind")
1770
1771
1772class AlterColumn(Expression):
1773    arg_types = {
1774        "this": True,
1775        "dtype": False,
1776        "collate": False,
1777        "using": False,
1778        "default": False,
1779        "drop": False,
1780        "comment": False,
1781        "allow_null": False,
1782        "visible": False,
1783    }
1784
1785
1786# https://dev.mysql.com/doc/refman/8.0/en/invisible-indexes.html
1787class AlterIndex(Expression):
1788    arg_types = {"this": True, "visible": True}
1789
1790
1791# https://docs.aws.amazon.com/redshift/latest/dg/r_ALTER_TABLE.html
1792class AlterDistStyle(Expression):
1793    pass
1794
1795
1796class AlterSortKey(Expression):
1797    arg_types = {"this": False, "expressions": False, "compound": False}
1798
1799
1800class AlterSet(Expression):
1801    arg_types = {
1802        "expressions": False,
1803        "option": False,
1804        "tablespace": False,
1805        "access_method": False,
1806        "file_format": False,
1807        "copy_options": False,
1808        "tag": False,
1809        "location": False,
1810        "serde": False,
1811    }
1812
1813
1814class RenameColumn(Expression):
1815    arg_types = {"this": True, "to": True, "exists": False}
1816
1817
1818class AlterRename(Expression):
1819    pass
1820
1821
1822class SwapTable(Expression):
1823    pass
1824
1825
1826class Comment(Expression):
1827    arg_types = {
1828        "this": True,
1829        "kind": True,
1830        "expression": True,
1831        "exists": False,
1832        "materialized": False,
1833    }
1834
1835
1836class Comprehension(Expression):
1837    arg_types = {"this": True, "expression": True, "iterator": True, "condition": False}
1838
1839
1840# https://clickhouse.com/docs/en/engines/table-engines/mergetree-family/mergetree#mergetree-table-ttl
1841class MergeTreeTTLAction(Expression):
1842    arg_types = {
1843        "this": True,
1844        "delete": False,
1845        "recompress": False,
1846        "to_disk": False,
1847        "to_volume": False,
1848    }
1849
1850
1851# https://clickhouse.com/docs/en/engines/table-engines/mergetree-family/mergetree#mergetree-table-ttl
1852class MergeTreeTTL(Expression):
1853    arg_types = {
1854        "expressions": True,
1855        "where": False,
1856        "group": False,
1857        "aggregates": False,
1858    }
1859
1860
1861# https://dev.mysql.com/doc/refman/8.0/en/create-table.html
1862class IndexConstraintOption(Expression):
1863    arg_types = {
1864        "key_block_size": False,
1865        "using": False,
1866        "parser": False,
1867        "comment": False,
1868        "visible": False,
1869        "engine_attr": False,
1870        "secondary_engine_attr": False,
1871    }
1872
1873
1874class ColumnConstraint(Expression):
1875    arg_types = {"this": False, "kind": True}
1876
1877    @property
1878    def kind(self) -> ColumnConstraintKind:
1879        return self.args["kind"]
1880
1881
1882class ColumnConstraintKind(Expression):
1883    pass
1884
1885
1886class AutoIncrementColumnConstraint(ColumnConstraintKind):
1887    pass
1888
1889
1890class PeriodForSystemTimeConstraint(ColumnConstraintKind):
1891    arg_types = {"this": True, "expression": True}
1892
1893
1894class CaseSpecificColumnConstraint(ColumnConstraintKind):
1895    arg_types = {"not_": True}
1896
1897
1898class CharacterSetColumnConstraint(ColumnConstraintKind):
1899    arg_types = {"this": True}
1900
1901
1902class CheckColumnConstraint(ColumnConstraintKind):
1903    arg_types = {"this": True, "enforced": False}
1904
1905
1906class ClusteredColumnConstraint(ColumnConstraintKind):
1907    pass
1908
1909
1910class CollateColumnConstraint(ColumnConstraintKind):
1911    pass
1912
1913
1914class CommentColumnConstraint(ColumnConstraintKind):
1915    pass
1916
1917
1918class CompressColumnConstraint(ColumnConstraintKind):
1919    arg_types = {"this": False}
1920
1921
1922class DateFormatColumnConstraint(ColumnConstraintKind):
1923    arg_types = {"this": True}
1924
1925
1926class DefaultColumnConstraint(ColumnConstraintKind):
1927    pass
1928
1929
1930class EncodeColumnConstraint(ColumnConstraintKind):
1931    pass
1932
1933
1934# https://www.postgresql.org/docs/current/sql-createtable.html#SQL-CREATETABLE-EXCLUDE
1935class ExcludeColumnConstraint(ColumnConstraintKind):
1936    pass
1937
1938
1939class EphemeralColumnConstraint(ColumnConstraintKind):
1940    arg_types = {"this": False}
1941
1942
1943class WithOperator(Expression):
1944    arg_types = {"this": True, "op": True}
1945
1946
1947class GeneratedAsIdentityColumnConstraint(ColumnConstraintKind):
1948    # this: True -> ALWAYS, this: False -> BY DEFAULT
1949    arg_types = {
1950        "this": False,
1951        "expression": False,
1952        "on_null": False,
1953        "start": False,
1954        "increment": False,
1955        "minvalue": False,
1956        "maxvalue": False,
1957        "cycle": False,
1958        "order": False,
1959    }
1960
1961
1962class GeneratedAsRowColumnConstraint(ColumnConstraintKind):
1963    arg_types = {"start": False, "hidden": False}
1964
1965
1966# https://dev.mysql.com/doc/refman/8.0/en/create-table.html
1967# https://github.com/ClickHouse/ClickHouse/blob/master/src/Parsers/ParserCreateQuery.h#L646
1968class IndexColumnConstraint(ColumnConstraintKind):
1969    arg_types = {
1970        "this": False,
1971        "expressions": False,
1972        "kind": False,
1973        "index_type": False,
1974        "options": False,
1975        "expression": False,  # Clickhouse
1976        "granularity": False,
1977    }
1978
1979
1980class InlineLengthColumnConstraint(ColumnConstraintKind):
1981    pass
1982
1983
1984class NonClusteredColumnConstraint(ColumnConstraintKind):
1985    pass
1986
1987
1988class NotForReplicationColumnConstraint(ColumnConstraintKind):
1989    arg_types = {}
1990
1991
1992# https://docs.snowflake.com/en/sql-reference/sql/create-table
1993class MaskingPolicyColumnConstraint(ColumnConstraintKind):
1994    arg_types = {"this": True, "expressions": False}
1995
1996
1997class NotNullColumnConstraint(ColumnConstraintKind):
1998    arg_types = {"allow_null": False}
1999
2000
2001# https://dev.mysql.com/doc/refman/5.7/en/timestamp-initialization.html
2002class OnUpdateColumnConstraint(ColumnConstraintKind):
2003    pass
2004
2005
2006class PrimaryKeyColumnConstraint(ColumnConstraintKind):
2007    arg_types = {"desc": False, "options": False}
2008
2009
2010class TitleColumnConstraint(ColumnConstraintKind):
2011    pass
2012
2013
2014class UniqueColumnConstraint(ColumnConstraintKind):
2015    arg_types = {
2016        "this": False,
2017        "index_type": False,
2018        "on_conflict": False,
2019        "nulls": False,
2020        "options": False,
2021    }
2022
2023
2024class UppercaseColumnConstraint(ColumnConstraintKind):
2025    arg_types: t.Dict[str, t.Any] = {}
2026
2027
2028# https://docs.risingwave.com/processing/watermarks#syntax
2029class WatermarkColumnConstraint(Expression):
2030    arg_types = {"this": True, "expression": True}
2031
2032
2033class PathColumnConstraint(ColumnConstraintKind):
2034    pass
2035
2036
2037# https://docs.snowflake.com/en/sql-reference/sql/create-table
2038class ProjectionPolicyColumnConstraint(ColumnConstraintKind):
2039    pass
2040
2041
2042# computed column expression
2043# https://learn.microsoft.com/en-us/sql/t-sql/statements/create-table-transact-sql?view=sql-server-ver16
2044class ComputedColumnConstraint(ColumnConstraintKind):
2045    arg_types = {"this": True, "persisted": False, "not_null": False}
2046
2047
2048class Constraint(Expression):
2049    arg_types = {"this": True, "expressions": True}
2050
2051
2052class Delete(DML):
2053    arg_types = {
2054        "with": False,
2055        "this": False,
2056        "using": False,
2057        "where": False,
2058        "returning": False,
2059        "limit": False,
2060        "tables": False,  # Multiple-Table Syntax (MySQL)
2061        "cluster": False,  # Clickhouse
2062    }
2063
2064    def delete(
2065        self,
2066        table: ExpOrStr,
2067        dialect: DialectType = None,
2068        copy: bool = True,
2069        **opts,
2070    ) -> Delete:
2071        """
2072        Create a DELETE expression or replace the table on an existing DELETE expression.
2073
2074        Example:
2075            >>> delete("tbl").sql()
2076            'DELETE FROM tbl'
2077
2078        Args:
2079            table: the table from which to delete.
2080            dialect: the dialect used to parse the input expression.
2081            copy: if `False`, modify this expression instance in-place.
2082            opts: other options to use to parse the input expressions.
2083
2084        Returns:
2085            Delete: the modified expression.
2086        """
2087        return _apply_builder(
2088            expression=table,
2089            instance=self,
2090            arg="this",
2091            dialect=dialect,
2092            into=Table,
2093            copy=copy,
2094            **opts,
2095        )
2096
2097    def where(
2098        self,
2099        *expressions: t.Optional[ExpOrStr],
2100        append: bool = True,
2101        dialect: DialectType = None,
2102        copy: bool = True,
2103        **opts,
2104    ) -> Delete:
2105        """
2106        Append to or set the WHERE expressions.
2107
2108        Example:
2109            >>> delete("tbl").where("x = 'a' OR x < 'b'").sql()
2110            "DELETE FROM tbl WHERE x = 'a' OR x < 'b'"
2111
2112        Args:
2113            *expressions: the SQL code strings to parse.
2114                If an `Expression` instance is passed, it will be used as-is.
2115                Multiple expressions are combined with an AND operator.
2116            append: if `True`, AND the new expressions to any existing expression.
2117                Otherwise, this resets the expression.
2118            dialect: the dialect used to parse the input expressions.
2119            copy: if `False`, modify this expression instance in-place.
2120            opts: other options to use to parse the input expressions.
2121
2122        Returns:
2123            Delete: the modified expression.
2124        """
2125        return _apply_conjunction_builder(
2126            *expressions,
2127            instance=self,
2128            arg="where",
2129            append=append,
2130            into=Where,
2131            dialect=dialect,
2132            copy=copy,
2133            **opts,
2134        )
2135
2136
2137class Drop(Expression):
2138    arg_types = {
2139        "this": False,
2140        "kind": False,
2141        "expressions": False,
2142        "exists": False,
2143        "temporary": False,
2144        "materialized": False,
2145        "cascade": False,
2146        "constraints": False,
2147        "purge": False,
2148        "cluster": False,
2149        "concurrently": False,
2150    }
2151
2152    @property
2153    def kind(self) -> t.Optional[str]:
2154        kind = self.args.get("kind")
2155        return kind and kind.upper()
2156
2157
2158# https://cloud.google.com/bigquery/docs/reference/standard-sql/export-statements
2159class Export(Expression):
2160    arg_types = {"this": True, "connection": False, "options": True}
2161
2162
2163class Filter(Expression):
2164    arg_types = {"this": True, "expression": True}
2165
2166
2167class Check(Expression):
2168    pass
2169
2170
2171class Changes(Expression):
2172    arg_types = {"information": True, "at_before": False, "end": False}
2173
2174
2175# https://docs.snowflake.com/en/sql-reference/constructs/connect-by
2176class Connect(Expression):
2177    arg_types = {"start": False, "connect": True, "nocycle": False}
2178
2179
2180class CopyParameter(Expression):
2181    arg_types = {"this": True, "expression": False, "expressions": False}
2182
2183
2184class Copy(DML):
2185    arg_types = {
2186        "this": True,
2187        "kind": True,
2188        "files": True,
2189        "credentials": False,
2190        "format": False,
2191        "params": False,
2192    }
2193
2194
2195class Credentials(Expression):
2196    arg_types = {
2197        "credentials": False,
2198        "encryption": False,
2199        "storage": False,
2200        "iam_role": False,
2201        "region": False,
2202    }
2203
2204
2205class Prior(Expression):
2206    pass
2207
2208
2209class Directory(Expression):
2210    # https://spark.apache.org/docs/3.0.0-preview/sql-ref-syntax-dml-insert-overwrite-directory-hive.html
2211    arg_types = {"this": True, "local": False, "row_format": False}
2212
2213
2214class ForeignKey(Expression):
2215    arg_types = {
2216        "expressions": False,
2217        "reference": False,
2218        "delete": False,
2219        "update": False,
2220        "options": False,
2221    }
2222
2223
2224class ColumnPrefix(Expression):
2225    arg_types = {"this": True, "expression": True}
2226
2227
2228class PrimaryKey(Expression):
2229    arg_types = {"expressions": True, "options": False, "include": False}
2230
2231
2232# https://www.postgresql.org/docs/9.1/sql-selectinto.html
2233# https://docs.aws.amazon.com/redshift/latest/dg/r_SELECT_INTO.html#r_SELECT_INTO-examples
2234class Into(Expression):
2235    arg_types = {
2236        "this": False,
2237        "temporary": False,
2238        "unlogged": False,
2239        "bulk_collect": False,
2240        "expressions": False,
2241    }
2242
2243
2244class From(Expression):
2245    @property
2246    def name(self) -> str:
2247        return self.this.name
2248
2249    @property
2250    def alias_or_name(self) -> str:
2251        return self.this.alias_or_name
2252
2253
2254class Having(Expression):
2255    pass
2256
2257
2258class Hint(Expression):
2259    arg_types = {"expressions": True}
2260
2261
2262class JoinHint(Expression):
2263    arg_types = {"this": True, "expressions": True}
2264
2265
2266class Identifier(Expression):
2267    arg_types = {"this": True, "quoted": False, "global": False, "temporary": False}
2268
2269    @property
2270    def quoted(self) -> bool:
2271        return bool(self.args.get("quoted"))
2272
2273    @property
2274    def hashable_args(self) -> t.Any:
2275        return (self.this, self.quoted)
2276
2277    @property
2278    def output_name(self) -> str:
2279        return self.name
2280
2281
2282# https://www.postgresql.org/docs/current/indexes-opclass.html
2283class Opclass(Expression):
2284    arg_types = {"this": True, "expression": True}
2285
2286
2287class Index(Expression):
2288    arg_types = {
2289        "this": False,
2290        "table": False,
2291        "unique": False,
2292        "primary": False,
2293        "amp": False,  # teradata
2294        "params": False,
2295    }
2296
2297
2298class IndexParameters(Expression):
2299    arg_types = {
2300        "using": False,
2301        "include": False,
2302        "columns": False,
2303        "with_storage": False,
2304        "partition_by": False,
2305        "tablespace": False,
2306        "where": False,
2307        "on": False,
2308    }
2309
2310
2311class Insert(DDL, DML):
2312    arg_types = {
2313        "hint": False,
2314        "with": False,
2315        "is_function": False,
2316        "this": False,
2317        "expression": False,
2318        "conflict": False,
2319        "returning": False,
2320        "overwrite": False,
2321        "exists": False,
2322        "alternative": False,
2323        "where": False,
2324        "ignore": False,
2325        "by_name": False,
2326        "stored": False,
2327        "partition": False,
2328        "settings": False,
2329        "source": False,
2330    }
2331
2332    def with_(
2333        self,
2334        alias: ExpOrStr,
2335        as_: ExpOrStr,
2336        recursive: t.Optional[bool] = None,
2337        materialized: t.Optional[bool] = None,
2338        append: bool = True,
2339        dialect: DialectType = None,
2340        copy: bool = True,
2341        **opts,
2342    ) -> Insert:
2343        """
2344        Append to or set the common table expressions.
2345
2346        Example:
2347            >>> insert("SELECT x FROM cte", "t").with_("cte", as_="SELECT * FROM tbl").sql()
2348            'WITH cte AS (SELECT * FROM tbl) INSERT INTO t SELECT x FROM cte'
2349
2350        Args:
2351            alias: the SQL code string to parse as the table name.
2352                If an `Expression` instance is passed, this is used as-is.
2353            as_: the SQL code string to parse as the table expression.
2354                If an `Expression` instance is passed, it will be used as-is.
2355            recursive: set the RECURSIVE part of the expression. Defaults to `False`.
2356            materialized: set the MATERIALIZED part of the expression.
2357            append: if `True`, add to any existing expressions.
2358                Otherwise, this resets the expressions.
2359            dialect: the dialect used to parse the input expression.
2360            copy: if `False`, modify this expression instance in-place.
2361            opts: other options to use to parse the input expressions.
2362
2363        Returns:
2364            The modified expression.
2365        """
2366        return _apply_cte_builder(
2367            self,
2368            alias,
2369            as_,
2370            recursive=recursive,
2371            materialized=materialized,
2372            append=append,
2373            dialect=dialect,
2374            copy=copy,
2375            **opts,
2376        )
2377
2378
2379class ConditionalInsert(Expression):
2380    arg_types = {"this": True, "expression": False, "else_": False}
2381
2382
2383class MultitableInserts(Expression):
2384    arg_types = {"expressions": True, "kind": True, "source": True}
2385
2386
2387class OnConflict(Expression):
2388    arg_types = {
2389        "duplicate": False,
2390        "expressions": False,
2391        "action": False,
2392        "conflict_keys": False,
2393        "constraint": False,
2394        "where": False,
2395    }
2396
2397
2398class OnCondition(Expression):
2399    arg_types = {"error": False, "empty": False, "null": False}
2400
2401
2402class Returning(Expression):
2403    arg_types = {"expressions": True, "into": False}
2404
2405
2406# https://dev.mysql.com/doc/refman/8.0/en/charset-introducer.html
2407class Introducer(Expression):
2408    arg_types = {"this": True, "expression": True}
2409
2410
2411# national char, like n'utf8'
2412class National(Expression):
2413    pass
2414
2415
2416class LoadData(Expression):
2417    arg_types = {
2418        "this": True,
2419        "local": False,
2420        "overwrite": False,
2421        "inpath": True,
2422        "partition": False,
2423        "input_format": False,
2424        "serde": False,
2425    }
2426
2427
2428class Partition(Expression):
2429    arg_types = {"expressions": True, "subpartition": False}
2430
2431
2432class PartitionRange(Expression):
2433    arg_types = {"this": True, "expression": False, "expressions": False}
2434
2435
2436# https://clickhouse.com/docs/en/sql-reference/statements/alter/partition#how-to-set-partition-expression
2437class PartitionId(Expression):
2438    pass
2439
2440
2441class Fetch(Expression):
2442    arg_types = {
2443        "direction": False,
2444        "count": False,
2445        "limit_options": False,
2446    }
2447
2448
2449class Grant(Expression):
2450    arg_types = {
2451        "privileges": True,
2452        "kind": False,
2453        "securable": True,
2454        "principals": True,
2455        "grant_option": False,
2456    }
2457
2458
2459class Group(Expression):
2460    arg_types = {
2461        "expressions": False,
2462        "grouping_sets": False,
2463        "cube": False,
2464        "rollup": False,
2465        "totals": False,
2466        "all": False,
2467    }
2468
2469
2470class Cube(Expression):
2471    arg_types = {"expressions": False}
2472
2473
2474class Rollup(Expression):
2475    arg_types = {"expressions": False}
2476
2477
2478class GroupingSets(Expression):
2479    arg_types = {"expressions": True}
2480
2481
2482class Lambda(Expression):
2483    arg_types = {"this": True, "expressions": True, "colon": False}
2484
2485
2486class Limit(Expression):
2487    arg_types = {
2488        "this": False,
2489        "expression": True,
2490        "offset": False,
2491        "limit_options": False,
2492        "expressions": False,
2493    }
2494
2495
2496class LimitOptions(Expression):
2497    arg_types = {
2498        "percent": False,
2499        "rows": False,
2500        "with_ties": False,
2501    }
2502
2503
2504class Literal(Condition):
2505    arg_types = {"this": True, "is_string": True}
2506
2507    @property
2508    def hashable_args(self) -> t.Any:
2509        return (self.this, self.args.get("is_string"))
2510
2511    @classmethod
2512    def number(cls, number) -> Literal:
2513        return cls(this=str(number), is_string=False)
2514
2515    @classmethod
2516    def string(cls, string) -> Literal:
2517        return cls(this=str(string), is_string=True)
2518
2519    @property
2520    def output_name(self) -> str:
2521        return self.name
2522
2523    def to_py(self) -> int | str | Decimal:
2524        if self.is_number:
2525            try:
2526                return int(self.this)
2527            except ValueError:
2528                return Decimal(self.this)
2529        return self.this
2530
2531
2532class Join(Expression):
2533    arg_types = {
2534        "this": True,
2535        "on": False,
2536        "side": False,
2537        "kind": False,
2538        "using": False,
2539        "method": False,
2540        "global": False,
2541        "hint": False,
2542        "match_condition": False,  # Snowflake
2543        "expressions": False,
2544        "pivots": False,
2545    }
2546
2547    @property
2548    def method(self) -> str:
2549        return self.text("method").upper()
2550
2551    @property
2552    def kind(self) -> str:
2553        return self.text("kind").upper()
2554
2555    @property
2556    def side(self) -> str:
2557        return self.text("side").upper()
2558
2559    @property
2560    def hint(self) -> str:
2561        return self.text("hint").upper()
2562
2563    @property
2564    def alias_or_name(self) -> str:
2565        return self.this.alias_or_name
2566
2567    @property
2568    def is_semi_or_anti_join(self) -> bool:
2569        return self.kind in ("SEMI", "ANTI")
2570
2571    def on(
2572        self,
2573        *expressions: t.Optional[ExpOrStr],
2574        append: bool = True,
2575        dialect: DialectType = None,
2576        copy: bool = True,
2577        **opts,
2578    ) -> Join:
2579        """
2580        Append to or set the ON expressions.
2581
2582        Example:
2583            >>> import sqlglot
2584            >>> sqlglot.parse_one("JOIN x", into=Join).on("y = 1").sql()
2585            'JOIN x ON y = 1'
2586
2587        Args:
2588            *expressions: the SQL code strings to parse.
2589                If an `Expression` instance is passed, it will be used as-is.
2590                Multiple expressions are combined with an AND operator.
2591            append: if `True`, AND the new expressions to any existing expression.
2592                Otherwise, this resets the expression.
2593            dialect: the dialect used to parse the input expressions.
2594            copy: if `False`, modify this expression instance in-place.
2595            opts: other options to use to parse the input expressions.
2596
2597        Returns:
2598            The modified Join expression.
2599        """
2600        join = _apply_conjunction_builder(
2601            *expressions,
2602            instance=self,
2603            arg="on",
2604            append=append,
2605            dialect=dialect,
2606            copy=copy,
2607            **opts,
2608        )
2609
2610        if join.kind == "CROSS":
2611            join.set("kind", None)
2612
2613        return join
2614
2615    def using(
2616        self,
2617        *expressions: t.Optional[ExpOrStr],
2618        append: bool = True,
2619        dialect: DialectType = None,
2620        copy: bool = True,
2621        **opts,
2622    ) -> Join:
2623        """
2624        Append to or set the USING expressions.
2625
2626        Example:
2627            >>> import sqlglot
2628            >>> sqlglot.parse_one("JOIN x", into=Join).using("foo", "bla").sql()
2629            'JOIN x USING (foo, bla)'
2630
2631        Args:
2632            *expressions: the SQL code strings to parse.
2633                If an `Expression` instance is passed, it will be used as-is.
2634            append: if `True`, concatenate the new expressions to the existing "using" list.
2635                Otherwise, this resets the expression.
2636            dialect: the dialect used to parse the input expressions.
2637            copy: if `False`, modify this expression instance in-place.
2638            opts: other options to use to parse the input expressions.
2639
2640        Returns:
2641            The modified Join expression.
2642        """
2643        join = _apply_list_builder(
2644            *expressions,
2645            instance=self,
2646            arg="using",
2647            append=append,
2648            dialect=dialect,
2649            copy=copy,
2650            **opts,
2651        )
2652
2653        if join.kind == "CROSS":
2654            join.set("kind", None)
2655
2656        return join
2657
2658
2659class Lateral(UDTF):
2660    arg_types = {
2661        "this": True,
2662        "view": False,
2663        "outer": False,
2664        "alias": False,
2665        "cross_apply": False,  # True -> CROSS APPLY, False -> OUTER APPLY
2666        "ordinality": False,
2667    }
2668
2669
2670# https://docs.snowflake.com/sql-reference/literals-table
2671# https://docs.snowflake.com/en/sql-reference/functions-table#using-a-table-function
2672class TableFromRows(UDTF):
2673    arg_types = {
2674        "this": True,
2675        "alias": False,
2676        "joins": False,
2677        "pivots": False,
2678        "sample": False,
2679    }
2680
2681
2682class MatchRecognizeMeasure(Expression):
2683    arg_types = {
2684        "this": True,
2685        "window_frame": False,
2686    }
2687
2688
2689class MatchRecognize(Expression):
2690    arg_types = {
2691        "partition_by": False,
2692        "order": False,
2693        "measures": False,
2694        "rows": False,
2695        "after": False,
2696        "pattern": False,
2697        "define": False,
2698        "alias": False,
2699    }
2700
2701
2702# Clickhouse FROM FINAL modifier
2703# https://clickhouse.com/docs/en/sql-reference/statements/select/from/#final-modifier
2704class Final(Expression):
2705    pass
2706
2707
2708class Offset(Expression):
2709    arg_types = {"this": False, "expression": True, "expressions": False}
2710
2711
2712class Order(Expression):
2713    arg_types = {"this": False, "expressions": True, "siblings": False}
2714
2715
2716# https://clickhouse.com/docs/en/sql-reference/statements/select/order-by#order-by-expr-with-fill-modifier
2717class WithFill(Expression):
2718    arg_types = {
2719        "from": False,
2720        "to": False,
2721        "step": False,
2722        "interpolate": False,
2723    }
2724
2725
2726# hive specific sorts
2727# https://cwiki.apache.org/confluence/display/Hive/LanguageManual+SortBy
2728class Cluster(Order):
2729    pass
2730
2731
2732class Distribute(Order):
2733    pass
2734
2735
2736class Sort(Order):
2737    pass
2738
2739
2740class Ordered(Expression):
2741    arg_types = {"this": True, "desc": False, "nulls_first": True, "with_fill": False}
2742
2743    @property
2744    def name(self) -> str:
2745        return self.this.name
2746
2747
2748class Property(Expression):
2749    arg_types = {"this": True, "value": True}
2750
2751
2752class GrantPrivilege(Expression):
2753    arg_types = {"this": True, "expressions": False}
2754
2755
2756class GrantPrincipal(Expression):
2757    arg_types = {"this": True, "kind": False}
2758
2759
2760class AllowedValuesProperty(Expression):
2761    arg_types = {"expressions": True}
2762
2763
2764class AlgorithmProperty(Property):
2765    arg_types = {"this": True}
2766
2767
2768class AutoIncrementProperty(Property):
2769    arg_types = {"this": True}
2770
2771
2772# https://docs.aws.amazon.com/prescriptive-guidance/latest/materialized-views-redshift/refreshing-materialized-views.html
2773class AutoRefreshProperty(Property):
2774    arg_types = {"this": True}
2775
2776
2777class BackupProperty(Property):
2778    arg_types = {"this": True}
2779
2780
2781class BlockCompressionProperty(Property):
2782    arg_types = {
2783        "autotemp": False,
2784        "always": False,
2785        "default": False,
2786        "manual": False,
2787        "never": False,
2788    }
2789
2790
2791class CharacterSetProperty(Property):
2792    arg_types = {"this": True, "default": True}
2793
2794
2795class ChecksumProperty(Property):
2796    arg_types = {"on": False, "default": False}
2797
2798
2799class CollateProperty(Property):
2800    arg_types = {"this": True, "default": False}
2801
2802
2803class CopyGrantsProperty(Property):
2804    arg_types = {}
2805
2806
2807class DataBlocksizeProperty(Property):
2808    arg_types = {
2809        "size": False,
2810        "units": False,
2811        "minimum": False,
2812        "maximum": False,
2813        "default": False,
2814    }
2815
2816
2817class DataDeletionProperty(Property):
2818    arg_types = {"on": True, "filter_col": False, "retention_period": False}
2819
2820
2821class DefinerProperty(Property):
2822    arg_types = {"this": True}
2823
2824
2825class DistKeyProperty(Property):
2826    arg_types = {"this": True}
2827
2828
2829# https://docs.starrocks.io/docs/sql-reference/sql-statements/data-definition/CREATE_TABLE/#distribution_desc
2830# https://doris.apache.org/docs/sql-manual/sql-statements/Data-Definition-Statements/Create/CREATE-TABLE?_highlight=create&_highlight=table#distribution_desc
2831class DistributedByProperty(Property):
2832    arg_types = {"expressions": False, "kind": True, "buckets": False, "order": False}
2833
2834
2835class DistStyleProperty(Property):
2836    arg_types = {"this": True}
2837
2838
2839class DuplicateKeyProperty(Property):
2840    arg_types = {"expressions": True}
2841
2842
2843class EngineProperty(Property):
2844    arg_types = {"this": True}
2845
2846
2847class HeapProperty(Property):
2848    arg_types = {}
2849
2850
2851class ToTableProperty(Property):
2852    arg_types = {"this": True}
2853
2854
2855class ExecuteAsProperty(Property):
2856    arg_types = {"this": True}
2857
2858
2859class ExternalProperty(Property):
2860    arg_types = {"this": False}
2861
2862
2863class FallbackProperty(Property):
2864    arg_types = {"no": True, "protection": False}
2865
2866
2867# https://docs.databricks.com/aws/en/sql/language-manual/sql-ref-syntax-ddl-create-table-hiveformat
2868class FileFormatProperty(Property):
2869    arg_types = {"this": False, "expressions": False, "hive_format": False}
2870
2871
2872class CredentialsProperty(Property):
2873    arg_types = {"expressions": True}
2874
2875
2876class FreespaceProperty(Property):
2877    arg_types = {"this": True, "percent": False}
2878
2879
2880class GlobalProperty(Property):
2881    arg_types = {}
2882
2883
2884class IcebergProperty(Property):
2885    arg_types = {}
2886
2887
2888class InheritsProperty(Property):
2889    arg_types = {"expressions": True}
2890
2891
2892class InputModelProperty(Property):
2893    arg_types = {"this": True}
2894
2895
2896class OutputModelProperty(Property):
2897    arg_types = {"this": True}
2898
2899
2900class IsolatedLoadingProperty(Property):
2901    arg_types = {"no": False, "concurrent": False, "target": False}
2902
2903
2904class JournalProperty(Property):
2905    arg_types = {
2906        "no": False,
2907        "dual": False,
2908        "before": False,
2909        "local": False,
2910        "after": False,
2911    }
2912
2913
2914class LanguageProperty(Property):
2915    arg_types = {"this": True}
2916
2917
2918class EnviromentProperty(Property):
2919    arg_types = {"expressions": True}
2920
2921
2922# spark ddl
2923class ClusteredByProperty(Property):
2924    arg_types = {"expressions": True, "sorted_by": False, "buckets": True}
2925
2926
2927class DictProperty(Property):
2928    arg_types = {"this": True, "kind": True, "settings": False}
2929
2930
2931class DictSubProperty(Property):
2932    pass
2933
2934
2935class DictRange(Property):
2936    arg_types = {"this": True, "min": True, "max": True}
2937
2938
2939class DynamicProperty(Property):
2940    arg_types = {}
2941
2942
2943# Clickhouse CREATE ... ON CLUSTER modifier
2944# https://clickhouse.com/docs/en/sql-reference/distributed-ddl
2945class OnCluster(Property):
2946    arg_types = {"this": True}
2947
2948
2949# Clickhouse EMPTY table "property"
2950class EmptyProperty(Property):
2951    arg_types = {}
2952
2953
2954class LikeProperty(Property):
2955    arg_types = {"this": True, "expressions": False}
2956
2957
2958class LocationProperty(Property):
2959    arg_types = {"this": True}
2960
2961
2962class LockProperty(Property):
2963    arg_types = {"this": True}
2964
2965
2966class LockingProperty(Property):
2967    arg_types = {
2968        "this": False,
2969        "kind": True,
2970        "for_or_in": False,
2971        "lock_type": True,
2972        "override": False,
2973    }
2974
2975
2976class LogProperty(Property):
2977    arg_types = {"no": True}
2978
2979
2980class MaterializedProperty(Property):
2981    arg_types = {"this": False}
2982
2983
2984class MergeBlockRatioProperty(Property):
2985    arg_types = {"this": False, "no": False, "default": False, "percent": False}
2986
2987
2988class NoPrimaryIndexProperty(Property):
2989    arg_types = {}
2990
2991
2992class OnProperty(Property):
2993    arg_types = {"this": True}
2994
2995
2996class OnCommitProperty(Property):
2997    arg_types = {"delete": False}
2998
2999
3000class PartitionedByProperty(Property):
3001    arg_types = {"this": True}
3002
3003
3004class PartitionedByBucket(Property):
3005    arg_types = {"this": True, "expression": True}
3006
3007
3008class PartitionByTruncate(Property):
3009    arg_types = {"this": True, "expression": True}
3010
3011
3012# https://docs.starrocks.io/docs/sql-reference/sql-statements/table_bucket_part_index/CREATE_TABLE/
3013class PartitionByRangeProperty(Property):
3014    arg_types = {"partition_expressions": True, "create_expressions": True}
3015
3016
3017# https://docs.starrocks.io/docs/table_design/data_distribution/#range-partitioning
3018class PartitionByRangePropertyDynamic(Expression):
3019    arg_types = {"this": False, "start": True, "end": True, "every": True}
3020
3021
3022# https://docs.starrocks.io/docs/sql-reference/sql-statements/table_bucket_part_index/CREATE_TABLE/
3023class UniqueKeyProperty(Property):
3024    arg_types = {"expressions": True}
3025
3026
3027# https://www.postgresql.org/docs/current/sql-createtable.html
3028class PartitionBoundSpec(Expression):
3029    # this -> IN / MODULUS, expression -> REMAINDER, from_expressions -> FROM (...), to_expressions -> TO (...)
3030    arg_types = {
3031        "this": False,
3032        "expression": False,
3033        "from_expressions": False,
3034        "to_expressions": False,
3035    }
3036
3037
3038class PartitionedOfProperty(Property):
3039    # this -> parent_table (schema), expression -> FOR VALUES ... / DEFAULT
3040    arg_types = {"this": True, "expression": True}
3041
3042
3043class StreamingTableProperty(Property):
3044    arg_types = {}
3045
3046
3047class RemoteWithConnectionModelProperty(Property):
3048    arg_types = {"this": True}
3049
3050
3051class ReturnsProperty(Property):
3052    arg_types = {"this": False, "is_table": False, "table": False, "null": False}
3053
3054
3055class StrictProperty(Property):
3056    arg_types = {}
3057
3058
3059class RowFormatProperty(Property):
3060    arg_types = {"this": True}
3061
3062
3063class RowFormatDelimitedProperty(Property):
3064    # https://cwiki.apache.org/confluence/display/hive/languagemanual+dml
3065    arg_types = {
3066        "fields": False,
3067        "escaped": False,
3068        "collection_items": False,
3069        "map_keys": False,
3070        "lines": False,
3071        "null": False,
3072        "serde": False,
3073    }
3074
3075
3076class RowFormatSerdeProperty(Property):
3077    arg_types = {"this": True, "serde_properties": False}
3078
3079
3080# https://spark.apache.org/docs/3.1.2/sql-ref-syntax-qry-select-transform.html
3081class QueryTransform(Expression):
3082    arg_types = {
3083        "expressions": True,
3084        "command_script": True,
3085        "schema": False,
3086        "row_format_before": False,
3087        "record_writer": False,
3088        "row_format_after": False,
3089        "record_reader": False,
3090    }
3091
3092
3093class SampleProperty(Property):
3094    arg_types = {"this": True}
3095
3096
3097# https://prestodb.io/docs/current/sql/create-view.html#synopsis
3098class SecurityProperty(Property):
3099    arg_types = {"this": True}
3100
3101
3102class SchemaCommentProperty(Property):
3103    arg_types = {"this": True}
3104
3105
3106class SemanticView(Expression):
3107    arg_types = {"this": True, "metrics": False, "dimensions": False, "where": False}
3108
3109
3110class SerdeProperties(Property):
3111    arg_types = {"expressions": True, "with": False}
3112
3113
3114class SetProperty(Property):
3115    arg_types = {"multi": True}
3116
3117
3118class SharingProperty(Property):
3119    arg_types = {"this": False}
3120
3121
3122class SetConfigProperty(Property):
3123    arg_types = {"this": True}
3124
3125
3126class SettingsProperty(Property):
3127    arg_types = {"expressions": True}
3128
3129
3130class SortKeyProperty(Property):
3131    arg_types = {"this": True, "compound": False}
3132
3133
3134class SqlReadWriteProperty(Property):
3135    arg_types = {"this": True}
3136
3137
3138class SqlSecurityProperty(Property):
3139    arg_types = {"definer": True}
3140
3141
3142class StabilityProperty(Property):
3143    arg_types = {"this": True}
3144
3145
3146class StorageHandlerProperty(Property):
3147    arg_types = {"this": True}
3148
3149
3150class TemporaryProperty(Property):
3151    arg_types = {"this": False}
3152
3153
3154class SecureProperty(Property):
3155    arg_types = {}
3156
3157
3158# https://docs.snowflake.com/en/sql-reference/sql/create-table
3159class Tags(ColumnConstraintKind, Property):
3160    arg_types = {"expressions": True}
3161
3162
3163class TransformModelProperty(Property):
3164    arg_types = {"expressions": True}
3165
3166
3167class TransientProperty(Property):
3168    arg_types = {"this": False}
3169
3170
3171class UnloggedProperty(Property):
3172    arg_types = {}
3173
3174
3175# https://docs.snowflake.com/en/sql-reference/sql/create-table#create-table-using-template
3176class UsingTemplateProperty(Property):
3177    arg_types = {"this": True}
3178
3179
3180# https://learn.microsoft.com/en-us/sql/t-sql/statements/create-view-transact-sql?view=sql-server-ver16
3181class ViewAttributeProperty(Property):
3182    arg_types = {"this": True}
3183
3184
3185class VolatileProperty(Property):
3186    arg_types = {"this": False}
3187
3188
3189class WithDataProperty(Property):
3190    arg_types = {"no": True, "statistics": False}
3191
3192
3193class WithJournalTableProperty(Property):
3194    arg_types = {"this": True}
3195
3196
3197class WithSchemaBindingProperty(Property):
3198    arg_types = {"this": True}
3199
3200
3201class WithSystemVersioningProperty(Property):
3202    arg_types = {
3203        "on": False,
3204        "this": False,
3205        "data_consistency": False,
3206        "retention_period": False,
3207        "with": True,
3208    }
3209
3210
3211class WithProcedureOptions(Property):
3212    arg_types = {"expressions": True}
3213
3214
3215class EncodeProperty(Property):
3216    arg_types = {"this": True, "properties": False, "key": False}
3217
3218
3219class IncludeProperty(Property):
3220    arg_types = {"this": True, "alias": False, "column_def": False}
3221
3222
3223class ForceProperty(Property):
3224    arg_types = {}
3225
3226
3227class Properties(Expression):
3228    arg_types = {"expressions": True}
3229
3230    NAME_TO_PROPERTY = {
3231        "ALGORITHM": AlgorithmProperty,
3232        "AUTO_INCREMENT": AutoIncrementProperty,
3233        "CHARACTER SET": CharacterSetProperty,
3234        "CLUSTERED_BY": ClusteredByProperty,
3235        "COLLATE": CollateProperty,
3236        "COMMENT": SchemaCommentProperty,
3237        "CREDENTIALS": CredentialsProperty,
3238        "DEFINER": DefinerProperty,
3239        "DISTKEY": DistKeyProperty,
3240        "DISTRIBUTED_BY": DistributedByProperty,
3241        "DISTSTYLE": DistStyleProperty,
3242        "ENGINE": EngineProperty,
3243        "EXECUTE AS": ExecuteAsProperty,
3244        "FORMAT": FileFormatProperty,
3245        "LANGUAGE": LanguageProperty,
3246        "LOCATION": LocationProperty,
3247        "LOCK": LockProperty,
3248        "PARTITIONED_BY": PartitionedByProperty,
3249        "RETURNS": ReturnsProperty,
3250        "ROW_FORMAT": RowFormatProperty,
3251        "SORTKEY": SortKeyProperty,
3252        "ENCODE": EncodeProperty,
3253        "INCLUDE": IncludeProperty,
3254    }
3255
3256    PROPERTY_TO_NAME = {v: k for k, v in NAME_TO_PROPERTY.items()}
3257
3258    # CREATE property locations
3259    # Form: schema specified
3260    #   create [POST_CREATE]
3261    #     table a [POST_NAME]
3262    #     (b int) [POST_SCHEMA]
3263    #     with ([POST_WITH])
3264    #     index (b) [POST_INDEX]
3265    #
3266    # Form: alias selection
3267    #   create [POST_CREATE]
3268    #     table a [POST_NAME]
3269    #     as [POST_ALIAS] (select * from b) [POST_EXPRESSION]
3270    #     index (c) [POST_INDEX]
3271    class Location(AutoName):
3272        POST_CREATE = auto()
3273        POST_NAME = auto()
3274        POST_SCHEMA = auto()
3275        POST_WITH = auto()
3276        POST_ALIAS = auto()
3277        POST_EXPRESSION = auto()
3278        POST_INDEX = auto()
3279        UNSUPPORTED = auto()
3280
3281    @classmethod
3282    def from_dict(cls, properties_dict: t.Dict) -> Properties:
3283        expressions = []
3284        for key, value in properties_dict.items():
3285            property_cls = cls.NAME_TO_PROPERTY.get(key.upper())
3286            if property_cls:
3287                expressions.append(property_cls(this=convert(value)))
3288            else:
3289                expressions.append(Property(this=Literal.string(key), value=convert(value)))
3290
3291        return cls(expressions=expressions)
3292
3293
3294class Qualify(Expression):
3295    pass
3296
3297
3298class InputOutputFormat(Expression):
3299    arg_types = {"input_format": False, "output_format": False}
3300
3301
3302# https://www.ibm.com/docs/en/ias?topic=procedures-return-statement-in-sql
3303class Return(Expression):
3304    pass
3305
3306
3307class Reference(Expression):
3308    arg_types = {"this": True, "expressions": False, "options": False}
3309
3310
3311class Tuple(Expression):
3312    arg_types = {"expressions": False}
3313
3314    def isin(
3315        self,
3316        *expressions: t.Any,
3317        query: t.Optional[ExpOrStr] = None,
3318        unnest: t.Optional[ExpOrStr] | t.Collection[ExpOrStr] = None,
3319        copy: bool = True,
3320        **opts,
3321    ) -> In:
3322        return In(
3323            this=maybe_copy(self, copy),
3324            expressions=[convert(e, copy=copy) for e in expressions],
3325            query=maybe_parse(query, copy=copy, **opts) if query else None,
3326            unnest=(
3327                Unnest(
3328                    expressions=[
3329                        maybe_parse(t.cast(ExpOrStr, e), copy=copy, **opts)
3330                        for e in ensure_list(unnest)
3331                    ]
3332                )
3333                if unnest
3334                else None
3335            ),
3336        )
3337
3338
3339QUERY_MODIFIERS = {
3340    "match": False,
3341    "laterals": False,
3342    "joins": False,
3343    "connect": False,
3344    "pivots": False,
3345    "prewhere": False,
3346    "where": False,
3347    "group": False,
3348    "having": False,
3349    "qualify": False,
3350    "windows": False,
3351    "distribute": False,
3352    "sort": False,
3353    "cluster": False,
3354    "order": False,
3355    "limit": False,
3356    "offset": False,
3357    "locks": False,
3358    "sample": False,
3359    "settings": False,
3360    "format": False,
3361    "options": False,
3362}
3363
3364
3365# https://learn.microsoft.com/en-us/sql/t-sql/queries/option-clause-transact-sql?view=sql-server-ver16
3366# https://learn.microsoft.com/en-us/sql/t-sql/queries/hints-transact-sql-query?view=sql-server-ver16
3367class QueryOption(Expression):
3368    arg_types = {"this": True, "expression": False}
3369
3370
3371# https://learn.microsoft.com/en-us/sql/t-sql/queries/hints-transact-sql-table?view=sql-server-ver16
3372class WithTableHint(Expression):
3373    arg_types = {"expressions": True}
3374
3375
3376# https://dev.mysql.com/doc/refman/8.0/en/index-hints.html
3377class IndexTableHint(Expression):
3378    arg_types = {"this": True, "expressions": False, "target": False}
3379
3380
3381# https://docs.snowflake.com/en/sql-reference/constructs/at-before
3382class HistoricalData(Expression):
3383    arg_types = {"this": True, "kind": True, "expression": True}
3384
3385
3386# https://docs.snowflake.com/en/sql-reference/sql/put
3387class Put(Expression):
3388    arg_types = {"this": True, "target": True, "properties": False}
3389
3390
3391# https://docs.snowflake.com/en/sql-reference/sql/get
3392class Get(Expression):
3393    arg_types = {"this": True, "target": True, "properties": False}
3394
3395
3396class Table(Expression):
3397    arg_types = {
3398        "this": False,
3399        "alias": False,
3400        "db": False,
3401        "catalog": False,
3402        "laterals": False,
3403        "joins": False,
3404        "pivots": False,
3405        "hints": False,
3406        "system_time": False,
3407        "version": False,
3408        "format": False,
3409        "pattern": False,
3410        "ordinality": False,
3411        "when": False,
3412        "only": False,
3413        "partition": False,
3414        "changes": False,
3415        "rows_from": False,
3416        "sample": False,
3417    }
3418
3419    @property
3420    def name(self) -> str:
3421        if not self.this or isinstance(self.this, Func):
3422            return ""
3423        return self.this.name
3424
3425    @property
3426    def db(self) -> str:
3427        return self.text("db")
3428
3429    @property
3430    def catalog(self) -> str:
3431        return self.text("catalog")
3432
3433    @property
3434    def selects(self) -> t.List[Expression]:
3435        return []
3436
3437    @property
3438    def named_selects(self) -> t.List[str]:
3439        return []
3440
3441    @property
3442    def parts(self) -> t.List[Expression]:
3443        """Return the parts of a table in order catalog, db, table."""
3444        parts: t.List[Expression] = []
3445
3446        for arg in ("catalog", "db", "this"):
3447            part = self.args.get(arg)
3448
3449            if isinstance(part, Dot):
3450                parts.extend(part.flatten())
3451            elif isinstance(part, Expression):
3452                parts.append(part)
3453
3454        return parts
3455
3456    def to_column(self, copy: bool = True) -> Expression:
3457        parts = self.parts
3458        last_part = parts[-1]
3459
3460        if isinstance(last_part, Identifier):
3461            col: Expression = column(*reversed(parts[0:4]), fields=parts[4:], copy=copy)  # type: ignore
3462        else:
3463            # This branch will be reached if a function or array is wrapped in a `Table`
3464            col = last_part
3465
3466        alias = self.args.get("alias")
3467        if alias:
3468            col = alias_(col, alias.this, copy=copy)
3469
3470        return col
3471
3472
3473class SetOperation(Query):
3474    arg_types = {
3475        "with": False,
3476        "this": True,
3477        "expression": True,
3478        "distinct": False,
3479        "by_name": False,
3480        "side": False,
3481        "kind": False,
3482        "on": False,
3483        **QUERY_MODIFIERS,
3484    }
3485
3486    def select(
3487        self: S,
3488        *expressions: t.Optional[ExpOrStr],
3489        append: bool = True,
3490        dialect: DialectType = None,
3491        copy: bool = True,
3492        **opts,
3493    ) -> S:
3494        this = maybe_copy(self, copy)
3495        this.this.unnest().select(*expressions, append=append, dialect=dialect, copy=False, **opts)
3496        this.expression.unnest().select(
3497            *expressions, append=append, dialect=dialect, copy=False, **opts
3498        )
3499        return this
3500
3501    @property
3502    def named_selects(self) -> t.List[str]:
3503        return self.this.unnest().named_selects
3504
3505    @property
3506    def is_star(self) -> bool:
3507        return self.this.is_star or self.expression.is_star
3508
3509    @property
3510    def selects(self) -> t.List[Expression]:
3511        return self.this.unnest().selects
3512
3513    @property
3514    def left(self) -> Query:
3515        return self.this
3516
3517    @property
3518    def right(self) -> Query:
3519        return self.expression
3520
3521    @property
3522    def kind(self) -> str:
3523        return self.text("kind").upper()
3524
3525    @property
3526    def side(self) -> str:
3527        return self.text("side").upper()
3528
3529
3530class Union(SetOperation):
3531    pass
3532
3533
3534class Except(SetOperation):
3535    pass
3536
3537
3538class Intersect(SetOperation):
3539    pass
3540
3541
3542class Update(DML):
3543    arg_types = {
3544        "with": False,
3545        "this": False,
3546        "expressions": True,
3547        "from": False,
3548        "where": False,
3549        "returning": False,
3550        "order": False,
3551        "limit": False,
3552    }
3553
3554    def table(
3555        self, expression: ExpOrStr, dialect: DialectType = None, copy: bool = True, **opts
3556    ) -> Update:
3557        """
3558        Set the table to update.
3559
3560        Example:
3561            >>> Update().table("my_table").set_("x = 1").sql()
3562            'UPDATE my_table SET x = 1'
3563
3564        Args:
3565            expression : the SQL code strings to parse.
3566                If a `Table` instance is passed, this is used as-is.
3567                If another `Expression` instance is passed, it will be wrapped in a `Table`.
3568            dialect: the dialect used to parse the input expression.
3569            copy: if `False`, modify this expression instance in-place.
3570            opts: other options to use to parse the input expressions.
3571
3572        Returns:
3573            The modified Update expression.
3574        """
3575        return _apply_builder(
3576            expression=expression,
3577            instance=self,
3578            arg="this",
3579            into=Table,
3580            prefix=None,
3581            dialect=dialect,
3582            copy=copy,
3583            **opts,
3584        )
3585
3586    def set_(
3587        self,
3588        *expressions: ExpOrStr,
3589        append: bool = True,
3590        dialect: DialectType = None,
3591        copy: bool = True,
3592        **opts,
3593    ) -> Update:
3594        """
3595        Append to or set the SET expressions.
3596
3597        Example:
3598            >>> Update().table("my_table").set_("x = 1").sql()
3599            'UPDATE my_table SET x = 1'
3600
3601        Args:
3602            *expressions: the SQL code strings to parse.
3603                If `Expression` instance(s) are passed, they will be used as-is.
3604                Multiple expressions are combined with a comma.
3605            append: if `True`, add the new expressions to any existing SET expressions.
3606                Otherwise, this resets the expressions.
3607            dialect: the dialect used to parse the input expressions.
3608            copy: if `False`, modify this expression instance in-place.
3609            opts: other options to use to parse the input expressions.
3610        """
3611        return _apply_list_builder(
3612            *expressions,
3613            instance=self,
3614            arg="expressions",
3615            append=append,
3616            into=Expression,
3617            prefix=None,
3618            dialect=dialect,
3619            copy=copy,
3620            **opts,
3621        )
3622
3623    def where(
3624        self,
3625        *expressions: t.Optional[ExpOrStr],
3626        append: bool = True,
3627        dialect: DialectType = None,
3628        copy: bool = True,
3629        **opts,
3630    ) -> Select:
3631        """
3632        Append to or set the WHERE expressions.
3633
3634        Example:
3635            >>> Update().table("tbl").set_("x = 1").where("x = 'a' OR x < 'b'").sql()
3636            "UPDATE tbl SET x = 1 WHERE x = 'a' OR x < 'b'"
3637
3638        Args:
3639            *expressions: the SQL code strings to parse.
3640                If an `Expression` instance is passed, it will be used as-is.
3641                Multiple expressions are combined with an AND operator.
3642            append: if `True`, AND the new expressions to any existing expression.
3643                Otherwise, this resets the expression.
3644            dialect: the dialect used to parse the input expressions.
3645            copy: if `False`, modify this expression instance in-place.
3646            opts: other options to use to parse the input expressions.
3647
3648        Returns:
3649            Select: the modified expression.
3650        """
3651        return _apply_conjunction_builder(
3652            *expressions,
3653            instance=self,
3654            arg="where",
3655            append=append,
3656            into=Where,
3657            dialect=dialect,
3658            copy=copy,
3659            **opts,
3660        )
3661
3662    def from_(
3663        self,
3664        expression: t.Optional[ExpOrStr] = None,
3665        dialect: DialectType = None,
3666        copy: bool = True,
3667        **opts,
3668    ) -> Update:
3669        """
3670        Set the FROM expression.
3671
3672        Example:
3673            >>> Update().table("my_table").set_("x = 1").from_("baz").sql()
3674            'UPDATE my_table SET x = 1 FROM baz'
3675
3676        Args:
3677            expression : the SQL code strings to parse.
3678                If a `From` instance is passed, this is used as-is.
3679                If another `Expression` instance is passed, it will be wrapped in a `From`.
3680                If nothing is passed in then a from is not applied to the expression
3681            dialect: the dialect used to parse the input expression.
3682            copy: if `False`, modify this expression instance in-place.
3683            opts: other options to use to parse the input expressions.
3684
3685        Returns:
3686            The modified Update expression.
3687        """
3688        if not expression:
3689            return maybe_copy(self, copy)
3690
3691        return _apply_builder(
3692            expression=expression,
3693            instance=self,
3694            arg="from",
3695            into=From,
3696            prefix="FROM",
3697            dialect=dialect,
3698            copy=copy,
3699            **opts,
3700        )
3701
3702    def with_(
3703        self,
3704        alias: ExpOrStr,
3705        as_: ExpOrStr,
3706        recursive: t.Optional[bool] = None,
3707        materialized: t.Optional[bool] = None,
3708        append: bool = True,
3709        dialect: DialectType = None,
3710        copy: bool = True,
3711        **opts,
3712    ) -> Update:
3713        """
3714        Append to or set the common table expressions.
3715
3716        Example:
3717            >>> Update().table("my_table").set_("x = 1").from_("baz").with_("baz", "SELECT id FROM foo").sql()
3718            'WITH baz AS (SELECT id FROM foo) UPDATE my_table SET x = 1 FROM baz'
3719
3720        Args:
3721            alias: the SQL code string to parse as the table name.
3722                If an `Expression` instance is passed, this is used as-is.
3723            as_: the SQL code string to parse as the table expression.
3724                If an `Expression` instance is passed, it will be used as-is.
3725            recursive: set the RECURSIVE part of the expression. Defaults to `False`.
3726            materialized: set the MATERIALIZED part of the expression.
3727            append: if `True`, add to any existing expressions.
3728                Otherwise, this resets the expressions.
3729            dialect: the dialect used to parse the input expression.
3730            copy: if `False`, modify this expression instance in-place.
3731            opts: other options to use to parse the input expressions.
3732
3733        Returns:
3734            The modified expression.
3735        """
3736        return _apply_cte_builder(
3737            self,
3738            alias,
3739            as_,
3740            recursive=recursive,
3741            materialized=materialized,
3742            append=append,
3743            dialect=dialect,
3744            copy=copy,
3745            **opts,
3746        )
3747
3748
3749class Values(UDTF):
3750    arg_types = {"expressions": True, "alias": False}
3751
3752
3753class Var(Expression):
3754    pass
3755
3756
3757class Version(Expression):
3758    """
3759    Time travel, iceberg, bigquery etc
3760    https://trino.io/docs/current/connector/iceberg.html?highlight=snapshot#using-snapshots
3761    https://www.databricks.com/blog/2019/02/04/introducing-delta-time-travel-for-large-scale-data-lakes.html
3762    https://cloud.google.com/bigquery/docs/reference/standard-sql/query-syntax#for_system_time_as_of
3763    https://learn.microsoft.com/en-us/sql/relational-databases/tables/querying-data-in-a-system-versioned-temporal-table?view=sql-server-ver16
3764    this is either TIMESTAMP or VERSION
3765    kind is ("AS OF", "BETWEEN")
3766    """
3767
3768    arg_types = {"this": True, "kind": True, "expression": False}
3769
3770
3771class Schema(Expression):
3772    arg_types = {"this": False, "expressions": False}
3773
3774
3775# https://dev.mysql.com/doc/refman/8.0/en/select.html
3776# https://docs.oracle.com/en/database/oracle/oracle-database/19/sqlrf/SELECT.html
3777class Lock(Expression):
3778    arg_types = {"update": True, "expressions": False, "wait": False, "key": False}
3779
3780
3781class Select(Query):
3782    arg_types = {
3783        "with": False,
3784        "kind": False,
3785        "expressions": False,
3786        "hint": False,
3787        "distinct": False,
3788        "into": False,
3789        "from": False,
3790        "operation_modifiers": False,
3791        **QUERY_MODIFIERS,
3792    }
3793
3794    def from_(
3795        self, expression: ExpOrStr, dialect: DialectType = None, copy: bool = True, **opts
3796    ) -> Select:
3797        """
3798        Set the FROM expression.
3799
3800        Example:
3801            >>> Select().from_("tbl").select("x").sql()
3802            'SELECT x FROM tbl'
3803
3804        Args:
3805            expression : the SQL code strings to parse.
3806                If a `From` instance is passed, this is used as-is.
3807                If another `Expression` instance is passed, it will be wrapped in a `From`.
3808            dialect: the dialect used to parse the input expression.
3809            copy: if `False`, modify this expression instance in-place.
3810            opts: other options to use to parse the input expressions.
3811
3812        Returns:
3813            The modified Select expression.
3814        """
3815        return _apply_builder(
3816            expression=expression,
3817            instance=self,
3818            arg="from",
3819            into=From,
3820            prefix="FROM",
3821            dialect=dialect,
3822            copy=copy,
3823            **opts,
3824        )
3825
3826    def group_by(
3827        self,
3828        *expressions: t.Optional[ExpOrStr],
3829        append: bool = True,
3830        dialect: DialectType = None,
3831        copy: bool = True,
3832        **opts,
3833    ) -> Select:
3834        """
3835        Set the GROUP BY expression.
3836
3837        Example:
3838            >>> Select().from_("tbl").select("x", "COUNT(1)").group_by("x").sql()
3839            'SELECT x, COUNT(1) FROM tbl GROUP BY x'
3840
3841        Args:
3842            *expressions: the SQL code strings to parse.
3843                If a `Group` instance is passed, this is used as-is.
3844                If another `Expression` instance is passed, it will be wrapped in a `Group`.
3845                If nothing is passed in then a group by is not applied to the expression
3846            append: if `True`, add to any existing expressions.
3847                Otherwise, this flattens all the `Group` expression into a single expression.
3848            dialect: the dialect used to parse the input expression.
3849            copy: if `False`, modify this expression instance in-place.
3850            opts: other options to use to parse the input expressions.
3851
3852        Returns:
3853            The modified Select expression.
3854        """
3855        if not expressions:
3856            return self if not copy else self.copy()
3857
3858        return _apply_child_list_builder(
3859            *expressions,
3860            instance=self,
3861            arg="group",
3862            append=append,
3863            copy=copy,
3864            prefix="GROUP BY",
3865            into=Group,
3866            dialect=dialect,
3867            **opts,
3868        )
3869
3870    def sort_by(
3871        self,
3872        *expressions: t.Optional[ExpOrStr],
3873        append: bool = True,
3874        dialect: DialectType = None,
3875        copy: bool = True,
3876        **opts,
3877    ) -> Select:
3878        """
3879        Set the SORT BY expression.
3880
3881        Example:
3882            >>> Select().from_("tbl").select("x").sort_by("x DESC").sql(dialect="hive")
3883            'SELECT x FROM tbl SORT BY x DESC'
3884
3885        Args:
3886            *expressions: the SQL code strings to parse.
3887                If a `Group` instance is passed, this is used as-is.
3888                If another `Expression` instance is passed, it will be wrapped in a `SORT`.
3889            append: if `True`, add to any existing expressions.
3890                Otherwise, this flattens all the `Order` expression into a single expression.
3891            dialect: the dialect used to parse the input expression.
3892            copy: if `False`, modify this expression instance in-place.
3893            opts: other options to use to parse the input expressions.
3894
3895        Returns:
3896            The modified Select expression.
3897        """
3898        return _apply_child_list_builder(
3899            *expressions,
3900            instance=self,
3901            arg="sort",
3902            append=append,
3903            copy=copy,
3904            prefix="SORT BY",
3905            into=Sort,
3906            dialect=dialect,
3907            **opts,
3908        )
3909
3910    def cluster_by(
3911        self,
3912        *expressions: t.Optional[ExpOrStr],
3913        append: bool = True,
3914        dialect: DialectType = None,
3915        copy: bool = True,
3916        **opts,
3917    ) -> Select:
3918        """
3919        Set the CLUSTER BY expression.
3920
3921        Example:
3922            >>> Select().from_("tbl").select("x").cluster_by("x DESC").sql(dialect="hive")
3923            'SELECT x FROM tbl CLUSTER BY x DESC'
3924
3925        Args:
3926            *expressions: the SQL code strings to parse.
3927                If a `Group` instance is passed, this is used as-is.
3928                If another `Expression` instance is passed, it will be wrapped in a `Cluster`.
3929            append: if `True`, add to any existing expressions.
3930                Otherwise, this flattens all the `Order` expression into a single expression.
3931            dialect: the dialect used to parse the input expression.
3932            copy: if `False`, modify this expression instance in-place.
3933            opts: other options to use to parse the input expressions.
3934
3935        Returns:
3936            The modified Select expression.
3937        """
3938        return _apply_child_list_builder(
3939            *expressions,
3940            instance=self,
3941            arg="cluster",
3942            append=append,
3943            copy=copy,
3944            prefix="CLUSTER BY",
3945            into=Cluster,
3946            dialect=dialect,
3947            **opts,
3948        )
3949
3950    def select(
3951        self,
3952        *expressions: t.Optional[ExpOrStr],
3953        append: bool = True,
3954        dialect: DialectType = None,
3955        copy: bool = True,
3956        **opts,
3957    ) -> Select:
3958        return _apply_list_builder(
3959            *expressions,
3960            instance=self,
3961            arg="expressions",
3962            append=append,
3963            dialect=dialect,
3964            into=Expression,
3965            copy=copy,
3966            **opts,
3967        )
3968
3969    def lateral(
3970        self,
3971        *expressions: t.Optional[ExpOrStr],
3972        append: bool = True,
3973        dialect: DialectType = None,
3974        copy: bool = True,
3975        **opts,
3976    ) -> Select:
3977        """
3978        Append to or set the LATERAL expressions.
3979
3980        Example:
3981            >>> Select().select("x").lateral("OUTER explode(y) tbl2 AS z").from_("tbl").sql()
3982            'SELECT x FROM tbl LATERAL VIEW OUTER EXPLODE(y) tbl2 AS z'
3983
3984        Args:
3985            *expressions: the SQL code strings to parse.
3986                If an `Expression` instance is passed, it will be used as-is.
3987            append: if `True`, add to any existing expressions.
3988                Otherwise, this resets the expressions.
3989            dialect: the dialect used to parse the input expressions.
3990            copy: if `False`, modify this expression instance in-place.
3991            opts: other options to use to parse the input expressions.
3992
3993        Returns:
3994            The modified Select expression.
3995        """
3996        return _apply_list_builder(
3997            *expressions,
3998            instance=self,
3999            arg="laterals",
4000            append=append,
4001            into=Lateral,
4002            prefix="LATERAL VIEW",
4003            dialect=dialect,
4004            copy=copy,
4005            **opts,
4006        )
4007
4008    def join(
4009        self,
4010        expression: ExpOrStr,
4011        on: t.Optional[ExpOrStr] = None,
4012        using: t.Optional[ExpOrStr | t.Collection[ExpOrStr]] = None,
4013        append: bool = True,
4014        join_type: t.Optional[str] = None,
4015        join_alias: t.Optional[Identifier | str] = None,
4016        dialect: DialectType = None,
4017        copy: bool = True,
4018        **opts,
4019    ) -> Select:
4020        """
4021        Append to or set the JOIN expressions.
4022
4023        Example:
4024            >>> Select().select("*").from_("tbl").join("tbl2", on="tbl1.y = tbl2.y").sql()
4025            'SELECT * FROM tbl JOIN tbl2 ON tbl1.y = tbl2.y'
4026
4027            >>> Select().select("1").from_("a").join("b", using=["x", "y", "z"]).sql()
4028            'SELECT 1 FROM a JOIN b USING (x, y, z)'
4029
4030            Use `join_type` to change the type of join:
4031
4032            >>> Select().select("*").from_("tbl").join("tbl2", on="tbl1.y = tbl2.y", join_type="left outer").sql()
4033            'SELECT * FROM tbl LEFT OUTER JOIN tbl2 ON tbl1.y = tbl2.y'
4034
4035        Args:
4036            expression: the SQL code string to parse.
4037                If an `Expression` instance is passed, it will be used as-is.
4038            on: optionally specify the join "on" criteria as a SQL string.
4039                If an `Expression` instance is passed, it will be used as-is.
4040            using: optionally specify the join "using" criteria as a SQL string.
4041                If an `Expression` instance is passed, it will be used as-is.
4042            append: if `True`, add to any existing expressions.
4043                Otherwise, this resets the expressions.
4044            join_type: if set, alter the parsed join type.
4045            join_alias: an optional alias for the joined source.
4046            dialect: the dialect used to parse the input expressions.
4047            copy: if `False`, modify this expression instance in-place.
4048            opts: other options to use to parse the input expressions.
4049
4050        Returns:
4051            Select: the modified expression.
4052        """
4053        parse_args: t.Dict[str, t.Any] = {"dialect": dialect, **opts}
4054
4055        try:
4056            expression = maybe_parse(expression, into=Join, prefix="JOIN", **parse_args)
4057        except ParseError:
4058            expression = maybe_parse(expression, into=(Join, Expression), **parse_args)
4059
4060        join = expression if isinstance(expression, Join) else Join(this=expression)
4061
4062        if isinstance(join.this, Select):
4063            join.this.replace(join.this.subquery())
4064
4065        if join_type:
4066            method: t.Optional[Token]
4067            side: t.Optional[Token]
4068            kind: t.Optional[Token]
4069
4070            method, side, kind = maybe_parse(join_type, into="JOIN_TYPE", **parse_args)  # type: ignore
4071
4072            if method:
4073                join.set("method", method.text)
4074            if side:
4075                join.set("side", side.text)
4076            if kind:
4077                join.set("kind", kind.text)
4078
4079        if on:
4080            on = and_(*ensure_list(on), dialect=dialect, copy=copy, **opts)
4081            join.set("on", on)
4082
4083        if using:
4084            join = _apply_list_builder(
4085                *ensure_list(using),
4086                instance=join,
4087                arg="using",
4088                append=append,
4089                copy=copy,
4090                into=Identifier,
4091                **opts,
4092            )
4093
4094        if join_alias:
4095            join.set("this", alias_(join.this, join_alias, table=True))
4096
4097        return _apply_list_builder(
4098            join,
4099            instance=self,
4100            arg="joins",
4101            append=append,
4102            copy=copy,
4103            **opts,
4104        )
4105
4106    def having(
4107        self,
4108        *expressions: t.Optional[ExpOrStr],
4109        append: bool = True,
4110        dialect: DialectType = None,
4111        copy: bool = True,
4112        **opts,
4113    ) -> Select:
4114        """
4115        Append to or set the HAVING expressions.
4116
4117        Example:
4118            >>> Select().select("x", "COUNT(y)").from_("tbl").group_by("x").having("COUNT(y) > 3").sql()
4119            'SELECT x, COUNT(y) FROM tbl GROUP BY x HAVING COUNT(y) > 3'
4120
4121        Args:
4122            *expressions: the SQL code strings to parse.
4123                If an `Expression` instance is passed, it will be used as-is.
4124                Multiple expressions are combined with an AND operator.
4125            append: if `True`, AND the new expressions to any existing expression.
4126                Otherwise, this resets the expression.
4127            dialect: the dialect used to parse the input expressions.
4128            copy: if `False`, modify this expression instance in-place.
4129            opts: other options to use to parse the input expressions.
4130
4131        Returns:
4132            The modified Select expression.
4133        """
4134        return _apply_conjunction_builder(
4135            *expressions,
4136            instance=self,
4137            arg="having",
4138            append=append,
4139            into=Having,
4140            dialect=dialect,
4141            copy=copy,
4142            **opts,
4143        )
4144
4145    def window(
4146        self,
4147        *expressions: t.Optional[ExpOrStr],
4148        append: bool = True,
4149        dialect: DialectType = None,
4150        copy: bool = True,
4151        **opts,
4152    ) -> Select:
4153        return _apply_list_builder(
4154            *expressions,
4155            instance=self,
4156            arg="windows",
4157            append=append,
4158            into=Window,
4159            dialect=dialect,
4160            copy=copy,
4161            **opts,
4162        )
4163
4164    def qualify(
4165        self,
4166        *expressions: t.Optional[ExpOrStr],
4167        append: bool = True,
4168        dialect: DialectType = None,
4169        copy: bool = True,
4170        **opts,
4171    ) -> Select:
4172        return _apply_conjunction_builder(
4173            *expressions,
4174            instance=self,
4175            arg="qualify",
4176            append=append,
4177            into=Qualify,
4178            dialect=dialect,
4179            copy=copy,
4180            **opts,
4181        )
4182
4183    def distinct(
4184        self, *ons: t.Optional[ExpOrStr], distinct: bool = True, copy: bool = True
4185    ) -> Select:
4186        """
4187        Set the OFFSET expression.
4188
4189        Example:
4190            >>> Select().from_("tbl").select("x").distinct().sql()
4191            'SELECT DISTINCT x FROM tbl'
4192
4193        Args:
4194            ons: the expressions to distinct on
4195            distinct: whether the Select should be distinct
4196            copy: if `False`, modify this expression instance in-place.
4197
4198        Returns:
4199            Select: the modified expression.
4200        """
4201        instance = maybe_copy(self, copy)
4202        on = Tuple(expressions=[maybe_parse(on, copy=copy) for on in ons if on]) if ons else None
4203        instance.set("distinct", Distinct(on=on) if distinct else None)
4204        return instance
4205
4206    def ctas(
4207        self,
4208        table: ExpOrStr,
4209        properties: t.Optional[t.Dict] = None,
4210        dialect: DialectType = None,
4211        copy: bool = True,
4212        **opts,
4213    ) -> Create:
4214        """
4215        Convert this expression to a CREATE TABLE AS statement.
4216
4217        Example:
4218            >>> Select().select("*").from_("tbl").ctas("x").sql()
4219            'CREATE TABLE x AS SELECT * FROM tbl'
4220
4221        Args:
4222            table: the SQL code string to parse as the table name.
4223                If another `Expression` instance is passed, it will be used as-is.
4224            properties: an optional mapping of table properties
4225            dialect: the dialect used to parse the input table.
4226            copy: if `False`, modify this expression instance in-place.
4227            opts: other options to use to parse the input table.
4228
4229        Returns:
4230            The new Create expression.
4231        """
4232        instance = maybe_copy(self, copy)
4233        table_expression = maybe_parse(table, into=Table, dialect=dialect, **opts)
4234
4235        properties_expression = None
4236        if properties:
4237            properties_expression = Properties.from_dict(properties)
4238
4239        return Create(
4240            this=table_expression,
4241            kind="TABLE",
4242            expression=instance,
4243            properties=properties_expression,
4244        )
4245
4246    def lock(self, update: bool = True, copy: bool = True) -> Select:
4247        """
4248        Set the locking read mode for this expression.
4249
4250        Examples:
4251            >>> Select().select("x").from_("tbl").where("x = 'a'").lock().sql("mysql")
4252            "SELECT x FROM tbl WHERE x = 'a' FOR UPDATE"
4253
4254            >>> Select().select("x").from_("tbl").where("x = 'a'").lock(update=False).sql("mysql")
4255            "SELECT x FROM tbl WHERE x = 'a' FOR SHARE"
4256
4257        Args:
4258            update: if `True`, the locking type will be `FOR UPDATE`, else it will be `FOR SHARE`.
4259            copy: if `False`, modify this expression instance in-place.
4260
4261        Returns:
4262            The modified expression.
4263        """
4264        inst = maybe_copy(self, copy)
4265        inst.set("locks", [Lock(update=update)])
4266
4267        return inst
4268
4269    def hint(self, *hints: ExpOrStr, dialect: DialectType = None, copy: bool = True) -> Select:
4270        """
4271        Set hints for this expression.
4272
4273        Examples:
4274            >>> Select().select("x").from_("tbl").hint("BROADCAST(y)").sql(dialect="spark")
4275            'SELECT /*+ BROADCAST(y) */ x FROM tbl'
4276
4277        Args:
4278            hints: The SQL code strings to parse as the hints.
4279                If an `Expression` instance is passed, it will be used as-is.
4280            dialect: The dialect used to parse the hints.
4281            copy: If `False`, modify this expression instance in-place.
4282
4283        Returns:
4284            The modified expression.
4285        """
4286        inst = maybe_copy(self, copy)
4287        inst.set(
4288            "hint", Hint(expressions=[maybe_parse(h, copy=copy, dialect=dialect) for h in hints])
4289        )
4290
4291        return inst
4292
4293    @property
4294    def named_selects(self) -> t.List[str]:
4295        return [e.output_name for e in self.expressions if e.alias_or_name]
4296
4297    @property
4298    def is_star(self) -> bool:
4299        return any(expression.is_star for expression in self.expressions)
4300
4301    @property
4302    def selects(self) -> t.List[Expression]:
4303        return self.expressions
4304
4305
4306UNWRAPPED_QUERIES = (Select, SetOperation)
4307
4308
4309class Subquery(DerivedTable, Query):
4310    arg_types = {
4311        "this": True,
4312        "alias": False,
4313        "with": False,
4314        **QUERY_MODIFIERS,
4315    }
4316
4317    def unnest(self):
4318        """Returns the first non subquery."""
4319        expression = self
4320        while isinstance(expression, Subquery):
4321            expression = expression.this
4322        return expression
4323
4324    def unwrap(self) -> Subquery:
4325        expression = self
4326        while expression.same_parent and expression.is_wrapper:
4327            expression = t.cast(Subquery, expression.parent)
4328        return expression
4329
4330    def select(
4331        self,
4332        *expressions: t.Optional[ExpOrStr],
4333        append: bool = True,
4334        dialect: DialectType = None,
4335        copy: bool = True,
4336        **opts,
4337    ) -> Subquery:
4338        this = maybe_copy(self, copy)
4339        this.unnest().select(*expressions, append=append, dialect=dialect, copy=False, **opts)
4340        return this
4341
4342    @property
4343    def is_wrapper(self) -> bool:
4344        """
4345        Whether this Subquery acts as a simple wrapper around another expression.
4346
4347        SELECT * FROM (((SELECT * FROM t)))
4348                      ^
4349                      This corresponds to a "wrapper" Subquery node
4350        """
4351        return all(v is None for k, v in self.args.items() if k != "this")
4352
4353    @property
4354    def is_star(self) -> bool:
4355        return self.this.is_star
4356
4357    @property
4358    def output_name(self) -> str:
4359        return self.alias
4360
4361
4362class TableSample(Expression):
4363    arg_types = {
4364        "expressions": False,
4365        "method": False,
4366        "bucket_numerator": False,
4367        "bucket_denominator": False,
4368        "bucket_field": False,
4369        "percent": False,
4370        "rows": False,
4371        "size": False,
4372        "seed": False,
4373    }
4374
4375
4376class Tag(Expression):
4377    """Tags are used for generating arbitrary sql like SELECT <span>x</span>."""
4378
4379    arg_types = {
4380        "this": False,
4381        "prefix": False,
4382        "postfix": False,
4383    }
4384
4385
4386# Represents both the standard SQL PIVOT operator and DuckDB's "simplified" PIVOT syntax
4387# https://duckdb.org/docs/sql/statements/pivot
4388class Pivot(Expression):
4389    arg_types = {
4390        "this": False,
4391        "alias": False,
4392        "expressions": False,
4393        "fields": False,
4394        "unpivot": False,
4395        "using": False,
4396        "group": False,
4397        "columns": False,
4398        "include_nulls": False,
4399        "default_on_null": False,
4400        "into": False,
4401    }
4402
4403    @property
4404    def unpivot(self) -> bool:
4405        return bool(self.args.get("unpivot"))
4406
4407    @property
4408    def fields(self) -> t.List[Expression]:
4409        return self.args.get("fields", [])
4410
4411
4412# https://duckdb.org/docs/sql/statements/unpivot#simplified-unpivot-syntax
4413# UNPIVOT ... INTO [NAME <col_name> VALUE <col_value>][...,]
4414class UnpivotColumns(Expression):
4415    arg_types = {"this": True, "expressions": True}
4416
4417
4418class Window(Condition):
4419    arg_types = {
4420        "this": True,
4421        "partition_by": False,
4422        "order": False,
4423        "spec": False,
4424        "alias": False,
4425        "over": False,
4426        "first": False,
4427    }
4428
4429
4430class WindowSpec(Expression):
4431    arg_types = {
4432        "kind": False,
4433        "start": False,
4434        "start_side": False,
4435        "end": False,
4436        "end_side": False,
4437        "exclude": False,
4438    }
4439
4440
4441class PreWhere(Expression):
4442    pass
4443
4444
4445class Where(Expression):
4446    pass
4447
4448
4449class Star(Expression):
4450    arg_types = {"except": False, "replace": False, "rename": False}
4451
4452    @property
4453    def name(self) -> str:
4454        return "*"
4455
4456    @property
4457    def output_name(self) -> str:
4458        return self.name
4459
4460
4461class Parameter(Condition):
4462    arg_types = {"this": True, "expression": False}
4463
4464
4465class SessionParameter(Condition):
4466    arg_types = {"this": True, "kind": False}
4467
4468
4469# https://www.databricks.com/blog/parameterized-queries-pyspark
4470class Placeholder(Condition):
4471    arg_types = {"this": False, "kind": False, "widget": False}
4472
4473    @property
4474    def name(self) -> str:
4475        return self.this or "?"
4476
4477
4478class Null(Condition):
4479    arg_types: t.Dict[str, t.Any] = {}
4480
4481    @property
4482    def name(self) -> str:
4483        return "NULL"
4484
4485    def to_py(self) -> Lit[None]:
4486        return None
4487
4488
4489class Boolean(Condition):
4490    def to_py(self) -> bool:
4491        return self.this
4492
4493
4494class DataTypeParam(Expression):
4495    arg_types = {"this": True, "expression": False}
4496
4497    @property
4498    def name(self) -> str:
4499        return self.this.name
4500
4501
4502# The `nullable` arg is helpful when transpiling types from other dialects to ClickHouse, which
4503# assumes non-nullable types by default. Values `None` and `True` mean the type is nullable.
4504class DataType(Expression):
4505    arg_types = {
4506        "this": True,
4507        "expressions": False,
4508        "nested": False,
4509        "values": False,
4510        "prefix": False,
4511        "kind": False,
4512        "nullable": False,
4513    }
4514
4515    class Type(AutoName):
4516        ARRAY = auto()
4517        AGGREGATEFUNCTION = auto()
4518        SIMPLEAGGREGATEFUNCTION = auto()
4519        BIGDECIMAL = auto()
4520        BIGINT = auto()
4521        BIGSERIAL = auto()
4522        BINARY = auto()
4523        BIT = auto()
4524        BLOB = auto()
4525        BOOLEAN = auto()
4526        BPCHAR = auto()
4527        CHAR = auto()
4528        DATE = auto()
4529        DATE32 = auto()
4530        DATEMULTIRANGE = auto()
4531        DATERANGE = auto()
4532        DATETIME = auto()
4533        DATETIME2 = auto()
4534        DATETIME64 = auto()
4535        DECIMAL = auto()
4536        DECIMAL32 = auto()
4537        DECIMAL64 = auto()
4538        DECIMAL128 = auto()
4539        DECIMAL256 = auto()
4540        DOUBLE = auto()
4541        DYNAMIC = auto()
4542        ENUM = auto()
4543        ENUM8 = auto()
4544        ENUM16 = auto()
4545        FIXEDSTRING = auto()
4546        FLOAT = auto()
4547        GEOGRAPHY = auto()
4548        GEOMETRY = auto()
4549        POINT = auto()
4550        RING = auto()
4551        LINESTRING = auto()
4552        MULTILINESTRING = auto()
4553        POLYGON = auto()
4554        MULTIPOLYGON = auto()
4555        HLLSKETCH = auto()
4556        HSTORE = auto()
4557        IMAGE = auto()
4558        INET = auto()
4559        INT = auto()
4560        INT128 = auto()
4561        INT256 = auto()
4562        INT4MULTIRANGE = auto()
4563        INT4RANGE = auto()
4564        INT8MULTIRANGE = auto()
4565        INT8RANGE = auto()
4566        INTERVAL = auto()
4567        IPADDRESS = auto()
4568        IPPREFIX = auto()
4569        IPV4 = auto()
4570        IPV6 = auto()
4571        JSON = auto()
4572        JSONB = auto()
4573        LIST = auto()
4574        LONGBLOB = auto()
4575        LONGTEXT = auto()
4576        LOWCARDINALITY = auto()
4577        MAP = auto()
4578        MEDIUMBLOB = auto()
4579        MEDIUMINT = auto()
4580        MEDIUMTEXT = auto()
4581        MONEY = auto()
4582        NAME = auto()
4583        NCHAR = auto()
4584        NESTED = auto()
4585        NOTHING = auto()
4586        NULL = auto()
4587        NUMMULTIRANGE = auto()
4588        NUMRANGE = auto()
4589        NVARCHAR = auto()
4590        OBJECT = auto()
4591        RANGE = auto()
4592        ROWVERSION = auto()
4593        SERIAL = auto()
4594        SET = auto()
4595        SMALLDATETIME = auto()
4596        SMALLINT = auto()
4597        SMALLMONEY = auto()
4598        SMALLSERIAL = auto()
4599        STRUCT = auto()
4600        SUPER = auto()
4601        TEXT = auto()
4602        TINYBLOB = auto()
4603        TINYTEXT = auto()
4604        TIME = auto()
4605        TIMETZ = auto()
4606        TIMESTAMP = auto()
4607        TIMESTAMPNTZ = auto()
4608        TIMESTAMPLTZ = auto()
4609        TIMESTAMPTZ = auto()
4610        TIMESTAMP_S = auto()
4611        TIMESTAMP_MS = auto()
4612        TIMESTAMP_NS = auto()
4613        TINYINT = auto()
4614        TSMULTIRANGE = auto()
4615        TSRANGE = auto()
4616        TSTZMULTIRANGE = auto()
4617        TSTZRANGE = auto()
4618        UBIGINT = auto()
4619        UINT = auto()
4620        UINT128 = auto()
4621        UINT256 = auto()
4622        UMEDIUMINT = auto()
4623        UDECIMAL = auto()
4624        UDOUBLE = auto()
4625        UNION = auto()
4626        UNKNOWN = auto()  # Sentinel value, useful for type annotation
4627        USERDEFINED = "USER-DEFINED"
4628        USMALLINT = auto()
4629        UTINYINT = auto()
4630        UUID = auto()
4631        VARBINARY = auto()
4632        VARCHAR = auto()
4633        VARIANT = auto()
4634        VECTOR = auto()
4635        XML = auto()
4636        YEAR = auto()
4637        TDIGEST = auto()
4638
4639    STRUCT_TYPES = {
4640        Type.NESTED,
4641        Type.OBJECT,
4642        Type.STRUCT,
4643        Type.UNION,
4644    }
4645
4646    ARRAY_TYPES = {
4647        Type.ARRAY,
4648        Type.LIST,
4649    }
4650
4651    NESTED_TYPES = {
4652        *STRUCT_TYPES,
4653        *ARRAY_TYPES,
4654        Type.MAP,
4655    }
4656
4657    TEXT_TYPES = {
4658        Type.CHAR,
4659        Type.NCHAR,
4660        Type.NVARCHAR,
4661        Type.TEXT,
4662        Type.VARCHAR,
4663        Type.NAME,
4664    }
4665
4666    SIGNED_INTEGER_TYPES = {
4667        Type.BIGINT,
4668        Type.INT,
4669        Type.INT128,
4670        Type.INT256,
4671        Type.MEDIUMINT,
4672        Type.SMALLINT,
4673        Type.TINYINT,
4674    }
4675
4676    UNSIGNED_INTEGER_TYPES = {
4677        Type.UBIGINT,
4678        Type.UINT,
4679        Type.UINT128,
4680        Type.UINT256,
4681        Type.UMEDIUMINT,
4682        Type.USMALLINT,
4683        Type.UTINYINT,
4684    }
4685
4686    INTEGER_TYPES = {
4687        *SIGNED_INTEGER_TYPES,
4688        *UNSIGNED_INTEGER_TYPES,
4689        Type.BIT,
4690    }
4691
4692    FLOAT_TYPES = {
4693        Type.DOUBLE,
4694        Type.FLOAT,
4695    }
4696
4697    REAL_TYPES = {
4698        *FLOAT_TYPES,
4699        Type.BIGDECIMAL,
4700        Type.DECIMAL,
4701        Type.DECIMAL32,
4702        Type.DECIMAL64,
4703        Type.DECIMAL128,
4704        Type.DECIMAL256,
4705        Type.MONEY,
4706        Type.SMALLMONEY,
4707        Type.UDECIMAL,
4708        Type.UDOUBLE,
4709    }
4710
4711    NUMERIC_TYPES = {
4712        *INTEGER_TYPES,
4713        *REAL_TYPES,
4714    }
4715
4716    TEMPORAL_TYPES = {
4717        Type.DATE,
4718        Type.DATE32,
4719        Type.DATETIME,
4720        Type.DATETIME2,
4721        Type.DATETIME64,
4722        Type.SMALLDATETIME,
4723        Type.TIME,
4724        Type.TIMESTAMP,
4725        Type.TIMESTAMPNTZ,
4726        Type.TIMESTAMPLTZ,
4727        Type.TIMESTAMPTZ,
4728        Type.TIMESTAMP_MS,
4729        Type.TIMESTAMP_NS,
4730        Type.TIMESTAMP_S,
4731        Type.TIMETZ,
4732    }
4733
4734    @classmethod
4735    def build(
4736        cls,
4737        dtype: DATA_TYPE,
4738        dialect: DialectType = None,
4739        udt: bool = False,
4740        copy: bool = True,
4741        **kwargs,
4742    ) -> DataType:
4743        """
4744        Constructs a DataType object.
4745
4746        Args:
4747            dtype: the data type of interest.
4748            dialect: the dialect to use for parsing `dtype`, in case it's a string.
4749            udt: when set to True, `dtype` will be used as-is if it can't be parsed into a
4750                DataType, thus creating a user-defined type.
4751            copy: whether to copy the data type.
4752            kwargs: additional arguments to pass in the constructor of DataType.
4753
4754        Returns:
4755            The constructed DataType object.
4756        """
4757        from sqlglot import parse_one
4758
4759        if isinstance(dtype, str):
4760            if dtype.upper() == "UNKNOWN":
4761                return DataType(this=DataType.Type.UNKNOWN, **kwargs)
4762
4763            try:
4764                data_type_exp = parse_one(
4765                    dtype, read=dialect, into=DataType, error_level=ErrorLevel.IGNORE
4766                )
4767            except ParseError:
4768                if udt:
4769                    return DataType(this=DataType.Type.USERDEFINED, kind=dtype, **kwargs)
4770                raise
4771        elif isinstance(dtype, (Identifier, Dot)) and udt:
4772            return DataType(this=DataType.Type.USERDEFINED, kind=dtype, **kwargs)
4773        elif isinstance(dtype, DataType.Type):
4774            data_type_exp = DataType(this=dtype)
4775        elif isinstance(dtype, DataType):
4776            return maybe_copy(dtype, copy)
4777        else:
4778            raise ValueError(f"Invalid data type: {type(dtype)}. Expected str or DataType.Type")
4779
4780        return DataType(**{**data_type_exp.args, **kwargs})
4781
4782    def is_type(self, *dtypes: DATA_TYPE, check_nullable: bool = False) -> bool:
4783        """
4784        Checks whether this DataType matches one of the provided data types. Nested types or precision
4785        will be compared using "structural equivalence" semantics, so e.g. array<int> != array<float>.
4786
4787        Args:
4788            dtypes: the data types to compare this DataType to.
4789            check_nullable: whether to take the NULLABLE type constructor into account for the comparison.
4790                If false, it means that NULLABLE<INT> is equivalent to INT.
4791
4792        Returns:
4793            True, if and only if there is a type in `dtypes` which is equal to this DataType.
4794        """
4795        self_is_nullable = self.args.get("nullable")
4796        for dtype in dtypes:
4797            other_type = DataType.build(dtype, copy=False, udt=True)
4798            other_is_nullable = other_type.args.get("nullable")
4799            if (
4800                other_type.expressions
4801                or (check_nullable and (self_is_nullable or other_is_nullable))
4802                or self.this == DataType.Type.USERDEFINED
4803                or other_type.this == DataType.Type.USERDEFINED
4804            ):
4805                matches = self == other_type
4806            else:
4807                matches = self.this == other_type.this
4808
4809            if matches:
4810                return True
4811        return False
4812
4813
4814# https://www.postgresql.org/docs/15/datatype-pseudo.html
4815class PseudoType(DataType):
4816    arg_types = {"this": True}
4817
4818
4819# https://www.postgresql.org/docs/15/datatype-oid.html
4820class ObjectIdentifier(DataType):
4821    arg_types = {"this": True}
4822
4823
4824# WHERE x <OP> EXISTS|ALL|ANY|SOME(SELECT ...)
4825class SubqueryPredicate(Predicate):
4826    pass
4827
4828
4829class All(SubqueryPredicate):
4830    pass
4831
4832
4833class Any(SubqueryPredicate):
4834    pass
4835
4836
4837# Commands to interact with the databases or engines. For most of the command
4838# expressions we parse whatever comes after the command's name as a string.
4839class Command(Expression):
4840    arg_types = {"this": True, "expression": False}
4841
4842
4843class Transaction(Expression):
4844    arg_types = {"this": False, "modes": False, "mark": False}
4845
4846
4847class Commit(Expression):
4848    arg_types = {"chain": False, "this": False, "durability": False}
4849
4850
4851class Rollback(Expression):
4852    arg_types = {"savepoint": False, "this": False}
4853
4854
4855class Alter(Expression):
4856    arg_types = {
4857        "this": True,
4858        "kind": True,
4859        "actions": True,
4860        "exists": False,
4861        "only": False,
4862        "options": False,
4863        "cluster": False,
4864        "not_valid": False,
4865    }
4866
4867    @property
4868    def kind(self) -> t.Optional[str]:
4869        kind = self.args.get("kind")
4870        return kind and kind.upper()
4871
4872    @property
4873    def actions(self) -> t.List[Expression]:
4874        return self.args.get("actions") or []
4875
4876
4877class Analyze(Expression):
4878    arg_types = {
4879        "kind": False,
4880        "this": False,
4881        "options": False,
4882        "mode": False,
4883        "partition": False,
4884        "expression": False,
4885        "properties": False,
4886    }
4887
4888
4889class AnalyzeStatistics(Expression):
4890    arg_types = {
4891        "kind": True,
4892        "option": False,
4893        "this": False,
4894        "expressions": False,
4895    }
4896
4897
4898class AnalyzeHistogram(Expression):
4899    arg_types = {
4900        "this": True,
4901        "expressions": True,
4902        "expression": False,
4903        "update_options": False,
4904    }
4905
4906
4907class AnalyzeSample(Expression):
4908    arg_types = {"kind": True, "sample": True}
4909
4910
4911class AnalyzeListChainedRows(Expression):
4912    arg_types = {"expression": False}
4913
4914
4915class AnalyzeDelete(Expression):
4916    arg_types = {"kind": False}
4917
4918
4919class AnalyzeWith(Expression):
4920    arg_types = {"expressions": True}
4921
4922
4923class AnalyzeValidate(Expression):
4924    arg_types = {
4925        "kind": True,
4926        "this": False,
4927        "expression": False,
4928    }
4929
4930
4931class AnalyzeColumns(Expression):
4932    pass
4933
4934
4935class UsingData(Expression):
4936    pass
4937
4938
4939class AddConstraint(Expression):
4940    arg_types = {"expressions": True}
4941
4942
4943class AddPartition(Expression):
4944    arg_types = {"this": True, "exists": False}
4945
4946
4947class AttachOption(Expression):
4948    arg_types = {"this": True, "expression": False}
4949
4950
4951class DropPartition(Expression):
4952    arg_types = {"expressions": True, "exists": False}
4953
4954
4955# https://clickhouse.com/docs/en/sql-reference/statements/alter/partition#replace-partition
4956class ReplacePartition(Expression):
4957    arg_types = {"expression": True, "source": True}
4958
4959
4960# Binary expressions like (ADD a b)
4961class Binary(Condition):
4962    arg_types = {"this": True, "expression": True}
4963
4964    @property
4965    def left(self) -> Expression:
4966        return self.this
4967
4968    @property
4969    def right(self) -> Expression:
4970        return self.expression
4971
4972
4973class Add(Binary):
4974    pass
4975
4976
4977class Connector(Binary):
4978    pass
4979
4980
4981class BitwiseAnd(Binary):
4982    pass
4983
4984
4985class BitwiseLeftShift(Binary):
4986    pass
4987
4988
4989class BitwiseOr(Binary):
4990    pass
4991
4992
4993class BitwiseRightShift(Binary):
4994    pass
4995
4996
4997class BitwiseXor(Binary):
4998    pass
4999
5000
5001class Div(Binary):
5002    arg_types = {"this": True, "expression": True, "typed": False, "safe": False}
5003
5004
5005class Overlaps(Binary):
5006    pass
5007
5008
5009class Dot(Binary):
5010    @property
5011    def is_star(self) -> bool:
5012        return self.expression.is_star
5013
5014    @property
5015    def name(self) -> str:
5016        return self.expression.name
5017
5018    @property
5019    def output_name(self) -> str:
5020        return self.name
5021
5022    @classmethod
5023    def build(self, expressions: t.Sequence[Expression]) -> Dot:
5024        """Build a Dot object with a sequence of expressions."""
5025        if len(expressions) < 2:
5026            raise ValueError("Dot requires >= 2 expressions.")
5027
5028        return t.cast(Dot, reduce(lambda x, y: Dot(this=x, expression=y), expressions))
5029
5030    @property
5031    def parts(self) -> t.List[Expression]:
5032        """Return the parts of a table / column in order catalog, db, table."""
5033        this, *parts = self.flatten()
5034
5035        parts.reverse()
5036
5037        for arg in COLUMN_PARTS:
5038            part = this.args.get(arg)
5039
5040            if isinstance(part, Expression):
5041                parts.append(part)
5042
5043        parts.reverse()
5044        return parts
5045
5046
5047DATA_TYPE = t.Union[str, Identifier, Dot, DataType, DataType.Type]
5048
5049
5050class DPipe(Binary):
5051    arg_types = {"this": True, "expression": True, "safe": False}
5052
5053
5054class EQ(Binary, Predicate):
5055    pass
5056
5057
5058class NullSafeEQ(Binary, Predicate):
5059    pass
5060
5061
5062class NullSafeNEQ(Binary, Predicate):
5063    pass
5064
5065
5066# Represents e.g. := in DuckDB which is mostly used for setting parameters
5067class PropertyEQ(Binary):
5068    pass
5069
5070
5071class Distance(Binary):
5072    pass
5073
5074
5075class Escape(Binary):
5076    pass
5077
5078
5079class Glob(Binary, Predicate):
5080    pass
5081
5082
5083class GT(Binary, Predicate):
5084    pass
5085
5086
5087class GTE(Binary, Predicate):
5088    pass
5089
5090
5091class ILike(Binary, Predicate):
5092    pass
5093
5094
5095class ILikeAny(Binary, Predicate):
5096    pass
5097
5098
5099class IntDiv(Binary):
5100    pass
5101
5102
5103class Is(Binary, Predicate):
5104    pass
5105
5106
5107class Kwarg(Binary):
5108    """Kwarg in special functions like func(kwarg => y)."""
5109
5110
5111class Like(Binary, Predicate):
5112    pass
5113
5114
5115class LikeAny(Binary, Predicate):
5116    pass
5117
5118
5119class LT(Binary, Predicate):
5120    pass
5121
5122
5123class LTE(Binary, Predicate):
5124    pass
5125
5126
5127class Mod(Binary):
5128    pass
5129
5130
5131class Mul(Binary):
5132    pass
5133
5134
5135class NEQ(Binary, Predicate):
5136    pass
5137
5138
5139# https://www.postgresql.org/docs/current/ddl-schemas.html#DDL-SCHEMAS-PATH
5140class Operator(Binary):
5141    arg_types = {"this": True, "operator": True, "expression": True}
5142
5143
5144class SimilarTo(Binary, Predicate):
5145    pass
5146
5147
5148class Slice(Binary):
5149    arg_types = {"this": False, "expression": False}
5150
5151
5152class Sub(Binary):
5153    pass
5154
5155
5156# Unary Expressions
5157# (NOT a)
5158class Unary(Condition):
5159    pass
5160
5161
5162class BitwiseNot(Unary):
5163    pass
5164
5165
5166class Not(Unary):
5167    pass
5168
5169
5170class Paren(Unary):
5171    @property
5172    def output_name(self) -> str:
5173        return self.this.name
5174
5175
5176class Neg(Unary):
5177    def to_py(self) -> int | Decimal:
5178        if self.is_number:
5179            return self.this.to_py() * -1
5180        return super().to_py()
5181
5182
5183class Alias(Expression):
5184    arg_types = {"this": True, "alias": False}
5185
5186    @property
5187    def output_name(self) -> str:
5188        return self.alias
5189
5190
5191# BigQuery requires the UNPIVOT column list aliases to be either strings or ints, but
5192# other dialects require identifiers. This enables us to transpile between them easily.
5193class PivotAlias(Alias):
5194    pass
5195
5196
5197# Represents Snowflake's ANY [ ORDER BY ... ] syntax
5198# https://docs.snowflake.com/en/sql-reference/constructs/pivot
5199class PivotAny(Expression):
5200    arg_types = {"this": False}
5201
5202
5203class Aliases(Expression):
5204    arg_types = {"this": True, "expressions": True}
5205
5206    @property
5207    def aliases(self):
5208        return self.expressions
5209
5210
5211# https://docs.aws.amazon.com/redshift/latest/dg/query-super.html
5212class AtIndex(Expression):
5213    arg_types = {"this": True, "expression": True}
5214
5215
5216class AtTimeZone(Expression):
5217    arg_types = {"this": True, "zone": True}
5218
5219
5220class FromTimeZone(Expression):
5221    arg_types = {"this": True, "zone": True}
5222
5223
5224class FormatPhrase(Expression):
5225    """Format override for a column in Teradata.
5226    Can be expanded to additional dialects as needed
5227
5228    https://docs.teradata.com/r/Enterprise_IntelliFlex_VMware/SQL-Data-Types-and-Literals/Data-Type-Formats-and-Format-Phrases/FORMAT
5229    """
5230
5231    arg_types = {"this": True, "format": True}
5232
5233
5234class Between(Predicate):
5235    arg_types = {"this": True, "low": True, "high": True, "symmetric": False}
5236
5237
5238class Bracket(Condition):
5239    # https://cloud.google.com/bigquery/docs/reference/standard-sql/operators#array_subscript_operator
5240    arg_types = {
5241        "this": True,
5242        "expressions": True,
5243        "offset": False,
5244        "safe": False,
5245        "returns_list_for_maps": False,
5246    }
5247
5248    @property
5249    def output_name(self) -> str:
5250        if len(self.expressions) == 1:
5251            return self.expressions[0].output_name
5252
5253        return super().output_name
5254
5255
5256class Distinct(Expression):
5257    arg_types = {"expressions": False, "on": False}
5258
5259
5260class In(Predicate):
5261    arg_types = {
5262        "this": True,
5263        "expressions": False,
5264        "query": False,
5265        "unnest": False,
5266        "field": False,
5267        "is_global": False,
5268    }
5269
5270
5271# https://cloud.google.com/bigquery/docs/reference/standard-sql/procedural-language#for-in
5272class ForIn(Expression):
5273    arg_types = {"this": True, "expression": True}
5274
5275
5276class TimeUnit(Expression):
5277    """Automatically converts unit arg into a var."""
5278
5279    arg_types = {"unit": False}
5280
5281    UNABBREVIATED_UNIT_NAME = {
5282        "D": "DAY",
5283        "H": "HOUR",
5284        "M": "MINUTE",
5285        "MS": "MILLISECOND",
5286        "NS": "NANOSECOND",
5287        "Q": "QUARTER",
5288        "S": "SECOND",
5289        "US": "MICROSECOND",
5290        "W": "WEEK",
5291        "Y": "YEAR",
5292    }
5293
5294    VAR_LIKE = (Column, Literal, Var)
5295
5296    def __init__(self, **args):
5297        unit = args.get("unit")
5298        if isinstance(unit, self.VAR_LIKE):
5299            args["unit"] = Var(
5300                this=(self.UNABBREVIATED_UNIT_NAME.get(unit.name) or unit.name).upper()
5301            )
5302        elif isinstance(unit, Week):
5303            unit.set("this", Var(this=unit.this.name.upper()))
5304
5305        super().__init__(**args)
5306
5307    @property
5308    def unit(self) -> t.Optional[Var | IntervalSpan]:
5309        return self.args.get("unit")
5310
5311
5312class IntervalOp(TimeUnit):
5313    arg_types = {"unit": False, "expression": True}
5314
5315    def interval(self):
5316        return Interval(
5317            this=self.expression.copy(),
5318            unit=self.unit.copy() if self.unit else None,
5319        )
5320
5321
5322# https://www.oracletutorial.com/oracle-basics/oracle-interval/
5323# https://trino.io/docs/current/language/types.html#interval-day-to-second
5324# https://docs.databricks.com/en/sql/language-manual/data-types/interval-type.html
5325class IntervalSpan(DataType):
5326    arg_types = {"this": True, "expression": True}
5327
5328
5329class Interval(TimeUnit):
5330    arg_types = {"this": False, "unit": False}
5331
5332
5333class IgnoreNulls(Expression):
5334    pass
5335
5336
5337class RespectNulls(Expression):
5338    pass
5339
5340
5341# https://cloud.google.com/bigquery/docs/reference/standard-sql/aggregate-function-calls#max_min_clause
5342class HavingMax(Expression):
5343    arg_types = {"this": True, "expression": True, "max": True}
5344
5345
5346# Functions
5347class Func(Condition):
5348    """
5349    The base class for all function expressions.
5350
5351    Attributes:
5352        is_var_len_args (bool): if set to True the last argument defined in arg_types will be
5353            treated as a variable length argument and the argument's value will be stored as a list.
5354        _sql_names (list): the SQL name (1st item in the list) and aliases (subsequent items) for this
5355            function expression. These values are used to map this node to a name during parsing as
5356            well as to provide the function's name during SQL string generation. By default the SQL
5357            name is set to the expression's class name transformed to snake case.
5358    """
5359
5360    is_var_len_args = False
5361
5362    @classmethod
5363    def from_arg_list(cls, args):
5364        if cls.is_var_len_args:
5365            all_arg_keys = list(cls.arg_types)
5366            # If this function supports variable length argument treat the last argument as such.
5367            non_var_len_arg_keys = all_arg_keys[:-1] if cls.is_var_len_args else all_arg_keys
5368            num_non_var = len(non_var_len_arg_keys)
5369
5370            args_dict = {arg_key: arg for arg, arg_key in zip(args, non_var_len_arg_keys)}
5371            args_dict[all_arg_keys[-1]] = args[num_non_var:]
5372        else:
5373            args_dict = {arg_key: arg for arg, arg_key in zip(args, cls.arg_types)}
5374
5375        return cls(**args_dict)
5376
5377    @classmethod
5378    def sql_names(cls):
5379        if cls is Func:
5380            raise NotImplementedError(
5381                "SQL name is only supported by concrete function implementations"
5382            )
5383        if "_sql_names" not in cls.__dict__:
5384            cls._sql_names = [camel_to_snake_case(cls.__name__)]
5385        return cls._sql_names
5386
5387    @classmethod
5388    def sql_name(cls):
5389        return cls.sql_names()[0]
5390
5391    @classmethod
5392    def default_parser_mappings(cls):
5393        return {name: cls.from_arg_list for name in cls.sql_names()}
5394
5395
5396class Typeof(Func):
5397    pass
5398
5399
5400class AggFunc(Func):
5401    pass
5402
5403
5404class BitwiseAndAgg(AggFunc):
5405    _sql_names = ["BIT_AND"]
5406
5407
5408class BitwiseOrAgg(AggFunc):
5409    _sql_names = ["BIT_OR"]
5410
5411
5412class BitwiseXorAgg(AggFunc):
5413    _sql_names = ["BIT_XOR"]
5414
5415
5416class BitwiseCountAgg(AggFunc):
5417    _sql_names = ["BIT_COUNT"]
5418
5419
5420class ArrayRemove(Func):
5421    arg_types = {"this": True, "expression": True}
5422
5423
5424class ParameterizedAgg(AggFunc):
5425    arg_types = {"this": True, "expressions": True, "params": True}
5426
5427
5428class Abs(Func):
5429    pass
5430
5431
5432class ArgMax(AggFunc):
5433    arg_types = {"this": True, "expression": True, "count": False}
5434    _sql_names = ["ARG_MAX", "ARGMAX", "MAX_BY"]
5435
5436
5437class ArgMin(AggFunc):
5438    arg_types = {"this": True, "expression": True, "count": False}
5439    _sql_names = ["ARG_MIN", "ARGMIN", "MIN_BY"]
5440
5441
5442class ApproxTopK(AggFunc):
5443    arg_types = {"this": True, "expression": False, "counters": False}
5444
5445
5446class Flatten(Func):
5447    pass
5448
5449
5450# https://spark.apache.org/docs/latest/api/sql/index.html#transform
5451class Transform(Func):
5452    arg_types = {"this": True, "expression": True}
5453
5454
5455class Anonymous(Func):
5456    arg_types = {"this": True, "expressions": False}
5457    is_var_len_args = True
5458
5459    @property
5460    def name(self) -> str:
5461        return self.this if isinstance(self.this, str) else self.this.name
5462
5463
5464class AnonymousAggFunc(AggFunc):
5465    arg_types = {"this": True, "expressions": False}
5466    is_var_len_args = True
5467
5468
5469# https://clickhouse.com/docs/en/sql-reference/aggregate-functions/combinators
5470class CombinedAggFunc(AnonymousAggFunc):
5471    arg_types = {"this": True, "expressions": False}
5472
5473
5474class CombinedParameterizedAgg(ParameterizedAgg):
5475    arg_types = {"this": True, "expressions": True, "params": True}
5476
5477
5478# https://docs.snowflake.com/en/sql-reference/functions/hll
5479# https://docs.aws.amazon.com/redshift/latest/dg/r_HLL_function.html
5480class Hll(AggFunc):
5481    arg_types = {"this": True, "expressions": False}
5482    is_var_len_args = True
5483
5484
5485class ApproxDistinct(AggFunc):
5486    arg_types = {"this": True, "accuracy": False}
5487    _sql_names = ["APPROX_DISTINCT", "APPROX_COUNT_DISTINCT"]
5488
5489
5490class Apply(Func):
5491    arg_types = {"this": True, "expression": True}
5492
5493
5494class Array(Func):
5495    arg_types = {"expressions": False, "bracket_notation": False}
5496    is_var_len_args = True
5497
5498
5499class Ascii(Func):
5500    pass
5501
5502
5503# https://docs.snowflake.com/en/sql-reference/functions/to_array
5504class ToArray(Func):
5505    pass
5506
5507
5508# https://materialize.com/docs/sql/types/list/
5509class List(Func):
5510    arg_types = {"expressions": False}
5511    is_var_len_args = True
5512
5513
5514# String pad, kind True -> LPAD, False -> RPAD
5515class Pad(Func):
5516    arg_types = {"this": True, "expression": True, "fill_pattern": False, "is_left": True}
5517
5518
5519# https://docs.snowflake.com/en/sql-reference/functions/to_char
5520# https://docs.oracle.com/en/database/oracle/oracle-database/23/sqlrf/TO_CHAR-number.html
5521class ToChar(Func):
5522    arg_types = {"this": True, "format": False, "nlsparam": False}
5523
5524
5525# https://docs.snowflake.com/en/sql-reference/functions/to_decimal
5526# https://docs.oracle.com/en/database/oracle/oracle-database/23/sqlrf/TO_NUMBER.html
5527class ToNumber(Func):
5528    arg_types = {
5529        "this": True,
5530        "format": False,
5531        "nlsparam": False,
5532        "precision": False,
5533        "scale": False,
5534    }
5535
5536
5537# https://docs.snowflake.com/en/sql-reference/functions/to_double
5538class ToDouble(Func):
5539    arg_types = {
5540        "this": True,
5541        "format": False,
5542    }
5543
5544
5545class Columns(Func):
5546    arg_types = {"this": True, "unpack": False}
5547
5548
5549# https://learn.microsoft.com/en-us/sql/t-sql/functions/cast-and-convert-transact-sql?view=sql-server-ver16#syntax
5550class Convert(Func):
5551    arg_types = {"this": True, "expression": True, "style": False}
5552
5553
5554# https://docs.oracle.com/en/database/oracle/oracle-database/19/sqlrf/CONVERT.html
5555class ConvertToCharset(Func):
5556    arg_types = {"this": True, "dest": True, "source": False}
5557
5558
5559class ConvertTimezone(Func):
5560    arg_types = {
5561        "source_tz": False,
5562        "target_tz": True,
5563        "timestamp": True,
5564        "options": False,
5565    }
5566
5567
5568class GenerateSeries(Func):
5569    arg_types = {"start": True, "end": True, "step": False, "is_end_exclusive": False}
5570
5571
5572# Postgres' GENERATE_SERIES function returns a row set, i.e. it implicitly explodes when it's
5573# used in a projection, so this expression is a helper that facilitates transpilation to other
5574# dialects. For example, we'd generate UNNEST(GENERATE_SERIES(...)) in DuckDB
5575class ExplodingGenerateSeries(GenerateSeries):
5576    pass
5577
5578
5579class ArrayAgg(AggFunc):
5580    arg_types = {"this": True, "nulls_excluded": False}
5581
5582
5583class ArrayUniqueAgg(AggFunc):
5584    pass
5585
5586
5587class ArrayAll(Func):
5588    arg_types = {"this": True, "expression": True}
5589
5590
5591# Represents Python's `any(f(x) for x in array)`, where `array` is `this` and `f` is `expression`
5592class ArrayAny(Func):
5593    arg_types = {"this": True, "expression": True}
5594
5595
5596class ArrayConcat(Func):
5597    _sql_names = ["ARRAY_CONCAT", "ARRAY_CAT"]
5598    arg_types = {"this": True, "expressions": False}
5599    is_var_len_args = True
5600
5601
5602class ArrayConcatAgg(AggFunc):
5603    pass
5604
5605
5606class ArrayConstructCompact(Func):
5607    arg_types = {"expressions": True}
5608    is_var_len_args = True
5609
5610
5611class ArrayContains(Binary, Func):
5612    _sql_names = ["ARRAY_CONTAINS", "ARRAY_HAS"]
5613
5614
5615class ArrayContainsAll(Binary, Func):
5616    _sql_names = ["ARRAY_CONTAINS_ALL", "ARRAY_HAS_ALL"]
5617
5618
5619class ArrayFilter(Func):
5620    arg_types = {"this": True, "expression": True}
5621    _sql_names = ["FILTER", "ARRAY_FILTER"]
5622
5623
5624class ArrayFirst(Func):
5625    pass
5626
5627
5628class ArrayLast(Func):
5629    pass
5630
5631
5632class ArrayReverse(Func):
5633    pass
5634
5635
5636class ArraySlice(Func):
5637    arg_types = {"this": True, "start": True, "end": False, "step": False}
5638
5639
5640class ArrayToString(Func):
5641    arg_types = {"this": True, "expression": True, "null": False}
5642    _sql_names = ["ARRAY_TO_STRING", "ARRAY_JOIN"]
5643
5644
5645class ArrayIntersect(Func):
5646    arg_types = {"expressions": True}
5647    is_var_len_args = True
5648    _sql_names = ["ARRAY_INTERSECT", "ARRAY_INTERSECTION"]
5649
5650
5651class StPoint(Func):
5652    arg_types = {"this": True, "expression": True, "null": False}
5653    _sql_names = ["ST_POINT", "ST_MAKEPOINT"]
5654
5655
5656class StDistance(Func):
5657    arg_types = {"this": True, "expression": True, "use_spheroid": False}
5658
5659
5660# https://cloud.google.com/bigquery/docs/reference/standard-sql/timestamp_functions#string
5661class String(Func):
5662    arg_types = {"this": True, "zone": False}
5663
5664
5665class StringToArray(Func):
5666    arg_types = {"this": True, "expression": False, "null": False}
5667    _sql_names = ["STRING_TO_ARRAY", "SPLIT_BY_STRING", "STRTOK_TO_ARRAY"]
5668
5669
5670class ArrayOverlaps(Binary, Func):
5671    pass
5672
5673
5674class ArraySize(Func):
5675    arg_types = {"this": True, "expression": False}
5676    _sql_names = ["ARRAY_SIZE", "ARRAY_LENGTH"]
5677
5678
5679class ArraySort(Func):
5680    arg_types = {"this": True, "expression": False}
5681
5682
5683class ArraySum(Func):
5684    arg_types = {"this": True, "expression": False}
5685
5686
5687class ArrayUnionAgg(AggFunc):
5688    pass
5689
5690
5691class Avg(AggFunc):
5692    pass
5693
5694
5695class AnyValue(AggFunc):
5696    pass
5697
5698
5699class Lag(AggFunc):
5700    arg_types = {"this": True, "offset": False, "default": False}
5701
5702
5703class Lead(AggFunc):
5704    arg_types = {"this": True, "offset": False, "default": False}
5705
5706
5707# some dialects have a distinction between first and first_value, usually first is an aggregate func
5708# and first_value is a window func
5709class First(AggFunc):
5710    pass
5711
5712
5713class Last(AggFunc):
5714    pass
5715
5716
5717class FirstValue(AggFunc):
5718    pass
5719
5720
5721class LastValue(AggFunc):
5722    pass
5723
5724
5725class NthValue(AggFunc):
5726    arg_types = {"this": True, "offset": True}
5727
5728
5729class Case(Func):
5730    arg_types = {"this": False, "ifs": True, "default": False}
5731
5732    def when(self, condition: ExpOrStr, then: ExpOrStr, copy: bool = True, **opts) -> Case:
5733        instance = maybe_copy(self, copy)
5734        instance.append(
5735            "ifs",
5736            If(
5737                this=maybe_parse(condition, copy=copy, **opts),
5738                true=maybe_parse(then, copy=copy, **opts),
5739            ),
5740        )
5741        return instance
5742
5743    def else_(self, condition: ExpOrStr, copy: bool = True, **opts) -> Case:
5744        instance = maybe_copy(self, copy)
5745        instance.set("default", maybe_parse(condition, copy=copy, **opts))
5746        return instance
5747
5748
5749class Cast(Func):
5750    arg_types = {
5751        "this": True,
5752        "to": True,
5753        "format": False,
5754        "safe": False,
5755        "action": False,
5756        "default": False,
5757    }
5758
5759    @property
5760    def name(self) -> str:
5761        return self.this.name
5762
5763    @property
5764    def to(self) -> DataType:
5765        return self.args["to"]
5766
5767    @property
5768    def output_name(self) -> str:
5769        return self.name
5770
5771    def is_type(self, *dtypes: DATA_TYPE) -> bool:
5772        """
5773        Checks whether this Cast's DataType matches one of the provided data types. Nested types
5774        like arrays or structs will be compared using "structural equivalence" semantics, so e.g.
5775        array<int> != array<float>.
5776
5777        Args:
5778            dtypes: the data types to compare this Cast's DataType to.
5779
5780        Returns:
5781            True, if and only if there is a type in `dtypes` which is equal to this Cast's DataType.
5782        """
5783        return self.to.is_type(*dtypes)
5784
5785
5786class TryCast(Cast):
5787    pass
5788
5789
5790# https://clickhouse.com/docs/sql-reference/data-types/newjson#reading-json-paths-as-sub-columns
5791class JSONCast(Cast):
5792    pass
5793
5794
5795class Try(Func):
5796    pass
5797
5798
5799class CastToStrType(Func):
5800    arg_types = {"this": True, "to": True}
5801
5802
5803# https://docs.teradata.com/r/Enterprise_IntelliFlex_VMware/SQL-Functions-Expressions-and-Predicates/String-Operators-and-Functions/TRANSLATE/TRANSLATE-Function-Syntax
5804class TranslateCharacters(Expression):
5805    arg_types = {"this": True, "expression": True, "with_error": False}
5806
5807
5808class Collate(Binary, Func):
5809    pass
5810
5811
5812class Ceil(Func):
5813    arg_types = {"this": True, "decimals": False, "to": False}
5814    _sql_names = ["CEIL", "CEILING"]
5815
5816
5817class Coalesce(Func):
5818    arg_types = {"this": True, "expressions": False, "is_nvl": False, "is_null": False}
5819    is_var_len_args = True
5820    _sql_names = ["COALESCE", "IFNULL", "NVL"]
5821
5822
5823class Chr(Func):
5824    arg_types = {"expressions": True, "charset": False}
5825    is_var_len_args = True
5826    _sql_names = ["CHR", "CHAR"]
5827
5828
5829class Concat(Func):
5830    arg_types = {"expressions": True, "safe": False, "coalesce": False}
5831    is_var_len_args = True
5832
5833
5834class ConcatWs(Concat):
5835    _sql_names = ["CONCAT_WS"]
5836
5837
5838class Contains(Func):
5839    arg_types = {"this": True, "expression": True}
5840
5841
5842# https://docs.oracle.com/cd/B13789_01/server.101/b10759/operators004.htm#i1035022
5843class ConnectByRoot(Func):
5844    pass
5845
5846
5847class Count(AggFunc):
5848    arg_types = {"this": False, "expressions": False, "big_int": False}
5849    is_var_len_args = True
5850
5851
5852class CountIf(AggFunc):
5853    _sql_names = ["COUNT_IF", "COUNTIF"]
5854
5855
5856# cube root
5857class Cbrt(Func):
5858    pass
5859
5860
5861class CurrentDate(Func):
5862    arg_types = {"this": False}
5863
5864
5865class CurrentDatetime(Func):
5866    arg_types = {"this": False}
5867
5868
5869class CurrentTime(Func):
5870    arg_types = {"this": False}
5871
5872
5873class CurrentTimestamp(Func):
5874    arg_types = {"this": False, "sysdate": False}
5875
5876
5877class CurrentTimestampLTZ(Func):
5878    arg_types = {}
5879
5880
5881class CurrentSchema(Func):
5882    arg_types = {"this": False}
5883
5884
5885class CurrentUser(Func):
5886    arg_types = {"this": False}
5887
5888
5889class DateAdd(Func, IntervalOp):
5890    arg_types = {"this": True, "expression": True, "unit": False}
5891
5892
5893class DateBin(Func, IntervalOp):
5894    arg_types = {"this": True, "expression": True, "unit": False, "zone": False}
5895
5896
5897class DateSub(Func, IntervalOp):
5898    arg_types = {"this": True, "expression": True, "unit": False}
5899
5900
5901class DateDiff(Func, TimeUnit):
5902    _sql_names = ["DATEDIFF", "DATE_DIFF"]
5903    arg_types = {"this": True, "expression": True, "unit": False, "zone": False}
5904
5905
5906class DateTrunc(Func):
5907    arg_types = {"unit": True, "this": True, "zone": False}
5908
5909    def __init__(self, **args):
5910        # Across most dialects it's safe to unabbreviate the unit (e.g. 'Q' -> 'QUARTER') except Oracle
5911        # https://docs.oracle.com/en/database/oracle/oracle-database/21/sqlrf/ROUND-and-TRUNC-Date-Functions.html
5912        unabbreviate = args.pop("unabbreviate", True)
5913
5914        unit = args.get("unit")
5915        if isinstance(unit, TimeUnit.VAR_LIKE):
5916            unit_name = unit.name.upper()
5917            if unabbreviate and unit_name in TimeUnit.UNABBREVIATED_UNIT_NAME:
5918                unit_name = TimeUnit.UNABBREVIATED_UNIT_NAME[unit_name]
5919
5920            args["unit"] = Literal.string(unit_name)
5921
5922        super().__init__(**args)
5923
5924    @property
5925    def unit(self) -> Expression:
5926        return self.args["unit"]
5927
5928
5929# https://cloud.google.com/bigquery/docs/reference/standard-sql/datetime_functions#datetime
5930# expression can either be time_expr or time_zone
5931class Datetime(Func):
5932    arg_types = {"this": True, "expression": False}
5933
5934
5935class DatetimeAdd(Func, IntervalOp):
5936    arg_types = {"this": True, "expression": True, "unit": False}
5937
5938
5939class DatetimeSub(Func, IntervalOp):
5940    arg_types = {"this": True, "expression": True, "unit": False}
5941
5942
5943class DatetimeDiff(Func, TimeUnit):
5944    arg_types = {"this": True, "expression": True, "unit": False}
5945
5946
5947class DatetimeTrunc(Func, TimeUnit):
5948    arg_types = {"this": True, "unit": True, "zone": False}
5949
5950
5951class DayOfWeek(Func):
5952    _sql_names = ["DAY_OF_WEEK", "DAYOFWEEK"]
5953
5954
5955# https://duckdb.org/docs/sql/functions/datepart.html#part-specifiers-only-usable-as-date-part-specifiers
5956# ISO day of week function in duckdb is ISODOW
5957class DayOfWeekIso(Func):
5958    _sql_names = ["DAYOFWEEK_ISO", "ISODOW"]
5959
5960
5961class DayOfMonth(Func):
5962    _sql_names = ["DAY_OF_MONTH", "DAYOFMONTH"]
5963
5964
5965class DayOfYear(Func):
5966    _sql_names = ["DAY_OF_YEAR", "DAYOFYEAR"]
5967
5968
5969class ToDays(Func):
5970    pass
5971
5972
5973class WeekOfYear(Func):
5974    _sql_names = ["WEEK_OF_YEAR", "WEEKOFYEAR"]
5975
5976
5977class MonthsBetween(Func):
5978    arg_types = {"this": True, "expression": True, "roundoff": False}
5979
5980
5981class MakeInterval(Func):
5982    arg_types = {
5983        "year": False,
5984        "month": False,
5985        "day": False,
5986        "hour": False,
5987        "minute": False,
5988        "second": False,
5989    }
5990
5991
5992class LastDay(Func, TimeUnit):
5993    _sql_names = ["LAST_DAY", "LAST_DAY_OF_MONTH"]
5994    arg_types = {"this": True, "unit": False}
5995
5996
5997class Extract(Func):
5998    arg_types = {"this": True, "expression": True}
5999
6000
6001class Exists(Func, SubqueryPredicate):
6002    arg_types = {"this": True, "expression": False}
6003
6004
6005class Timestamp(Func):
6006    arg_types = {"this": False, "zone": False, "with_tz": False}
6007
6008
6009class TimestampAdd(Func, TimeUnit):
6010    arg_types = {"this": True, "expression": True, "unit": False}
6011
6012
6013class TimestampSub(Func, TimeUnit):
6014    arg_types = {"this": True, "expression": True, "unit": False}
6015
6016
6017class TimestampDiff(Func, TimeUnit):
6018    _sql_names = ["TIMESTAMPDIFF", "TIMESTAMP_DIFF"]
6019    arg_types = {"this": True, "expression": True, "unit": False}
6020
6021
6022class TimestampTrunc(Func, TimeUnit):
6023    arg_types = {"this": True, "unit": True, "zone": False}
6024
6025
6026class TimeAdd(Func, TimeUnit):
6027    arg_types = {"this": True, "expression": True, "unit": False}
6028
6029
6030class TimeSub(Func, TimeUnit):
6031    arg_types = {"this": True, "expression": True, "unit": False}
6032
6033
6034class TimeDiff(Func, TimeUnit):
6035    arg_types = {"this": True, "expression": True, "unit": False}
6036
6037
6038class TimeTrunc(Func, TimeUnit):
6039    arg_types = {"this": True, "unit": True, "zone": False}
6040
6041
6042class DateFromParts(Func):
6043    _sql_names = ["DATE_FROM_PARTS", "DATEFROMPARTS"]
6044    arg_types = {"year": True, "month": True, "day": True}
6045
6046
6047class TimeFromParts(Func):
6048    _sql_names = ["TIME_FROM_PARTS", "TIMEFROMPARTS"]
6049    arg_types = {
6050        "hour": True,
6051        "min": True,
6052        "sec": True,
6053        "nano": False,
6054        "fractions": False,
6055        "precision": False,
6056    }
6057
6058
6059class DateStrToDate(Func):
6060    pass
6061
6062
6063class DateToDateStr(Func):
6064    pass
6065
6066
6067class DateToDi(Func):
6068    pass
6069
6070
6071# https://cloud.google.com/bigquery/docs/reference/standard-sql/date_functions#date
6072class Date(Func):
6073    arg_types = {"this": False, "zone": False, "expressions": False}
6074    is_var_len_args = True
6075
6076
6077class Day(Func):
6078    pass
6079
6080
6081class Decode(Func):
6082    arg_types = {"this": True, "charset": True, "replace": False}
6083
6084
6085class DecodeCase(Func):
6086    _sql_names: t.List[str] = []
6087    arg_types = {"expressions": True}
6088    is_var_len_args = True
6089
6090
6091class DiToDate(Func):
6092    pass
6093
6094
6095class Encode(Func):
6096    arg_types = {"this": True, "charset": True}
6097
6098
6099class Exp(Func):
6100    pass
6101
6102
6103# https://docs.snowflake.com/en/sql-reference/functions/flatten
6104class Explode(Func, UDTF):
6105    arg_types = {"this": True, "expressions": False}
6106    is_var_len_args = True
6107
6108
6109# https://spark.apache.org/docs/latest/api/sql/#inline
6110class Inline(Func):
6111    pass
6112
6113
6114class ExplodeOuter(Explode):
6115    pass
6116
6117
6118class Posexplode(Explode):
6119    pass
6120
6121
6122class PosexplodeOuter(Posexplode, ExplodeOuter):
6123    pass
6124
6125
6126class PositionalColumn(Expression):
6127    pass
6128
6129
6130class Unnest(Func, UDTF):
6131    arg_types = {
6132        "expressions": True,
6133        "alias": False,
6134        "offset": False,
6135        "explode_array": False,
6136    }
6137
6138    @property
6139    def selects(self) -> t.List[Expression]:
6140        columns = super().selects
6141        offset = self.args.get("offset")
6142        if offset:
6143            columns = columns + [to_identifier("offset") if offset is True else offset]
6144        return columns
6145
6146
6147class Floor(Func):
6148    arg_types = {"this": True, "decimals": False, "to": False}
6149
6150
6151class FromBase64(Func):
6152    pass
6153
6154
6155class FeaturesAtTime(Func):
6156    arg_types = {"this": True, "time": False, "num_rows": False, "ignore_feature_nulls": False}
6157
6158
6159class ToBase64(Func):
6160    pass
6161
6162
6163# https://trino.io/docs/current/functions/datetime.html#from_iso8601_timestamp
6164class FromISO8601Timestamp(Func):
6165    _sql_names = ["FROM_ISO8601_TIMESTAMP"]
6166
6167
6168class GapFill(Func):
6169    arg_types = {
6170        "this": True,
6171        "ts_column": True,
6172        "bucket_width": True,
6173        "partitioning_columns": False,
6174        "value_columns": False,
6175        "origin": False,
6176        "ignore_nulls": False,
6177    }
6178
6179
6180# https://cloud.google.com/bigquery/docs/reference/standard-sql/array_functions#generate_date_array
6181class GenerateDateArray(Func):
6182    arg_types = {"start": True, "end": True, "step": False}
6183
6184
6185# https://cloud.google.com/bigquery/docs/reference/standard-sql/array_functions#generate_timestamp_array
6186class GenerateTimestampArray(Func):
6187    arg_types = {"start": True, "end": True, "step": True}
6188
6189
6190class Greatest(Func):
6191    arg_types = {"this": True, "expressions": False}
6192    is_var_len_args = True
6193
6194
6195# Trino's `ON OVERFLOW TRUNCATE [filler_string] {WITH | WITHOUT} COUNT`
6196# https://trino.io/docs/current/functions/aggregate.html#listagg
6197class OverflowTruncateBehavior(Expression):
6198    arg_types = {"this": False, "with_count": True}
6199
6200
6201class GroupConcat(AggFunc):
6202    arg_types = {"this": True, "separator": False, "on_overflow": False}
6203
6204
6205class Hex(Func):
6206    pass
6207
6208
6209class LowerHex(Hex):
6210    pass
6211
6212
6213class And(Connector, Func):
6214    pass
6215
6216
6217class Or(Connector, Func):
6218    pass
6219
6220
6221class Xor(Connector, Func):
6222    arg_types = {"this": False, "expression": False, "expressions": False}
6223
6224
6225class If(Func):
6226    arg_types = {"this": True, "true": True, "false": False}
6227    _sql_names = ["IF", "IIF"]
6228
6229
6230class Nullif(Func):
6231    arg_types = {"this": True, "expression": True}
6232
6233
6234class Initcap(Func):
6235    arg_types = {"this": True, "expression": False}
6236
6237
6238class IsAscii(Func):
6239    pass
6240
6241
6242class IsNan(Func):
6243    _sql_names = ["IS_NAN", "ISNAN"]
6244
6245
6246# https://cloud.google.com/bigquery/docs/reference/standard-sql/json_functions#int64_for_json
6247class Int64(Func):
6248    pass
6249
6250
6251class IsInf(Func):
6252    _sql_names = ["IS_INF", "ISINF"]
6253
6254
6255# https://www.postgresql.org/docs/current/functions-json.html
6256class JSON(Expression):
6257    arg_types = {"this": False, "with": False, "unique": False}
6258
6259
6260class JSONPath(Expression):
6261    arg_types = {"expressions": True, "escape": False}
6262
6263    @property
6264    def output_name(self) -> str:
6265        last_segment = self.expressions[-1].this
6266        return last_segment if isinstance(last_segment, str) else ""
6267
6268
6269class JSONPathPart(Expression):
6270    arg_types = {}
6271
6272
6273class JSONPathFilter(JSONPathPart):
6274    arg_types = {"this": True}
6275
6276
6277class JSONPathKey(JSONPathPart):
6278    arg_types = {"this": True}
6279
6280
6281class JSONPathRecursive(JSONPathPart):
6282    arg_types = {"this": False}
6283
6284
6285class JSONPathRoot(JSONPathPart):
6286    pass
6287
6288
6289class JSONPathScript(JSONPathPart):
6290    arg_types = {"this": True}
6291
6292
6293class JSONPathSlice(JSONPathPart):
6294    arg_types = {"start": False, "end": False, "step": False}
6295
6296
6297class JSONPathSelector(JSONPathPart):
6298    arg_types = {"this": True}
6299
6300
6301class JSONPathSubscript(JSONPathPart):
6302    arg_types = {"this": True}
6303
6304
6305class JSONPathUnion(JSONPathPart):
6306    arg_types = {"expressions": True}
6307
6308
6309class JSONPathWildcard(JSONPathPart):
6310    pass
6311
6312
6313class FormatJson(Expression):
6314    pass
6315
6316
6317class JSONKeyValue(Expression):
6318    arg_types = {"this": True, "expression": True}
6319
6320
6321class JSONObject(Func):
6322    arg_types = {
6323        "expressions": False,
6324        "null_handling": False,
6325        "unique_keys": False,
6326        "return_type": False,
6327        "encoding": False,
6328    }
6329
6330
6331class JSONObjectAgg(AggFunc):
6332    arg_types = {
6333        "expressions": False,
6334        "null_handling": False,
6335        "unique_keys": False,
6336        "return_type": False,
6337        "encoding": False,
6338    }
6339
6340
6341# https://www.postgresql.org/docs/9.5/functions-aggregate.html
6342class JSONBObjectAgg(AggFunc):
6343    arg_types = {"this": True, "expression": True}
6344
6345
6346# https://docs.oracle.com/en/database/oracle/oracle-database/19/sqlrf/JSON_ARRAY.html
6347class JSONArray(Func):
6348    arg_types = {
6349        "expressions": False,
6350        "null_handling": False,
6351        "return_type": False,
6352        "strict": False,
6353    }
6354
6355
6356# https://docs.oracle.com/en/database/oracle/oracle-database/19/sqlrf/JSON_ARRAYAGG.html
6357class JSONArrayAgg(Func):
6358    arg_types = {
6359        "this": True,
6360        "order": False,
6361        "null_handling": False,
6362        "return_type": False,
6363        "strict": False,
6364    }
6365
6366
6367class JSONExists(Func):
6368    arg_types = {"this": True, "path": True, "passing": False, "on_condition": False}
6369
6370
6371# https://docs.oracle.com/en/database/oracle/oracle-database/19/sqlrf/JSON_TABLE.html
6372# Note: parsing of JSON column definitions is currently incomplete.
6373class JSONColumnDef(Expression):
6374    arg_types = {"this": False, "kind": False, "path": False, "nested_schema": False}
6375
6376
6377class JSONSchema(Expression):
6378    arg_types = {"expressions": True}
6379
6380
6381# https://dev.mysql.com/doc/refman/8.4/en/json-search-functions.html#function_json-value
6382class JSONValue(Expression):
6383    arg_types = {
6384        "this": True,
6385        "path": True,
6386        "returning": False,
6387        "on_condition": False,
6388    }
6389
6390
6391class JSONValueArray(Func):
6392    arg_types = {"this": True, "expression": False}
6393
6394
6395# https://docs.oracle.com/en/database/oracle/oracle-database/19/sqlrf/JSON_TABLE.html
6396class JSONTable(Func):
6397    arg_types = {
6398        "this": True,
6399        "schema": True,
6400        "path": False,
6401        "error_handling": False,
6402        "empty_handling": False,
6403    }
6404
6405
6406# https://cloud.google.com/bigquery/docs/reference/standard-sql/json_functions#json_type
6407# https://doris.apache.org/docs/sql-manual/sql-functions/scalar-functions/json-functions/json-type#description
6408class JSONType(Func):
6409    arg_types = {"this": True, "expression": False}
6410    _sql_names = ["JSON_TYPE"]
6411
6412
6413# https://docs.snowflake.com/en/sql-reference/functions/object_insert
6414class ObjectInsert(Func):
6415    arg_types = {
6416        "this": True,
6417        "key": True,
6418        "value": True,
6419        "update_flag": False,
6420    }
6421
6422
6423class OpenJSONColumnDef(Expression):
6424    arg_types = {"this": True, "kind": True, "path": False, "as_json": False}
6425
6426
6427class OpenJSON(Func):
6428    arg_types = {"this": True, "path": False, "expressions": False}
6429
6430
6431class JSONBContains(Binary, Func):
6432    _sql_names = ["JSONB_CONTAINS"]
6433
6434
6435class JSONBExists(Func):
6436    arg_types = {"this": True, "path": True}
6437    _sql_names = ["JSONB_EXISTS"]
6438
6439
6440class JSONExtract(Binary, Func):
6441    arg_types = {
6442        "this": True,
6443        "expression": True,
6444        "only_json_types": False,
6445        "expressions": False,
6446        "variant_extract": False,
6447        "json_query": False,
6448        "option": False,
6449        "quote": False,
6450        "on_condition": False,
6451    }
6452    _sql_names = ["JSON_EXTRACT"]
6453    is_var_len_args = True
6454
6455    @property
6456    def output_name(self) -> str:
6457        return self.expression.output_name if not self.expressions else ""
6458
6459
6460# https://trino.io/docs/current/functions/json.html#json-query
6461class JSONExtractQuote(Expression):
6462    arg_types = {
6463        "option": True,
6464        "scalar": False,
6465    }
6466
6467
6468class JSONExtractArray(Func):
6469    arg_types = {"this": True, "expression": False}
6470    _sql_names = ["JSON_EXTRACT_ARRAY"]
6471
6472
6473class JSONExtractScalar(Binary, Func):
6474    arg_types = {"this": True, "expression": True, "only_json_types": False, "expressions": False}
6475    _sql_names = ["JSON_EXTRACT_SCALAR"]
6476    is_var_len_args = True
6477
6478    @property
6479    def output_name(self) -> str:
6480        return self.expression.output_name
6481
6482
6483class JSONBExtract(Binary, Func):
6484    _sql_names = ["JSONB_EXTRACT"]
6485
6486
6487class JSONBExtractScalar(Binary, Func):
6488    _sql_names = ["JSONB_EXTRACT_SCALAR"]
6489
6490
6491class JSONFormat(Func):
6492    arg_types = {"this": False, "options": False, "is_json": False}
6493    _sql_names = ["JSON_FORMAT"]
6494
6495
6496# https://dev.mysql.com/doc/refman/8.0/en/json-search-functions.html#operator_member-of
6497class JSONArrayContains(Binary, Predicate, Func):
6498    _sql_names = ["JSON_ARRAY_CONTAINS"]
6499
6500
6501class ParseJSON(Func):
6502    # BigQuery, Snowflake have PARSE_JSON, Presto has JSON_PARSE
6503    # Snowflake also has TRY_PARSE_JSON, which is represented using `safe`
6504    _sql_names = ["PARSE_JSON", "JSON_PARSE"]
6505    arg_types = {"this": True, "expression": False, "safe": False}
6506
6507
6508class Least(Func):
6509    arg_types = {"this": True, "expressions": False}
6510    is_var_len_args = True
6511
6512
6513class Left(Func):
6514    arg_types = {"this": True, "expression": True}
6515
6516
6517class Right(Func):
6518    arg_types = {"this": True, "expression": True}
6519
6520
6521class Length(Func):
6522    arg_types = {"this": True, "binary": False, "encoding": False}
6523    _sql_names = ["LENGTH", "LEN", "CHAR_LENGTH", "CHARACTER_LENGTH"]
6524
6525
6526class Levenshtein(Func):
6527    arg_types = {
6528        "this": True,
6529        "expression": False,
6530        "ins_cost": False,
6531        "del_cost": False,
6532        "sub_cost": False,
6533        "max_dist": False,
6534    }
6535
6536
6537class Ln(Func):
6538    pass
6539
6540
6541class Log(Func):
6542    arg_types = {"this": True, "expression": False}
6543
6544
6545class LogicalOr(AggFunc):
6546    _sql_names = ["LOGICAL_OR", "BOOL_OR", "BOOLOR_AGG"]
6547
6548
6549class LogicalAnd(AggFunc):
6550    _sql_names = ["LOGICAL_AND", "BOOL_AND", "BOOLAND_AGG"]
6551
6552
6553class Lower(Func):
6554    _sql_names = ["LOWER", "LCASE"]
6555
6556
6557class Map(Func):
6558    arg_types = {"keys": False, "values": False}
6559
6560    @property
6561    def keys(self) -> t.List[Expression]:
6562        keys = self.args.get("keys")
6563        return keys.expressions if keys else []
6564
6565    @property
6566    def values(self) -> t.List[Expression]:
6567        values = self.args.get("values")
6568        return values.expressions if values else []
6569
6570
6571# Represents the MAP {...} syntax in DuckDB - basically convert a struct to a MAP
6572class ToMap(Func):
6573    pass
6574
6575
6576class MapFromEntries(Func):
6577    pass
6578
6579
6580# https://learn.microsoft.com/en-us/sql/t-sql/language-elements/scope-resolution-operator-transact-sql?view=sql-server-ver16
6581class ScopeResolution(Expression):
6582    arg_types = {"this": False, "expression": True}
6583
6584
6585class Stream(Expression):
6586    pass
6587
6588
6589class StarMap(Func):
6590    pass
6591
6592
6593class VarMap(Func):
6594    arg_types = {"keys": True, "values": True}
6595    is_var_len_args = True
6596
6597    @property
6598    def keys(self) -> t.List[Expression]:
6599        return self.args["keys"].expressions
6600
6601    @property
6602    def values(self) -> t.List[Expression]:
6603        return self.args["values"].expressions
6604
6605
6606# https://dev.mysql.com/doc/refman/8.0/en/fulltext-search.html
6607class MatchAgainst(Func):
6608    arg_types = {"this": True, "expressions": True, "modifier": False}
6609
6610
6611class Max(AggFunc):
6612    arg_types = {"this": True, "expressions": False}
6613    is_var_len_args = True
6614
6615
6616class MD5(Func):
6617    _sql_names = ["MD5"]
6618
6619
6620# Represents the variant of the MD5 function that returns a binary value
6621class MD5Digest(Func):
6622    _sql_names = ["MD5_DIGEST"]
6623
6624
6625class Median(AggFunc):
6626    pass
6627
6628
6629class Min(AggFunc):
6630    arg_types = {"this": True, "expressions": False}
6631    is_var_len_args = True
6632
6633
6634class Month(Func):
6635    pass
6636
6637
6638class AddMonths(Func):
6639    arg_types = {"this": True, "expression": True}
6640
6641
6642class Nvl2(Func):
6643    arg_types = {"this": True, "true": True, "false": False}
6644
6645
6646class Normalize(Func):
6647    arg_types = {"this": True, "form": False}
6648
6649
6650class Overlay(Func):
6651    arg_types = {"this": True, "expression": True, "from": True, "for": False}
6652
6653
6654# https://cloud.google.com/bigquery/docs/reference/standard-sql/bigqueryml-syntax-predict#mlpredict_function
6655class Predict(Func):
6656    arg_types = {"this": True, "expression": True, "params_struct": False}
6657
6658
6659class Pow(Binary, Func):
6660    _sql_names = ["POWER", "POW"]
6661
6662
6663class PercentileCont(AggFunc):
6664    arg_types = {"this": True, "expression": False}
6665
6666
6667class PercentileDisc(AggFunc):
6668    arg_types = {"this": True, "expression": False}
6669
6670
6671class Quantile(AggFunc):
6672    arg_types = {"this": True, "quantile": True}
6673
6674
6675class ApproxQuantile(Quantile):
6676    arg_types = {"this": True, "quantile": True, "accuracy": False, "weight": False}
6677
6678
6679class Quarter(Func):
6680    pass
6681
6682
6683# https://docs.teradata.com/r/Enterprise_IntelliFlex_VMware/SQL-Functions-Expressions-and-Predicates/Arithmetic-Trigonometric-Hyperbolic-Operators/Functions/RANDOM/RANDOM-Function-Syntax
6684# teradata lower and upper bounds
6685class Rand(Func):
6686    _sql_names = ["RAND", "RANDOM"]
6687    arg_types = {"this": False, "lower": False, "upper": False}
6688
6689
6690class Randn(Func):
6691    arg_types = {"this": False}
6692
6693
6694class RangeN(Func):
6695    arg_types = {"this": True, "expressions": True, "each": False}
6696
6697
6698class ReadCSV(Func):
6699    _sql_names = ["READ_CSV"]
6700    is_var_len_args = True
6701    arg_types = {"this": True, "expressions": False}
6702
6703
6704class Reduce(Func):
6705    arg_types = {"this": True, "initial": True, "merge": True, "finish": False}
6706
6707
6708class RegexpExtract(Func):
6709    arg_types = {
6710        "this": True,
6711        "expression": True,
6712        "position": False,
6713        "occurrence": False,
6714        "parameters": False,
6715        "group": False,
6716    }
6717
6718
6719class RegexpExtractAll(Func):
6720    arg_types = {
6721        "this": True,
6722        "expression": True,
6723        "position": False,
6724        "occurrence": False,
6725        "parameters": False,
6726        "group": False,
6727    }
6728
6729
6730class RegexpReplace(Func):
6731    arg_types = {
6732        "this": True,
6733        "expression": True,
6734        "replacement": False,
6735        "position": False,
6736        "occurrence": False,
6737        "modifiers": False,
6738    }
6739
6740
6741class RegexpLike(Binary, Func):
6742    arg_types = {"this": True, "expression": True, "flag": False}
6743
6744
6745class RegexpILike(Binary, Func):
6746    arg_types = {"this": True, "expression": True, "flag": False}
6747
6748
6749# https://spark.apache.org/docs/latest/api/python/reference/pyspark.sql/api/pyspark.sql.functions.split.html
6750# limit is the number of times a pattern is applied
6751class RegexpSplit(Func):
6752    arg_types = {"this": True, "expression": True, "limit": False}
6753
6754
6755class Repeat(Func):
6756    arg_types = {"this": True, "times": True}
6757
6758
6759# Some dialects like Snowflake support two argument replace
6760class Replace(Func):
6761    arg_types = {"this": True, "expression": True, "replacement": False}
6762
6763
6764# https://learn.microsoft.com/en-us/sql/t-sql/functions/round-transact-sql?view=sql-server-ver16
6765# tsql third argument function == trunctaion if not 0
6766class Round(Func):
6767    arg_types = {"this": True, "decimals": False, "truncate": False}
6768
6769
6770class RowNumber(Func):
6771    arg_types = {"this": False}
6772
6773
6774class SafeDivide(Func):
6775    arg_types = {"this": True, "expression": True}
6776
6777
6778class SHA(Func):
6779    _sql_names = ["SHA", "SHA1"]
6780
6781
6782class SHA2(Func):
6783    _sql_names = ["SHA2"]
6784    arg_types = {"this": True, "length": False}
6785
6786
6787class Sign(Func):
6788    _sql_names = ["SIGN", "SIGNUM"]
6789
6790
6791class SortArray(Func):
6792    arg_types = {"this": True, "asc": False}
6793
6794
6795class Split(Func):
6796    arg_types = {"this": True, "expression": True, "limit": False}
6797
6798
6799# https://spark.apache.org/docs/latest/api/python/reference/pyspark.sql/api/pyspark.sql.functions.split_part.html
6800class SplitPart(Func):
6801    arg_types = {"this": True, "delimiter": True, "part_index": True}
6802
6803
6804# Start may be omitted in the case of postgres
6805# https://www.postgresql.org/docs/9.1/functions-string.html @ Table 9-6
6806class Substring(Func):
6807    _sql_names = ["SUBSTRING", "SUBSTR"]
6808    arg_types = {"this": True, "start": False, "length": False}
6809
6810
6811class SubstringIndex(Func):
6812    """
6813    SUBSTRING_INDEX(str, delim, count)
6814
6815    *count* > 0  → left slice before the *count*-th delimiter
6816    *count* < 0  → right slice after the |count|-th delimiter
6817    """
6818
6819    arg_types = {"this": True, "delimiter": True, "count": True}
6820
6821
6822class StandardHash(Func):
6823    arg_types = {"this": True, "expression": False}
6824
6825
6826class StartsWith(Func):
6827    _sql_names = ["STARTS_WITH", "STARTSWITH"]
6828    arg_types = {"this": True, "expression": True}
6829
6830
6831class EndsWith(Func):
6832    _sql_names = ["ENDS_WITH", "ENDSWITH"]
6833    arg_types = {"this": True, "expression": True}
6834
6835
6836class StrPosition(Func):
6837    arg_types = {
6838        "this": True,
6839        "substr": True,
6840        "position": False,
6841        "occurrence": False,
6842    }
6843
6844
6845class StrToDate(Func):
6846    arg_types = {"this": True, "format": False, "safe": False}
6847
6848
6849class StrToTime(Func):
6850    arg_types = {"this": True, "format": True, "zone": False, "safe": False}
6851
6852
6853# Spark allows unix_timestamp()
6854# https://spark.apache.org/docs/3.1.3/api/python/reference/api/pyspark.sql.functions.unix_timestamp.html
6855class StrToUnix(Func):
6856    arg_types = {"this": False, "format": False}
6857
6858
6859# https://prestodb.io/docs/current/functions/string.html
6860# https://spark.apache.org/docs/latest/api/sql/index.html#str_to_map
6861class StrToMap(Func):
6862    arg_types = {
6863        "this": True,
6864        "pair_delim": False,
6865        "key_value_delim": False,
6866        "duplicate_resolution_callback": False,
6867    }
6868
6869
6870class NumberToStr(Func):
6871    arg_types = {"this": True, "format": True, "culture": False}
6872
6873
6874class FromBase(Func):
6875    arg_types = {"this": True, "expression": True}
6876
6877
6878class Space(Func):
6879    """
6880    SPACE(n) → string consisting of n blank characters
6881    """
6882
6883    pass
6884
6885
6886class Struct(Func):
6887    arg_types = {"expressions": False}
6888    is_var_len_args = True
6889
6890
6891class StructExtract(Func):
6892    arg_types = {"this": True, "expression": True}
6893
6894
6895# https://learn.microsoft.com/en-us/sql/t-sql/functions/stuff-transact-sql?view=sql-server-ver16
6896# https://docs.snowflake.com/en/sql-reference/functions/insert
6897class Stuff(Func):
6898    _sql_names = ["STUFF", "INSERT"]
6899    arg_types = {"this": True, "start": True, "length": True, "expression": True}
6900
6901
6902class Sum(AggFunc):
6903    pass
6904
6905
6906class Sqrt(Func):
6907    pass
6908
6909
6910class Stddev(AggFunc):
6911    _sql_names = ["STDDEV", "STDEV"]
6912
6913
6914class StddevPop(AggFunc):
6915    pass
6916
6917
6918class StddevSamp(AggFunc):
6919    pass
6920
6921
6922# https://cloud.google.com/bigquery/docs/reference/standard-sql/time_functions#time
6923class Time(Func):
6924    arg_types = {"this": False, "zone": False}
6925
6926
6927class TimeToStr(Func):
6928    arg_types = {"this": True, "format": True, "culture": False, "zone": False}
6929
6930
6931class TimeToTimeStr(Func):
6932    pass
6933
6934
6935class TimeToUnix(Func):
6936    pass
6937
6938
6939class TimeStrToDate(Func):
6940    pass
6941
6942
6943class TimeStrToTime(Func):
6944    arg_types = {"this": True, "zone": False}
6945
6946
6947class TimeStrToUnix(Func):
6948    pass
6949
6950
6951class Trim(Func):
6952    arg_types = {
6953        "this": True,
6954        "expression": False,
6955        "position": False,
6956        "collation": False,
6957    }
6958
6959
6960class TsOrDsAdd(Func, TimeUnit):
6961    # return_type is used to correctly cast the arguments of this expression when transpiling it
6962    arg_types = {"this": True, "expression": True, "unit": False, "return_type": False}
6963
6964    @property
6965    def return_type(self) -> DataType:
6966        return DataType.build(self.args.get("return_type") or DataType.Type.DATE)
6967
6968
6969class TsOrDsDiff(Func, TimeUnit):
6970    arg_types = {"this": True, "expression": True, "unit": False}
6971
6972
6973class TsOrDsToDateStr(Func):
6974    pass
6975
6976
6977class TsOrDsToDate(Func):
6978    arg_types = {"this": True, "format": False, "safe": False}
6979
6980
6981class TsOrDsToDatetime(Func):
6982    pass
6983
6984
6985class TsOrDsToTime(Func):
6986    arg_types = {"this": True, "format": False, "safe": False}
6987
6988
6989class TsOrDsToTimestamp(Func):
6990    pass
6991
6992
6993class TsOrDiToDi(Func):
6994    pass
6995
6996
6997class Unhex(Func):
6998    arg_types = {"this": True, "expression": False}
6999
7000
7001class Unicode(Func):
7002    pass
7003
7004
7005# https://cloud.google.com/bigquery/docs/reference/standard-sql/date_functions#unix_date
7006class UnixDate(Func):
7007    pass
7008
7009
7010class UnixToStr(Func):
7011    arg_types = {"this": True, "format": False}
7012
7013
7014# https://prestodb.io/docs/current/functions/datetime.html
7015# presto has weird zone/hours/minutes
7016class UnixToTime(Func):
7017    arg_types = {
7018        "this": True,
7019        "scale": False,
7020        "zone": False,
7021        "hours": False,
7022        "minutes": False,
7023        "format": False,
7024    }
7025
7026    SECONDS = Literal.number(0)
7027    DECIS = Literal.number(1)
7028    CENTIS = Literal.number(2)
7029    MILLIS = Literal.number(3)
7030    DECIMILLIS = Literal.number(4)
7031    CENTIMILLIS = Literal.number(5)
7032    MICROS = Literal.number(6)
7033    DECIMICROS = Literal.number(7)
7034    CENTIMICROS = Literal.number(8)
7035    NANOS = Literal.number(9)
7036
7037
7038class UnixToTimeStr(Func):
7039    pass
7040
7041
7042class UnixSeconds(Func):
7043    pass
7044
7045
7046class Uuid(Func):
7047    _sql_names = ["UUID", "GEN_RANDOM_UUID", "GENERATE_UUID", "UUID_STRING"]
7048
7049    arg_types = {"this": False, "name": False}
7050
7051
7052class TimestampFromParts(Func):
7053    _sql_names = ["TIMESTAMP_FROM_PARTS", "TIMESTAMPFROMPARTS"]
7054    arg_types = {
7055        "year": True,
7056        "month": True,
7057        "day": True,
7058        "hour": True,
7059        "min": True,
7060        "sec": True,
7061        "nano": False,
7062        "zone": False,
7063        "milli": False,
7064    }
7065
7066
7067class Upper(Func):
7068    _sql_names = ["UPPER", "UCASE"]
7069
7070
7071class Corr(Binary, AggFunc):
7072    pass
7073
7074
7075class Variance(AggFunc):
7076    _sql_names = ["VARIANCE", "VARIANCE_SAMP", "VAR_SAMP"]
7077
7078
7079class VariancePop(AggFunc):
7080    _sql_names = ["VARIANCE_POP", "VAR_POP"]
7081
7082
7083class CovarSamp(Binary, AggFunc):
7084    pass
7085
7086
7087class CovarPop(Binary, AggFunc):
7088    pass
7089
7090
7091class Week(Func):
7092    arg_types = {"this": True, "mode": False}
7093
7094
7095class XMLElement(Func):
7096    _sql_names = ["XMLELEMENT"]
7097    arg_types = {"this": True, "expressions": False}
7098
7099
7100class XMLTable(Func):
7101    arg_types = {
7102        "this": True,
7103        "namespaces": False,
7104        "passing": False,
7105        "columns": False,
7106        "by_ref": False,
7107    }
7108
7109
7110class XMLNamespace(Expression):
7111    pass
7112
7113
7114# https://learn.microsoft.com/en-us/sql/t-sql/queries/select-for-clause-transact-sql?view=sql-server-ver17#syntax
7115class XMLKeyValueOption(Expression):
7116    arg_types = {"this": True, "expression": False}
7117
7118
7119class Year(Func):
7120    pass
7121
7122
7123class Use(Expression):
7124    arg_types = {"this": False, "expressions": False, "kind": False}
7125
7126
7127class Merge(DML):
7128    arg_types = {
7129        "this": True,
7130        "using": True,
7131        "on": True,
7132        "whens": True,
7133        "with": False,
7134        "returning": False,
7135    }
7136
7137
7138class When(Expression):
7139    arg_types = {"matched": True, "source": False, "condition": False, "then": True}
7140
7141
7142class Whens(Expression):
7143    """Wraps around one or more WHEN [NOT] MATCHED [...] clauses."""
7144
7145    arg_types = {"expressions": True}
7146
7147
7148# https://docs.oracle.com/javadb/10.8.3.0/ref/rrefsqljnextvaluefor.html
7149# https://learn.microsoft.com/en-us/sql/t-sql/functions/next-value-for-transact-sql?view=sql-server-ver16
7150class NextValueFor(Func):
7151    arg_types = {"this": True, "order": False}
7152
7153
7154# Refers to a trailing semi-colon. This is only used to preserve trailing comments
7155# select 1; -- my comment
7156class Semicolon(Expression):
7157    arg_types = {}
7158
7159
7160# BigQuery allows SELECT t FROM t and treats the projection as a struct value. This expression
7161# type is intended to be constructed by qualify so that we can properly annotate its type later
7162class TableColumn(Expression):
7163    pass
7164
7165
7166def _norm_arg(arg):
7167    return arg.lower() if type(arg) is str else arg
7168
7169
7170ALL_FUNCTIONS = subclasses(__name__, Func, (AggFunc, Anonymous, Func))
7171FUNCTION_BY_NAME = {name: func for func in ALL_FUNCTIONS for name in func.sql_names()}
7172
7173JSON_PATH_PARTS = subclasses(__name__, JSONPathPart, (JSONPathPart,))
7174
7175PERCENTILES = (PercentileCont, PercentileDisc)
7176
7177
7178# Helpers
7179@t.overload
7180def maybe_parse(
7181    sql_or_expression: ExpOrStr,
7182    *,
7183    into: t.Type[E],
7184    dialect: DialectType = None,
7185    prefix: t.Optional[str] = None,
7186    copy: bool = False,
7187    **opts,
7188) -> E: ...
7189
7190
7191@t.overload
7192def maybe_parse(
7193    sql_or_expression: str | E,
7194    *,
7195    into: t.Optional[IntoType] = None,
7196    dialect: DialectType = None,
7197    prefix: t.Optional[str] = None,
7198    copy: bool = False,
7199    **opts,
7200) -> E: ...
7201
7202
7203def maybe_parse(
7204    sql_or_expression: ExpOrStr,
7205    *,
7206    into: t.Optional[IntoType] = None,
7207    dialect: DialectType = None,
7208    prefix: t.Optional[str] = None,
7209    copy: bool = False,
7210    **opts,
7211) -> Expression:
7212    """Gracefully handle a possible string or expression.
7213
7214    Example:
7215        >>> maybe_parse("1")
7216        Literal(this=1, is_string=False)
7217        >>> maybe_parse(to_identifier("x"))
7218        Identifier(this=x, quoted=False)
7219
7220    Args:
7221        sql_or_expression: the SQL code string or an expression
7222        into: the SQLGlot Expression to parse into
7223        dialect: the dialect used to parse the input expressions (in the case that an
7224            input expression is a SQL string).
7225        prefix: a string to prefix the sql with before it gets parsed
7226            (automatically includes a space)
7227        copy: whether to copy the expression.
7228        **opts: other options to use to parse the input expressions (again, in the case
7229            that an input expression is a SQL string).
7230
7231    Returns:
7232        Expression: the parsed or given expression.
7233    """
7234    if isinstance(sql_or_expression, Expression):
7235        if copy:
7236            return sql_or_expression.copy()
7237        return sql_or_expression
7238
7239    if sql_or_expression is None:
7240        raise ParseError("SQL cannot be None")
7241
7242    import sqlglot
7243
7244    sql = str(sql_or_expression)
7245    if prefix:
7246        sql = f"{prefix} {sql}"
7247
7248    return sqlglot.parse_one(sql, read=dialect, into=into, **opts)
7249
7250
7251@t.overload
7252def maybe_copy(instance: None, copy: bool = True) -> None: ...
7253
7254
7255@t.overload
7256def maybe_copy(instance: E, copy: bool = True) -> E: ...
7257
7258
7259def maybe_copy(instance, copy=True):
7260    return instance.copy() if copy and instance else instance
7261
7262
7263def _to_s(node: t.Any, verbose: bool = False, level: int = 0, repr_str: bool = False) -> str:
7264    """Generate a textual representation of an Expression tree"""
7265    indent = "\n" + ("  " * (level + 1))
7266    delim = f",{indent}"
7267
7268    if isinstance(node, Expression):
7269        args = {k: v for k, v in node.args.items() if (v is not None and v != []) or verbose}
7270
7271        if (node.type or verbose) and not isinstance(node, DataType):
7272            args["_type"] = node.type
7273        if node.comments or verbose:
7274            args["_comments"] = node.comments
7275
7276        if verbose:
7277            args["_id"] = id(node)
7278
7279        # Inline leaves for a more compact representation
7280        if node.is_leaf():
7281            indent = ""
7282            delim = ", "
7283
7284        repr_str = node.is_string or (isinstance(node, Identifier) and node.quoted)
7285        items = delim.join(
7286            [f"{k}={_to_s(v, verbose, level + 1, repr_str=repr_str)}" for k, v in args.items()]
7287        )
7288        return f"{node.__class__.__name__}({indent}{items})"
7289
7290    if isinstance(node, list):
7291        items = delim.join(_to_s(i, verbose, level + 1) for i in node)
7292        items = f"{indent}{items}" if items else ""
7293        return f"[{items}]"
7294
7295    # We use the representation of the string to avoid stripping out important whitespace
7296    if repr_str and isinstance(node, str):
7297        node = repr(node)
7298
7299    # Indent multiline strings to match the current level
7300    return indent.join(textwrap.dedent(str(node).strip("\n")).splitlines())
7301
7302
7303def _is_wrong_expression(expression, into):
7304    return isinstance(expression, Expression) and not isinstance(expression, into)
7305
7306
7307def _apply_builder(
7308    expression,
7309    instance,
7310    arg,
7311    copy=True,
7312    prefix=None,
7313    into=None,
7314    dialect=None,
7315    into_arg="this",
7316    **opts,
7317):
7318    if _is_wrong_expression(expression, into):
7319        expression = into(**{into_arg: expression})
7320    instance = maybe_copy(instance, copy)
7321    expression = maybe_parse(
7322        sql_or_expression=expression,
7323        prefix=prefix,
7324        into=into,
7325        dialect=dialect,
7326        **opts,
7327    )
7328    instance.set(arg, expression)
7329    return instance
7330
7331
7332def _apply_child_list_builder(
7333    *expressions,
7334    instance,
7335    arg,
7336    append=True,
7337    copy=True,
7338    prefix=None,
7339    into=None,
7340    dialect=None,
7341    properties=None,
7342    **opts,
7343):
7344    instance = maybe_copy(instance, copy)
7345    parsed = []
7346    properties = {} if properties is None else properties
7347
7348    for expression in expressions:
7349        if expression is not None:
7350            if _is_wrong_expression(expression, into):
7351                expression = into(expressions=[expression])
7352
7353            expression = maybe_parse(
7354                expression,
7355                into=into,
7356                dialect=dialect,
7357                prefix=prefix,
7358                **opts,
7359            )
7360            for k, v in expression.args.items():
7361                if k == "expressions":
7362                    parsed.extend(v)
7363                else:
7364                    properties[k] = v
7365
7366    existing = instance.args.get(arg)
7367    if append and existing:
7368        parsed = existing.expressions + parsed
7369
7370    child = into(expressions=parsed)
7371    for k, v in properties.items():
7372        child.set(k, v)
7373    instance.set(arg, child)
7374
7375    return instance
7376
7377
7378def _apply_list_builder(
7379    *expressions,
7380    instance,
7381    arg,
7382    append=True,
7383    copy=True,
7384    prefix=None,
7385    into=None,
7386    dialect=None,
7387    **opts,
7388):
7389    inst = maybe_copy(instance, copy)
7390
7391    expressions = [
7392        maybe_parse(
7393            sql_or_expression=expression,
7394            into=into,
7395            prefix=prefix,
7396            dialect=dialect,
7397            **opts,
7398        )
7399        for expression in expressions
7400        if expression is not None
7401    ]
7402
7403    existing_expressions = inst.args.get(arg)
7404    if append and existing_expressions:
7405        expressions = existing_expressions + expressions
7406
7407    inst.set(arg, expressions)
7408    return inst
7409
7410
7411def _apply_conjunction_builder(
7412    *expressions,
7413    instance,
7414    arg,
7415    into=None,
7416    append=True,
7417    copy=True,
7418    dialect=None,
7419    **opts,
7420):
7421    expressions = [exp for exp in expressions if exp is not None and exp != ""]
7422    if not expressions:
7423        return instance
7424
7425    inst = maybe_copy(instance, copy)
7426
7427    existing = inst.args.get(arg)
7428    if append and existing is not None:
7429        expressions = [existing.this if into else existing] + list(expressions)
7430
7431    node = and_(*expressions, dialect=dialect, copy=copy, **opts)
7432
7433    inst.set(arg, into(this=node) if into else node)
7434    return inst
7435
7436
7437def _apply_cte_builder(
7438    instance: E,
7439    alias: ExpOrStr,
7440    as_: ExpOrStr,
7441    recursive: t.Optional[bool] = None,
7442    materialized: t.Optional[bool] = None,
7443    append: bool = True,
7444    dialect: DialectType = None,
7445    copy: bool = True,
7446    scalar: bool = False,
7447    **opts,
7448) -> E:
7449    alias_expression = maybe_parse(alias, dialect=dialect, into=TableAlias, **opts)
7450    as_expression = maybe_parse(as_, dialect=dialect, copy=copy, **opts)
7451    if scalar and not isinstance(as_expression, Subquery):
7452        # scalar CTE must be wrapped in a subquery
7453        as_expression = Subquery(this=as_expression)
7454    cte = CTE(this=as_expression, alias=alias_expression, materialized=materialized, scalar=scalar)
7455    return _apply_child_list_builder(
7456        cte,
7457        instance=instance,
7458        arg="with",
7459        append=append,
7460        copy=copy,
7461        into=With,
7462        properties={"recursive": recursive or False},
7463    )
7464
7465
7466def _combine(
7467    expressions: t.Sequence[t.Optional[ExpOrStr]],
7468    operator: t.Type[Connector],
7469    dialect: DialectType = None,
7470    copy: bool = True,
7471    wrap: bool = True,
7472    **opts,
7473) -> Expression:
7474    conditions = [
7475        condition(expression, dialect=dialect, copy=copy, **opts)
7476        for expression in expressions
7477        if expression is not None
7478    ]
7479
7480    this, *rest = conditions
7481    if rest and wrap:
7482        this = _wrap(this, Connector)
7483    for expression in rest:
7484        this = operator(this=this, expression=_wrap(expression, Connector) if wrap else expression)
7485
7486    return this
7487
7488
7489@t.overload
7490def _wrap(expression: None, kind: t.Type[Expression]) -> None: ...
7491
7492
7493@t.overload
7494def _wrap(expression: E, kind: t.Type[Expression]) -> E | Paren: ...
7495
7496
7497def _wrap(expression: t.Optional[E], kind: t.Type[Expression]) -> t.Optional[E] | Paren:
7498    return Paren(this=expression) if isinstance(expression, kind) else expression
7499
7500
7501def _apply_set_operation(
7502    *expressions: ExpOrStr,
7503    set_operation: t.Type[S],
7504    distinct: bool = True,
7505    dialect: DialectType = None,
7506    copy: bool = True,
7507    **opts,
7508) -> S:
7509    return reduce(
7510        lambda x, y: set_operation(this=x, expression=y, distinct=distinct, **opts),
7511        (maybe_parse(e, dialect=dialect, copy=copy, **opts) for e in expressions),
7512    )
7513
7514
7515def union(
7516    *expressions: ExpOrStr,
7517    distinct: bool = True,
7518    dialect: DialectType = None,
7519    copy: bool = True,
7520    **opts,
7521) -> Union:
7522    """
7523    Initializes a syntax tree for the `UNION` operation.
7524
7525    Example:
7526        >>> union("SELECT * FROM foo", "SELECT * FROM bla").sql()
7527        'SELECT * FROM foo UNION SELECT * FROM bla'
7528
7529    Args:
7530        expressions: the SQL code strings, corresponding to the `UNION`'s operands.
7531            If `Expression` instances are passed, they will be used as-is.
7532        distinct: set the DISTINCT flag if and only if this is true.
7533        dialect: the dialect used to parse the input expression.
7534        copy: whether to copy the expression.
7535        opts: other options to use to parse the input expressions.
7536
7537    Returns:
7538        The new Union instance.
7539    """
7540    assert len(expressions) >= 2, "At least two expressions are required by `union`."
7541    return _apply_set_operation(
7542        *expressions, set_operation=Union, distinct=distinct, dialect=dialect, copy=copy, **opts
7543    )
7544
7545
7546def intersect(
7547    *expressions: ExpOrStr,
7548    distinct: bool = True,
7549    dialect: DialectType = None,
7550    copy: bool = True,
7551    **opts,
7552) -> Intersect:
7553    """
7554    Initializes a syntax tree for the `INTERSECT` operation.
7555
7556    Example:
7557        >>> intersect("SELECT * FROM foo", "SELECT * FROM bla").sql()
7558        'SELECT * FROM foo INTERSECT SELECT * FROM bla'
7559
7560    Args:
7561        expressions: the SQL code strings, corresponding to the `INTERSECT`'s operands.
7562            If `Expression` instances are passed, they will be used as-is.
7563        distinct: set the DISTINCT flag if and only if this is true.
7564        dialect: the dialect used to parse the input expression.
7565        copy: whether to copy the expression.
7566        opts: other options to use to parse the input expressions.
7567
7568    Returns:
7569        The new Intersect instance.
7570    """
7571    assert len(expressions) >= 2, "At least two expressions are required by `intersect`."
7572    return _apply_set_operation(
7573        *expressions, set_operation=Intersect, distinct=distinct, dialect=dialect, copy=copy, **opts
7574    )
7575
7576
7577def except_(
7578    *expressions: ExpOrStr,
7579    distinct: bool = True,
7580    dialect: DialectType = None,
7581    copy: bool = True,
7582    **opts,
7583) -> Except:
7584    """
7585    Initializes a syntax tree for the `EXCEPT` operation.
7586
7587    Example:
7588        >>> except_("SELECT * FROM foo", "SELECT * FROM bla").sql()
7589        'SELECT * FROM foo EXCEPT SELECT * FROM bla'
7590
7591    Args:
7592        expressions: the SQL code strings, corresponding to the `EXCEPT`'s operands.
7593            If `Expression` instances are passed, they will be used as-is.
7594        distinct: set the DISTINCT flag if and only if this is true.
7595        dialect: the dialect used to parse the input expression.
7596        copy: whether to copy the expression.
7597        opts: other options to use to parse the input expressions.
7598
7599    Returns:
7600        The new Except instance.
7601    """
7602    assert len(expressions) >= 2, "At least two expressions are required by `except_`."
7603    return _apply_set_operation(
7604        *expressions, set_operation=Except, distinct=distinct, dialect=dialect, copy=copy, **opts
7605    )
7606
7607
7608def select(*expressions: ExpOrStr, dialect: DialectType = None, **opts) -> Select:
7609    """
7610    Initializes a syntax tree from one or multiple SELECT expressions.
7611
7612    Example:
7613        >>> select("col1", "col2").from_("tbl").sql()
7614        'SELECT col1, col2 FROM tbl'
7615
7616    Args:
7617        *expressions: the SQL code string to parse as the expressions of a
7618            SELECT statement. If an Expression instance is passed, this is used as-is.
7619        dialect: the dialect used to parse the input expressions (in the case that an
7620            input expression is a SQL string).
7621        **opts: other options to use to parse the input expressions (again, in the case
7622            that an input expression is a SQL string).
7623
7624    Returns:
7625        Select: the syntax tree for the SELECT statement.
7626    """
7627    return Select().select(*expressions, dialect=dialect, **opts)
7628
7629
7630def from_(expression: ExpOrStr, dialect: DialectType = None, **opts) -> Select:
7631    """
7632    Initializes a syntax tree from a FROM expression.
7633
7634    Example:
7635        >>> from_("tbl").select("col1", "col2").sql()
7636        'SELECT col1, col2 FROM tbl'
7637
7638    Args:
7639        *expression: the SQL code string to parse as the FROM expressions of a
7640            SELECT statement. If an Expression instance is passed, this is used as-is.
7641        dialect: the dialect used to parse the input expression (in the case that the
7642            input expression is a SQL string).
7643        **opts: other options to use to parse the input expressions (again, in the case
7644            that the input expression is a SQL string).
7645
7646    Returns:
7647        Select: the syntax tree for the SELECT statement.
7648    """
7649    return Select().from_(expression, dialect=dialect, **opts)
7650
7651
7652def update(
7653    table: str | Table,
7654    properties: t.Optional[dict] = None,
7655    where: t.Optional[ExpOrStr] = None,
7656    from_: t.Optional[ExpOrStr] = None,
7657    with_: t.Optional[t.Dict[str, ExpOrStr]] = None,
7658    dialect: DialectType = None,
7659    **opts,
7660) -> Update:
7661    """
7662    Creates an update statement.
7663
7664    Example:
7665        >>> update("my_table", {"x": 1, "y": "2", "z": None}, from_="baz_cte", where="baz_cte.id > 1 and my_table.id = baz_cte.id", with_={"baz_cte": "SELECT id FROM foo"}).sql()
7666        "WITH baz_cte AS (SELECT id FROM foo) UPDATE my_table SET x = 1, y = '2', z = NULL FROM baz_cte WHERE baz_cte.id > 1 AND my_table.id = baz_cte.id"
7667
7668    Args:
7669        properties: dictionary of properties to SET which are
7670            auto converted to sql objects eg None -> NULL
7671        where: sql conditional parsed into a WHERE statement
7672        from_: sql statement parsed into a FROM statement
7673        with_: dictionary of CTE aliases / select statements to include in a WITH clause.
7674        dialect: the dialect used to parse the input expressions.
7675        **opts: other options to use to parse the input expressions.
7676
7677    Returns:
7678        Update: the syntax tree for the UPDATE statement.
7679    """
7680    update_expr = Update(this=maybe_parse(table, into=Table, dialect=dialect))
7681    if properties:
7682        update_expr.set(
7683            "expressions",
7684            [
7685                EQ(this=maybe_parse(k, dialect=dialect, **opts), expression=convert(v))
7686                for k, v in properties.items()
7687            ],
7688        )
7689    if from_:
7690        update_expr.set(
7691            "from",
7692            maybe_parse(from_, into=From, dialect=dialect, prefix="FROM", **opts),
7693        )
7694    if isinstance(where, Condition):
7695        where = Where(this=where)
7696    if where:
7697        update_expr.set(
7698            "where",
7699            maybe_parse(where, into=Where, dialect=dialect, prefix="WHERE", **opts),
7700        )
7701    if with_:
7702        cte_list = [
7703            alias_(CTE(this=maybe_parse(qry, dialect=dialect, **opts)), alias, table=True)
7704            for alias, qry in with_.items()
7705        ]
7706        update_expr.set(
7707            "with",
7708            With(expressions=cte_list),
7709        )
7710    return update_expr
7711
7712
7713def delete(
7714    table: ExpOrStr,
7715    where: t.Optional[ExpOrStr] = None,
7716    returning: t.Optional[ExpOrStr] = None,
7717    dialect: DialectType = None,
7718    **opts,
7719) -> Delete:
7720    """
7721    Builds a delete statement.
7722
7723    Example:
7724        >>> delete("my_table", where="id > 1").sql()
7725        'DELETE FROM my_table WHERE id > 1'
7726
7727    Args:
7728        where: sql conditional parsed into a WHERE statement
7729        returning: sql conditional parsed into a RETURNING statement
7730        dialect: the dialect used to parse the input expressions.
7731        **opts: other options to use to parse the input expressions.
7732
7733    Returns:
7734        Delete: the syntax tree for the DELETE statement.
7735    """
7736    delete_expr = Delete().delete(table, dialect=dialect, copy=False, **opts)
7737    if where:
7738        delete_expr = delete_expr.where(where, dialect=dialect, copy=False, **opts)
7739    if returning:
7740        delete_expr = delete_expr.returning(returning, dialect=dialect, copy=False, **opts)
7741    return delete_expr
7742
7743
7744def insert(
7745    expression: ExpOrStr,
7746    into: ExpOrStr,
7747    columns: t.Optional[t.Sequence[str | Identifier]] = None,
7748    overwrite: t.Optional[bool] = None,
7749    returning: t.Optional[ExpOrStr] = None,
7750    dialect: DialectType = None,
7751    copy: bool = True,
7752    **opts,
7753) -> Insert:
7754    """
7755    Builds an INSERT statement.
7756
7757    Example:
7758        >>> insert("VALUES (1, 2, 3)", "tbl").sql()
7759        'INSERT INTO tbl VALUES (1, 2, 3)'
7760
7761    Args:
7762        expression: the sql string or expression of the INSERT statement
7763        into: the tbl to insert data to.
7764        columns: optionally the table's column names.
7765        overwrite: whether to INSERT OVERWRITE or not.
7766        returning: sql conditional parsed into a RETURNING statement
7767        dialect: the dialect used to parse the input expressions.
7768        copy: whether to copy the expression.
7769        **opts: other options to use to parse the input expressions.
7770
7771    Returns:
7772        Insert: the syntax tree for the INSERT statement.
7773    """
7774    expr = maybe_parse(expression, dialect=dialect, copy=copy, **opts)
7775    this: Table | Schema = maybe_parse(into, into=Table, dialect=dialect, copy=copy, **opts)
7776
7777    if columns:
7778        this = Schema(this=this, expressions=[to_identifier(c, copy=copy) for c in columns])
7779
7780    insert = Insert(this=this, expression=expr, overwrite=overwrite)
7781
7782    if returning:
7783        insert = insert.returning(returning, dialect=dialect, copy=False, **opts)
7784
7785    return insert
7786
7787
7788def merge(
7789    *when_exprs: ExpOrStr,
7790    into: ExpOrStr,
7791    using: ExpOrStr,
7792    on: ExpOrStr,
7793    returning: t.Optional[ExpOrStr] = None,
7794    dialect: DialectType = None,
7795    copy: bool = True,
7796    **opts,
7797) -> Merge:
7798    """
7799    Builds a MERGE statement.
7800
7801    Example:
7802        >>> merge("WHEN MATCHED THEN UPDATE SET col1 = source_table.col1",
7803        ...       "WHEN NOT MATCHED THEN INSERT (col1) VALUES (source_table.col1)",
7804        ...       into="my_table",
7805        ...       using="source_table",
7806        ...       on="my_table.id = source_table.id").sql()
7807        'MERGE INTO my_table USING source_table ON my_table.id = source_table.id WHEN MATCHED THEN UPDATE SET col1 = source_table.col1 WHEN NOT MATCHED THEN INSERT (col1) VALUES (source_table.col1)'
7808
7809    Args:
7810        *when_exprs: The WHEN clauses specifying actions for matched and unmatched rows.
7811        into: The target table to merge data into.
7812        using: The source table to merge data from.
7813        on: The join condition for the merge.
7814        returning: The columns to return from the merge.
7815        dialect: The dialect used to parse the input expressions.
7816        copy: Whether to copy the expression.
7817        **opts: Other options to use to parse the input expressions.
7818
7819    Returns:
7820        Merge: The syntax tree for the MERGE statement.
7821    """
7822    expressions: t.List[Expression] = []
7823    for when_expr in when_exprs:
7824        expression = maybe_parse(when_expr, dialect=dialect, copy=copy, into=Whens, **opts)
7825        expressions.extend([expression] if isinstance(expression, When) else expression.expressions)
7826
7827    merge = Merge(
7828        this=maybe_parse(into, dialect=dialect, copy=copy, **opts),
7829        using=maybe_parse(using, dialect=dialect, copy=copy, **opts),
7830        on=maybe_parse(on, dialect=dialect, copy=copy, **opts),
7831        whens=Whens(expressions=expressions),
7832    )
7833    if returning:
7834        merge = merge.returning(returning, dialect=dialect, copy=False, **opts)
7835
7836    return merge
7837
7838
7839def condition(
7840    expression: ExpOrStr, dialect: DialectType = None, copy: bool = True, **opts
7841) -> Condition:
7842    """
7843    Initialize a logical condition expression.
7844
7845    Example:
7846        >>> condition("x=1").sql()
7847        'x = 1'
7848
7849        This is helpful for composing larger logical syntax trees:
7850        >>> where = condition("x=1")
7851        >>> where = where.and_("y=1")
7852        >>> Select().from_("tbl").select("*").where(where).sql()
7853        'SELECT * FROM tbl WHERE x = 1 AND y = 1'
7854
7855    Args:
7856        *expression: the SQL code string to parse.
7857            If an Expression instance is passed, this is used as-is.
7858        dialect: the dialect used to parse the input expression (in the case that the
7859            input expression is a SQL string).
7860        copy: Whether to copy `expression` (only applies to expressions).
7861        **opts: other options to use to parse the input expressions (again, in the case
7862            that the input expression is a SQL string).
7863
7864    Returns:
7865        The new Condition instance
7866    """
7867    return maybe_parse(
7868        expression,
7869        into=Condition,
7870        dialect=dialect,
7871        copy=copy,
7872        **opts,
7873    )
7874
7875
7876def and_(
7877    *expressions: t.Optional[ExpOrStr],
7878    dialect: DialectType = None,
7879    copy: bool = True,
7880    wrap: bool = True,
7881    **opts,
7882) -> Condition:
7883    """
7884    Combine multiple conditions with an AND logical operator.
7885
7886    Example:
7887        >>> and_("x=1", and_("y=1", "z=1")).sql()
7888        'x = 1 AND (y = 1 AND z = 1)'
7889
7890    Args:
7891        *expressions: the SQL code strings to parse.
7892            If an Expression instance is passed, this is used as-is.
7893        dialect: the dialect used to parse the input expression.
7894        copy: whether to copy `expressions` (only applies to Expressions).
7895        wrap: whether to wrap the operands in `Paren`s. This is true by default to avoid
7896            precedence issues, but can be turned off when the produced AST is too deep and
7897            causes recursion-related issues.
7898        **opts: other options to use to parse the input expressions.
7899
7900    Returns:
7901        The new condition
7902    """
7903    return t.cast(Condition, _combine(expressions, And, dialect, copy=copy, wrap=wrap, **opts))
7904
7905
7906def or_(
7907    *expressions: t.Optional[ExpOrStr],
7908    dialect: DialectType = None,
7909    copy: bool = True,
7910    wrap: bool = True,
7911    **opts,
7912) -> Condition:
7913    """
7914    Combine multiple conditions with an OR logical operator.
7915
7916    Example:
7917        >>> or_("x=1", or_("y=1", "z=1")).sql()
7918        'x = 1 OR (y = 1 OR z = 1)'
7919
7920    Args:
7921        *expressions: the SQL code strings to parse.
7922            If an Expression instance is passed, this is used as-is.
7923        dialect: the dialect used to parse the input expression.
7924        copy: whether to copy `expressions` (only applies to Expressions).
7925        wrap: whether to wrap the operands in `Paren`s. This is true by default to avoid
7926            precedence issues, but can be turned off when the produced AST is too deep and
7927            causes recursion-related issues.
7928        **opts: other options to use to parse the input expressions.
7929
7930    Returns:
7931        The new condition
7932    """
7933    return t.cast(Condition, _combine(expressions, Or, dialect, copy=copy, wrap=wrap, **opts))
7934
7935
7936def xor(
7937    *expressions: t.Optional[ExpOrStr],
7938    dialect: DialectType = None,
7939    copy: bool = True,
7940    wrap: bool = True,
7941    **opts,
7942) -> Condition:
7943    """
7944    Combine multiple conditions with an XOR logical operator.
7945
7946    Example:
7947        >>> xor("x=1", xor("y=1", "z=1")).sql()
7948        'x = 1 XOR (y = 1 XOR z = 1)'
7949
7950    Args:
7951        *expressions: the SQL code strings to parse.
7952            If an Expression instance is passed, this is used as-is.
7953        dialect: the dialect used to parse the input expression.
7954        copy: whether to copy `expressions` (only applies to Expressions).
7955        wrap: whether to wrap the operands in `Paren`s. This is true by default to avoid
7956            precedence issues, but can be turned off when the produced AST is too deep and
7957            causes recursion-related issues.
7958        **opts: other options to use to parse the input expressions.
7959
7960    Returns:
7961        The new condition
7962    """
7963    return t.cast(Condition, _combine(expressions, Xor, dialect, copy=copy, wrap=wrap, **opts))
7964
7965
7966def not_(expression: ExpOrStr, dialect: DialectType = None, copy: bool = True, **opts) -> Not:
7967    """
7968    Wrap a condition with a NOT operator.
7969
7970    Example:
7971        >>> not_("this_suit='black'").sql()
7972        "NOT this_suit = 'black'"
7973
7974    Args:
7975        expression: the SQL code string to parse.
7976            If an Expression instance is passed, this is used as-is.
7977        dialect: the dialect used to parse the input expression.
7978        copy: whether to copy the expression or not.
7979        **opts: other options to use to parse the input expressions.
7980
7981    Returns:
7982        The new condition.
7983    """
7984    this = condition(
7985        expression,
7986        dialect=dialect,
7987        copy=copy,
7988        **opts,
7989    )
7990    return Not(this=_wrap(this, Connector))
7991
7992
7993def paren(expression: ExpOrStr, copy: bool = True) -> Paren:
7994    """
7995    Wrap an expression in parentheses.
7996
7997    Example:
7998        >>> paren("5 + 3").sql()
7999        '(5 + 3)'
8000
8001    Args:
8002        expression: the SQL code string to parse.
8003            If an Expression instance is passed, this is used as-is.
8004        copy: whether to copy the expression or not.
8005
8006    Returns:
8007        The wrapped expression.
8008    """
8009    return Paren(this=maybe_parse(expression, copy=copy))
8010
8011
8012SAFE_IDENTIFIER_RE: t.Pattern[str] = re.compile(r"^[_a-zA-Z][\w]*$")
8013
8014
8015@t.overload
8016def to_identifier(name: None, quoted: t.Optional[bool] = None, copy: bool = True) -> None: ...
8017
8018
8019@t.overload
8020def to_identifier(
8021    name: str | Identifier, quoted: t.Optional[bool] = None, copy: bool = True
8022) -> Identifier: ...
8023
8024
8025def to_identifier(name, quoted=None, copy=True):
8026    """Builds an identifier.
8027
8028    Args:
8029        name: The name to turn into an identifier.
8030        quoted: Whether to force quote the identifier.
8031        copy: Whether to copy name if it's an Identifier.
8032
8033    Returns:
8034        The identifier ast node.
8035    """
8036
8037    if name is None:
8038        return None
8039
8040    if isinstance(name, Identifier):
8041        identifier = maybe_copy(name, copy)
8042    elif isinstance(name, str):
8043        identifier = Identifier(
8044            this=name,
8045            quoted=not SAFE_IDENTIFIER_RE.match(name) if quoted is None else quoted,
8046        )
8047    else:
8048        raise ValueError(f"Name needs to be a string or an Identifier, got: {name.__class__}")
8049    return identifier
8050
8051
8052def parse_identifier(name: str | Identifier, dialect: DialectType = None) -> Identifier:
8053    """
8054    Parses a given string into an identifier.
8055
8056    Args:
8057        name: The name to parse into an identifier.
8058        dialect: The dialect to parse against.
8059
8060    Returns:
8061        The identifier ast node.
8062    """
8063    try:
8064        expression = maybe_parse(name, dialect=dialect, into=Identifier)
8065    except (ParseError, TokenError):
8066        expression = to_identifier(name)
8067
8068    return expression
8069
8070
8071INTERVAL_STRING_RE = re.compile(r"\s*(-?[0-9]+(?:\.[0-9]+)?)\s*([a-zA-Z]+)\s*")
8072
8073
8074def to_interval(interval: str | Literal) -> Interval:
8075    """Builds an interval expression from a string like '1 day' or '5 months'."""
8076    if isinstance(interval, Literal):
8077        if not interval.is_string:
8078            raise ValueError("Invalid interval string.")
8079
8080        interval = interval.this
8081
8082    interval = maybe_parse(f"INTERVAL {interval}")
8083    assert isinstance(interval, Interval)
8084    return interval
8085
8086
8087def to_table(
8088    sql_path: str | Table, dialect: DialectType = None, copy: bool = True, **kwargs
8089) -> Table:
8090    """
8091    Create a table expression from a `[catalog].[schema].[table]` sql path. Catalog and schema are optional.
8092    If a table is passed in then that table is returned.
8093
8094    Args:
8095        sql_path: a `[catalog].[schema].[table]` string.
8096        dialect: the source dialect according to which the table name will be parsed.
8097        copy: Whether to copy a table if it is passed in.
8098        kwargs: the kwargs to instantiate the resulting `Table` expression with.
8099
8100    Returns:
8101        A table expression.
8102    """
8103    if isinstance(sql_path, Table):
8104        return maybe_copy(sql_path, copy=copy)
8105
8106    try:
8107        table = maybe_parse(sql_path, into=Table, dialect=dialect)
8108    except ParseError:
8109        catalog, db, this = split_num_words(sql_path, ".", 3)
8110
8111        if not this:
8112            raise
8113
8114        table = table_(this, db=db, catalog=catalog)
8115
8116    for k, v in kwargs.items():
8117        table.set(k, v)
8118
8119    return table
8120
8121
8122def to_column(
8123    sql_path: str | Column,
8124    quoted: t.Optional[bool] = None,
8125    dialect: DialectType = None,
8126    copy: bool = True,
8127    **kwargs,
8128) -> Column:
8129    """
8130    Create a column from a `[table].[column]` sql path. Table is optional.
8131    If a column is passed in then that column is returned.
8132
8133    Args:
8134        sql_path: a `[table].[column]` string.
8135        quoted: Whether or not to force quote identifiers.
8136        dialect: the source dialect according to which the column name will be parsed.
8137        copy: Whether to copy a column if it is passed in.
8138        kwargs: the kwargs to instantiate the resulting `Column` expression with.
8139
8140    Returns:
8141        A column expression.
8142    """
8143    if isinstance(sql_path, Column):
8144        return maybe_copy(sql_path, copy=copy)
8145
8146    try:
8147        col = maybe_parse(sql_path, into=Column, dialect=dialect)
8148    except ParseError:
8149        return column(*reversed(sql_path.split(".")), quoted=quoted, **kwargs)
8150
8151    for k, v in kwargs.items():
8152        col.set(k, v)
8153
8154    if quoted:
8155        for i in col.find_all(Identifier):
8156            i.set("quoted", True)
8157
8158    return col
8159
8160
8161def alias_(
8162    expression: ExpOrStr,
8163    alias: t.Optional[str | Identifier],
8164    table: bool | t.Sequence[str | Identifier] = False,
8165    quoted: t.Optional[bool] = None,
8166    dialect: DialectType = None,
8167    copy: bool = True,
8168    **opts,
8169):
8170    """Create an Alias expression.
8171
8172    Example:
8173        >>> alias_('foo', 'bar').sql()
8174        'foo AS bar'
8175
8176        >>> alias_('(select 1, 2)', 'bar', table=['a', 'b']).sql()
8177        '(SELECT 1, 2) AS bar(a, b)'
8178
8179    Args:
8180        expression: the SQL code strings to parse.
8181            If an Expression instance is passed, this is used as-is.
8182        alias: the alias name to use. If the name has
8183            special characters it is quoted.
8184        table: Whether to create a table alias, can also be a list of columns.
8185        quoted: whether to quote the alias
8186        dialect: the dialect used to parse the input expression.
8187        copy: Whether to copy the expression.
8188        **opts: other options to use to parse the input expressions.
8189
8190    Returns:
8191        Alias: the aliased expression
8192    """
8193    exp = maybe_parse(expression, dialect=dialect, copy=copy, **opts)
8194    alias = to_identifier(alias, quoted=quoted)
8195
8196    if table:
8197        table_alias = TableAlias(this=alias)
8198        exp.set("alias", table_alias)
8199
8200        if not isinstance(table, bool):
8201            for column in table:
8202                table_alias.append("columns", to_identifier(column, quoted=quoted))
8203
8204        return exp
8205
8206    # We don't set the "alias" arg for Window expressions, because that would add an IDENTIFIER node in
8207    # the AST, representing a "named_window" [1] construct (eg. bigquery). What we want is an ALIAS node
8208    # for the complete Window expression.
8209    #
8210    # [1]: https://cloud.google.com/bigquery/docs/reference/standard-sql/window-function-calls
8211
8212    if "alias" in exp.arg_types and not isinstance(exp, Window):
8213        exp.set("alias", alias)
8214        return exp
8215    return Alias(this=exp, alias=alias)
8216
8217
8218def subquery(
8219    expression: ExpOrStr,
8220    alias: t.Optional[Identifier | str] = None,
8221    dialect: DialectType = None,
8222    **opts,
8223) -> Select:
8224    """
8225    Build a subquery expression that's selected from.
8226
8227    Example:
8228        >>> subquery('select x from tbl', 'bar').select('x').sql()
8229        'SELECT x FROM (SELECT x FROM tbl) AS bar'
8230
8231    Args:
8232        expression: the SQL code strings to parse.
8233            If an Expression instance is passed, this is used as-is.
8234        alias: the alias name to use.
8235        dialect: the dialect used to parse the input expression.
8236        **opts: other options to use to parse the input expressions.
8237
8238    Returns:
8239        A new Select instance with the subquery expression included.
8240    """
8241
8242    expression = maybe_parse(expression, dialect=dialect, **opts).subquery(alias, **opts)
8243    return Select().from_(expression, dialect=dialect, **opts)
8244
8245
8246@t.overload
8247def column(
8248    col: str | Identifier,
8249    table: t.Optional[str | Identifier] = None,
8250    db: t.Optional[str | Identifier] = None,
8251    catalog: t.Optional[str | Identifier] = None,
8252    *,
8253    fields: t.Collection[t.Union[str, Identifier]],
8254    quoted: t.Optional[bool] = None,
8255    copy: bool = True,
8256) -> Dot:
8257    pass
8258
8259
8260@t.overload
8261def column(
8262    col: str | Identifier | Star,
8263    table: t.Optional[str | Identifier] = None,
8264    db: t.Optional[str | Identifier] = None,
8265    catalog: t.Optional[str | Identifier] = None,
8266    *,
8267    fields: Lit[None] = None,
8268    quoted: t.Optional[bool] = None,
8269    copy: bool = True,
8270) -> Column:
8271    pass
8272
8273
8274def column(
8275    col,
8276    table=None,
8277    db=None,
8278    catalog=None,
8279    *,
8280    fields=None,
8281    quoted=None,
8282    copy=True,
8283):
8284    """
8285    Build a Column.
8286
8287    Args:
8288        col: Column name.
8289        table: Table name.
8290        db: Database name.
8291        catalog: Catalog name.
8292        fields: Additional fields using dots.
8293        quoted: Whether to force quotes on the column's identifiers.
8294        copy: Whether to copy identifiers if passed in.
8295
8296    Returns:
8297        The new Column instance.
8298    """
8299    if not isinstance(col, Star):
8300        col = to_identifier(col, quoted=quoted, copy=copy)
8301
8302    this = Column(
8303        this=col,
8304        table=to_identifier(table, quoted=quoted, copy=copy),
8305        db=to_identifier(db, quoted=quoted, copy=copy),
8306        catalog=to_identifier(catalog, quoted=quoted, copy=copy),
8307    )
8308
8309    if fields:
8310        this = Dot.build(
8311            (this, *(to_identifier(field, quoted=quoted, copy=copy) for field in fields))
8312        )
8313    return this
8314
8315
8316def cast(
8317    expression: ExpOrStr, to: DATA_TYPE, copy: bool = True, dialect: DialectType = None, **opts
8318) -> Cast:
8319    """Cast an expression to a data type.
8320
8321    Example:
8322        >>> cast('x + 1', 'int').sql()
8323        'CAST(x + 1 AS INT)'
8324
8325    Args:
8326        expression: The expression to cast.
8327        to: The datatype to cast to.
8328        copy: Whether to copy the supplied expressions.
8329        dialect: The target dialect. This is used to prevent a re-cast in the following scenario:
8330            - The expression to be cast is already a exp.Cast expression
8331            - The existing cast is to a type that is logically equivalent to new type
8332
8333            For example, if :expression='CAST(x as DATETIME)' and :to=Type.TIMESTAMP,
8334            but in the target dialect DATETIME is mapped to TIMESTAMP, then we will NOT return `CAST(x (as DATETIME) as TIMESTAMP)`
8335            and instead just return the original expression `CAST(x as DATETIME)`.
8336
8337            This is to prevent it being output as a double cast `CAST(x (as TIMESTAMP) as TIMESTAMP)` once the DATETIME -> TIMESTAMP
8338            mapping is applied in the target dialect generator.
8339
8340    Returns:
8341        The new Cast instance.
8342    """
8343    expr = maybe_parse(expression, copy=copy, dialect=dialect, **opts)
8344    data_type = DataType.build(to, copy=copy, dialect=dialect, **opts)
8345
8346    # dont re-cast if the expression is already a cast to the correct type
8347    if isinstance(expr, Cast):
8348        from sqlglot.dialects.dialect import Dialect
8349
8350        target_dialect = Dialect.get_or_raise(dialect)
8351        type_mapping = target_dialect.generator_class.TYPE_MAPPING
8352
8353        existing_cast_type: DataType.Type = expr.to.this
8354        new_cast_type: DataType.Type = data_type.this
8355        types_are_equivalent = type_mapping.get(
8356            existing_cast_type, existing_cast_type.value
8357        ) == type_mapping.get(new_cast_type, new_cast_type.value)
8358
8359        if expr.is_type(data_type) or types_are_equivalent:
8360            return expr
8361
8362    expr = Cast(this=expr, to=data_type)
8363    expr.type = data_type
8364
8365    return expr
8366
8367
8368def table_(
8369    table: Identifier | str,
8370    db: t.Optional[Identifier | str] = None,
8371    catalog: t.Optional[Identifier | str] = None,
8372    quoted: t.Optional[bool] = None,
8373    alias: t.Optional[Identifier | str] = None,
8374) -> Table:
8375    """Build a Table.
8376
8377    Args:
8378        table: Table name.
8379        db: Database name.
8380        catalog: Catalog name.
8381        quote: Whether to force quotes on the table's identifiers.
8382        alias: Table's alias.
8383
8384    Returns:
8385        The new Table instance.
8386    """
8387    return Table(
8388        this=to_identifier(table, quoted=quoted) if table else None,
8389        db=to_identifier(db, quoted=quoted) if db else None,
8390        catalog=to_identifier(catalog, quoted=quoted) if catalog else None,
8391        alias=TableAlias(this=to_identifier(alias)) if alias else None,
8392    )
8393
8394
8395def values(
8396    values: t.Iterable[t.Tuple[t.Any, ...]],
8397    alias: t.Optional[str] = None,
8398    columns: t.Optional[t.Iterable[str] | t.Dict[str, DataType]] = None,
8399) -> Values:
8400    """Build VALUES statement.
8401
8402    Example:
8403        >>> values([(1, '2')]).sql()
8404        "VALUES (1, '2')"
8405
8406    Args:
8407        values: values statements that will be converted to SQL
8408        alias: optional alias
8409        columns: Optional list of ordered column names or ordered dictionary of column names to types.
8410         If either are provided then an alias is also required.
8411
8412    Returns:
8413        Values: the Values expression object
8414    """
8415    if columns and not alias:
8416        raise ValueError("Alias is required when providing columns")
8417
8418    return Values(
8419        expressions=[convert(tup) for tup in values],
8420        alias=(
8421            TableAlias(this=to_identifier(alias), columns=[to_identifier(x) for x in columns])
8422            if columns
8423            else (TableAlias(this=to_identifier(alias)) if alias else None)
8424        ),
8425    )
8426
8427
8428def var(name: t.Optional[ExpOrStr]) -> Var:
8429    """Build a SQL variable.
8430
8431    Example:
8432        >>> repr(var('x'))
8433        'Var(this=x)'
8434
8435        >>> repr(var(column('x', table='y')))
8436        'Var(this=x)'
8437
8438    Args:
8439        name: The name of the var or an expression who's name will become the var.
8440
8441    Returns:
8442        The new variable node.
8443    """
8444    if not name:
8445        raise ValueError("Cannot convert empty name into var.")
8446
8447    if isinstance(name, Expression):
8448        name = name.name
8449    return Var(this=name)
8450
8451
8452def rename_table(
8453    old_name: str | Table,
8454    new_name: str | Table,
8455    dialect: DialectType = None,
8456) -> Alter:
8457    """Build ALTER TABLE... RENAME... expression
8458
8459    Args:
8460        old_name: The old name of the table
8461        new_name: The new name of the table
8462        dialect: The dialect to parse the table.
8463
8464    Returns:
8465        Alter table expression
8466    """
8467    old_table = to_table(old_name, dialect=dialect)
8468    new_table = to_table(new_name, dialect=dialect)
8469    return Alter(
8470        this=old_table,
8471        kind="TABLE",
8472        actions=[
8473            AlterRename(this=new_table),
8474        ],
8475    )
8476
8477
8478def rename_column(
8479    table_name: str | Table,
8480    old_column_name: str | Column,
8481    new_column_name: str | Column,
8482    exists: t.Optional[bool] = None,
8483    dialect: DialectType = None,
8484) -> Alter:
8485    """Build ALTER TABLE... RENAME COLUMN... expression
8486
8487    Args:
8488        table_name: Name of the table
8489        old_column: The old name of the column
8490        new_column: The new name of the column
8491        exists: Whether to add the `IF EXISTS` clause
8492        dialect: The dialect to parse the table/column.
8493
8494    Returns:
8495        Alter table expression
8496    """
8497    table = to_table(table_name, dialect=dialect)
8498    old_column = to_column(old_column_name, dialect=dialect)
8499    new_column = to_column(new_column_name, dialect=dialect)
8500    return Alter(
8501        this=table,
8502        kind="TABLE",
8503        actions=[
8504            RenameColumn(this=old_column, to=new_column, exists=exists),
8505        ],
8506    )
8507
8508
8509def convert(value: t.Any, copy: bool = False) -> Expression:
8510    """Convert a python value into an expression object.
8511
8512    Raises an error if a conversion is not possible.
8513
8514    Args:
8515        value: A python object.
8516        copy: Whether to copy `value` (only applies to Expressions and collections).
8517
8518    Returns:
8519        The equivalent expression object.
8520    """
8521    if isinstance(value, Expression):
8522        return maybe_copy(value, copy)
8523    if isinstance(value, str):
8524        return Literal.string(value)
8525    if isinstance(value, bool):
8526        return Boolean(this=value)
8527    if value is None or (isinstance(value, float) and math.isnan(value)):
8528        return null()
8529    if isinstance(value, numbers.Number):
8530        return Literal.number(value)
8531    if isinstance(value, bytes):
8532        return HexString(this=value.hex())
8533    if isinstance(value, datetime.datetime):
8534        datetime_literal = Literal.string(value.isoformat(sep=" "))
8535
8536        tz = None
8537        if value.tzinfo:
8538            # this works for zoneinfo.ZoneInfo, pytz.timezone and datetime.datetime.utc to return IANA timezone names like "America/Los_Angeles"
8539            # instead of abbreviations like "PDT". This is for consistency with other timezone handling functions in SQLGlot
8540            tz = Literal.string(str(value.tzinfo))
8541
8542        return TimeStrToTime(this=datetime_literal, zone=tz)
8543    if isinstance(value, datetime.date):
8544        date_literal = Literal.string(value.strftime("%Y-%m-%d"))
8545        return DateStrToDate(this=date_literal)
8546    if isinstance(value, datetime.time):
8547        time_literal = Literal.string(value.isoformat())
8548        return TsOrDsToTime(this=time_literal)
8549    if isinstance(value, tuple):
8550        if hasattr(value, "_fields"):
8551            return Struct(
8552                expressions=[
8553                    PropertyEQ(
8554                        this=to_identifier(k), expression=convert(getattr(value, k), copy=copy)
8555                    )
8556                    for k in value._fields
8557                ]
8558            )
8559        return Tuple(expressions=[convert(v, copy=copy) for v in value])
8560    if isinstance(value, list):
8561        return Array(expressions=[convert(v, copy=copy) for v in value])
8562    if isinstance(value, dict):
8563        return Map(
8564            keys=Array(expressions=[convert(k, copy=copy) for k in value]),
8565            values=Array(expressions=[convert(v, copy=copy) for v in value.values()]),
8566        )
8567    if hasattr(value, "__dict__"):
8568        return Struct(
8569            expressions=[
8570                PropertyEQ(this=to_identifier(k), expression=convert(v, copy=copy))
8571                for k, v in value.__dict__.items()
8572            ]
8573        )
8574    raise ValueError(f"Cannot convert {value}")
8575
8576
8577def replace_children(expression: Expression, fun: t.Callable, *args, **kwargs) -> None:
8578    """
8579    Replace children of an expression with the result of a lambda fun(child) -> exp.
8580    """
8581    for k, v in tuple(expression.args.items()):
8582        is_list_arg = type(v) is list
8583
8584        child_nodes = v if is_list_arg else [v]
8585        new_child_nodes = []
8586
8587        for cn in child_nodes:
8588            if isinstance(cn, Expression):
8589                for child_node in ensure_collection(fun(cn, *args, **kwargs)):
8590                    new_child_nodes.append(child_node)
8591            else:
8592                new_child_nodes.append(cn)
8593
8594        expression.set(k, new_child_nodes if is_list_arg else seq_get(new_child_nodes, 0))
8595
8596
8597def replace_tree(
8598    expression: Expression,
8599    fun: t.Callable,
8600    prune: t.Optional[t.Callable[[Expression], bool]] = None,
8601) -> Expression:
8602    """
8603    Replace an entire tree with the result of function calls on each node.
8604
8605    This will be traversed in reverse dfs, so leaves first.
8606    If new nodes are created as a result of function calls, they will also be traversed.
8607    """
8608    stack = list(expression.dfs(prune=prune))
8609
8610    while stack:
8611        node = stack.pop()
8612        new_node = fun(node)
8613
8614        if new_node is not node:
8615            node.replace(new_node)
8616
8617            if isinstance(new_node, Expression):
8618                stack.append(new_node)
8619
8620    return new_node
8621
8622
8623def column_table_names(expression: Expression, exclude: str = "") -> t.Set[str]:
8624    """
8625    Return all table names referenced through columns in an expression.
8626
8627    Example:
8628        >>> import sqlglot
8629        >>> sorted(column_table_names(sqlglot.parse_one("a.b AND c.d AND c.e")))
8630        ['a', 'c']
8631
8632    Args:
8633        expression: expression to find table names.
8634        exclude: a table name to exclude
8635
8636    Returns:
8637        A list of unique names.
8638    """
8639    return {
8640        table
8641        for table in (column.table for column in expression.find_all(Column))
8642        if table and table != exclude
8643    }
8644
8645
8646def table_name(table: Table | str, dialect: DialectType = None, identify: bool = False) -> str:
8647    """Get the full name of a table as a string.
8648
8649    Args:
8650        table: Table expression node or string.
8651        dialect: The dialect to generate the table name for.
8652        identify: Determines when an identifier should be quoted. Possible values are:
8653            False (default): Never quote, except in cases where it's mandatory by the dialect.
8654            True: Always quote.
8655
8656    Examples:
8657        >>> from sqlglot import exp, parse_one
8658        >>> table_name(parse_one("select * from a.b.c").find(exp.Table))
8659        'a.b.c'
8660
8661    Returns:
8662        The table name.
8663    """
8664
8665    table = maybe_parse(table, into=Table, dialect=dialect)
8666
8667    if not table:
8668        raise ValueError(f"Cannot parse {table}")
8669
8670    return ".".join(
8671        (
8672            part.sql(dialect=dialect, identify=True, copy=False, comments=False)
8673            if identify or not SAFE_IDENTIFIER_RE.match(part.name)
8674            else part.name
8675        )
8676        for part in table.parts
8677    )
8678
8679
8680def normalize_table_name(table: str | Table, dialect: DialectType = None, copy: bool = True) -> str:
8681    """Returns a case normalized table name without quotes.
8682
8683    Args:
8684        table: the table to normalize
8685        dialect: the dialect to use for normalization rules
8686        copy: whether to copy the expression.
8687
8688    Examples:
8689        >>> normalize_table_name("`A-B`.c", dialect="bigquery")
8690        'A-B.c'
8691    """
8692    from sqlglot.optimizer.normalize_identifiers import normalize_identifiers
8693
8694    return ".".join(
8695        p.name
8696        for p in normalize_identifiers(
8697            to_table(table, dialect=dialect, copy=copy), dialect=dialect
8698        ).parts
8699    )
8700
8701
8702def replace_tables(
8703    expression: E, mapping: t.Dict[str, str], dialect: DialectType = None, copy: bool = True
8704) -> E:
8705    """Replace all tables in expression according to the mapping.
8706
8707    Args:
8708        expression: expression node to be transformed and replaced.
8709        mapping: mapping of table names.
8710        dialect: the dialect of the mapping table
8711        copy: whether to copy the expression.
8712
8713    Examples:
8714        >>> from sqlglot import exp, parse_one
8715        >>> replace_tables(parse_one("select * from a.b"), {"a.b": "c"}).sql()
8716        'SELECT * FROM c /* a.b */'
8717
8718    Returns:
8719        The mapped expression.
8720    """
8721
8722    mapping = {normalize_table_name(k, dialect=dialect): v for k, v in mapping.items()}
8723
8724    def _replace_tables(node: Expression) -> Expression:
8725        if isinstance(node, Table) and node.meta.get("replace") is not False:
8726            original = normalize_table_name(node, dialect=dialect)
8727            new_name = mapping.get(original)
8728
8729            if new_name:
8730                table = to_table(
8731                    new_name,
8732                    **{k: v for k, v in node.args.items() if k not in TABLE_PARTS},
8733                    dialect=dialect,
8734                )
8735                table.add_comments([original])
8736                return table
8737        return node
8738
8739    return expression.transform(_replace_tables, copy=copy)  # type: ignore
8740
8741
8742def replace_placeholders(expression: Expression, *args, **kwargs) -> Expression:
8743    """Replace placeholders in an expression.
8744
8745    Args:
8746        expression: expression node to be transformed and replaced.
8747        args: positional names that will substitute unnamed placeholders in the given order.
8748        kwargs: keyword arguments that will substitute named placeholders.
8749
8750    Examples:
8751        >>> from sqlglot import exp, parse_one
8752        >>> replace_placeholders(
8753        ...     parse_one("select * from :tbl where ? = ?"),
8754        ...     exp.to_identifier("str_col"), "b", tbl=exp.to_identifier("foo")
8755        ... ).sql()
8756        "SELECT * FROM foo WHERE str_col = 'b'"
8757
8758    Returns:
8759        The mapped expression.
8760    """
8761
8762    def _replace_placeholders(node: Expression, args, **kwargs) -> Expression:
8763        if isinstance(node, Placeholder):
8764            if node.this:
8765                new_name = kwargs.get(node.this)
8766                if new_name is not None:
8767                    return convert(new_name)
8768            else:
8769                try:
8770                    return convert(next(args))
8771                except StopIteration:
8772                    pass
8773        return node
8774
8775    return expression.transform(_replace_placeholders, iter(args), **kwargs)
8776
8777
8778def expand(
8779    expression: Expression,
8780    sources: t.Dict[str, Query | t.Callable[[], Query]],
8781    dialect: DialectType = None,
8782    copy: bool = True,
8783) -> Expression:
8784    """Transforms an expression by expanding all referenced sources into subqueries.
8785
8786    Examples:
8787        >>> from sqlglot import parse_one
8788        >>> expand(parse_one("select * from x AS z"), {"x": parse_one("select * from y")}).sql()
8789        'SELECT * FROM (SELECT * FROM y) AS z /* source: x */'
8790
8791        >>> expand(parse_one("select * from x AS z"), {"x": parse_one("select * from y"), "y": parse_one("select * from z")}).sql()
8792        'SELECT * FROM (SELECT * FROM (SELECT * FROM z) AS y /* source: y */) AS z /* source: x */'
8793
8794    Args:
8795        expression: The expression to expand.
8796        sources: A dict of name to query or a callable that provides a query on demand.
8797        dialect: The dialect of the sources dict or the callable.
8798        copy: Whether to copy the expression during transformation. Defaults to True.
8799
8800    Returns:
8801        The transformed expression.
8802    """
8803    normalized_sources = {normalize_table_name(k, dialect=dialect): v for k, v in sources.items()}
8804
8805    def _expand(node: Expression):
8806        if isinstance(node, Table):
8807            name = normalize_table_name(node, dialect=dialect)
8808            source = normalized_sources.get(name)
8809
8810            if source:
8811                # Create a subquery with the same alias (or table name if no alias)
8812                parsed_source = source() if callable(source) else source
8813                subquery = parsed_source.subquery(node.alias or name)
8814                subquery.comments = [f"source: {name}"]
8815
8816                # Continue expanding within the subquery
8817                return subquery.transform(_expand, copy=False)
8818
8819        return node
8820
8821    return expression.transform(_expand, copy=copy)
8822
8823
8824def func(name: str, *args, copy: bool = True, dialect: DialectType = None, **kwargs) -> Func:
8825    """
8826    Returns a Func expression.
8827
8828    Examples:
8829        >>> func("abs", 5).sql()
8830        'ABS(5)'
8831
8832        >>> func("cast", this=5, to=DataType.build("DOUBLE")).sql()
8833        'CAST(5 AS DOUBLE)'
8834
8835    Args:
8836        name: the name of the function to build.
8837        args: the args used to instantiate the function of interest.
8838        copy: whether to copy the argument expressions.
8839        dialect: the source dialect.
8840        kwargs: the kwargs used to instantiate the function of interest.
8841
8842    Note:
8843        The arguments `args` and `kwargs` are mutually exclusive.
8844
8845    Returns:
8846        An instance of the function of interest, or an anonymous function, if `name` doesn't
8847        correspond to an existing `sqlglot.expressions.Func` class.
8848    """
8849    if args and kwargs:
8850        raise ValueError("Can't use both args and kwargs to instantiate a function.")
8851
8852    from sqlglot.dialects.dialect import Dialect
8853
8854    dialect = Dialect.get_or_raise(dialect)
8855
8856    converted: t.List[Expression] = [maybe_parse(arg, dialect=dialect, copy=copy) for arg in args]
8857    kwargs = {key: maybe_parse(value, dialect=dialect, copy=copy) for key, value in kwargs.items()}
8858
8859    constructor = dialect.parser_class.FUNCTIONS.get(name.upper())
8860    if constructor:
8861        if converted:
8862            if "dialect" in constructor.__code__.co_varnames:
8863                function = constructor(converted, dialect=dialect)
8864            else:
8865                function = constructor(converted)
8866        elif constructor.__name__ == "from_arg_list":
8867            function = constructor.__self__(**kwargs)  # type: ignore
8868        else:
8869            constructor = FUNCTION_BY_NAME.get(name.upper())
8870            if constructor:
8871                function = constructor(**kwargs)
8872            else:
8873                raise ValueError(
8874                    f"Unable to convert '{name}' into a Func. Either manually construct "
8875                    "the Func expression of interest or parse the function call."
8876                )
8877    else:
8878        kwargs = kwargs or {"expressions": converted}
8879        function = Anonymous(this=name, **kwargs)
8880
8881    for error_message in function.error_messages(converted):
8882        raise ValueError(error_message)
8883
8884    return function
8885
8886
8887def case(
8888    expression: t.Optional[ExpOrStr] = None,
8889    **opts,
8890) -> Case:
8891    """
8892    Initialize a CASE statement.
8893
8894    Example:
8895        case().when("a = 1", "foo").else_("bar")
8896
8897    Args:
8898        expression: Optionally, the input expression (not all dialects support this)
8899        **opts: Extra keyword arguments for parsing `expression`
8900    """
8901    if expression is not None:
8902        this = maybe_parse(expression, **opts)
8903    else:
8904        this = None
8905    return Case(this=this, ifs=[])
8906
8907
8908def array(
8909    *expressions: ExpOrStr, copy: bool = True, dialect: DialectType = None, **kwargs
8910) -> Array:
8911    """
8912    Returns an array.
8913
8914    Examples:
8915        >>> array(1, 'x').sql()
8916        'ARRAY(1, x)'
8917
8918    Args:
8919        expressions: the expressions to add to the array.
8920        copy: whether to copy the argument expressions.
8921        dialect: the source dialect.
8922        kwargs: the kwargs used to instantiate the function of interest.
8923
8924    Returns:
8925        An array expression.
8926    """
8927    return Array(
8928        expressions=[
8929            maybe_parse(expression, copy=copy, dialect=dialect, **kwargs)
8930            for expression in expressions
8931        ]
8932    )
8933
8934
8935def tuple_(
8936    *expressions: ExpOrStr, copy: bool = True, dialect: DialectType = None, **kwargs
8937) -> Tuple:
8938    """
8939    Returns an tuple.
8940
8941    Examples:
8942        >>> tuple_(1, 'x').sql()
8943        '(1, x)'
8944
8945    Args:
8946        expressions: the expressions to add to the tuple.
8947        copy: whether to copy the argument expressions.
8948        dialect: the source dialect.
8949        kwargs: the kwargs used to instantiate the function of interest.
8950
8951    Returns:
8952        A tuple expression.
8953    """
8954    return Tuple(
8955        expressions=[
8956            maybe_parse(expression, copy=copy, dialect=dialect, **kwargs)
8957            for expression in expressions
8958        ]
8959    )
8960
8961
8962def true() -> Boolean:
8963    """
8964    Returns a true Boolean expression.
8965    """
8966    return Boolean(this=True)
8967
8968
8969def false() -> Boolean:
8970    """
8971    Returns a false Boolean expression.
8972    """
8973    return Boolean(this=False)
8974
8975
8976def null() -> Null:
8977    """
8978    Returns a Null expression.
8979    """
8980    return Null()
8981
8982
8983NONNULL_CONSTANTS = (
8984    Literal,
8985    Boolean,
8986)
8987
8988CONSTANTS = (
8989    Literal,
8990    Boolean,
8991    Null,
8992)