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