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