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