1"""sqlglot expressions core - base classes, traits, operators, and helpers."""
   2
   3from __future__ import annotations
   4
   5import datetime
   6import logging
   7import math
   8import numbers
   9import re
  10import sys
  11import textwrap
  12import typing as t
  13from builtins import type as Type
  14from collections import deque
  15from collections.abc import Collection, Iterator, Mapping, MutableMapping, Sequence
  16from copy import deepcopy
  17from decimal import Decimal, InvalidOperation
  18from functools import reduce
  19
  20from sqlglot._typing import E, GeneratorNoDialectArgs, ParserNoDialectArgs, T
  21from sqlglot.errors import ParseError
  22from sqlglot.helper import (
  23    camel_to_snake_case,
  24    ensure_list,
  25    seq_get,
  26    to_bool,
  27    trait,
  28)
  29from sqlglot.tokenizer_core import Token
  30
  31if t.TYPE_CHECKING:
  32    from typing_extensions import Concatenate, Self, Unpack
  33
  34    from sqlglot._typing import P
  35    from sqlglot.dialects.dialect import DialectType
  36    from sqlglot.expressions.datatypes import DATA_TYPE, DataType, DType, Interval
  37    from sqlglot.expressions.query import Select
  38
  39    R = t.TypeVar("R")
  40
  41logger = logging.getLogger("sqlglot")
  42
  43SQLGLOT_META: str = "sqlglot.meta"
  44SQLGLOT_ANONYMOUS = "sqlglot.anonymous"
  45TABLE_PARTS = ("this", "db", "catalog")
  46COLUMN_PARTS = ("this", "table", "db", "catalog")
  47POSITION_META_KEYS: tuple[str, ...] = ("line", "col", "start", "end")
  48UNITTEST: bool = "unittest" in sys.modules or "pytest" in sys.modules
  49
  50
  51@trait
  52class Expr:
  53    """
  54    The base class for all expressions in a syntax tree. Each Expr encapsulates any necessary
  55    context, such as its child expressions, their names (arg keys), and whether a given child expression
  56    is optional or not.
  57
  58    Attributes:
  59        key: a unique key for each class in the Expr hierarchy. This is useful for hashing
  60            and representing expressions as strings.
  61        arg_types: determines the arguments (child nodes) supported by an expression. It maps
  62            arg keys to booleans that indicate whether the corresponding args are optional.
  63        parent: a reference to the parent expression (or None, in case of root expressions).
  64        arg_key: the arg key an expression is associated with, i.e. the name its parent expression
  65            uses to refer to it.
  66        index: the index of an expression if it is inside of a list argument in its parent.
  67        comments: a list of comments that are associated with a given expression. This is used in
  68            order to preserve comments when transpiling SQL code.
  69        type: the `sqlglot.expressions.DataType` type of an expression. This is inferred by the
  70            optimizer, in order to enable some transformations that require type information.
  71        meta: a dictionary that can be used to store useful metadata for a given expression.
  72
  73    Example:
  74        >>> class Foo(Expr):
  75        ...     arg_types = {"this": True, "expression": False}
  76
  77        The above definition informs us that Foo is an Expr that requires an argument called
  78        "this" and may also optionally receive an argument called "expression".
  79
  80    Args:
  81        args: a mapping used for retrieving the arguments of an expression, given their arg keys.
  82    """
  83
  84    key: t.ClassVar[str] = "expression"
  85    arg_types: t.ClassVar[dict[str, bool]] = {"this": True}
  86    required_args: t.ClassVar[set[str]] = {"this"}
  87    is_var_len_args: t.ClassVar[bool] = False
  88    var_len_arg_key: t.ClassVar[str] = "expressions"
  89    _hash_raw_args: t.ClassVar[bool] = False
  90    is_subquery: t.ClassVar[bool] = False
  91    is_cast: t.ClassVar[bool] = False
  92    is_data_type: t.ClassVar[bool] = False
  93
  94    args: dict[str, t.Any]
  95    parent: Expr | None
  96    arg_key: str | None
  97    index: int | None
  98    comments: list[str] | None
  99    _type: DataType | None
 100    _meta: dict[str, t.Any] | None
 101    _hash: int | None
 102
 103    @classmethod
 104    def __init_subclass__(cls, **kwargs: t.Any) -> None:
 105        super().__init_subclass__(**kwargs)
 106        # When an Expr class is created, its key is automatically set
 107        # to be the lowercase version of the class' name.
 108        cls.key = cls.__name__.lower()
 109        cls.required_args = {k for k, v in cls.arg_types.items() if v}
 110        # This is so that docstrings are not inherited in pdoc
 111        setattr(cls, "__doc__", getattr(cls, "__doc__", None) or "")
 112
 113    is_primitive: t.ClassVar[bool] = False
 114
 115    def __init__(self, **args: object) -> None:
 116        self.args: dict[str, t.Any] = args
 117        self.parent: Expr | None = None
 118        self.arg_key: str | None = None
 119        self.index: int | None = None
 120        self.comments: list[str] | None = None
 121        self._type: DataType | None = None
 122        self._meta: dict[str, t.Any] | None = None
 123        self._hash: int | None = None
 124
 125        if not self.is_primitive:
 126            for arg_key, value in self.args.items():
 127                self._set_parent(arg_key, value)
 128
 129    @property
 130    def this(self) -> t.Any:
 131        """
 132        Retrieves the argument with key "this".
 133        """
 134        raise NotImplementedError
 135
 136    @property
 137    def expression(self) -> t.Any:
 138        """
 139        Retrieves the argument with key "expression".
 140        """
 141        raise NotImplementedError
 142
 143    @property
 144    def expressions(self) -> list[t.Any]:
 145        """
 146        Retrieves the argument with key "expressions".
 147        """
 148        raise NotImplementedError
 149
 150    def text(self, key: str) -> str:
 151        """
 152        Returns a textual representation of the argument corresponding to "key". This can only be used
 153        for args that are strings or leaf Expr instances, such as identifiers and literals.
 154        """
 155        raise NotImplementedError
 156
 157    @property
 158    def is_string(self) -> bool:
 159        """
 160        Checks whether a Literal expression is a string.
 161        """
 162        raise NotImplementedError
 163
 164    @property
 165    def is_number(self) -> bool:
 166        """
 167        Checks whether a Literal expression is a number.
 168        """
 169        raise NotImplementedError
 170
 171    def to_py(self) -> t.Any:
 172        """
 173        Returns a Python object equivalent of the SQL node.
 174        """
 175        raise NotImplementedError
 176
 177    @property
 178    def is_int(self) -> bool:
 179        """
 180        Checks whether an expression is an integer.
 181        """
 182        raise NotImplementedError
 183
 184    @property
 185    def is_star(self) -> bool:
 186        """Checks whether an expression is a star."""
 187        raise NotImplementedError
 188
 189    @property
 190    def alias(self) -> str:
 191        """
 192        Returns the alias of the expression, or an empty string if it's not aliased.
 193        """
 194        raise NotImplementedError
 195
 196    @property
 197    def alias_column_names(self) -> list[str]:
 198        raise NotImplementedError
 199
 200    @property
 201    def name(self) -> str:
 202        raise NotImplementedError
 203
 204    @property
 205    def alias_or_name(self) -> str:
 206        raise NotImplementedError
 207
 208    @property
 209    def output_name(self) -> str:
 210        """
 211        Name of the output column if this expression is a selection.
 212
 213        If the Expr has no output name, an empty string is returned.
 214
 215        Example:
 216            >>> from sqlglot import parse_one
 217            >>> parse_one("SELECT a").expressions[0].output_name
 218            'a'
 219            >>> parse_one("SELECT b AS c").expressions[0].output_name
 220            'c'
 221            >>> parse_one("SELECT 1 + 2").expressions[0].output_name
 222            ''
 223        """
 224        raise NotImplementedError
 225
 226    @property
 227    def type(self) -> DataType | None:
 228        raise NotImplementedError
 229
 230    @type.setter
 231    def type(self, dtype: DataType | DType | str | None) -> None:
 232        raise NotImplementedError
 233
 234    def is_type(self, *dtypes: DATA_TYPE) -> bool:
 235        raise NotImplementedError
 236
 237    def is_leaf(self) -> bool:
 238        raise NotImplementedError
 239
 240    @property
 241    def meta(self) -> dict[str, t.Any]:
 242        raise NotImplementedError
 243
 244    def meta_get(self, key: str, default: t.Any = None) -> t.Any:
 245        raise NotImplementedError
 246
 247    def __deepcopy__(self, memo: t.Any) -> Expr:
 248        raise NotImplementedError
 249
 250    def copy(self: E) -> E:
 251        """
 252        Returns a deep copy of the expression.
 253        """
 254        raise NotImplementedError
 255
 256    def add_comments(self, comments: list[str] | None = None, prepend: bool = False) -> None:
 257        raise NotImplementedError
 258
 259    def pop_comments(self) -> list[str]:
 260        raise NotImplementedError
 261
 262    def append(self, arg_key: str, value: t.Any) -> None:
 263        """
 264        Appends value to arg_key if it's a list or sets it as a new list.
 265
 266        Args:
 267            arg_key (str): name of the list expression arg
 268            value (Any): value to append to the list
 269        """
 270        raise NotImplementedError
 271
 272    def set(
 273        self,
 274        arg_key: str,
 275        value: object,
 276        index: int | None = None,
 277        overwrite: bool = True,
 278    ) -> None:
 279        """
 280        Sets arg_key to value.
 281
 282        Args:
 283            arg_key: name of the expression arg.
 284            value: value to set the arg to.
 285            index: if the arg is a list, this specifies what position to add the value in it.
 286            overwrite: assuming an index is given, this determines whether to overwrite the
 287                list entry instead of only inserting a new value (i.e., like list.insert).
 288        """
 289        raise NotImplementedError
 290
 291    def _set_parent(self, arg_key: str, value: object, index: int | None = None) -> None:
 292        raise NotImplementedError
 293
 294    @property
 295    def depth(self) -> int:
 296        """
 297        Returns the depth of this tree.
 298        """
 299        raise NotImplementedError
 300
 301    def iter_expressions(self: E, reverse: bool = False) -> Iterator[E]:
 302        """Yields the key and expression for all arguments, exploding list args."""
 303        raise NotImplementedError
 304
 305    def find(self, *expression_types: Type[E], bfs: bool = True) -> E | None:
 306        """
 307        Returns the first node in this tree which matches at least one of
 308        the specified types.
 309
 310        Args:
 311            expression_types: the expression type(s) to match.
 312            bfs: whether to search the AST using the BFS algorithm (DFS is used if false).
 313
 314        Returns:
 315            The node which matches the criteria or None if no such node was found.
 316        """
 317        raise NotImplementedError
 318
 319    def find_all(self, *expression_types: Type[E], bfs: bool = True) -> Iterator[E]:
 320        """
 321        Returns a generator object which visits all nodes in this tree and only
 322        yields those that match at least one of the specified expression types.
 323
 324        Args:
 325            expression_types: the expression type(s) to match.
 326            bfs: whether to search the AST using the BFS algorithm (DFS is used if false).
 327
 328        Returns:
 329            The generator object.
 330        """
 331        raise NotImplementedError
 332
 333    def find_ancestor(self, *expression_types: Type[E]) -> E | None:
 334        """
 335        Returns a nearest parent matching expression_types.
 336
 337        Args:
 338            expression_types: the expression type(s) to match.
 339
 340        Returns:
 341            The parent node.
 342        """
 343        raise NotImplementedError
 344
 345    @property
 346    def parent_select(self) -> Select | None:
 347        """
 348        Returns the parent select statement.
 349        """
 350        raise NotImplementedError
 351
 352    @property
 353    def same_parent(self) -> bool:
 354        """Returns if the parent is the same class as itself."""
 355        raise NotImplementedError
 356
 357    def root(self) -> Expr:
 358        """
 359        Returns the root expression of this tree.
 360        """
 361        raise NotImplementedError
 362
 363    def walk(
 364        self, bfs: bool = True, prune: t.Callable[[Expr], bool] | None = None
 365    ) -> Iterator[Expr]:
 366        """
 367        Returns a generator object which visits all nodes in this tree.
 368
 369        Args:
 370            bfs: if set to True the BFS traversal order will be applied,
 371                otherwise the DFS traversal will be used instead.
 372            prune: callable that returns True if the generator should stop traversing
 373                this branch of the tree.
 374
 375        Returns:
 376            the generator object.
 377        """
 378        raise NotImplementedError
 379
 380    def dfs(self, prune: t.Callable[[Expr], bool] | None = None) -> Iterator[Expr]:
 381        """
 382        Returns a generator object which visits all nodes in this tree in
 383        the DFS (Depth-first) order.
 384
 385        Returns:
 386            The generator object.
 387        """
 388        raise NotImplementedError
 389
 390    def bfs(self, prune: t.Callable[[Expr], bool] | None = None) -> Iterator[Expr]:
 391        """
 392        Returns a generator object which visits all nodes in this tree in
 393        the BFS (Breadth-first) order.
 394
 395        Returns:
 396            The generator object.
 397        """
 398        raise NotImplementedError
 399
 400    def unnest(self) -> Expr:
 401        """
 402        Returns the first non parenthesis child or self.
 403        """
 404        raise NotImplementedError
 405
 406    def unalias(self) -> Expr:
 407        """
 408        Returns the inner expression if this is an Alias.
 409        """
 410        raise NotImplementedError
 411
 412    def unnest_operands(self) -> tuple[Expr, ...]:
 413        """
 414        Returns unnested operands as a tuple.
 415        """
 416        raise NotImplementedError
 417
 418    def flatten(self, unnest: bool = True) -> Iterator[Expr]:
 419        """
 420        Returns a generator which yields child nodes whose parents are the same class.
 421
 422        A AND B AND C -> [A, B, C]
 423        """
 424        raise NotImplementedError
 425
 426    def to_s(self) -> str:
 427        """
 428        Same as __repr__, but includes additional information which can be useful
 429        for debugging, like empty or missing args and the AST nodes' object IDs.
 430        """
 431        raise NotImplementedError
 432
 433    def sql(
 434        self, dialect: DialectType = None, copy: bool = True, **opts: Unpack[GeneratorNoDialectArgs]
 435    ) -> str:
 436        """
 437        Returns SQL string representation of this tree.
 438
 439        Args:
 440            dialect: the dialect of the output SQL string (eg. "spark", "hive", "presto", "mysql").
 441            opts: other `sqlglot.generator.Generator` options.
 442
 443        Returns:
 444            The SQL string.
 445        """
 446        raise NotImplementedError
 447
 448    def transform(
 449        self, fun: t.Callable[..., T], *args: object, copy: bool = True, **kwargs: object
 450    ) -> T:
 451        """
 452        Visits all tree nodes (excluding already transformed ones)
 453        and applies the given transformation function to each node.
 454
 455        Args:
 456            fun: a function which takes a node as an argument and returns a
 457                new transformed node or the same node without modifications. If the function
 458                returns None, then the corresponding node will be removed from the syntax tree.
 459            copy: if set to True a new tree instance is constructed, otherwise the tree is
 460                modified in place.
 461
 462        Returns:
 463            The transformed tree.
 464        """
 465        raise NotImplementedError
 466
 467    def replace(self, expression: T) -> T:
 468        """
 469        Swap out this expression with a new expression.
 470
 471        For example::
 472
 473            >>> import sqlglot
 474            >>> tree = sqlglot.parse_one("SELECT x FROM tbl")
 475            >>> tree.find(sqlglot.exp.Column).replace(sqlglot.exp.column("y"))
 476            Column(
 477              this=Identifier(this=y, quoted=False))
 478            >>> tree.sql()
 479            'SELECT y FROM tbl'
 480
 481        Args:
 482            expression (T): new node
 483
 484        Returns:
 485            T: The new expression or expressions.
 486        """
 487        raise NotImplementedError
 488
 489    def pop(self: E) -> E:
 490        """
 491        Remove this expression from its AST.
 492
 493        Returns:
 494            The popped expression.
 495        """
 496        raise NotImplementedError
 497
 498    def assert_is(self, type_: Type[E]) -> E:
 499        """
 500        Assert that this `Expr` is an instance of `type_`.
 501
 502        If it is NOT an instance of `type_`, this raises an assertion error.
 503        Otherwise, this returns this expression.
 504
 505        Examples:
 506            This is useful for type security in chained expressions:
 507
 508            >>> import sqlglot
 509            >>> sqlglot.parse_one("SELECT x from y").assert_is(sqlglot.exp.Select).select("z").sql()
 510            'SELECT x, z FROM y'
 511        """
 512        raise NotImplementedError
 513
 514    def error_messages(self, args: Sequence[object] | None = None) -> list[str]:
 515        """
 516        Checks if this expression is valid (e.g. all mandatory args are set).
 517
 518        Args:
 519            args: a sequence of values that were used to instantiate a Func expression. This is used
 520                to check that the provided arguments don't exceed the function argument limit.
 521
 522        Returns:
 523            A list of error messages for all possible errors that were found.
 524        """
 525        raise NotImplementedError
 526
 527    def dump(self) -> list[dict[str, t.Any]]:
 528        """
 529        Dump this Expr to a JSON-serializable dict.
 530        """
 531        from sqlglot.serde import dump
 532
 533        return dump(self)
 534
 535    @classmethod
 536    def load(cls, obj: list[dict[str, Any]] | None) -> Expr:
 537        """
 538        Load a dict (as returned by `Expr.dump`) into an Expr instance.
 539        """
 540        from sqlglot.serde import load
 541
 542        result = load(obj)
 543        assert isinstance(result, Expr)
 544        return result
 545
 546    def and_(
 547        self,
 548        *expressions: ExpOrStr | None,
 549        dialect: DialectType = None,
 550        copy: bool = True,
 551        wrap: bool = True,
 552        **opts: Unpack[ParserNoDialectArgs],
 553    ) -> Condition:
 554        """
 555        AND this condition with one or multiple expressions.
 556
 557        Example:
 558            >>> condition("x=1").and_("y=1").sql()
 559            'x = 1 AND y = 1'
 560
 561        Args:
 562            *expressions: the SQL code strings to parse.
 563                If an `Expr` instance is passed, it will be used as-is.
 564            dialect: the dialect used to parse the input expression.
 565            copy: whether to copy the involved expressions (only applies to Exprs).
 566            wrap: whether to wrap the operands in `Paren`s. This is true by default to avoid
 567                precedence issues, but can be turned off when the produced AST is too deep and
 568                causes recursion-related issues.
 569            opts: other options to use to parse the input expressions.
 570
 571        Returns:
 572            The new And condition.
 573        """
 574        raise NotImplementedError
 575
 576    def or_(
 577        self,
 578        *expressions: ExpOrStr | None,
 579        dialect: DialectType = None,
 580        copy: bool = True,
 581        wrap: bool = True,
 582        **opts: Unpack[ParserNoDialectArgs],
 583    ) -> Condition:
 584        """
 585        OR this condition with one or multiple expressions.
 586
 587        Example:
 588            >>> condition("x=1").or_("y=1").sql()
 589            'x = 1 OR y = 1'
 590
 591        Args:
 592            *expressions: the SQL code strings to parse.
 593                If an `Expr` instance is passed, it will be used as-is.
 594            dialect: the dialect used to parse the input expression.
 595            copy: whether to copy the involved expressions (only applies to Exprs).
 596            wrap: whether to wrap the operands in `Paren`s. This is true by default to avoid
 597                precedence issues, but can be turned off when the produced AST is too deep and
 598                causes recursion-related issues.
 599            opts: other options to use to parse the input expressions.
 600
 601        Returns:
 602            The new Or condition.
 603        """
 604        raise NotImplementedError
 605
 606    def not_(self, copy: bool = True) -> Not:
 607        """
 608        Wrap this condition with NOT.
 609
 610        Example:
 611            >>> condition("x=1").not_().sql()
 612            'NOT x = 1'
 613
 614        Args:
 615            copy: whether to copy this object.
 616
 617        Returns:
 618            The new Not instance.
 619        """
 620        raise NotImplementedError
 621
 622    def update_positions(
 623        self: E,
 624        other: Token | Expr | None = None,
 625        line: int | None = None,
 626        col: int | None = None,
 627        start: int | None = None,
 628        end: int | None = None,
 629    ) -> E:
 630        """
 631        Update this expression with positions from a token or other expression.
 632
 633        Args:
 634            other: a token or expression to update this expression with.
 635            line: the line number to use if other is None
 636            col: column number
 637            start: start char index
 638            end:  end char index
 639
 640        Returns:
 641            The updated expression.
 642        """
 643        raise NotImplementedError
 644
 645    def as_(
 646        self,
 647        alias: str | Identifier,
 648        quoted: bool | None = None,
 649        dialect: DialectType = None,
 650        copy: bool = True,
 651        table: bool | Sequence[str | Identifier] = False,
 652        **opts: Unpack[ParserNoDialectArgs],
 653    ) -> Expr:
 654        raise NotImplementedError
 655
 656    def _binop(self, klass: Type[E], other: t.Any, reverse: bool = False) -> E:
 657        raise NotImplementedError
 658
 659    def __getitem__(self, other: ExpOrStr | tuple[ExpOrStr, ...]) -> Bracket:
 660        raise NotImplementedError
 661
 662    def __iter__(self) -> Iterator:
 663        raise NotImplementedError
 664
 665    def isin(
 666        self,
 667        *expressions: t.Any,
 668        query: ExpOrStr | None = None,
 669        unnest: ExpOrStr | None | list[ExpOrStr] | tuple[ExpOrStr, ...] = None,
 670        dialect: DialectType = None,
 671        copy: bool = True,
 672        **opts: Unpack[ParserNoDialectArgs],
 673    ) -> In:
 674        raise NotImplementedError
 675
 676    def between(
 677        self, low: t.Any, high: t.Any, copy: bool = True, symmetric: bool | None = None
 678    ) -> Between:
 679        raise NotImplementedError
 680
 681    def is_(self, other: ExpOrStr) -> Is:
 682        raise NotImplementedError
 683
 684    def like(self, other: ExpOrStr) -> Like:
 685        raise NotImplementedError
 686
 687    def ilike(self, other: ExpOrStr) -> ILike:
 688        raise NotImplementedError
 689
 690    def eq(self, other: t.Any) -> EQ:
 691        raise NotImplementedError
 692
 693    def neq(self, other: t.Any) -> NEQ:
 694        raise NotImplementedError
 695
 696    def rlike(self, other: ExpOrStr) -> RegexpLike:
 697        raise NotImplementedError
 698
 699    def div(self, other: ExpOrStr, typed: bool = False, safe: bool = False) -> Div:
 700        raise NotImplementedError
 701
 702    def asc(self, nulls_first: bool = True) -> Ordered:
 703        raise NotImplementedError
 704
 705    def desc(self, nulls_first: bool = False) -> Ordered:
 706        raise NotImplementedError
 707
 708    def __lt__(self, other: t.Any) -> LT:
 709        raise NotImplementedError
 710
 711    def __le__(self, other: t.Any) -> LTE:
 712        raise NotImplementedError
 713
 714    def __gt__(self, other: t.Any) -> GT:
 715        raise NotImplementedError
 716
 717    def __ge__(self, other: t.Any) -> GTE:
 718        raise NotImplementedError
 719
 720    def __add__(self, other: t.Any) -> Add:
 721        raise NotImplementedError
 722
 723    def __radd__(self, other: t.Any) -> Add:
 724        raise NotImplementedError
 725
 726    def __sub__(self, other: t.Any) -> Sub:
 727        raise NotImplementedError
 728
 729    def __rsub__(self, other: t.Any) -> Sub:
 730        raise NotImplementedError
 731
 732    def __mul__(self, other: t.Any) -> Mul:
 733        raise NotImplementedError
 734
 735    def __rmul__(self, other: t.Any) -> Mul:
 736        raise NotImplementedError
 737
 738    def __truediv__(self, other: t.Any) -> Div:
 739        raise NotImplementedError
 740
 741    def __rtruediv__(self, other: t.Any) -> Div:
 742        raise NotImplementedError
 743
 744    def __floordiv__(self, other: t.Any) -> IntDiv:
 745        raise NotImplementedError
 746
 747    def __rfloordiv__(self, other: t.Any) -> IntDiv:
 748        raise NotImplementedError
 749
 750    def __mod__(self, other: t.Any) -> Mod:
 751        raise NotImplementedError
 752
 753    def __rmod__(self, other: t.Any) -> Mod:
 754        raise NotImplementedError
 755
 756    def __pow__(self, other: t.Any) -> Pow:
 757        raise NotImplementedError
 758
 759    def __rpow__(self, other: t.Any) -> Pow:
 760        raise NotImplementedError
 761
 762    def __and__(self, other: t.Any) -> And:
 763        raise NotImplementedError
 764
 765    def __rand__(self, other: t.Any) -> And:
 766        raise NotImplementedError
 767
 768    def __or__(self, other: t.Any) -> Or:
 769        raise NotImplementedError
 770
 771    def __ror__(self, other: t.Any) -> Or:
 772        raise NotImplementedError
 773
 774    def __neg__(self) -> Neg:
 775        raise NotImplementedError
 776
 777    def __invert__(self) -> Not:
 778        raise NotImplementedError
 779
 780    def pipe(
 781        self, func: t.Callable[Concatenate[Self, P], R], *args: P.args, **kwargs: P.kwargs
 782    ) -> R:
 783        """Apply a function to `Self` (the current instance) and return the result.
 784
 785        Doing `expr.pipe(func, *args, **kwargs)` is equivalent to `func(expr, *args, **kwargs)`.
 786
 787        It allows you to chain operations in a fluent way on any given function that takes `Self` as its first argument.
 788
 789        Tip:
 790            If `func` doesn't take `Self` as it's first argument, you can use a lambda to work around it.
 791
 792        Args:
 793            func: The function to apply. It should take `Self` as its first argument, followed by any additional arguments specified in `*args` and `**kwargs`.
 794            *args: Additional positional arguments to pass to `func` after `Self`.
 795            **kwargs: Additional keyword arguments to pass to `func`.
 796
 797        Returns:
 798            The result of applying `func` to `Self` with the given arguments.
 799        """
 800        return func(self, *args, **kwargs)
 801
 802    def apply(
 803        self, func: t.Callable[Concatenate[Self, P], t.Any], *args: P.args, **kwargs: P.kwargs
 804    ) -> Self:
 805        """Apply a function to `Self` (the current instance) for side effects, and return `Self`.
 806
 807        Useful for inspecting intermediate expressions in a method chain by simply adding/removing `apply` calls, especially when combined with `pipe`.
 808
 809        Tip:
 810            If `func` doesn't take `Self` as it's first argument, you can use a lambda to work around it.
 811
 812        Args:
 813            func: The function to apply. It should take `Self` as its first argument, followed by any additional arguments specified in `*args` and `**kwargs`.
 814            *args: Additional positional arguments to pass to `func` after `Self`.
 815            **kwargs: Additional keyword arguments to pass to `func`.
 816
 817        Returns:
 818            The same instance.
 819        """
 820        func(self, *args, **kwargs)
 821        return self
 822
 823
 824class Expression(Expr):
 825    __slots__ = (
 826        "args",
 827        "parent",
 828        "arg_key",
 829        "index",
 830        "comments",
 831        "_type",
 832        "_meta",
 833        "_hash",
 834    )
 835
 836    def __eq__(self, other: object) -> bool:
 837        return self is other or (type(self) is type(other) and hash(self) == hash(other))
 838
 839    def __ne__(self, other: object) -> bool:
 840        return not self.__eq__(other)
 841
 842    def __hash__(self) -> int:
 843        if self._hash is None:
 844            nodes: list[Expr] = []
 845            stack: list[Expr] = [self]
 846
 847            # Collect nodes, finding child expressions inline instead of via the
 848            # iter_expressions generator (whose per-node generator object dominates the
 849            # hash's cost). reversed(nodes) is a valid post-order regardless of DFS/BFS.
 850            while stack:
 851                node = stack.pop()
 852                nodes.append(node)
 853
 854                for v in node.args.values():
 855                    if isinstance(v, Expr):
 856                        if v._hash is None:
 857                            stack.append(v)
 858                    elif type(v) is list:
 859                        for x in v:
 860                            if isinstance(x, Expr) and x._hash is None:
 861                                stack.append(x)
 862
 863            for node in reversed(nodes):
 864                hash_ = hash(node.key)
 865
 866                if node._hash_raw_args:
 867                    for k in sorted(node.args):
 868                        v = node.args[k]
 869                        if v:
 870                            hash_ = hash((hash_, k, tuple(v) if type(v) is list else v))
 871                else:
 872                    for k in sorted(node.args):
 873                        v = node.args[k]
 874                        vt = type(v)
 875
 876                        if vt is list:
 877                            for x in v:
 878                                if x is not None and x is not False:
 879                                    hash_ = hash((hash_, k, x.lower() if type(x) is str else x))
 880                                else:
 881                                    hash_ = hash((hash_, k))
 882                        elif v is not None and v is not False:
 883                            hash_ = hash((hash_, k, v.lower() if vt is str else v))
 884
 885                node._hash = hash_
 886        assert self._hash
 887        return self._hash
 888
 889    def __reduce__(
 890        self,
 891    ) -> tuple[
 892        t.Callable[[list[dict[str, t.Any]] | None], Expr | DType | None],
 893        tuple[list[dict[str, t.Any]]],
 894    ]:
 895        from sqlglot.serde import dump, load
 896
 897        return (load, (dump(self),))
 898
 899    @property
 900    def this(self) -> t.Any:
 901        return self.args.get("this")
 902
 903    @property
 904    def expression(self) -> t.Any:
 905        return self.args.get("expression")
 906
 907    @property
 908    def expressions(self) -> list[t.Any]:
 909        return self.args.get("expressions") or []
 910
 911    def text(self, key: str) -> str:
 912        field = self.args.get(key)
 913        if isinstance(field, str):
 914            return field
 915        if isinstance(field, (Identifier, Literal, Var)):
 916            return field.this
 917        if isinstance(field, (Star, Null)):
 918            return field.name
 919        return ""
 920
 921    @property
 922    def is_string(self) -> bool:
 923        return isinstance(self, Literal) and self.args["is_string"]
 924
 925    @property
 926    def is_number(self) -> bool:
 927        return (isinstance(self, Literal) and not self.args["is_string"]) or (
 928            isinstance(self, Neg) and self.this.is_number
 929        )
 930
 931    def to_py(self) -> t.Any:
 932        raise ValueError(f"{self} cannot be converted to a Python object.")
 933
 934    @property
 935    def is_int(self) -> bool:
 936        return self.is_number and isinstance(self.to_py(), int)
 937
 938    @property
 939    def is_star(self) -> bool:
 940        return isinstance(self, Star) or (isinstance(self, Column) and isinstance(self.this, Star))
 941
 942    @property
 943    def alias(self) -> str:
 944        alias = self.args.get("alias")
 945        if isinstance(alias, Expression):
 946            return alias.name
 947        return self.text("alias")
 948
 949    @property
 950    def alias_column_names(self) -> list[str]:
 951        table_alias = self.args.get("alias")
 952        if not table_alias:
 953            return []
 954        return [c.name for c in table_alias.args.get("columns") or []]
 955
 956    @property
 957    def name(self) -> str:
 958        return self.text("this")
 959
 960    @property
 961    def alias_or_name(self) -> str:
 962        return self.alias or self.name
 963
 964    @property
 965    def output_name(self) -> str:
 966        return ""
 967
 968    @property
 969    def type(self) -> DataType | None:
 970        if self.is_data_type:
 971            return self  # type: ignore[return-value]
 972        if self.is_cast:
 973            return self._type or self.to  # type: ignore[attr-defined]
 974        return self._type
 975
 976    @type.setter
 977    def type(self, dtype: DataType | DType | str | None) -> None:
 978        if dtype and type(dtype).__name__ != "DataType":
 979            from sqlglot.expressions.datatypes import DataType as _DataType
 980
 981            dtype = _DataType.build(dtype)
 982        self._type = dtype  # type: ignore[assignment]
 983
 984    def is_type(self, *dtypes: DATA_TYPE) -> bool:
 985        t = self._type
 986        return t is not None and t.is_type(*dtypes)
 987
 988    def is_leaf(self) -> bool:
 989        return not any((isinstance(v, Expr) or type(v) is list) and v for v in self.args.values())
 990
 991    @property
 992    def meta(self) -> dict[str, t.Any]:
 993        if self._meta is None:
 994            self._meta = {}
 995        return self._meta
 996
 997    def meta_get(self, key: str, default: t.Any = None) -> t.Any:
 998        """Reads a meta value without allocating the meta dict (unlike the `meta` property)."""
 999        meta = self._meta
