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