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