1000        return meta.get(key, default) if meta is not None else default
1001
1002    def __deepcopy__(self, memo: t.Any) -> Expr:
1003        root = self.__class__()
1004        stack: list[tuple[Expr, Expr]] = [(self, root)]
1005
1006        while stack:
1007            node, copy = stack.pop()
1008
1009            if node.comments is not None:
1010                copy.comments = deepcopy(node.comments)
1011            if node._type is not None:
1012                copy._type = deepcopy(node._type)
1013            if node._meta is not None:
1014                copy._meta = deepcopy(node._meta)
1015            if node._hash is not None:
1016                copy._hash = node._hash
1017
1018            for k, vs in node.args.items():
1019                if isinstance(vs, Expr):
1020                    stack.append((vs, vs.__class__()))
1021                    copy.set(k, stack[-1][-1])
1022                elif type(vs) is list:
1023                    copy.args[k] = []
1024
1025                    for v in vs:
1026                        if isinstance(v, Expr):
1027                            stack.append((v, v.__class__()))
1028                            copy.append(k, stack[-1][-1])
1029                        else:
1030                            copy.append(k, v)
1031                else:
1032                    copy.args[k] = vs
1033
1034        return root
1035
1036    def copy(self: E) -> E:
1037        return deepcopy(self)
1038
1039    def add_comments(self, comments: list[str] | None = None, prepend: bool = False) -> None:
1040        if self.comments is None:
1041            self.comments = []
1042
1043        if comments:
1044            for comment in comments:
1045                _, *meta = comment.split(SQLGLOT_META)
1046                if meta:
1047                    for kv in "".join(meta).split(","):
1048                        k, *v = kv.split("=")
1049                        self.meta[k.strip()] = to_bool(v[0].strip() if v else True)
1050
1051                if not prepend:
1052                    self.comments.append(comment)
1053
1054            if prepend:
1055                self.comments = comments + self.comments
1056
1057    def pop_comments(self) -> list[str]:
1058        comments = self.comments or []
1059        self.comments = None
1060        return comments
1061
1062    def append(self, arg_key: str, value: t.Any) -> None:
1063        node: Expr | None = self
1064        while node and node._hash is not None:
1065            node._hash = None
1066            node = node.parent
1067
1068        if type(self.args.get(arg_key)) is not list:
1069            self.args[arg_key] = []
1070        self._set_parent(arg_key, value)
1071        values = self.args[arg_key]
1072        if isinstance(value, Expr):
1073            value.index = len(values)
1074        values.append(value)
1075
1076    def set(
1077        self,
1078        arg_key: str,
1079        value: object,
1080        index: int | None = None,
1081        overwrite: bool = True,
1082    ) -> None:
1083        node: Expr | None = self
1084
1085        while node and node._hash is not None:
1086            node._hash = None
1087            node = node.parent
1088
1089        if index is not None:
1090            expressions = self.args.get(arg_key) or []
1091
1092            if seq_get(expressions, index) is None:
1093                return
1094
1095            if value is None:
1096                expressions.pop(index)
1097                for v in expressions[index:]:
1098                    v.index = v.index - 1
1099                return
1100
1101            if isinstance(value, list):
1102                expressions.pop(index)
1103                expressions[index:index] = value
1104            elif overwrite:
1105                expressions[index] = value
1106            else:
1107                expressions.insert(index, value)
1108
1109            value = expressions
1110        elif value is None:
1111            self.args.pop(arg_key, None)
1112            return
1113
1114        self.args[arg_key] = value
1115        self._set_parent(arg_key, value, index)
1116
1117    def _set_parent(self, arg_key: str, value: object, index: int | None = None) -> None:
1118        if isinstance(value, Expr):
1119            value.parent = self
1120            value.arg_key = arg_key
1121            value.index = index
1122        elif isinstance(value, list):
1123            for i, v in enumerate(value):
1124                if isinstance(v, Expr):
1125                    v.parent = self
1126                    v.arg_key = arg_key
1127                    v.index = i
1128
1129    def set_kwargs(self, kwargs: Mapping[str, object]) -> Self:
1130        """Set multiples keyword arguments at once, using `.set()` method.
1131
1132        Args:
1133            kwargs (Mapping[str, object]): a `Mapping` of arg keys to values to set.
1134        Returns:
1135            Self: The same `Expression` with the updated arguments.
1136        """
1137        if kwargs:
1138            for k, v in kwargs.items():
1139                self.set(k, v)
1140        return self
1141
1142    @property
1143    def depth(self) -> int:
1144        if self.parent:
1145            return self.parent.depth + 1
1146        return 0
1147
1148    def iter_expressions(self: E, reverse: bool = False) -> Iterator[E]:
1149        for vs in reversed(self.args.values()) if reverse else self.args.values():
1150            if isinstance(vs, list):
1151                for v in reversed(vs) if reverse else vs:
1152                    if isinstance(v, Expr):
1153                        yield t.cast(E, v)
1154            elif isinstance(vs, Expr):
1155                yield t.cast(E, vs)
1156
1157    def find(self, *expression_types: Type[E], bfs: bool = True) -> E | None:
1158        return next(self.find_all(*expression_types, bfs=bfs), None)
1159
1160    def find_all(self, *expression_types: Type[E], bfs: bool = True) -> Iterator[E]:
1161        for expression in self.walk(bfs=bfs):
1162            if isinstance(expression, expression_types):
1163                yield expression
1164
1165    def find_ancestor(self, *expression_types: Type[E]) -> E | None:
1166        ancestor = self.parent
1167        while ancestor and not isinstance(ancestor, expression_types):
1168            ancestor = ancestor.parent
1169        return ancestor  # type: ignore[return-value]
1170
1171    @property
1172    def parent_select(self) -> Select | None:
1173        from sqlglot.expressions.query import Select as _Select
1174
1175        return self.find_ancestor(_Select)
1176
1177    @property
1178    def same_parent(self) -> bool:
1179        return type(self.parent) is self.__class__
1180
1181    def root(self) -> Expr:
1182        expression: Expr = self
1183        while expression.parent:
1184            expression = expression.parent
1185        return expression
1186
1187    def walk(
1188        self, bfs: bool = True, prune: t.Callable[[Expr], bool] | None = None
1189    ) -> Iterator[Expr]:
1190        if bfs:
1191            yield from self.bfs(prune=prune)
1192        else:
1193            yield from self.dfs(prune=prune)
1194
1195    def dfs(self, prune: t.Callable[[Expr], bool] | None = None) -> Iterator[Expr]:
1196        stack = [self]
1197
1198        while stack:
1199            node = stack.pop()
1200            yield node
1201            if prune and prune(node):
1202                continue
1203            for v in node.iter_expressions(reverse=True):
1204                stack.append(v)
1205
1206    def bfs(self, prune: t.Callable[[Expr], bool] | None = None) -> Iterator[Expr]:
1207        queue: deque[Expr] = deque()
1208        queue.append(self)
1209
1210        while queue:
1211            node = queue.popleft()
1212            yield node
1213            if prune and prune(node):
1214                continue
1215            for v in node.iter_expressions():
1216                queue.append(v)
1217
1218    def unnest(self) -> Expr:
1219        expression = self
1220        while type(expression) is Paren:
1221            expression = expression.this
1222        return expression
1223
1224    def unalias(self) -> Expr:
1225        if isinstance(self, Alias):
1226            return self.this
1227        return self
1228
1229    def unnest_operands(self) -> tuple[Expr, ...]:
1230        return tuple(arg.unnest() for arg in self.iter_expressions())
1231
1232    def flatten(self, unnest: bool = True) -> Iterator[Expr]:
1233        for node in self.dfs(prune=lambda n: bool(n.parent and type(n) is not self.__class__)):
1234            if type(node) is not self.__class__:
1235                yield node.unnest() if unnest and not node.is_subquery else node
1236
1237    def __str__(self) -> str:
1238        return self.sql()
1239
1240    def __repr__(self) -> str:
1241        return _to_s(self)
1242
1243    def to_s(self) -> str:
1244        return _to_s(self, verbose=True)
1245
1246    def sql(
1247        self, dialect: DialectType = None, copy: bool = True, **opts: Unpack[GeneratorNoDialectArgs]
1248    ) -> str:
1249        from sqlglot.dialects.dialect import Dialect
1250
1251        return Dialect.get_or_raise(dialect).generate(self, copy=copy, **opts)
1252
1253    def transform(
1254        self, fun: t.Callable[..., T], *args: object, copy: bool = True, **kwargs: object
1255    ) -> T:
1256        root: t.Any = None
1257        new_node: t.Any = None
1258
1259        for node in (self.copy() if copy else self).dfs(prune=lambda n: n is not new_node):
1260            parent, arg_key, index = node.parent, node.arg_key, node.index
1261            new_node = fun(node, *args, **kwargs)
1262
1263            if not root:
1264                root = new_node
1265            elif parent and arg_key and new_node is not node:
1266                parent.set(arg_key, new_node, index)
1267
1268        assert root
1269        return root
1270
1271    def replace(self, expression: T) -> T:
1272        parent = self.parent
1273
1274        if not parent or parent is expression:
1275            return expression
1276
1277        key = self.arg_key
1278
1279        if key:
1280            value = parent.args.get(key)
1281
1282            if type(expression) is list and isinstance(value, Expr):
1283                # We are trying to replace an Expr with a list, so it's assumed that
1284                # the intention was to really replace the parent of this expression.
1285                if value.parent:
1286                    value.parent.replace(expression)
1287            else:
1288                parent.set(key, expression, self.index)
1289
1290        if expression is not self:
1291            self.parent = None
1292            self.arg_key = None
1293            self.index = None
1294
1295        return expression
1296
1297    def pop(self: E) -> E:
1298        self.replace(None)
1299        return self
1300
1301    def assert_is(self, type_: Type[E]) -> E:
1302        if not isinstance(self, type_):
1303            raise AssertionError(f"{self} is not {type_}.")
1304        return self
1305
1306    def error_messages(self, args: Sequence[object] | None = None) -> list[str]:
1307        if UNITTEST:
1308            for k in self.args:
1309                if k not in self.arg_types:
1310                    raise TypeError(f"Unexpected keyword: '{k}' for {self.__class__}")
1311
1312        errors: list[str] | None = None
1313
1314        for k in self.required_args:
1315            v = self.args.get(k)
1316            if v is None or (isinstance(v, list) and not v):
1317                if errors is None:
1318                    errors = []
1319                errors.append(f"Required keyword: '{k}' missing for {self.__class__}")
1320
1321        if (
1322            args
1323            and isinstance(self, Func)
1324            and len(args) > len(self.arg_types)
1325            and not self.is_var_len_args
1326        ):
1327            if errors is None:
1328                errors = []
1329            errors.append(
1330                f"The number of provided arguments ({len(args)}) is greater than "
1331                f"the maximum number of supported arguments ({len(self.arg_types)})"
1332            )
1333
1334        return errors or []
1335
1336    def and_(
1337        self,
1338        *expressions: ExpOrStr | None,
1339        dialect: DialectType = None,
1340        copy: bool = True,
1341        wrap: bool = True,
1342        **opts: Unpack[ParserNoDialectArgs],
1343    ) -> Condition:
1344        return and_(self, *expressions, dialect=dialect, copy=copy, wrap=wrap, **opts)
1345
1346    def or_(
1347        self,
1348        *expressions: ExpOrStr | None,
1349        dialect: DialectType = None,
1350        copy: bool = True,
1351        wrap: bool = True,
1352        **opts: Unpack[ParserNoDialectArgs],
1353    ) -> Condition:
1354        return or_(self, *expressions, dialect=dialect, copy=copy, wrap=wrap, **opts)
1355
1356    def not_(self, copy: bool = True) -> Not:
1357        return not_(self, copy=copy)
1358
1359    def update_positions(
1360        self: E,
1361        other: Token | Expr | None = None,
1362        line: int | None = None,
1363        col: int | None = None,
1364        start: int | None = None,
1365        end: int | None = None,
1366    ) -> E:
1367        if isinstance(other, Token):
1368            meta = self.meta
1369            meta["line"] = other.line
1370            meta["col"] = other.col
1371            meta["start"] = other.start
1372            meta["end"] = other.end
1373        elif other is not None:
1374            other_meta = other._meta
1375            if other_meta:
1376                meta = self.meta
1377                for k in POSITION_META_KEYS:
1378                    if k in other_meta:
1379                        meta[k] = other_meta[k]
1380        else:
1381            meta = self.meta
1382            meta["line"] = line
1383            meta["col"] = col
1384            meta["start"] = start
1385            meta["end"] = end
1386        return self
1387
1388    def as_(
1389        self,
1390        alias: str | Identifier,
1391        quoted: bool | None = None,
1392        dialect: DialectType = None,
1393        copy: bool = True,
1394        table: bool | Sequence[str | Identifier] = False,
1395        **opts: Unpack[ParserNoDialectArgs],
1396    ) -> Expr:
1397        return alias_(self, alias, quoted=quoted, dialect=dialect, copy=copy, table=table, **opts)
1398
1399    def _binop(self, klass: Type[E], other: t.Any, reverse: bool = False) -> E:
1400        this = self.copy()
1401        other = convert(other, copy=True)
1402        if not isinstance(this, klass) and not isinstance(other, klass):
1403            this = _wrap(this, Binary)
1404            other = _wrap(other, Binary)
1405        if reverse:
1406            return klass(this=other, expression=this)
1407        return klass(this=this, expression=other)
1408
1409    def __getitem__(self, other: ExpOrStr | tuple[ExpOrStr, ...]) -> Bracket:
1410        return Bracket(
1411            this=self.copy(), expressions=[convert(e, copy=True) for e in ensure_list(other)]
1412        )
1413
1414    def __iter__(self) -> Iterator:
1415        if "expressions" in self.arg_types:
1416            return iter(self.args.get("expressions") or [])
1417        # We define this because __getitem__ converts Expr into an iterable, which is
1418        # problematic because one can hit infinite loops if they do "for x in some_expr: ..."
1419        # See: https://peps.python.org/pep-0234/
1420        raise TypeError(f"'{self.__class__.__name__}' object is not iterable")
1421
1422    def isin(
1423        self,
1424        *expressions: t.Any,
1425        query: ExpOrStr | None = None,
1426        unnest: ExpOrStr | None | list[ExpOrStr] | tuple[ExpOrStr, ...] = None,
1427        dialect: DialectType = None,
1428        copy: bool = True,
1429        **opts: Unpack[ParserNoDialectArgs],
1430    ) -> In:
1431        from sqlglot.expressions.query import Query
1432
1433        subquery: Expr | None = None
1434        if query:
1435            subquery = maybe_parse(query, dialect=dialect, copy=copy, **opts)
1436            if isinstance(subquery, Query):
1437                subquery = subquery.subquery(copy=False)
1438        unnest_list: list[ExpOrStr] = ensure_list(unnest)
1439        return In(
1440            this=maybe_copy(self, copy),
1441            expressions=[convert(e, copy=copy) for e in expressions],
1442            query=subquery,
1443            unnest=(
1444                _lazy_unnest(
1445                    expressions=[
1446                        maybe_parse(e, dialect=dialect, copy=copy, **opts) for e in unnest_list
1447                    ]
1448                )
1449                if unnest
1450                else None
1451            ),
1452        )
1453
1454    def between(
1455        self, low: t.Any, high: t.Any, copy: bool = True, symmetric: bool | None = None
1456    ) -> Between:
1457        between = Between(
1458            this=maybe_copy(self, copy),
1459            low=convert(low, copy=copy),
1460            high=convert(high, copy=copy),
1461        )
1462        if symmetric is not None:
1463            between.set("symmetric", symmetric)
1464
1465        return between
1466
1467    def is_(self, other: ExpOrStr) -> Is:
1468        return self._binop(Is, other)
1469
1470    def like(self, other: ExpOrStr) -> Like:
1471        return self._binop(Like, other)
1472
1473    def ilike(self, other: ExpOrStr) -> ILike:
1474        return self._binop(ILike, other)
1475
1476    def eq(self, other: t.Any) -> EQ:
1477        return self._binop(EQ, other)
1478
1479    def neq(self, other: t.Any) -> NEQ:
1480        return self._binop(NEQ, other)
1481
1482    def rlike(self, other: ExpOrStr) -> RegexpLike:
1483        return self._binop(RegexpLike, other)
1484
1485    def div(self, other: ExpOrStr, typed: bool = False, safe: bool = False) -> Div:
1486        div = self._binop(Div, other)
1487        div.set("typed", typed)
1488        div.set("safe", safe)
1489        return div
1490
1491    def asc(self, nulls_first: bool = True) -> Ordered:
1492        return Ordered(this=self.copy(), nulls_first=nulls_first)
1493
1494    def desc(self, nulls_first: bool = False) -> Ordered:
1495        return Ordered(this=self.copy(), desc=True, nulls_first=nulls_first)
1496
1497    def __lt__(self, other: t.Any) -> LT:
1498        return self._binop(LT, other)
1499
1500    def __le__(self, other: t.Any) -> LTE:
1501        return self._binop(LTE, other)
1502
1503    def __gt__(self, other: t.Any) -> GT:
1504        return self._binop(GT, other)
1505
1506    def __ge__(self, other: t.Any) -> GTE:
1507        return self._binop(GTE, other)
1508
1509    def __add__(self, other: t.Any) -> Add:
1510        return self._binop(Add, other)
1511
1512    def __radd__(self, other: t.Any) -> Add:
1513        return self._binop(Add, other, reverse=True)
1514
1515    def __sub__(self, other: t.Any) -> Sub:
1516        return self._binop(Sub, other)
1517
1518    def __rsub__(self, other: t.Any) -> Sub:
1519        return self._binop(Sub, other, reverse=True)
1520
1521    def __mul__(self, other: t.Any) -> Mul:
1522        return self._binop(Mul, other)
1523
1524    def __rmul__(self, other: t.Any) -> Mul:
1525        return self._binop(Mul, other, reverse=True)
1526
1527    def __truediv__(self, other: t.Any) -> Div:
1528        return self._binop(Div, other)
1529
1530    def __rtruediv__(self, other: t.Any) -> Div:
1531        return self._binop(Div, other, reverse=True)
1532
1533    def __floordiv__(self, other: t.Any) -> IntDiv:
1534        return self._binop(IntDiv, other)
1535
1536    def __rfloordiv__(self, other: t.Any) -> IntDiv:
1537        return self._binop(IntDiv, other, reverse=True)
1538
1539    def __mod__(self, other: t.Any) -> Mod:
1540        return self._binop(Mod, other)
1541
1542    def __rmod__(self, other: t.Any) -> Mod:
1543        return self._binop(Mod, other, reverse=True)
1544
1545    def __pow__(self, other: t.Any) -> Pow:
1546        return self._binop(Pow, other)
1547
1548    def __rpow__(self, other: t.Any) -> Pow:
1549        return self._binop(Pow, other, reverse=True)
1550
1551    def __and__(self, other: t.Any) -> And:
1552        return self._binop(And, other)
1553
1554    def __rand__(self, other: t.Any) -> And:
1555        return self._binop(And, other, reverse=True)
1556
1557    def __or__(self, other: t.Any) -> Or:
1558        return self._binop(Or, other)
1559
1560    def __ror__(self, other: t.Any) -> Or:
1561        return self._binop(Or, other, reverse=True)
1562
1563    def __neg__(self) -> Neg:
1564        return Neg(this=_wrap(self.copy(), Binary))
1565
1566    def __invert__(self) -> Not:
1567        return not_(self.copy())
1568
1569
1570IntoType = t.Union[Type[Expr], Collection[Type[Expr]]]
1571ExpOrStr = t.Union[int, str, Expr]
1572
1573
1574@trait
1575class Condition(Expr):
1576    """Logical conditions like x AND y, or simply x"""
1577
1578
1579@trait
1580class Predicate(Condition):
1581    """Any condition that evaluates to a boolean, e.g. x = y, x LIKE 'a%', a @> b."""
1582
1583
1584class Cache(Expression):
1585    arg_types = {
1586        "this": True,
1587        "lazy": False,
1588        "options": False,
1589        "expression": False,
1590    }
1591
1592
1593class Uncache(Expression):
1594    arg_types = {"this": True, "exists": False}
1595
1596
1597class Refresh(Expression):
1598    arg_types = {
1599        "this": True,
1600        "kind": True,
1601        "partition_start": False,
1602        "partition_end": False,
1603        "force": False,
1604        "mode": False,
1605    }
1606
1607
1608class LockingStatement(Expression):
1609    arg_types = {"this": True, "expression": True}
1610
1611
1612@trait
1613class ColumnConstraintKind(Expr):
1614    pass
1615
1616
1617@trait
1618class SubqueryPredicate(Predicate):
1619    pass
1620
1621
1622class All(Expression, SubqueryPredicate):
1623    pass
1624
1625
1626class Any(Expression, SubqueryPredicate):
1627    pass
1628
1629
1630@trait
1631class Binary(Condition):
1632    arg_types: t.ClassVar[dict[str, bool]] = {"this": True, "expression": True}
1633
1634    @property
1635    def left(self) -> Expr:
1636        return self.args["this"]
1637
1638    @property
1639    def right(self) -> Expr:
1640        return self.args["expression"]
1641
1642
1643@trait
1644class Connector(Binary):
1645    pass
1646
1647
1648@trait
1649class Func(Condition):
1650    """
1651    The base class for all function expressions.
1652
1653    Attributes:
1654        is_var_len_args (bool): if set to True the argument identified by var_len_arg_key will be
1655            treated as a variable length argument and the argument's value will be stored as a list.
1656        var_len_arg_key (str): the arg_types key that collects the variable length arguments.
1657            Arguments preceding it in arg_types are filled positionally; those following it (e.g.
1658            dialect flags) are never populated by from_arg_list.
1659        _sql_names (list): the SQL name (1st item in the list) and aliases (subsequent items) for this
1660            function expression. These values are used to map this node to a name during parsing as
1661            well as to provide the function's name during SQL string generation. By default the SQL
1662            name is set to the expression's class name transformed to snake case.
1663    """
1664
1665    is_var_len_args: t.ClassVar[bool] = False
1666    var_len_arg_key: t.ClassVar[str] = "expressions"
1667    _sql_names: t.ClassVar[list[str]] = []
1668
1669    @classmethod
1670    def from_arg_list(cls, args: Sequence[object]) -> Self:
1671        if cls.is_var_len_args:
1672            all_arg_keys = tuple(cls.arg_types)
1673            var_len_index = all_arg_keys.index(cls.var_len_arg_key)
1674
1675            args_dict = {arg_key: arg for arg, arg_key in zip(args, all_arg_keys[:var_len_index])}
1676            args_dict[cls.var_len_arg_key] = args[var_len_index:]
1677        else:
1678            args_dict = {arg_key: arg for arg, arg_key in zip(args, cls.arg_types)}
1679
1680        return cls(**args_dict)
1681
1682    @classmethod
1683    def sql_names(cls) -> list[str]:
1684        if cls is Func:
1685            raise NotImplementedError(
1686                "SQL name is only supported by concrete function implementations"
1687            )
1688        if not cls._sql_names:
1689            return [camel_to_snake_case(cls.__name__)]
1690        return cls._sql_names
1691
1692    @classmethod
1693    def sql_name(cls) -> str:
1694        sql_names = cls.sql_names()
1695        assert sql_names, f"Expected non-empty 'sql_names' for Func: {cls.__name__}."
1696        return sql_names[0]
1697
1698    @classmethod
1699    def default_parser_mappings(cls) -> dict[str, t.Callable[[Sequence[object]], Self]]:
1700        return {name: cls.from_arg_list for name in cls.sql_names()}
1701
1702
1703@trait
1704class AggFunc(Func):
1705    pass
1706
1707
1708class Column(Expression, Condition):
1709    # "shadow" marks a column whose qualifier is shadowed by a projection alias, so it must be
1710    # rendered unqualified in dialects where PROJECTION_ALIASES_SHADOW_SOURCE_NAMES is set
1711    arg_types = {
1712        "this": True,
1713        "table": False,
1714        "db": False,
1715        "catalog": False,
1716        "join_mark": False,
1717        "shadow": False,
1718    }
1719
1720    @property
1721    def table(self) -> str:
1722        return self.text("table")
1723
1724    @property
1725    def db(self) -> str:
1726        return self.text("db")
1727
1728    @property
1729    def catalog(self) -> str:
1730        return self.text("catalog")
1731
1732    @property
1733    def output_name(self) -> str:
1734        return self.name
1735
1736    @property
1737    def parts(self) -> list[Identifier | Star]:
1738        """Return the parts of a column in order catalog, db, table, name."""
1739        return [
1740            self.args[part] for part in ("catalog", "db", "table", "this") if self.args.get(part)
1741        ]
1742
1743    def to_dot(self, include_dots: bool = True) -> Dot | Identifier | Star:
1744        """Converts the column into a dot expression."""
1745        parts = self.parts
1746        parent = self.parent
1747
1748        if include_dots:
1749            while isinstance(parent, Dot):
1750                parts.append(parent.expression)
1751                parent = parent.parent
1752
1753        return Dot.build(deepcopy(parts)) if len(parts) > 1 else parts[0]
1754
1755
1756class Literal(Expression, Condition):
1757    arg_types = {"this": True, "is_string": True}
1758    _hash_raw_args = True
1759    is_primitive = True
1760
1761    @classmethod
1762    def number(cls, number: object) -> Literal | Neg:
1763        lit = cls(this=str(number), is_string=False)
1764        try:
1765            to_py = lit.to_py()
1766            if not isinstance(to_py, str) and to_py < 0:
1767                lit.set("this", str(abs(to_py)))
1768                return Neg(this=lit)
1769        except Exception:
1770            pass
1771        return lit
1772
1773    @classmethod
1774    def string(cls, string: object) -> Literal:
1775        return cls(this=str(string), is_string=True)
1776
1777    @property
1778    def output_name(self) -> str:
1779        return self.name
1780
1781    def to_py(self) -> int | str | Decimal:
1782        if self.is_number:
1783            try:
1784                return int(self.this)
1785            except ValueError:
1786                try:
1787                    return Decimal(self.this)
1788                except InvalidOperation as e:
1789                    raise ValueError(f"Invalid numeric literal: {self.this!r}") from e
1790        return self.this
1791
1792
1793class Var(Expression):
1794    is_primitive = True
1795
1796
1797class WithinGroup(Expression):
1798    arg_types = {"this": True, "expression": False}
1799
1800
1801class Pseudocolumn(Column):
1802    pass
1803
1804
1805class Hint(Expression):
1806    arg_types = {"expressions": True}
1807
1808
1809class JoinHint(Expression):
1810    arg_types = {"this": True, "expressions": True}
1811
1812
1813class Identifier(Expression):
1814    arg_types = {
1815        "this": True,
1816        "quoted": False,
1817        "global_": False,
1818        "temporary": False,
1819    }
1820    is_primitive = True
1821    _hash_raw_args = True
1822
1823    @property
1824    def quoted(self) -> bool:
1825        return bool(self.args.get("quoted"))
1826
1827    @property
1828    def output_name(self) -> str:
1829        return self.name
1830
1831
1832# https://docs.snowflake.com/en/sql-reference/identifier-literal
1833# "expressions" holds the arguments when the resolved identifier is invoked as a
1834# function, e.g. `IDENTIFIER('my_func')(1, 2)`
1835class DynamicIdentifier(Expression, Func):
1836    arg_types = {"this": True, "expressions": False}
1837
1838    @property
1839    def name(self) -> str:
1840        return self.this.name if self.this else ""
1841
1842
1843class Opclass(Expression):
1844    arg_types = {"this": True, "expression": True}
1845
1846
1847class Star(Expression):
1848    arg_types = {"except_": False, "replace": False, "rename": False, "ilike": False}
1849
1850    @property
1851    def name(self) -> str:
1852        return "*"
1853
1854    @property
1855    def output_name(self) -> str:
1856        return self.name
1857
1858
1859class Parameter(Expression, Condition):
1860    arg_types = {"this": True, "expression": False}
1861
1862
1863class SessionParameter(Expression, Condition):
1864    arg_types = {"this": True, "kind": False}
1865
1866
1867class Placeholder(Expression, Condition):
1868    arg_types = {"this": False, "kind": False, "widget": False, "jdbc": False}
1869    _hash_raw_args = True
1870
1871    @property
1872    def name(self) -> str:
1873        return self.text("this") or "?"
1874
1875
1876class Null(Expression, Condition):
1877    arg_types = {}
1878
1879    @property
1880    def name(self) -> str:
1881        return "NULL"
1882
1883    def to_py(self) -> t.Literal[None]:
1884        return None
1885
1886
1887class Boolean(Expression, Condition):
1888    is_primitive = True
1889
1890    def to_py(self) -> bool:
1891        return self.this
1892
1893
1894class Dot(Expression, Binary):
1895    @property
1896    def is_star(self) -> bool:
1897        return self.expression.is_star
1898
1899    @property
1900    def name(self) -> str:
1901        return self.expression.name
1902
1903    @property
1904    def output_name(self) -> str:
1905        return self.name
1906
1907    @classmethod
1908    def build(cls, expressions: Sequence[Expr]) -> Dot:
1909        """Build a Dot object with a sequence of expressions."""
1910        if len(expressions) < 2:
1911            raise ValueError("Dot requires >= 2 expressions.")
1912
1913        return t.cast(Dot, reduce(lambda x, y: Dot(this=x, expression=y), expressions))
1914
1915    @property
1916    def parts(self) -> list[Expr]:
1917        """Return the parts of a table / column in order catalog, db, table."""
1918        this, *parts = self.flatten()
1919
1920        parts.reverse()
1921
1922        for arg in COLUMN_PARTS:
1923            part = this.args.get(arg)
1924
1925            if isinstance(part, Expr):
1926                parts.append(part)
1927
1928        parts.reverse()
1929        return parts
1930
1931
1932class Kwarg(Expression, Binary):
1933    """Kwarg in special functions like func(kwarg => y)."""
1934
1935
1936class Alias(Expression):
1937    arg_types = {"this": True, "alias": False}
1938
1939    @property
1940    def output_name(self) -> str:
1941        return self.alias
1942
1943
1944class PivotAlias(Alias):
1945    pass
1946
1947
1948class PivotAny(Expression):
1949    arg_types = {"this": False}
1950
1951
1952class Aliases(Expression):
1953    arg_types = {"this": True, "expressions": True}
1954
1955    @property
1956    def aliases(self) -> list[Expr]:
1957        return self.expressions
1958
1959
1960class Bracket(Expression, Condition):
1961    # https://cloud.google.com/bigquery/docs/reference/standard-sql/operators#array_subscript_operator
1962    arg_types = {
1963        "this": True,
1964        "expressions": True,
1965        "offset": False,
1966        "safe": False,
1967        "returns_list_for_maps": False,
1968        "json_access": False,
1969    }
1970
1971    @property
1972    def output_name(self) -> str:
1973        if len(self.expressions) == 1:
1974            return self.expressions[0].output_name
1975
1976        return super().output_name
1977
1978
1979class ForIn(Expression):
1980    arg_types = {"this": True, "expression": True}
1981
1982
1983class IgnoreNulls(Expression):
1984    pass
1985
1986
1987class RespectNulls(Expression):
1988    pass
1989
1990
1991class HavingMax(Expression):
1992    arg_types = {"this": True, "expression": True, "max": True}
1993
1994
1995class SafeFunc(Expression, Func):
1996    pass
1997
1998
1999class Typeof(Expression, Func):
2000    pass
2001
2002
2003class ParameterizedAgg(Expression, AggFunc):
2004    arg_types = {"this": True, "expressions": True, "params": True}
2005    _hash_raw_args = True
2006
2007
2008class Anonymous(Expression, Func):
2009    arg_types = {"this": True, "expressions": False}
2010    is_var_len_args = True
2011
2012    @property
2013    def name(self) -> str:
2014        return self.this if isinstance(self.this, str) else self.this.name
2015
2016
2017class AnonymousAggFunc(Expression, AggFunc):
2018    arg_types = {"this": True, "expressions": False}
2019    is_var_len_args = True
2020    _hash_raw_args = True
2021
2022
2023class CombinedAggFunc(AnonymousAggFunc):
2024    arg_types = {"this": True, "expressions": False}
2025
2026
2027class CombinedParameterizedAgg(ParameterizedAgg):
2028    arg_types = {"this": True, "expressions": True, "params": True}
2029
2030
2031class HashAgg(Expression, AggFunc):
2032    arg_types = {"this": True, "expressions": False}
2033    is_var_len_args = True
2034
2035
2036class Hll(Expression, AggFunc):
2037    arg_types = {"this": True, "expressions": False}
2038    is_var_len_args = True
2039
2040
2041class ApproxDistinct(Expression, AggFunc):
2042    arg_types = {"this": True, "accuracy": False}
2043    _sql_names = ["APPROX_DISTINCT", "APPROX_COUNT_DISTINCT"]
2044
2045
2046class Slice(Expression):
2047    arg_types = {"this": False, "expression": False, "step": False}
2048
2049
2050@trait
2051class TimeUnit(Expr):
2052    """Automatically converts unit arg into a var."""
2053
2054    UNABBREVIATED_UNIT_NAME: t.ClassVar[dict[str, str]] = {
2055        "D": "DAY",
2056        "H": "HOUR",
2057        "M": "MINUTE",
2058        "MS": "MILLISECOND",
2059        "NS": "NANOSECOND",
2060        "Q": "QUARTER",
2061        "S": "SECOND",
2062        "US": "MICROSECOND",
2063        "W": "WEEK",
2064        "Y": "YEAR",
2065    }
2066
2067    VAR_LIKE: t.ClassVar[tuple[Type[Expr], ...]] = (Column, Literal, Var)
2068
2069    def __init__(self, **args: object) -> None:
2070        super().__init__(**args)
2071
2072        unit = self.args.get("unit")
2073        if (
2074            unit
2075            and type(unit) in TimeUnit.VAR_LIKE
2076            and not (isinstance(unit, Column) and len(unit.parts) != 1)
2077        ):
2078            unit = Var(this=(self.UNABBREVIATED_UNIT_NAME.get(unit.name) or unit.name).upper())
2079            self.args["unit"] = unit
2080            self._set_parent("unit", unit)
2081        elif type(unit).__name__ == "Week":
2082            unit.set("this", Var(this=unit.this.name.upper()))  # type: ignore[union-attr]
2083
2084    @property
2085    def unit(self) -> Expr | None:
2086        return self.args.get("unit")
2087
2088
2089class _TimeUnit(Expression, TimeUnit):
2090    """Automatically converts unit arg into a var."""
2091
2092    arg_types = {"unit": False}
2093
2094
2095@trait
2096class IntervalOp(TimeUnit):
2097    def interval(self) -> Interval:
2098        from sqlglot.expressions.datatypes import Interval
2099
2100        expr = self.expression
2101        return Interval(
2102            this=expr.copy() if expr is not None else None,
2103            unit=self.unit.copy() if self.unit else None,
2104        )
2105
2106
2107class Filter(Expression):
2108    arg_types = {"this": True, "expression": True}
2109
2110
2111class Check(Expression):
2112    pass
2113
2114
2115class Ordered(Expression):
2116    arg_types = {"this": True, "desc": False, "nulls_first": True, "with_fill": False}
2117
2118    @property
2119    def name(self) -> str:
2120        return self.this.name
2121
2122
2123class Add(Expression, Binary):
2124    pass
2125
2126
2127class BitwiseAnd(Expression, Binary):
2128    arg_types = {"this": True, "expression": True, "padside": False}
2129
2130
2131class BitwiseLeftShift(Expression, Binary):
2132    arg_types = {"this": True, "expression": True, "requires_int128": False}
2133
2134
2135class BitwiseOr(Expression, Binary):
2136    arg_types = {"this": True, "expression": True, "padside": False}
2137
2138
2139class BitwiseRightShift(Expression, Binary):
2140    arg_types = {"this": True, "expression": True, "requires_int128": False}
2141
2142
2143class BitwiseXor(Expression, Binary):
2144    arg_types = {"this": True, "expression": True, "padside": False}
2145
2146
2147class Div(Expression, Binary):
2148    arg_types = {"this": True, "expression": True, "typed": False, "safe": False}
2149
2150
2151class Overlaps(Expression, Binary, Predicate):
2152    pass
2153
2154
2155class ExtendsLeft(Expression, Binary, Predicate):
2156    pass
2157
2158
2159class ExtendsRight(Expression, Binary, Predicate):
2160    pass
2161
2162
2163class DPipe(Expression, Binary):
2164    arg_types = {"this": True, "expression": True, "safe": False}
2165
2166
2167class EQ(Expression, Binary, Predicate):
2168    pass
2169
2170
2171class NullSafeEQ(Expression, Binary, Predicate):
2172    pass
2173
2174
2175class NullSafeNEQ(Expression, Binary, Predicate):
2176    pass
2177
2178
2179class PropertyEQ(Expression, Binary):
2180    pass
2181
2182
2183class Distance(Expression, Binary):
2184    pass
2185
2186
2187class DistanceNd(Expression, Binary):
2188    pass
2189
2190
2191class Escape(Expression, Binary):
2192    pass
2193
2194
2195class Glob(Expression, Binary, Predicate):
2196    pass
2197
2198
2199class GT(Expression, Binary, Predicate):
2200    pass
2201
2202
2203class GTE(Expression, Binary, Predicate):
2204    pass
2205
2206
2207class ILike(Expression, Binary, Predicate):
2208    arg_types = {"this": True, "expression": True, "negate": False}
2209
2210
2211class IntDiv(Expression, Binary):
2212    pass
2213
2214
2215class Is(Expression, Binary, Predicate):
2216    arg_types = {"this": True, "expression": True, "negate": False}
2217
2218
2219class Like(Expression, Binary, Predicate):
2220    arg_types = {"this": True, "expression": True, "negate": False}
2221
2222
2223class Match(Expression, Binary, Predicate):
2224    arg_types = {"this": True, "expression": True, "kind": False, "analyzer": False}
2225
2226
2227class LT(Expression, Binary, Predicate):
2228    pass
2229
2230
2231class LTE(Expression, Binary, Predicate):
2232    pass
2233
2234
2235class Mod(Expression, Binary):
2236    pass
2237
2238
2239class Mul(Expression, Binary):
2240    pass
2241
2242
2243class NEQ(Expression, Binary, Predicate):
2244    pass
2245
2246
2247class NestedJSONSelect(Expression, Binary):
2248    pass
2249
2250
2251class Operator(Expression, Binary):
2252    arg_types = {"this": True, "operator": True, "expression": True}
2253
2254
2255class SimilarTo(Expression, Binary, Predicate):
2256    pass
2257
2258
2259class Sub(Expression, Binary):
2260    pass
2261
2262
2263class Adjacent(Expression, Binary, Predicate):
2264    pass
2265
2266
2267class Unary(Expression, Condition):
2268    pass
2269
2270
2271class BitwiseNot(Unary):
2272    pass
2273
2274
2275class Not(Unary):
2276    pass
2277
2278
2279class Paren(Unary):
2280    @property
2281    def output_name(self) -> str:
2282        return self.this.name
2283
2284
2285class Neg(Unary):
2286    def to_py(self) -> int | Decimal:
2287        if self.is_number:
2288            return self.this.to_py() * -1
2289        return super().to_py()
2290
2291
2292class AtIndex(Expression):
2293    arg_types = {"this": True, "expression": True}
2294
2295
2296class AtTimeZone(Expression):
2297    arg_types = {"this": True, "zone": True}
2298
2299
2300class FromTimeZone(Expression):
2301    arg_types = {"this": True, "zone": True}
2302
2303
2304class FormatPhrase(Expression):
2305    """Format override for a column in Teradata.
2306    Can be expanded to additional dialects as needed
2307
2308    https://docs.teradata.com/r/Enterprise_IntelliFlex_VMware/SQL-Data-Types-and-Literals/Data-Type-Formats-and-Format-Phrases/FORMAT
2309    """
2310
2311    arg_types = {"this": True, "format": True}
2312
2313
2314class Between(Expression, Predicate):
2315    arg_types = {"this": True, "low": True, "high": True, "symmetric": False}
2316
2317
2318class Distinct(Expression):
2319    arg_types = {"expressions": False, "on": False}
2320
2321
2322class In(Expression, Predicate):
2323    arg_types = {
2324        "this": True,
2325        "expressions": False,
2326        "query": False,
2327        "unnest": False,
2328        "field": False,
2329        "is_global": False,
2330    }
2331
2332
2333class And(Expression, Connector, Func):
2334    pass
2335
2336
2337class Or(Expression, Connector, Func):
2338    pass
2339
2340
2341class Xor(Expression, Connector, Func):
2342    arg_types = {"this": True, "expression": True, "round_input": False}
2343
2344
2345class Pow(Expression, Binary, Func):
2346    _sql_names = ["POWER", "POW"]
2347
2348
2349class RegexpLike(Expression, Binary, Predicate, Func):
2350    arg_types = {"this": True, "expression": True, "flag": False, "full_match": False}
2351
2352
2353def not_(
2354    expression: ExpOrStr,
2355    dialect: DialectType = None,
2356    copy: bool = True,
2357    **opts: Unpack[ParserNoDialectArgs],
2358) -> Not:
2359    """
2360    Wrap a condition with a NOT operator.
2361
2362    Example:
2363        >>> not_("this_suit='black'").sql()
2364        "NOT this_suit = 'black'"
2365
2366    Args:
2367        expression: the SQL code string to parse.
2368            If an Expr instance is passed, this is used as-is.
2369        dialect: the dialect used to parse the input expression.
2370        copy: whether to copy the expression or not.
2371        **opts: other options to use to parse the input expressions.
2372
2373    Returns:
2374        The new condition.
2375    """
2376    this = condition(
2377        expression,
2378        dialect=dialect,
2379        copy=copy,
2380        **opts,
2381    )
2382    return Not(this=_wrap(this, Connector))
2383
2384
2385def _lazy_unnest(**kwargs: object) -> Expr:
2386    from sqlglot.expressions.array import Unnest
2387
2388    return Unnest(**kwargs)
2389
2390
2391def convert(value: t.Any, copy: bool = False) -> Expr:
2392    """Convert a python value into an expression object.
2393
2394    Raises an error if a conversion is not possible.
2395
2396    Args:
2397        value: A python object.
2398        copy: Whether to copy `value` (only applies to Exprs and collections).
2399
2400    Returns:
2401        The equivalent expression object.
2402    """
2403    if isinstance(value, Expr):
2404        return maybe_copy(value, copy)
2405    if isinstance(value, str):
2406        return Literal.string(value)
2407    if isinstance(value, bool):
2408        return Boolean(this=value)
2409    if value is None or (isinstance(value, float) and math.isnan(value)):
2410        return Null()
2411    if isinstance(value, numbers.Number):
2412        return Literal.number(value)
2413    if isinstance(value, bytes):
2414        from sqlglot.expressions.query import HexString as _HexString
2415
2416        return _HexString(this=value.hex())
2417    if isinstance(value, datetime.datetime):
2418        datetime_literal = Literal.string(value.isoformat(sep=" "))
2419
2420        tz = None
2421        if value.tzinfo:
2422            # this works for zoneinfo.ZoneInfo, pytz.timezone and datetime.datetime.utc to return IANA timezone names like "America/Los_Angeles"
2423            # instead of abbreviations like "PDT". This is for consistency with other timezone handling functions in SQLGlot
2424            tz = Literal.string(str(value.tzinfo))
2425
2426        from sqlglot.expressions.temporal import TimeStrToTime as _TimeStrToTime
2427
2428        return _TimeStrToTime(this=datetime_literal, zone=tz)
2429    if isinstance(value, datetime.date):
2430        date_literal = Literal.string(value.strftime("%Y-%m-%d"))
2431        from sqlglot.expressions.temporal import DateStrToDate as _DateStrToDate
2432
2433        return _DateStrToDate(this=date_literal)
2434    if isinstance(value, datetime.time):
2435        time_literal = Literal.string(value.isoformat())
2436        from sqlglot.expressions.temporal import TsOrDsToTime as _TsOrDsToTime
2437
2438        return _TsOrDsToTime(this=time_literal)
2439    if isinstance(value, tuple):
2440        if hasattr(value, "_fields"):
2441            from sqlglot.expressions.array import Struct as _Struct
2442
2443            return _Struct(
2444                expressions=[
2445                    PropertyEQ(
2446                        this=to_identifier(k), expression=convert(getattr(value, k), copy=copy)
2447                    )
2448                    for k in value._fields
2449                ]
2450            )
2451        from sqlglot.expressions.query import Tuple as _Tuple
2452
2453        return _Tuple(expressions=[convert(v, copy=copy) for v in value])
2454    if isinstance(value, list):
2455        from sqlglot.expressions.array import Array as _Array
2456
2457        return _Array(expressions=[convert(v, copy=copy) for v in value])
2458    if isinstance(value, dict):
2459        from sqlglot.expressions.array import Array as _Array
2460        from sqlglot.expressions.array import Map as _Map
2461
2462        return _Map(
2463            keys=_Array(expressions=[convert(k, copy=copy) for k in value]),
2464            values=_Array(expressions=[convert(v, copy=copy) for v in value.values()]),
2465        )
2466    if hasattr(value, "__dict__"):
2467        from sqlglot.expressions.array import Struct as _Struct
2468
2469        return _Struct(
2470            expressions=[
2471                PropertyEQ(this=to_identifier(k), expression=convert(v, copy=copy))
2472                for k, v in value.__dict__.items()
2473            ]
2474        )
2475    raise ValueError(f"Cannot convert {value}")
2476
2477
2478QUERY_MODIFIERS = {
2479    "match": False,
2480    "laterals": False,
2481    "joins": False,
2482    "connect": False,
2483    "pivots": False,
2484    "prewhere": False,
2485    "where": False,
2486    "group": False,
2487    "having": False,
2488    "qualify": False,
2489    "windows": False,
2490    "distribute": False,
2491    "sort": False,
2492    "cluster": False,
2493    "order": False,
2494    "limit": False,
2495    "offset": False,
2496    "locks": False,
2497    "sample": False,
2498    "settings": False,
2499    "format": False,
2500    "options": False,
2501    "for_": False,
2502}
2503
2504
2505TIMESTAMP_PARTS = {
2506    "year": False,
2507    "month": False,
2508    "day": False,
2509    "hour": False,
2510    "min": False,
2511    "sec": False,
2512    "nano": False,
2513}
2514
2515
2516@t.overload
2517def maybe_parse(
2518    sql_or_expression: int | str,
2519    *,
2520    into: Type[E],
2521    dialect: DialectType = None,
2522    prefix: str | None = None,
2523    copy: bool = False,
2524    **opts: Unpack[ParserNoDialectArgs],
2525) -> E: ...
2526
2527
2528@t.overload
2529def maybe_parse(
2530    sql_or_expression: int | str | E,
2531    *,
2532    into: IntoType | None = None,
2533    dialect: DialectType = None,
2534    prefix: str | None = None,
2535    copy: bool = False,
2536    **opts: Unpack[ParserNoDialectArgs],
2537) -> E: ...
2538
2539
2540def maybe_parse(
2541    sql_or_expression: ExpOrStr,
2542    *,
2543    into: IntoType | None = None,
2544    dialect: DialectType = None,
2545    prefix: str | None = None,
2546    copy: bool = False,
2547    **opts: Unpack[ParserNoDialectArgs],
2548) -> Expr:
2549    """Gracefully handle a possible string or expression.
2550
2551    Example:
2552        >>> maybe_parse("1")
2553        Literal(this=1, is_string=False)
2554        >>> maybe_parse(to_identifier("x"))
2555        Identifier(this=x, quoted=False)
2556
2557    Args:
2558        sql_or_expression: the SQL code string or an expression
2559        into: the SQLGlot Expr to parse into
2560        dialect: the dialect used to parse the input expressions (in the case that an
2561            input expression is a SQL string).
2562        prefix: a string to prefix the sql with before it gets parsed
2563            (automatically includes a space)
2564        copy: whether to copy the expression.
2565        **opts: other options to use to parse the input expressions (again, in the case
2566            that an input expression is a SQL string).
2567
2568    Returns:
2569        Expr: the parsed or given expression.
2570    """
2571    if isinstance(sql_or_expression, Expr):
2572        if copy:
2573            return sql_or_expression.copy()
2574        return sql_or_expression
2575
2576    if sql_or_expression is None:
2577        raise ParseError("SQL cannot be None")
2578
2579    import sqlglot
2580
2581    sql = str(sql_or_expression)
2582    if prefix:
2583        sql = f"{prefix} {sql}"
2584
2585    return sqlglot.parse_one(sql, read=dialect, into=into, **opts)
2586
2587
2588@t.overload
2589def maybe_copy(instance: None, copy: bool = True) -> None: ...
2590
2591
2592@t.overload
2593def maybe_copy(instance: E, copy: bool = True) -> E: ...
2594
2595
2596def maybe_copy(instance, copy=True):
2597    return instance.copy() if copy and instance else instance
2598
2599
2600def _to_s(node: t.Any, verbose: bool = False, level: int = 0, repr_str: bool = False) -> str:
2601    """Generate a textual representation of an Expr tree"""
2602    indent = "\n" + ("  " * (level + 1))
2603    delim = f",{indent}"
2604
2605    if isinstance(node, Expr):
2606        args = {k: v for k, v in node.args.items() if (v is not None and v != []) or verbose}
2607
2608        if (node.type or verbose) and not node.is_data_type:
2609            args["_type"] = node.type
2610        if node.comments or verbose:
2611            args["_comments"] = node.comments
2612
2613        if verbose:
2614            args["_id"] = id(node)
2615
2616        # Inline leaves for a more compact representation
2617        if node.is_leaf():
2618            indent = ""
2619            delim = ", "
2620
2621        repr_str = node.is_string or (isinstance(node, Identifier) and node.quoted)
2622        items = delim.join(
2623            [f"{k}={_to_s(v, verbose, level + 1, repr_str=repr_str)}" for k, v in args.items()]
2624        )
2625        return f"{node.__class__.__name__}({indent}{items})"
2626
2627    if isinstance(node, list):
2628        items = delim.join(_to_s(i, verbose, level + 1) for i in node)
2629        items = f"{indent}{items}" if items else ""
2630        return f"[{items}]"
2631
2632    # We use the representation of the string to avoid stripping out important whitespace
2633    if repr_str and isinstance(node, str):
2634        node = repr(node)
2635
2636    # Indent multiline strings to match the current level
2637    return indent.join(textwrap.dedent(str(node).strip("\n")).splitlines())
2638
2639
2640def _is_wrong_expression(expression, into):
2641    return isinstance(expression, Expr) and not isinstance(expression, into)
2642
2643
2644def _apply_builder(
2645    expression: ExpOrStr,
2646    instance: E,
2647    arg: str,
2648    copy: bool = True,
2649    prefix: str | None = None,
2650    into: Type[Expr] | None = None,
2651    dialect: DialectType = None,
2652    into_arg="this",
2653    **opts: Unpack[ParserNoDialectArgs],
2654) -> E:
2655    if _is_wrong_expression(expression, into) and into is not None:
2656        expression = into(**{into_arg: expression})
2657    instance = maybe_copy(instance, copy)
2658    expression = maybe_parse(
2659        sql_or_expression=expression,
2660        prefix=prefix,
2661        into=into,
2662        dialect=dialect,
2663        **opts,
2664    )
2665    instance.set(arg, expression)
2666    return instance
2667
2668
2669def _apply_child_list_builder(
2670    *expressions: ExpOrStr | None,
2671    instance: E,
2672    arg: str,
2673    append: bool = True,
2674    copy: bool = True,
2675    prefix: str | None = None,
2676    into: Type[Expr] | None = None,
2677    dialect: DialectType = None,
2678    properties: MutableMapping[str, object] | None = None,
2679    **opts: Unpack[ParserNoDialectArgs],
2680) -> E:
2681    instance = maybe_copy(instance, copy)
2682    parsed = []
2683    properties = {} if properties is None else properties
2684
2685    for expression in expressions:
2686        if expression is not None:
2687            if _is_wrong_expression(expression, into) and into is not None:
2688                expression = into(expressions=[expression])
2689
2690            expression = maybe_parse(
2691                expression,
2692                into=into,
2693                dialect=dialect,
2694                prefix=prefix,
2695                **opts,
2696            )
2697            for k, v in expression.args.items():
2698                if k == "expressions":
2699                    parsed.extend(v)
2700                else:
2701                    properties[k] = v
2702
2703    existing = instance.args.get(arg)
2704    if append and existing:
2705        parsed = existing.expressions + parsed
2706    if into is None:
2707        raise ValueError("`into` is required to use `_apply_child_list_builder`")
2708    child = into(expressions=parsed)
2709    for k, v in properties.items():
2710        child.set(k, v)
2711    instance.set(arg, child)
2712
2713    return instance
2714
2715
2716def _apply_list_builder(
2717    *expressions: ExpOrStr | None,
2718    instance: E,
2719    arg: str,
2720    append: bool = True,
2721    copy: bool = True,
2722    prefix: str | None = None,
2723    into: Type[Expr] | None = None,
2724    dialect: DialectType = None,
2725    **opts: Unpack[ParserNoDialectArgs],
2726) -> E:
2727    inst = maybe_copy(instance, copy)
2728
2729    parsed = [
2730        maybe_parse(
2731            sql_or_expression=expression,
2732            into=into,
2733            prefix=prefix,
2734            dialect=dialect,
2735            **opts,
2736        )
2737        for expression in expressions
2738        if expression is not None
2739    ]
2740
2741    existing_expressions = inst.args.get(arg)
2742    if append and existing_expressions:
2743        parsed = existing_expressions + parsed
2744
2745    inst.set(arg, parsed)
2746    return inst
2747
2748
2749def _apply_conjunction_builder(
2750    *expressions: ExpOrStr | None,
2751    instance: E,
2752    arg: str,
2753    into: Type[Expr] | None = None,
2754    append: bool = True,
2755    copy: bool = True,
2756    dialect: DialectType = None,
2757    **opts: Unpack[ParserNoDialectArgs],
2758) -> E:
2759    filtered = [exp for exp in expressions if exp is not None and exp != ""]
2760    if not filtered:
2761        return instance
2762
2763    inst = maybe_copy(instance, copy)
2764
2765    existing = inst.args.get(arg)
2766    if append and existing is not None:
2767        filtered = [existing.this if into else existing] + filtered
2768
2769    node = and_(*filtered, dialect=dialect, copy=copy, **opts)
2770
2771    inst.set(arg, into(this=node) if into else node)
2772    return inst
2773
2774
2775def _combine(
2776    expressions: Sequence[ExpOrStr | None],
2777    operator: Type[Expr],
2778    dialect: DialectType = None,
2779    copy: bool = True,
2780    wrap: bool = True,
2781    **opts: Unpack[ParserNoDialectArgs],
2782) -> Expr:
2783    conditions = [
2784        condition(expression, dialect=dialect, copy=copy, **opts)
2785        for expression in expressions
2786        if expression is not None
2787    ]
2788
2789    this, *rest = conditions
2790    if rest and wrap:
2791        this = _wrap(this, Connector)
2792    for expression in rest:
2793        this = operator(this=this, expression=_wrap(expression, Connector) if wrap else expression)
2794
2795    return this
2796
2797
2798@t.overload
2799def _wrap(expression: None, kind: Type[Expr]) -> None: ...
2800
2801
2802@t.overload
2803def _wrap(expression: E, kind: Type[Expr]) -> E | Paren: ...
2804
2805
2806def _wrap(expression: E | None, kind: Type[Expr]) -> E | None | Paren:
2807    return Paren(this=expression) if isinstance(expression, kind) else expression
2808
2809
2810def _apply_set_operation(
2811    *expressions: ExpOrStr,
2812    set_operation: Type,
2813    distinct: bool = True,
2814    dialect: DialectType = None,
2815    copy: bool = True,
2816    **opts: Unpack[ParserNoDialectArgs],
2817) -> t.Any:
2818    return reduce(
2819        lambda x, y: set_operation(this=x, expression=y, distinct=distinct, **opts),
2820        (maybe_parse(e, dialect=dialect, copy=copy, **opts) for e in expressions),
2821    )
2822
2823
2824SAFE_IDENTIFIER_RE: t.Pattern[str] = re.compile(r"^[_a-zA-Z][\w]*$")
2825
2826
2827@t.overload
2828def to_identifier(name: None, quoted: bool | None = None, copy: bool = True) -> None: ...
2829
2830
2831@t.overload
2832def to_identifier(
2833    name: int | str | Identifier, quoted: bool | None = None, copy: bool = True
2834) -> Identifier: ...
2835
2836
2837def to_identifier(name, quoted=None, copy=True):
2838    """Builds an identifier.
2839
2840    Args:
2841        name: The name to turn into an identifier.
2842        quoted: Whether to force quote the identifier.
2843        copy: Whether to copy name if it's an Identifier.
2844
2845    Returns:
2846        The identifier ast node.
2847    """
2848
2849    if name is None:
2850        return None
2851
2852    if isinstance(name, Identifier):
2853        identifier = maybe_copy(name, copy)
2854    elif isinstance(name, str):
2855        identifier = Identifier(
2856            this=name,
2857            quoted=not SAFE_IDENTIFIER_RE.match(name) if quoted is None else quoted,
2858        )
2859    else:
2860        raise ValueError(f"Name needs to be a string or an Identifier, got: {name.__class__}")
2861    return identifier
2862
2863
2864def condition(
2865    expression: ExpOrStr,
2866    dialect: DialectType = None,
2867    copy: bool = True,
2868    **opts: Unpack[ParserNoDialectArgs],
2869) -> Expr:
2870    """
2871    Initialize a logical condition expression.
2872
2873    Example:
2874        >>> condition("x=1").sql()
2875        'x = 1'
2876
2877        This is helpful for composing larger logical syntax trees:
2878        >>> where = condition("x=1")
2879        >>> where = where.and_("y=1")
2880        >>> where.sql()
2881        'x = 1 AND y = 1'
2882
2883    Args:
2884        *expression: the SQL code string to parse.
2885            If an Expr instance is passed, this is used as-is.
2886        dialect: the dialect used to parse the input expression (in the case that the
2887            input expression is a SQL string).
2888        copy: Whether to copy `expression` (only applies to expressions).
2889        **opts: other options to use to parse the input expressions (again, in the case
2890            that the input expression is a SQL string).
2891
2892    Returns:
2893        The new Condition instance
2894    """
2895    return maybe_parse(
2896        expression,
2897        into=Condition,
2898        dialect=dialect,
2899        copy=copy,
2900        **opts,
2901    )
2902
2903
2904def and_(
2905    *expressions: ExpOrStr | None,
2906    dialect: DialectType = None,
2907    copy: bool = True,
2908    wrap: bool = True,
2909    **opts: Unpack[ParserNoDialectArgs],
2910) -> Condition:
2911    """
2912    Combine multiple conditions with an AND logical operator.
2913
2914    Example:
2915        >>> and_("x=1", and_("y=1", "z=1")).sql()
2916        'x = 1 AND (y = 1 AND z = 1)'
2917
2918    Args:
2919        *expressions: the SQL code strings to parse.
2920            If an Expr instance is passed, this is used as-is.
2921        dialect: the dialect used to parse the input expression.
2922        copy: whether to copy `expressions` (only applies to Exprs).
2923        wrap: whether to wrap the operands in `Paren`s. This is true by default to avoid
2924            precedence issues, but can be turned off when the produced AST is too deep and
2925            causes recursion-related issues.
2926        **opts: other options to use to parse the input expressions.
2927
2928    Returns:
2929        The new condition
2930    """
2931    return t.cast(Condition, _combine(expressions, And, dialect, copy=copy, wrap=wrap, **opts))
2932
2933
2934def or_(
2935    *expressions: ExpOrStr | None,
2936    dialect: DialectType = None,
2937    copy: bool = True,
2938    wrap: bool = True,
2939    **opts: Unpack[ParserNoDialectArgs],
2940) -> Condition:
2941    """
2942    Combine multiple conditions with an OR logical operator.
2943
2944    Example:
2945        >>> or_("x=1", or_("y=1", "z=1")).sql()
2946        'x = 1 OR (y = 1 OR z = 1)'
2947
2948    Args:
2949        *expressions: the SQL code strings to parse.
2950            If an Expr instance is passed, this is used as-is.
2951        dialect: the dialect used to parse the input expression.
2952        copy: whether to copy `expressions` (only applies to Exprs).
2953        wrap: whether to wrap the operands in `Paren`s. This is true by default to avoid
2954            precedence issues, but can be turned off when the produced AST is too deep and
2955            causes recursion-related issues.
2956        **opts: other options to use to parse the input expressions.
2957
2958    Returns:
2959        The new condition
2960    """
2961    return t.cast(Condition, _combine(expressions, Or, dialect, copy=copy, wrap=wrap, **opts))
2962
2963
2964def xor(
2965    *expressions: ExpOrStr | None,
2966    dialect: DialectType = None,
2967    copy: bool = True,
2968    wrap: bool = True,
2969    **opts: Unpack[ParserNoDialectArgs],
2970) -> Condition:
2971    """
2972    Combine multiple conditions with an XOR logical operator.
2973
2974    Example:
2975        >>> xor("x=1", xor("y=1", "z=1")).sql()
2976        'x = 1 XOR (y = 1 XOR z = 1)'
2977
2978    Args:
2979        *expressions: the SQL code strings to parse.
2980            If an Expr instance is passed, this is used as-is.
2981        dialect: the dialect used to parse the input expression.
2982        copy: whether to copy `expressions` (only applies to Exprs).
2983        wrap: whether to wrap the operands in `Paren`s. This is true by default to avoid
2984            precedence issues, but can be turned off when the produced AST is too deep and
2985            causes recursion-related issues.
2986        **opts: other options to use to parse the input expressions.
2987
2988    Returns:
2989        The new condition
2990    """
2991    return t.cast(Condition, _combine(expressions, Xor, dialect, copy=copy, wrap=wrap, **opts))
2992
2993
2994def paren(expression: ExpOrStr, copy: bool = True) -> Paren:
2995    """
2996    Wrap an expression in parentheses.
2997
2998    Example:
2999        >>> paren("5 + 3").sql()
3000        '(5 + 3)'
3001
3002    Args:
3003        expression: the SQL code string to parse.
3004            If an Expr instance is passed, this is used as-is.
3005        copy: whether to copy the expression or not.
3006
3007    Returns:
3008        The wrapped expression.
3009    """
3010    return Paren(this=maybe_parse(expression, copy=copy))
3011
3012
3013def alias_(
3014    expression: ExpOrStr,
3015    alias: str | Identifier | None,
3016    table: bool | Sequence[str | Identifier] = False,
3017    quoted: bool | None = None,
3018    dialect: DialectType = None,
3019    copy: bool = True,
3020    **opts: Unpack[ParserNoDialectArgs],
3021) -> Expr:
3022    """Create an Alias expression.
3023
3024    Example:
3025        >>> alias_('foo', 'bar').sql()
3026        'foo AS bar'
3027
3028        >>> alias_('(select 1, 2)', 'bar', table=['a', 'b']).sql()
3029        '(SELECT 1, 2) AS bar(a, b)'
3030
3031    Args:
3032        expression: the SQL code strings to parse.
3033            If an Expr instance is passed, this is used as-is.
3034        alias: the alias name to use. If the name has
3035            special characters it is quoted.
3036        table: Whether to create a table alias, can also be a list of columns.
3037        quoted: whether to quote the alias
3038        dialect: the dialect used to parse the input expression.
3039        copy: Whether to copy the expression.
3040        **opts: other options to use to parse the input expressions.
3041
3042    Returns:
3043        Alias: the aliased expression
3044    """
3045    exp = maybe_parse(expression, dialect=dialect, copy=copy, **opts)
3046    alias = to_identifier(alias, quoted=quoted)
3047
3048    if table:
3049        from sqlglot.expressions.query import TableAlias as _TableAlias
3050
3051        table_alias = _TableAlias(this=alias)
3052        exp.set("alias", table_alias)
3053
3054        if not isinstance(table, bool):
3055            for column in table:
3056                table_alias.append("columns", to_identifier(column, quoted=quoted))
3057
3058        return exp
3059
3060    # We don't set the "alias" arg for Window expressions, because that would add an IDENTIFIER node in
3061    # the AST, representing a "named_window" [1] construct (eg. bigquery). What we want is an ALIAS node
3062    # for the complete Window expression.
3063    #
3064    # [1]: https://cloud.google.com/bigquery/docs/reference/standard-sql/window-function-calls
3065
3066    if "alias" in exp.arg_types and type(exp).__name__ != "Window":
3067        exp.set("alias", alias)
3068        return exp
3069    return Alias(this=exp, alias=alias)
3070
3071
3072@t.overload
3073def column(
3074    col: str | Identifier,
3075    table: str | Identifier | None = None,
3076    db: str | Identifier | None = None,
3077    catalog: str | Identifier | None = None,
3078    *,
3079    fields: Collection[str | Identifier],
3080    quoted: bool | None = None,
3081    copy: bool = True,
3082) -> Dot:
3083    pass
3084
3085
3086@t.overload
3087def column(
3088    col: str | Identifier | Star,
3089    table: str | Identifier | None = None,
3090    db: str | Identifier | None = None,
3091    catalog: str | Identifier | None = None,
3092    *,
3093    fields: t.Literal[None] = None,
3094    quoted: bool | None = None,
3095    copy: bool = True,
3096) -> Column:
3097    pass
3098
3099
3100def column(
3101    col,
3102    table=None,
3103    db=None,
3104    catalog=None,
3105    *,
3106    fields=None,
3107    quoted=None,
3108    copy: bool = True,
3109):
3110    """
3111    Build a Column.
3112
3113    Args:
3114        col: Column name.
3115        table: Table name.
3116        db: Database name.
3117        catalog: Catalog name.
3118        fields: Additional fields using dots.
3119        quoted: Whether to force quotes on the column's identifiers.
3120        copy: Whether to copy identifiers if passed in.
3121
3122    Returns:
3123        The new Column instance.
3124    """
3125    if not isinstance(col, Star):
3126        col = to_identifier(col, quoted=quoted, copy=copy)
3127
3128    this: Column | Dot = Column(
3129        this=col,
3130        table=to_identifier(table, quoted=quoted, copy=copy),
3131        db=to_identifier(db, quoted=quoted, copy=copy),
3132        catalog=to_identifier(catalog, quoted=quoted, copy=copy),
3133    )
3134
3135    if fields:
3136        this = Dot.build(
3137            (this, *(to_identifier(field, quoted=quoted, copy=copy) for field in fields))
3138        )
3139    return this