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, 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 = {"this": True, "kind": True}
1599
1600
1601class LockingStatement(Expression):
1602    arg_types = {"this": True, "expression": True}
1603
1604
1605@trait
1606class ColumnConstraintKind(Expr):
1607    pass
1608
1609
1610@trait
1611class SubqueryPredicate(Predicate):
1612    pass
1613
1614
1615class All(Expression, SubqueryPredicate):
1616    pass
1617
1618
1619class Any(Expression, SubqueryPredicate):
1620    pass
1621
1622
1623@trait
1624class Binary(Condition):
1625    arg_types: t.ClassVar[dict[str, bool]] = {"this": True, "expression": True}
1626
1627    @property
1628    def left(self) -> Expr:
1629        return self.args["this"]
1630
1631    @property
1632    def right(self) -> Expr:
1633        return self.args["expression"]
1634
1635
1636@trait
1637class Connector(Binary):
1638    pass
1639
1640
1641@trait
1642class Func(Condition):
1643    """
1644    The base class for all function expressions.
1645
1646    Attributes:
1647        is_var_len_args (bool): if set to True the argument identified by var_len_arg_key will be
1648            treated as a variable length argument and the argument's value will be stored as a list.
1649        var_len_arg_key (str): the arg_types key that collects the variable length arguments.
1650            Arguments preceding it in arg_types are filled positionally; those following it (e.g.
1651            dialect flags) are never populated by from_arg_list.
1652        _sql_names (list): the SQL name (1st item in the list) and aliases (subsequent items) for this
1653            function expression. These values are used to map this node to a name during parsing as
1654            well as to provide the function's name during SQL string generation. By default the SQL
1655            name is set to the expression's class name transformed to snake case.
1656    """
1657
1658    is_var_len_args: t.ClassVar[bool] = False
1659    var_len_arg_key: t.ClassVar[str] = "expressions"
1660    _sql_names: t.ClassVar[list[str]] = []
1661
1662    @classmethod
1663    def from_arg_list(cls, args: Sequence[object]) -> Self:
1664        if cls.is_var_len_args:
1665            all_arg_keys = tuple(cls.arg_types)
1666            var_len_index = all_arg_keys.index(cls.var_len_arg_key)
1667
1668            args_dict = {arg_key: arg for arg, arg_key in zip(args, all_arg_keys[:var_len_index])}
1669            args_dict[cls.var_len_arg_key] = args[var_len_index:]
1670        else:
1671            args_dict = {arg_key: arg for arg, arg_key in zip(args, cls.arg_types)}
1672
1673        return cls(**args_dict)
1674
1675    @classmethod
1676    def sql_names(cls) -> list[str]:
1677        if cls is Func:
1678            raise NotImplementedError(
1679                "SQL name is only supported by concrete function implementations"
1680            )
1681        if not cls._sql_names:
1682            return [camel_to_snake_case(cls.__name__)]
1683        return cls._sql_names
1684
1685    @classmethod
1686    def sql_name(cls) -> str:
1687        sql_names = cls.sql_names()
1688        assert sql_names, f"Expected non-empty 'sql_names' for Func: {cls.__name__}."
1689        return sql_names[0]
1690
1691    @classmethod
1692    def default_parser_mappings(cls) -> dict[str, t.Callable[[Sequence[object]], Self]]:
1693        return {name: cls.from_arg_list for name in cls.sql_names()}
1694
1695
1696@trait
1697class AggFunc(Func):
1698    pass
1699
1700
1701class Column(Expression, Condition):
1702    # "shadow" marks a column whose qualifier is shadowed by a projection alias, so it must be
1703    # rendered unqualified in dialects where PROJECTION_ALIASES_SHADOW_SOURCE_NAMES is set
1704    arg_types = {
1705        "this": True,
1706        "table": False,
1707        "db": False,
1708        "catalog": False,
1709        "join_mark": False,
1710        "shadow": False,
1711    }
1712
1713    @property
1714    def table(self) -> str:
1715        return self.text("table")
1716
1717    @property
1718    def db(self) -> str:
1719        return self.text("db")
1720
1721    @property
1722    def catalog(self) -> str:
1723        return self.text("catalog")
1724
1725    @property
1726    def output_name(self) -> str:
1727        return self.name
1728
1729    @property
1730    def parts(self) -> list[Identifier | Star]:
1731        """Return the parts of a column in order catalog, db, table, name."""
1732        return [
1733            self.args[part] for part in ("catalog", "db", "table", "this") if self.args.get(part)
1734        ]
1735
1736    def to_dot(self, include_dots: bool = True) -> Dot | Identifier | Star:
1737        """Converts the column into a dot expression."""
1738        parts = self.parts
1739        parent = self.parent
1740
1741        if include_dots:
1742            while isinstance(parent, Dot):
1743                parts.append(parent.expression)
1744                parent = parent.parent
1745
1746        return Dot.build(deepcopy(parts)) if len(parts) > 1 else parts[0]
1747
1748
1749class Literal(Expression, Condition):
1750    arg_types = {"this": True, "is_string": True}
1751    _hash_raw_args = True
1752    is_primitive = True
1753
1754    @classmethod
1755    def number(cls, number: object) -> Literal | Neg:
1756        lit = cls(this=str(number), is_string=False)
1757        try:
1758            to_py = lit.to_py()
1759            if not isinstance(to_py, str) and to_py < 0:
1760                lit.set("this", str(abs(to_py)))
1761                return Neg(this=lit)
1762        except Exception:
1763            pass
1764        return lit
1765
1766    @classmethod
1767    def string(cls, string: object) -> Literal:
1768        return cls(this=str(string), is_string=True)
1769
1770    @property
1771    def output_name(self) -> str:
1772        return self.name
1773
1774    def to_py(self) -> int | str | Decimal:
1775        if self.is_number:
1776            try:
1777                return int(self.this)
1778            except ValueError:
1779                try:
1780                    return Decimal(self.this)
1781                except InvalidOperation as e:
1782                    raise ValueError(f"Invalid numeric literal: {self.this!r}") from e
1783        return self.this
1784
1785
1786class Var(Expression):
1787    is_primitive = True
1788
1789
1790class WithinGroup(Expression):
1791    arg_types = {"this": True, "expression": False}
1792
1793
1794class Pseudocolumn(Column):
1795    pass
1796
1797
1798class Hint(Expression):
1799    arg_types = {"expressions": True}
1800
1801
1802class JoinHint(Expression):
1803    arg_types = {"this": True, "expressions": True}
1804
1805
1806class Identifier(Expression):
1807    arg_types = {
1808        "this": True,
1809        "quoted": False,
1810        "global_": False,
1811        "temporary": False,
1812    }
1813    is_primitive = True
1814    _hash_raw_args = True
1815
1816    @property
1817    def quoted(self) -> bool:
1818        return bool(self.args.get("quoted"))
1819
1820    @property
1821    def output_name(self) -> str:
1822        return self.name
1823
1824
1825# https://docs.snowflake.com/en/sql-reference/identifier-literal
1826# "expressions" holds the arguments when the resolved identifier is invoked as a
1827# function, e.g. `IDENTIFIER('my_func')(1, 2)`
1828class DynamicIdentifier(Expression, Func):
1829    arg_types = {"this": True, "expressions": False}
1830
1831
1832class Opclass(Expression):
1833    arg_types = {"this": True, "expression": True}
1834
1835
1836class Star(Expression):
1837    arg_types = {"except_": False, "replace": False, "rename": False, "ilike": False}
1838
1839    @property
1840    def name(self) -> str:
1841        return "*"
1842
1843    @property
1844    def output_name(self) -> str:
1845        return self.name
1846
1847
1848class Parameter(Expression, Condition):
1849    arg_types = {"this": True, "expression": False}
1850
1851
1852class SessionParameter(Expression, Condition):
1853    arg_types = {"this": True, "kind": False}
1854
1855
1856class Placeholder(Expression, Condition):
1857    arg_types = {"this": False, "kind": False, "widget": False, "jdbc": False}
1858
1859    @property
1860    def name(self) -> str:
1861        return self.text("this") or "?"
1862
1863
1864class Null(Expression, Condition):
1865    arg_types = {}
1866
1867    @property
1868    def name(self) -> str:
1869        return "NULL"
1870
1871    def to_py(self) -> t.Literal[None]:
1872        return None
1873
1874
1875class Boolean(Expression, Condition):
1876    is_primitive = True
1877
1878    def to_py(self) -> bool:
1879        return self.this
1880
1881
1882class Dot(Expression, Binary):
1883    @property
1884    def is_star(self) -> bool:
1885        return self.expression.is_star
1886
1887    @property
1888    def name(self) -> str:
1889        return self.expression.name
1890
1891    @property
1892    def output_name(self) -> str:
1893        return self.name
1894
1895    @classmethod
1896    def build(cls, expressions: Sequence[Expr]) -> Dot:
1897        """Build a Dot object with a sequence of expressions."""
1898        if len(expressions) < 2:
1899            raise ValueError("Dot requires >= 2 expressions.")
1900
1901        return t.cast(Dot, reduce(lambda x, y: Dot(this=x, expression=y), expressions))
1902
1903    @property
1904    def parts(self) -> list[Expr]:
1905        """Return the parts of a table / column in order catalog, db, table."""
1906        this, *parts = self.flatten()
1907
1908        parts.reverse()
1909
1910        for arg in COLUMN_PARTS:
1911            part = this.args.get(arg)
1912
1913            if isinstance(part, Expr):
1914                parts.append(part)
1915
1916        parts.reverse()
1917        return parts
1918
1919
1920class Kwarg(Expression, Binary):
1921    """Kwarg in special functions like func(kwarg => y)."""
1922
1923
1924class Alias(Expression):
1925    arg_types = {"this": True, "alias": False}
1926
1927    @property
1928    def output_name(self) -> str:
1929        return self.alias
1930
1931
1932class PivotAlias(Alias):
1933    pass
1934
1935
1936class PivotAny(Expression):
1937    arg_types = {"this": False}
1938
1939
1940class Aliases(Expression):
1941    arg_types = {"this": True, "expressions": True}
1942
1943    @property
1944    def aliases(self) -> list[Expr]:
1945        return self.expressions
1946
1947
1948class Bracket(Expression, Condition):
1949    # https://cloud.google.com/bigquery/docs/reference/standard-sql/operators#array_subscript_operator
1950    arg_types = {
1951        "this": True,
1952        "expressions": True,
1953        "offset": False,
1954        "safe": False,
1955        "returns_list_for_maps": False,
1956        "json_access": False,
1957    }
1958
1959    @property
1960    def output_name(self) -> str:
1961        if len(self.expressions) == 1:
1962            return self.expressions[0].output_name
1963
1964        return super().output_name
1965
1966
1967class ForIn(Expression):
1968    arg_types = {"this": True, "expression": True}
1969
1970
1971class IgnoreNulls(Expression):
1972    pass
1973
1974
1975class RespectNulls(Expression):
1976    pass
1977
1978
1979class HavingMax(Expression):
1980    arg_types = {"this": True, "expression": True, "max": True}
1981
1982
1983class SafeFunc(Expression, Func):
1984    pass
1985
1986
1987class Typeof(Expression, Func):
1988    pass
1989
1990
1991class ParameterizedAgg(Expression, AggFunc):
1992    arg_types = {"this": True, "expressions": True, "params": True}
1993
1994
1995class Anonymous(Expression, Func):
1996    arg_types = {"this": True, "expressions": False}
1997    is_var_len_args = True
1998
1999    @property
2000    def name(self) -> str:
2001        return self.this if isinstance(self.this, str) else self.this.name
2002
2003
2004class AnonymousAggFunc(Expression, AggFunc):
2005    arg_types = {"this": True, "expressions": False}
2006    is_var_len_args = True
2007
2008
2009class CombinedAggFunc(AnonymousAggFunc):
2010    arg_types = {"this": True, "expressions": False}
2011
2012
2013class CombinedParameterizedAgg(ParameterizedAgg):
2014    arg_types = {"this": True, "expressions": True, "params": True}
2015
2016
2017class HashAgg(Expression, AggFunc):
2018    arg_types = {"this": True, "expressions": False}
2019    is_var_len_args = True
2020
2021
2022class Hll(Expression, AggFunc):
2023    arg_types = {"this": True, "expressions": False}
2024    is_var_len_args = True
2025
2026
2027class ApproxDistinct(Expression, AggFunc):
2028    arg_types = {"this": True, "accuracy": False}
2029    _sql_names = ["APPROX_DISTINCT", "APPROX_COUNT_DISTINCT"]
2030
2031
2032class Slice(Expression):
2033    arg_types = {"this": False, "expression": False, "step": False}
2034
2035
2036@trait
2037class TimeUnit(Expr):
2038    """Automatically converts unit arg into a var."""
2039
2040    UNABBREVIATED_UNIT_NAME: t.ClassVar[dict[str, str]] = {
2041        "D": "DAY",
2042        "H": "HOUR",
2043        "M": "MINUTE",
2044        "MS": "MILLISECOND",
2045        "NS": "NANOSECOND",
2046        "Q": "QUARTER",
2047        "S": "SECOND",
2048        "US": "MICROSECOND",
2049        "W": "WEEK",
2050        "Y": "YEAR",
2051    }
2052
2053    VAR_LIKE: t.ClassVar[tuple[Type[Expr], ...]] = (Column, Literal, Var)
2054
2055    def __init__(self, **args: object) -> None:
2056        super().__init__(**args)
2057
2058        unit = self.args.get("unit")
2059        if (
2060            unit
2061            and type(unit) in TimeUnit.VAR_LIKE
2062            and not (isinstance(unit, Column) and len(unit.parts) != 1)
2063        ):
2064            unit = Var(this=(self.UNABBREVIATED_UNIT_NAME.get(unit.name) or unit.name).upper())
2065            self.args["unit"] = unit
2066            self._set_parent("unit", unit)
2067        elif type(unit).__name__ == "Week":
2068            unit.set("this", Var(this=unit.this.name.upper()))  # type: ignore[union-attr]
2069
2070    @property
2071    def unit(self) -> Expr | None:
2072        return self.args.get("unit")
2073
2074
2075class _TimeUnit(Expression, TimeUnit):
2076    """Automatically converts unit arg into a var."""
2077
2078    arg_types = {"unit": False}
2079
2080
2081@trait
2082class IntervalOp(TimeUnit):
2083    def interval(self) -> Interval:
2084        from sqlglot.expressions.datatypes import Interval
2085
2086        expr = self.expression
2087        return Interval(
2088            this=expr.copy() if expr is not None else None,
2089            unit=self.unit.copy() if self.unit else None,
2090        )
2091
2092
2093class Filter(Expression):
2094    arg_types = {"this": True, "expression": True}
2095
2096
2097class Check(Expression):
2098    pass
2099
2100
2101class Ordered(Expression):
2102    arg_types = {"this": True, "desc": False, "nulls_first": True, "with_fill": False}
2103
2104    @property
2105    def name(self) -> str:
2106        return self.this.name
2107
2108
2109class Add(Expression, Binary):
2110    pass
2111
2112
2113class BitwiseAnd(Expression, Binary):
2114    arg_types = {"this": True, "expression": True, "padside": False}
2115
2116
2117class BitwiseLeftShift(Expression, Binary):
2118    arg_types = {"this": True, "expression": True, "requires_int128": False}
2119
2120
2121class BitwiseOr(Expression, Binary):
2122    arg_types = {"this": True, "expression": True, "padside": False}
2123
2124
2125class BitwiseRightShift(Expression, Binary):
2126    arg_types = {"this": True, "expression": True, "requires_int128": False}
2127
2128
2129class BitwiseXor(Expression, Binary):
2130    arg_types = {"this": True, "expression": True, "padside": False}
2131
2132
2133class Div(Expression, Binary):
2134    arg_types = {"this": True, "expression": True, "typed": False, "safe": False}
2135
2136
2137class Overlaps(Expression, Binary, Predicate):
2138    pass
2139
2140
2141class ExtendsLeft(Expression, Binary, Predicate):
2142    pass
2143
2144
2145class ExtendsRight(Expression, Binary, Predicate):
2146    pass
2147
2148
2149class DPipe(Expression, Binary):
2150    arg_types = {"this": True, "expression": True, "safe": False}
2151
2152
2153class EQ(Expression, Binary, Predicate):
2154    pass
2155
2156
2157class NullSafeEQ(Expression, Binary, Predicate):
2158    pass
2159
2160
2161class NullSafeNEQ(Expression, Binary, Predicate):
2162    pass
2163
2164
2165class PropertyEQ(Expression, Binary):
2166    pass
2167
2168
2169class Distance(Expression, Binary):
2170    pass
2171
2172
2173class DistanceNd(Expression, Binary):
2174    pass
2175
2176
2177class Escape(Expression, Binary):
2178    pass
2179
2180
2181class Glob(Expression, Binary, Predicate):
2182    pass
2183
2184
2185class GT(Expression, Binary, Predicate):
2186    pass
2187
2188
2189class GTE(Expression, Binary, Predicate):
2190    pass
2191
2192
2193class ILike(Expression, Binary, Predicate):
2194    arg_types = {"this": True, "expression": True, "negate": False}
2195
2196
2197class IntDiv(Expression, Binary):
2198    pass
2199
2200
2201class Is(Expression, Binary, Predicate):
2202    arg_types = {"this": True, "expression": True, "negate": False}
2203
2204
2205class Like(Expression, Binary, Predicate):
2206    arg_types = {"this": True, "expression": True, "negate": False}
2207
2208
2209class Match(Expression, Binary, Predicate):
2210    pass
2211
2212
2213class LT(Expression, Binary, Predicate):
2214    pass
2215
2216
2217class LTE(Expression, Binary, Predicate):
2218    pass
2219
2220
2221class Mod(Expression, Binary):
2222    pass
2223
2224
2225class Mul(Expression, Binary):
2226    pass
2227
2228
2229class NEQ(Expression, Binary, Predicate):
2230    pass
2231
2232
2233class NestedJSONSelect(Expression, Binary):
2234    pass
2235
2236
2237class Operator(Expression, Binary):
2238    arg_types = {"this": True, "operator": True, "expression": True}
2239
2240
2241class SimilarTo(Expression, Binary, Predicate):
2242    pass
2243
2244
2245class Sub(Expression, Binary):
2246    pass
2247
2248
2249class Adjacent(Expression, Binary, Predicate):
2250    pass
2251
2252
2253class Unary(Expression, Condition):
2254    pass
2255
2256
2257class BitwiseNot(Unary):
2258    pass
2259
2260
2261class Not(Unary):
2262    pass
2263
2264
2265class Paren(Unary):
2266    @property
2267    def output_name(self) -> str:
2268        return self.this.name
2269
2270
2271class Neg(Unary):
2272    def to_py(self) -> int | Decimal:
2273        if self.is_number:
2274            return self.this.to_py() * -1
2275        return super().to_py()
2276
2277
2278class AtIndex(Expression):
2279    arg_types = {"this": True, "expression": True}
2280
2281
2282class AtTimeZone(Expression):
2283    arg_types = {"this": True, "zone": True}
2284
2285
2286class FromTimeZone(Expression):
2287    arg_types = {"this": True, "zone": True}
2288
2289
2290class FormatPhrase(Expression):
2291    """Format override for a column in Teradata.
2292    Can be expanded to additional dialects as needed
2293
2294    https://docs.teradata.com/r/Enterprise_IntelliFlex_VMware/SQL-Data-Types-and-Literals/Data-Type-Formats-and-Format-Phrases/FORMAT
2295    """
2296
2297    arg_types = {"this": True, "format": True}
2298
2299
2300class Between(Expression, Predicate):
2301    arg_types = {"this": True, "low": True, "high": True, "symmetric": False}
2302
2303
2304class Distinct(Expression):
2305    arg_types = {"expressions": False, "on": False}
2306
2307
2308class In(Expression, Predicate):
2309    arg_types = {
2310        "this": True,
2311        "expressions": False,
2312        "query": False,
2313        "unnest": False,
2314        "field": False,
2315        "is_global": False,
2316    }
2317
2318
2319class And(Expression, Connector, Func):
2320    pass
2321
2322
2323class Or(Expression, Connector, Func):
2324    pass
2325
2326
2327class Xor(Expression, Connector, Func):
2328    arg_types = {"this": True, "expression": True, "round_input": False}
2329
2330
2331class Pow(Expression, Binary, Func):
2332    _sql_names = ["POWER", "POW"]
2333
2334
2335class RegexpLike(Expression, Binary, Predicate, Func):
2336    arg_types = {"this": True, "expression": True, "flag": False, "full_match": False}
2337
2338
2339def not_(
2340    expression: ExpOrStr,
2341    dialect: DialectType = None,
2342    copy: bool = True,
2343    **opts: Unpack[ParserNoDialectArgs],
2344) -> Not:
2345    """
2346    Wrap a condition with a NOT operator.
2347
2348    Example:
2349        >>> not_("this_suit='black'").sql()
2350        "NOT this_suit = 'black'"
2351
2352    Args:
2353        expression: the SQL code string to parse.
2354            If an Expr instance is passed, this is used as-is.
2355        dialect: the dialect used to parse the input expression.
2356        copy: whether to copy the expression or not.
2357        **opts: other options to use to parse the input expressions.
2358
2359    Returns:
2360        The new condition.
2361    """
2362    this = condition(
2363        expression,
2364        dialect=dialect,
2365        copy=copy,
2366        **opts,
2367    )
2368    return Not(this=_wrap(this, Connector))
2369
2370
2371def _lazy_unnest(**kwargs: object) -> Expr:
2372    from sqlglot.expressions.array import Unnest
2373
2374    return Unnest(**kwargs)
2375
2376
2377def convert(value: t.Any, copy: bool = False) -> Expr:
2378    """Convert a python value into an expression object.
2379
2380    Raises an error if a conversion is not possible.
2381
2382    Args:
2383        value: A python object.
2384        copy: Whether to copy `value` (only applies to Exprs and collections).
2385
2386    Returns:
2387        The equivalent expression object.
2388    """
2389    if isinstance(value, Expr):
2390        return maybe_copy(value, copy)
2391    if isinstance(value, str):
2392        return Literal.string(value)
2393    if isinstance(value, bool):
2394        return Boolean(this=value)
2395    if value is None or (isinstance(value, float) and math.isnan(value)):
2396        return Null()
2397    if isinstance(value, numbers.Number):
2398        return Literal.number(value)
2399    if isinstance(value, bytes):
2400        from sqlglot.expressions.query import HexString as _HexString
2401
2402        return _HexString(this=value.hex())
2403    if isinstance(value, datetime.datetime):
2404        datetime_literal = Literal.string(value.isoformat(sep=" "))
2405
2406        tz = None
2407        if value.tzinfo:
2408            # this works for zoneinfo.ZoneInfo, pytz.timezone and datetime.datetime.utc to return IANA timezone names like "America/Los_Angeles"
2409            # instead of abbreviations like "PDT". This is for consistency with other timezone handling functions in SQLGlot
2410            tz = Literal.string(str(value.tzinfo))
2411
2412        from sqlglot.expressions.temporal import TimeStrToTime as _TimeStrToTime
2413
2414        return _TimeStrToTime(this=datetime_literal, zone=tz)
2415    if isinstance(value, datetime.date):
2416        date_literal = Literal.string(value.strftime("%Y-%m-%d"))
2417        from sqlglot.expressions.temporal import DateStrToDate as _DateStrToDate
2418
2419        return _DateStrToDate(this=date_literal)
2420    if isinstance(value, datetime.time):
2421        time_literal = Literal.string(value.isoformat())
2422        from sqlglot.expressions.temporal import TsOrDsToTime as _TsOrDsToTime
2423
2424        return _TsOrDsToTime(this=time_literal)
2425    if isinstance(value, tuple):
2426        if hasattr(value, "_fields"):
2427            from sqlglot.expressions.array import Struct as _Struct
2428
2429            return _Struct(
2430                expressions=[
2431                    PropertyEQ(
2432                        this=to_identifier(k), expression=convert(getattr(value, k), copy=copy)
2433                    )
2434                    for k in value._fields
2435                ]
2436            )
2437        from sqlglot.expressions.query import Tuple as _Tuple
2438
2439        return _Tuple(expressions=[convert(v, copy=copy) for v in value])
2440    if isinstance(value, list):
2441        from sqlglot.expressions.array import Array as _Array
2442
2443        return _Array(expressions=[convert(v, copy=copy) for v in value])
2444    if isinstance(value, dict):
2445        from sqlglot.expressions.array import Array as _Array
2446        from sqlglot.expressions.array import Map as _Map
2447
2448        return _Map(
2449            keys=_Array(expressions=[convert(k, copy=copy) for k in value]),
2450            values=_Array(expressions=[convert(v, copy=copy) for v in value.values()]),
2451        )
2452    if hasattr(value, "__dict__"):
2453        from sqlglot.expressions.array import Struct as _Struct
2454
2455        return _Struct(
2456            expressions=[
2457                PropertyEQ(this=to_identifier(k), expression=convert(v, copy=copy))
2458                for k, v in value.__dict__.items()
2459            ]
2460        )
2461    raise ValueError(f"Cannot convert {value}")
2462
2463
2464QUERY_MODIFIERS = {
2465    "match": False,
2466    "laterals": False,
2467    "joins": False,
2468    "connect": False,
2469    "pivots": False,
2470    "prewhere": False,
2471    "where": False,
2472    "group": False,
2473    "having": False,
2474    "qualify": False,
2475    "windows": False,
2476    "distribute": False,
2477    "sort": False,
2478    "cluster": False,
2479    "order": False,
2480    "limit": False,
2481    "offset": False,
2482    "locks": False,
2483    "sample": False,
2484    "settings": False,
2485    "format": False,
2486    "options": False,
2487    "for_": False,
2488}
2489
2490
2491TIMESTAMP_PARTS = {
2492    "year": False,
2493    "month": False,
2494    "day": False,
2495    "hour": False,
2496    "min": False,
2497    "sec": False,
2498    "nano": False,
2499}
2500
2501
2502@t.overload
2503def maybe_parse(
2504    sql_or_expression: int | str,
2505    *,
2506    into: Type[E],
2507    dialect: DialectType = None,
2508    prefix: str | None = None,
2509    copy: bool = False,
2510    **opts: Unpack[ParserNoDialectArgs],
2511) -> E: ...
2512
2513
2514@t.overload
2515def maybe_parse(
2516    sql_or_expression: int | str | E,
2517    *,
2518    into: IntoType | None = None,
2519    dialect: DialectType = None,
2520    prefix: str | None = None,
2521    copy: bool = False,
2522    **opts: Unpack[ParserNoDialectArgs],
2523) -> E: ...
2524
2525
2526def maybe_parse(
2527    sql_or_expression: ExpOrStr,
2528    *,
2529    into: IntoType | None = None,
2530    dialect: DialectType = None,
2531    prefix: str | None = None,
2532    copy: bool = False,
2533    **opts: Unpack[ParserNoDialectArgs],
2534) -> Expr:
2535    """Gracefully handle a possible string or expression.
2536
2537    Example:
2538        >>> maybe_parse("1")
2539        Literal(this=1, is_string=False)
2540        >>> maybe_parse(to_identifier("x"))
2541        Identifier(this=x, quoted=False)
2542
2543    Args:
2544        sql_or_expression: the SQL code string or an expression
2545        into: the SQLGlot Expr to parse into
2546        dialect: the dialect used to parse the input expressions (in the case that an
2547            input expression is a SQL string).
2548        prefix: a string to prefix the sql with before it gets parsed
2549            (automatically includes a space)
2550        copy: whether to copy the expression.
2551        **opts: other options to use to parse the input expressions (again, in the case
2552            that an input expression is a SQL string).
2553
2554    Returns:
2555        Expr: the parsed or given expression.
2556    """
2557    if isinstance(sql_or_expression, Expr):
2558        if copy:
2559            return sql_or_expression.copy()
2560        return sql_or_expression
2561
2562    if sql_or_expression is None:
2563        raise ParseError("SQL cannot be None")
2564
2565    import sqlglot
2566
2567    sql = str(sql_or_expression)
2568    if prefix:
2569        sql = f"{prefix} {sql}"
2570
2571    return sqlglot.parse_one(sql, read=dialect, into=into, **opts)
2572
2573
2574@t.overload
2575def maybe_copy(instance: None, copy: bool = True) -> None: ...
2576
2577
2578@t.overload
2579def maybe_copy(instance: E, copy: bool = True) -> E: ...
2580
2581
2582def maybe_copy(instance, copy=True):
2583    return instance.copy() if copy and instance else instance
2584
2585
2586def _to_s(node: t.Any, verbose: bool = False, level: int = 0, repr_str: bool = False) -> str:
2587    """Generate a textual representation of an Expr tree"""
2588    indent = "\n" + ("  " * (level + 1))
2589    delim = f",{indent}"
2590
2591    if isinstance(node, Expr):
2592        args = {k: v for k, v in node.args.items() if (v is not None and v != []) or verbose}
2593
2594        if (node.type or verbose) and not node.is_data_type:
2595            args["_type"] = node.type
2596        if node.comments or verbose:
2597            args["_comments"] = node.comments
2598
2599        if verbose:
2600            args["_id"] = id(node)
2601
2602        # Inline leaves for a more compact representation
2603        if node.is_leaf():
2604            indent = ""
2605            delim = ", "
2606
2607        repr_str = node.is_string or (isinstance(node, Identifier) and node.quoted)
2608        items = delim.join(
2609            [f"{k}={_to_s(v, verbose, level + 1, repr_str=repr_str)}" for k, v in args.items()]
2610        )
2611        return f"{node.__class__.__name__}({indent}{items})"
2612
2613    if isinstance(node, list):
2614        items = delim.join(_to_s(i, verbose, level + 1) for i in node)
2615        items = f"{indent}{items}" if items else ""
2616        return f"[{items}]"
2617
2618    # We use the representation of the string to avoid stripping out important whitespace
2619    if repr_str and isinstance(node, str):
2620        node = repr(node)
2621
2622    # Indent multiline strings to match the current level
2623    return indent.join(textwrap.dedent(str(node).strip("\n")).splitlines())
2624
2625
2626def _is_wrong_expression(expression, into):
2627    return isinstance(expression, Expr) and not isinstance(expression, into)
2628
2629
2630def _apply_builder(
2631    expression: ExpOrStr,
2632    instance: E,
2633    arg: str,
2634    copy: bool = True,
2635    prefix: str | None = None,
2636    into: Type[Expr] | None = None,
2637    dialect: DialectType = None,
2638    into_arg="this",
2639    **opts: Unpack[ParserNoDialectArgs],
2640) -> E:
2641    if _is_wrong_expression(expression, into) and into is not None:
2642        expression = into(**{into_arg: expression})
2643    instance = maybe_copy(instance, copy)
2644    expression = maybe_parse(
2645        sql_or_expression=expression,
2646        prefix=prefix,
2647        into=into,
2648        dialect=dialect,
2649        **opts,
2650    )
2651    instance.set(arg, expression)
2652    return instance
2653
2654
2655def _apply_child_list_builder(
2656    *expressions: ExpOrStr | None,
2657    instance: E,
2658    arg: str,
2659    append: bool = True,
2660    copy: bool = True,
2661    prefix: str | None = None,
2662    into: Type[Expr] | None = None,
2663    dialect: DialectType = None,
2664    properties: MutableMapping[str, object] | None = None,
2665    **opts: Unpack[ParserNoDialectArgs],
2666) -> E:
2667    instance = maybe_copy(instance, copy)
2668    parsed = []
2669    properties = {} if properties is None else properties
2670
2671    for expression in expressions:
2672        if expression is not None:
2673            if _is_wrong_expression(expression, into) and into is not None:
2674                expression = into(expressions=[expression])
2675
2676            expression = maybe_parse(
2677                expression,
2678                into=into,
2679                dialect=dialect,
2680                prefix=prefix,
2681                **opts,
2682            )
2683            for k, v in expression.args.items():
2684                if k == "expressions":
2685                    parsed.extend(v)
2686                else:
2687                    properties[k] = v
2688
2689    existing = instance.args.get(arg)
2690    if append and existing:
2691        parsed = existing.expressions + parsed
2692    if into is None:
2693        raise ValueError("`into` is required to use `_apply_child_list_builder`")
2694    child = into(expressions=parsed)
2695    for k, v in properties.items():
2696        child.set(k, v)
2697    instance.set(arg, child)
2698
2699    return instance
2700
2701
2702def _apply_list_builder(
2703    *expressions: ExpOrStr | None,
2704    instance: E,
2705    arg: str,
2706    append: bool = True,
2707    copy: bool = True,
2708    prefix: str | None = None,
2709    into: Type[Expr] | None = None,
2710    dialect: DialectType = None,
2711    **opts: Unpack[ParserNoDialectArgs],
2712) -> E:
2713    inst = maybe_copy(instance, copy)
2714
2715    parsed = [
2716        maybe_parse(
2717            sql_or_expression=expression,
2718            into=into,
2719            prefix=prefix,
2720            dialect=dialect,
2721            **opts,
2722        )
2723        for expression in expressions
2724        if expression is not None
2725    ]
2726
2727    existing_expressions = inst.args.get(arg)
2728    if append and existing_expressions:
2729        parsed = existing_expressions + parsed
2730
2731    inst.set(arg, parsed)
2732    return inst
2733
2734
2735def _apply_conjunction_builder(
2736    *expressions: ExpOrStr | None,
2737    instance: E,
2738    arg: str,
2739    into: Type[Expr] | None = None,
2740    append: bool = True,
2741    copy: bool = True,
2742    dialect: DialectType = None,
2743    **opts: Unpack[ParserNoDialectArgs],
2744) -> E:
2745    filtered = [exp for exp in expressions if exp is not None and exp != ""]
2746    if not filtered:
2747        return instance
2748
2749    inst = maybe_copy(instance, copy)
2750
2751    existing = inst.args.get(arg)
2752    if append and existing is not None:
2753        filtered = [existing.this if into else existing] + filtered
2754
2755    node = and_(*filtered, dialect=dialect, copy=copy, **opts)
2756
2757    inst.set(arg, into(this=node) if into else node)
2758    return inst
2759
2760
2761def _combine(
2762    expressions: Sequence[ExpOrStr | None],
2763    operator: Type[Expr],
2764    dialect: DialectType = None,
2765    copy: bool = True,
2766    wrap: bool = True,
2767    **opts: Unpack[ParserNoDialectArgs],
2768) -> Expr:
2769    conditions = [
2770        condition(expression, dialect=dialect, copy=copy, **opts)
2771        for expression in expressions
2772        if expression is not None
2773    ]
2774
2775    this, *rest = conditions
2776    if rest and wrap:
2777        this = _wrap(this, Connector)
2778    for expression in rest:
2779        this = operator(this=this, expression=_wrap(expression, Connector) if wrap else expression)
2780
2781    return this
2782
2783
2784@t.overload
2785def _wrap(expression: None, kind: Type[Expr]) -> None: ...
2786
2787
2788@t.overload
2789def _wrap(expression: E, kind: Type[Expr]) -> E | Paren: ...
2790
2791
2792def _wrap(expression: E | None, kind: Type[Expr]) -> E | None | Paren:
2793    return Paren(this=expression) if isinstance(expression, kind) else expression
2794
2795
2796def _apply_set_operation(
2797    *expressions: ExpOrStr,
2798    set_operation: Type,
2799    distinct: bool = True,
2800    dialect: DialectType = None,
2801    copy: bool = True,
2802    **opts: Unpack[ParserNoDialectArgs],
2803) -> t.Any:
2804    return reduce(
2805        lambda x, y: set_operation(this=x, expression=y, distinct=distinct, **opts),
2806        (maybe_parse(e, dialect=dialect, copy=copy, **opts) for e in expressions),
2807    )
2808
2809
2810SAFE_IDENTIFIER_RE: t.Pattern[str] = re.compile(r"^[_a-zA-Z][\w]*$")
2811
2812
2813@t.overload
2814def to_identifier(name: None, quoted: bool | None = None, copy: bool = True) -> None: ...
2815
2816
2817@t.overload
2818def to_identifier(
2819    name: int | str | Identifier, quoted: bool | None = None, copy: bool = True
2820) -> Identifier: ...
2821
2822
2823def to_identifier(name, quoted=None, copy=True):
2824    """Builds an identifier.
2825
2826    Args:
2827        name: The name to turn into an identifier.
2828        quoted: Whether to force quote the identifier.
2829        copy: Whether to copy name if it's an Identifier.
2830
2831    Returns:
2832        The identifier ast node.
2833    """
2834
2835    if name is None:
2836        return None
2837
2838    if isinstance(name, Identifier):
2839        identifier = maybe_copy(name, copy)
2840    elif isinstance(name, str):
2841        identifier = Identifier(
2842            this=name,
2843            quoted=not SAFE_IDENTIFIER_RE.match(name) if quoted is None else quoted,
2844        )
2845    else:
2846        raise ValueError(f"Name needs to be a string or an Identifier, got: {name.__class__}")
2847    return identifier
2848
2849
2850def condition(
2851    expression: ExpOrStr,
2852    dialect: DialectType = None,
2853    copy: bool = True,
2854    **opts: Unpack[ParserNoDialectArgs],
2855) -> Expr:
2856    """
2857    Initialize a logical condition expression.
2858
2859    Example:
2860        >>> condition("x=1").sql()
2861        'x = 1'
2862
2863        This is helpful for composing larger logical syntax trees:
2864        >>> where = condition("x=1")
2865        >>> where = where.and_("y=1")
2866        >>> where.sql()
2867        'x = 1 AND y = 1'
2868
2869    Args:
2870        *expression: the SQL code string to parse.
2871            If an Expr instance is passed, this is used as-is.
2872        dialect: the dialect used to parse the input expression (in the case that the
2873            input expression is a SQL string).
2874        copy: Whether to copy `expression` (only applies to expressions).
2875        **opts: other options to use to parse the input expressions (again, in the case
2876            that the input expression is a SQL string).
2877
2878    Returns:
2879        The new Condition instance
2880    """
2881    return maybe_parse(
2882        expression,
2883        into=Condition,
2884        dialect=dialect,
2885        copy=copy,
2886        **opts,
2887    )
2888
2889
2890def and_(
2891    *expressions: ExpOrStr | None,
2892    dialect: DialectType = None,
2893    copy: bool = True,
2894    wrap: bool = True,
2895    **opts: Unpack[ParserNoDialectArgs],
2896) -> Condition:
2897    """
2898    Combine multiple conditions with an AND logical operator.
2899
2900    Example:
2901        >>> and_("x=1", and_("y=1", "z=1")).sql()
2902        'x = 1 AND (y = 1 AND z = 1)'
2903
2904    Args:
2905        *expressions: the SQL code strings to parse.
2906            If an Expr instance is passed, this is used as-is.
2907        dialect: the dialect used to parse the input expression.
2908        copy: whether to copy `expressions` (only applies to Exprs).
2909        wrap: whether to wrap the operands in `Paren`s. This is true by default to avoid
2910            precedence issues, but can be turned off when the produced AST is too deep and
2911            causes recursion-related issues.
2912        **opts: other options to use to parse the input expressions.
2913
2914    Returns:
2915        The new condition
2916    """
2917    return t.cast(Condition, _combine(expressions, And, dialect, copy=copy, wrap=wrap, **opts))
2918
2919
2920def or_(
2921    *expressions: ExpOrStr | None,
2922    dialect: DialectType = None,
2923    copy: bool = True,
2924    wrap: bool = True,
2925    **opts: Unpack[ParserNoDialectArgs],
2926) -> Condition:
2927    """
2928    Combine multiple conditions with an OR logical operator.
2929
2930    Example:
2931        >>> or_("x=1", or_("y=1", "z=1")).sql()
2932        'x = 1 OR (y = 1 OR z = 1)'
2933
2934    Args:
2935        *expressions: the SQL code strings to parse.
2936            If an Expr instance is passed, this is used as-is.
2937        dialect: the dialect used to parse the input expression.
2938        copy: whether to copy `expressions` (only applies to Exprs).
2939        wrap: whether to wrap the operands in `Paren`s. This is true by default to avoid
2940            precedence issues, but can be turned off when the produced AST is too deep and
2941            causes recursion-related issues.
2942        **opts: other options to use to parse the input expressions.
2943
2944    Returns:
2945        The new condition
2946    """
2947    return t.cast(Condition, _combine(expressions, Or, dialect, copy=copy, wrap=wrap, **opts))
2948
2949
2950def xor(
2951    *expressions: ExpOrStr | None,
2952    dialect: DialectType = None,
2953    copy: bool = True,
2954    wrap: bool = True,
2955    **opts: Unpack[ParserNoDialectArgs],
2956) -> Condition:
2957    """
2958    Combine multiple conditions with an XOR logical operator.
2959
2960    Example:
2961        >>> xor("x=1", xor("y=1", "z=1")).sql()
2962        'x = 1 XOR (y = 1 XOR z = 1)'
2963
2964    Args:
2965        *expressions: the SQL code strings to parse.
2966            If an Expr instance is passed, this is used as-is.
2967        dialect: the dialect used to parse the input expression.
2968        copy: whether to copy `expressions` (only applies to Exprs).
2969        wrap: whether to wrap the operands in `Paren`s. This is true by default to avoid
2970            precedence issues, but can be turned off when the produced AST is too deep and
2971            causes recursion-related issues.
2972        **opts: other options to use to parse the input expressions.
2973
2974    Returns:
2975        The new condition
2976    """
2977    return t.cast(Condition, _combine(expressions, Xor, dialect, copy=copy, wrap=wrap, **opts))
2978
2979
2980def paren(expression: ExpOrStr, copy: bool = True) -> Paren:
2981    """
2982    Wrap an expression in parentheses.
2983
2984    Example:
2985        >>> paren("5 + 3").sql()
2986        '(5 + 3)'
2987
2988    Args:
2989        expression: the SQL code string to parse.
2990            If an Expr instance is passed, this is used as-is.
2991        copy: whether to copy the expression or not.
2992
2993    Returns:
2994        The wrapped expression.
2995    """
2996    return Paren(this=maybe_parse(expression, copy=copy))
2997
2998
2999def alias_(
3000    expression: ExpOrStr,
3001    alias: str | Identifier | None,
3002    table: bool | Sequence[str | Identifier] = False,
3003    quoted: bool | None = None,
3004    dialect: DialectType = None,
3005    copy: bool = True,
3006    **opts: Unpack[ParserNoDialectArgs],
3007) -> Expr:
3008    """Create an Alias expression.
3009
3010    Example:
3011        >>> alias_('foo', 'bar').sql()
3012        'foo AS bar'
3013
3014        >>> alias_('(select 1, 2)', 'bar', table=['a', 'b']).sql()
3015        '(SELECT 1, 2) AS bar(a, b)'
3016
3017    Args:
3018        expression: the SQL code strings to parse.
3019            If an Expr instance is passed, this is used as-is.
3020        alias: the alias name to use. If the name has
3021            special characters it is quoted.
3022        table: Whether to create a table alias, can also be a list of columns.
3023        quoted: whether to quote the alias
3024        dialect: the dialect used to parse the input expression.
3025        copy: Whether to copy the expression.
3026        **opts: other options to use to parse the input expressions.
3027
3028    Returns:
3029        Alias: the aliased expression
3030    """
3031    exp = maybe_parse(expression, dialect=dialect, copy=copy, **opts)
3032    alias = to_identifier(alias, quoted=quoted)
3033
3034    if table:
3035        from sqlglot.expressions.query import TableAlias as _TableAlias
3036
3037        table_alias = _TableAlias(this=alias)
3038        exp.set("alias", table_alias)
3039
3040        if not isinstance(table, bool):
3041            for column in table:
3042                table_alias.append("columns", to_identifier(column, quoted=quoted))
3043
3044        return exp
3045
3046    # We don't set the "alias" arg for Window expressions, because that would add an IDENTIFIER node in
3047    # the AST, representing a "named_window" [1] construct (eg. bigquery). What we want is an ALIAS node
3048    # for the complete Window expression.
3049    #
3050    # [1]: https://cloud.google.com/bigquery/docs/reference/standard-sql/window-function-calls
3051
3052    if "alias" in exp.arg_types and type(exp).__name__ != "Window":
3053        exp.set("alias", alias)
3054        return exp
3055    return Alias(this=exp, alias=alias)
3056
3057
3058@t.overload
3059def column(
3060    col: str | Identifier,
3061    table: str | Identifier | None = None,
3062    db: str | Identifier | None = None,
3063    catalog: str | Identifier | None = None,
3064    *,
3065    fields: Collection[str | Identifier],
3066    quoted: bool | None = None,
3067    copy: bool = True,
3068) -> Dot:
3069    pass
3070
3071
3072@t.overload
3073def column(
3074    col: str | Identifier | Star,
3075    table: str | Identifier | None = None,
3076    db: str | Identifier | None = None,
3077    catalog: str | Identifier | None = None,
3078    *,
3079    fields: t.Literal[None] = None,
3080    quoted: bool | None = None,
3081    copy: bool = True,
3082) -> Column:
3083    pass
3084
3085
3086def column(
3087    col,
3088    table=None,
3089    db=None,
3090    catalog=None,
3091    *,
3092    fields=None,
3093    quoted=None,
3094    copy: bool = True,
3095):
3096    """
3097    Build a Column.
3098
3099    Args:
3100        col: Column name.
3101        table: Table name.
3102        db: Database name.
3103        catalog: Catalog name.
3104        fields: Additional fields using dots.
3105        quoted: Whether to force quotes on the column's identifiers.
3106        copy: Whether to copy identifiers if passed in.
3107
3108    Returns:
3109        The new Column instance.
3110    """
3111    if not isinstance(col, Star):
3112        col = to_identifier(col, quoted=quoted, copy=copy)
3113
3114    this: Column | Dot = Column(
3115        this=col,
3116        table=to_identifier(table, quoted=quoted, copy=copy),
3117        db=to_identifier(db, quoted=quoted, copy=copy),
3118        catalog=to_identifier(catalog, quoted=quoted, copy=copy),
3119    )
3120
3121    if fields:
3122        this = Dot.build(
3123            (this, *(to_identifier(field, quoted=quoted, copy=copy) for field in fields))
3124        )
3125    return this