1"""
   2## Expressions
   3
   4Every AST node in SQLGlot is represented by a subclass of `Expression`.
   5
   6This module contains the implementation of all supported `Expression` types. Additionally,
   7it exposes a number of helper functions, which are mainly used to programmatically build
   8SQL expressions, such as `sqlglot.expressions.select`.
   9
  10----
  11"""
  12
  13from __future__ import annotations
  14
  15import datetime
  16import math
  17import numbers
  18import re
  19import typing as t
  20from collections import deque
  21from copy import deepcopy
  22from enum import auto
  23from functools import reduce
  24
  25from sqlglot._typing import E
  26from sqlglot.errors import ParseError
  27from sqlglot.helper import (
  28    AutoName,
  29    camel_to_snake_case,
  30    ensure_collection,
  31    ensure_list,
  32    seq_get,
  33    subclasses,
  34)
  35from sqlglot.tokens import Token
  36
  37if t.TYPE_CHECKING:
  38    from sqlglot.dialects.dialect import DialectType
  39
  40
  41class _Expression(type):
  42    def __new__(cls, clsname, bases, attrs):
  43        klass = super().__new__(cls, clsname, bases, attrs)
  44
  45        # When an Expression class is created, its key is automatically set to be
  46        # the lowercase version of the class' name.
  47        klass.key = clsname.lower()
  48
  49        # This is so that docstrings are not inherited in pdoc
  50        klass.__doc__ = klass.__doc__ or ""
  51
  52        return klass
  53
  54
  55class Expression(metaclass=_Expression):
  56    """
  57    The base class for all expressions in a syntax tree. Each Expression encapsulates any necessary
  58    context, such as its child expressions, their names (arg keys), and whether a given child expression
  59    is optional or not.
  60
  61    Attributes:
  62        key: a unique key for each class in the Expression hierarchy. This is useful for hashing
  63            and representing expressions as strings.
  64        arg_types: determines what arguments (child nodes) are supported by an expression. It
  65            maps arg keys to booleans that indicate whether the corresponding args are optional.
  66        parent: a reference to the parent expression (or None, in case of root expressions).
  67        arg_key: the arg key an expression is associated with, i.e. the name its parent expression
  68            uses to refer to it.
  69        comments: a list of comments that are associated with a given expression. This is used in
  70            order to preserve comments when transpiling SQL code.
  71        type: the `sqlglot.expressions.DataType` type of an expression. This is inferred by the
  72            optimizer, in order to enable some transformations that require type information.
  73        meta: a dictionary that can be used to store useful metadata for a given expression.
  74
  75    Example:
  76        >>> class Foo(Expression):
  77        ...     arg_types = {"this": True, "expression": False}
  78
  79        The above definition informs us that Foo is an Expression that requires an argument called
  80        "this" and may also optionally receive an argument called "expression".
  81
  82    Args:
  83        args: a mapping used for retrieving the arguments of an expression, given their arg keys.
  84    """
  85
  86    key = "expression"
  87    arg_types = {"this": True}
  88    __slots__ = ("args", "parent", "arg_key", "comments", "_type", "_meta", "_hash")
  89
  90    def __init__(self, **args: t.Any):
  91        self.args: t.Dict[str, t.Any] = args
  92        self.parent: t.Optional[Expression] = None
  93        self.arg_key: t.Optional[str] = None
  94        self.comments: t.Optional[t.List[str]] = None
  95        self._type: t.Optional[DataType] = None
  96        self._meta: t.Optional[t.Dict[str, t.Any]] = None
  97        self._hash: t.Optional[int] = None
  98
  99        for arg_key, value in self.args.items():
 100            self._set_parent(arg_key, value)
 101
 102    def __eq__(self, other) -> bool:
 103        return type(self) is type(other) and hash(self) == hash(other)
 104
 105    @property
 106    def hashable_args(self) -> t.Any:
 107        return frozenset(
 108            (k, tuple(_norm_arg(a) for a in v) if type(v) is list else _norm_arg(v))
 109            for k, v in self.args.items()
 110            if not (v is None or v is False or (type(v) is list and not v))
 111        )
 112
 113    def __hash__(self) -> int:
 114        if self._hash is not None:
 115            return self._hash
 116
 117        return hash((self.__class__, self.hashable_args))
 118
 119    @property
 120    def this(self):
 121        """
 122        Retrieves the argument with key "this".
 123        """
 124        return self.args.get("this")
 125
 126    @property
 127    def expression(self):
 128        """
 129        Retrieves the argument with key "expression".
 130        """
 131        return self.args.get("expression")
 132
 133    @property
 134    def expressions(self):
 135        """
 136        Retrieves the argument with key "expressions".
 137        """
 138        return self.args.get("expressions") or []
 139
 140    def text(self, key) -> str:
 141        """
 142        Returns a textual representation of the argument corresponding to "key". This can only be used
 143        for args that are strings or leaf Expression instances, such as identifiers and literals.
 144        """
 145        field = self.args.get(key)
 146        if isinstance(field, str):
 147            return field
 148        if isinstance(field, (Identifier, Literal, Var)):
 149            return field.this
 150        if isinstance(field, (Star, Null)):
 151            return field.name
 152        return ""
 153
 154    @property
 155    def is_string(self) -> bool:
 156        """
 157        Checks whether a Literal expression is a string.
 158        """
 159        return isinstance(self, Literal) and self.args["is_string"]
 160
 161    @property
 162    def is_number(self) -> bool:
 163        """
 164        Checks whether a Literal expression is a number.
 165        """
 166        return isinstance(self, Literal) and not self.args["is_string"]
 167
 168    @property
 169    def is_int(self) -> bool:
 170        """
 171        Checks whether a Literal expression is an integer.
 172        """
 173        if self.is_number:
 174            try:
 175                int(self.name)
 176                return True
 177            except ValueError:
 178                pass
 179        return False
 180
 181    @property
 182    def is_star(self) -> bool:
 183        """Checks whether an expression is a star."""
 184        return isinstance(self, Star) or (isinstance(self, Column) and isinstance(self.this, Star))
 185
 186    @property
 187    def alias(self) -> str:
 188        """
 189        Returns the alias of the expression, or an empty string if it's not aliased.
 190        """
 191        if isinstance(self.args.get("alias"), TableAlias):
 192            return self.args["alias"].name
 193        return self.text("alias")
 194
 195    @property
 196    def alias_column_names(self) -> t.List[str]:
 197        table_alias = self.args.get("alias")
 198        if not table_alias:
 199            return []
 200        return [c.name for c in table_alias.args.get("columns") or []]
 201
 202    @property
 203    def name(self) -> str:
 204        return self.text("this")
 205
 206    @property
 207    def alias_or_name(self) -> str:
 208        return self.alias or self.name
 209
 210    @property
 211    def output_name(self) -> str:
 212        """
 213        Name of the output column if this expression is a selection.
 214
 215        If the Expression has no output name, an empty string is returned.
 216
 217        Example:
 218            >>> from sqlglot import parse_one
 219            >>> parse_one("SELECT a").expressions[0].output_name
 220            'a'
 221            >>> parse_one("SELECT b AS c").expressions[0].output_name
 222            'c'
 223            >>> parse_one("SELECT 1 + 2").expressions[0].output_name
 224            ''
 225        """
 226        return ""
 227
 228    @property
 229    def type(self) -> t.Optional[DataType]:
 230        return self._type
 231
 232    @type.setter
 233    def type(self, dtype: t.Optional[DataType | DataType.Type | str]) -> None:
 234        if dtype and not isinstance(dtype, DataType):
 235            dtype = DataType.build(dtype)
 236        self._type = dtype  # type: ignore
 237
 238    @property
 239    def meta(self) -> t.Dict[str, t.Any]:
 240        if self._meta is None:
 241            self._meta = {}
 242        return self._meta
 243
 244    def __deepcopy__(self, memo):
 245        copy = self.__class__(**deepcopy(self.args))
 246        if self.comments is not None:
 247            copy.comments = deepcopy(self.comments)
 248
 249        if self._type is not None:
 250            copy._type = self._type.copy()
 251
 252        if self._meta is not None:
 253            copy._meta = deepcopy(self._meta)
 254
 255        return copy
 256
 257    def copy(self):
 258        """
 259        Returns a deep copy of the expression.
 260        """
 261        new = deepcopy(self)
 262        new.parent = self.parent
 263        return new
 264
 265    def add_comments(self, comments: t.Optional[t.List[str]]) -> None:
 266        if self.comments is None:
 267            self.comments = []
 268        if comments:
 269            self.comments.extend(comments)
 270
 271    def append(self, arg_key: str, value: t.Any) -> None:
 272        """
 273        Appends value to arg_key if it's a list or sets it as a new list.
 274
 275        Args:
 276            arg_key (str): name of the list expression arg
 277            value (Any): value to append to the list
 278        """
 279        if not isinstance(self.args.get(arg_key), list):
 280            self.args[arg_key] = []
 281        self.args[arg_key].append(value)
 282        self._set_parent(arg_key, value)
 283
 284    def set(self, arg_key: str, value: t.Any) -> None:
 285        """
 286        Sets arg_key to value.
 287
 288        Args:
 289            arg_key: name of the expression arg.
 290            value: value to set the arg to.
 291        """
 292        if value is None:
 293            self.args.pop(arg_key, None)
 294            return
 295
 296        self.args[arg_key] = value
 297        self._set_parent(arg_key, value)
 298
 299    def _set_parent(self, arg_key: str, value: t.Any) -> None:
 300        if hasattr(value, "parent"):
 301            value.parent = self
 302            value.arg_key = arg_key
 303        elif type(value) is list:
 304            for v in value:
 305                if hasattr(v, "parent"):
 306                    v.parent = self
 307                    v.arg_key = arg_key
 308
 309    @property
 310    def depth(self) -> int:
 311        """
 312        Returns the depth of this tree.
 313        """
 314        if self.parent:
 315            return self.parent.depth + 1
 316        return 0
 317
 318    def iter_expressions(self) -> t.Iterator[t.Tuple[str, Expression]]:
 319        """Yields the key and expression for all arguments, exploding list args."""
 320        for k, vs in self.args.items():
 321            if type(vs) is list:
 322                for v in vs:
 323                    if hasattr(v, "parent"):
 324                        yield k, v
 325            else:
 326                if hasattr(vs, "parent"):
 327                    yield k, vs
 328
 329    def find(self, *expression_types: t.Type[E], bfs: bool = True) -> t.Optional[E]:
 330        """
 331        Returns the first node in this tree which matches at least one of
 332        the specified types.
 333
 334        Args:
 335            expression_types: the expression type(s) to match.
 336            bfs: whether to search the AST using the BFS algorithm (DFS is used if false).
 337
 338        Returns:
 339            The node which matches the criteria or None if no such node was found.
 340        """
 341        return next(self.find_all(*expression_types, bfs=bfs), None)
 342
 343    def find_all(self, *expression_types: t.Type[E], bfs: bool = True) -> t.Iterator[E]:
 344        """
 345        Returns a generator object which visits all nodes in this tree and only
 346        yields those that match at least one of the specified expression types.
 347
 348        Args:
 349            expression_types: the expression type(s) to match.
 350            bfs: whether to search the AST using the BFS algorithm (DFS is used if false).
 351
 352        Returns:
 353            The generator object.
 354        """
 355        for expression, *_ in self.walk(bfs=bfs):
 356            if isinstance(expression, expression_types):
 357                yield expression
 358
 359    def find_ancestor(self, *expression_types: t.Type[E]) -> t.Optional[E]:
 360        """
 361        Returns a nearest parent matching expression_types.
 362
 363        Args:
 364            expression_types: the expression type(s) to match.
 365
 366        Returns:
 367            The parent node.
 368        """
 369        ancestor = self.parent
 370        while ancestor and not isinstance(ancestor, expression_types):
 371            ancestor = ancestor.parent
 372        return t.cast(E, ancestor)
 373
 374    @property
 375    def parent_select(self) -> t.Optional[Select]:
 376        """
 377        Returns the parent select statement.
 378        """
 379        return self.find_ancestor(Select)
 380
 381    @property
 382    def same_parent(self) -> bool:
 383        """Returns if the parent is the same class as itself."""
 384        return type(self.parent) is self.__class__
 385
 386    def root(self) -> Expression:
 387        """
 388        Returns the root expression of this tree.
 389        """
 390        expression = self
 391        while expression.parent:
 392            expression = expression.parent
 393        return expression
 394
 395    def walk(self, bfs=True, prune=None):
 396        """
 397        Returns a generator object which visits all nodes in this tree.
 398
 399        Args:
 400            bfs (bool): if set to True the BFS traversal order will be applied,
 401                otherwise the DFS traversal will be used instead.
 402            prune ((node, parent, arg_key) -> bool): callable that returns True if
 403                the generator should stop traversing this branch of the tree.
 404
 405        Returns:
 406            the generator object.
 407        """
 408        if bfs:
 409            yield from self.bfs(prune=prune)
 410        else:
 411            yield from self.dfs(prune=prune)
 412
 413    def dfs(self, parent=None, key=None, prune=None):
 414        """
 415        Returns a generator object which visits all nodes in this tree in
 416        the DFS (Depth-first) order.
 417
 418        Returns:
 419            The generator object.
 420        """
 421        parent = parent or self.parent
 422        yield self, parent, key
 423        if prune and prune(self, parent, key):
 424            return
 425
 426        for k, v in self.iter_expressions():
 427            yield from v.dfs(self, k, prune)
 428
 429    def bfs(self, prune=None):
 430        """
 431        Returns a generator object which visits all nodes in this tree in
 432        the BFS (Breadth-first) order.
 433
 434        Returns:
 435            The generator object.
 436        """
 437        queue = deque([(self, self.parent, None)])
 438
 439        while queue:
 440            item, parent, key = queue.popleft()
 441
 442            yield item, parent, key
 443            if prune and prune(item, parent, key):
 444                continue
 445
 446            for k, v in item.iter_expressions():
 447                queue.append((v, item, k))
 448
 449    def unnest(self):
 450        """
 451        Returns the first non parenthesis child or self.
 452        """
 453        expression = self
 454        while type(expression) is Paren:
 455            expression = expression.this
 456        return expression
 457
 458    def unalias(self):
 459        """
 460        Returns the inner expression if this is an Alias.
 461        """
 462        if isinstance(self, Alias):
 463            return self.this
 464        return self
 465
 466    def unnest_operands(self):
 467        """
 468        Returns unnested operands as a tuple.
 469        """
 470        return tuple(arg.unnest() for _, arg in self.iter_expressions())
 471
 472    def flatten(self, unnest=True):
 473        """
 474        Returns a generator which yields child nodes who's parents are the same class.
 475
 476        A AND B AND C -> [A, B, C]
 477        """
 478        for node, _, _ in self.dfs(prune=lambda n, p, *_: p and not type(n) is self.__class__):
 479            if not type(node) is self.__class__:
 480                yield node.unnest() if unnest else node
 481
 482    def __str__(self) -> str:
 483        return self.sql()
 484
 485    def __repr__(self) -> str:
 486        return self._to_s()
 487
 488    def sql(self, dialect: DialectType = None, **opts) -> str:
 489        """
 490        Returns SQL string representation of this tree.
 491
 492        Args:
 493            dialect: the dialect of the output SQL string (eg. "spark", "hive", "presto", "mysql").
 494            opts: other `sqlglot.generator.Generator` options.
 495
 496        Returns:
 497            The SQL string.
 498        """
 499        from sqlglot.dialects import Dialect
 500
 501        return Dialect.get_or_raise(dialect)().generate(self, **opts)
 502
 503    def _to_s(self, hide_missing: bool = True, level: int = 0) -> str:
 504        indent = "" if not level else "\n"
 505        indent += "".join(["  "] * level)
 506        left = f"({self.key.upper()} "
 507
 508        args: t.Dict[str, t.Any] = {
 509            k: ", ".join(
 510                v._to_s(hide_missing=hide_missing, level=level + 1)
 511                if hasattr(v, "_to_s")
 512                else str(v)
 513                for v in ensure_list(vs)
 514                if v is not None
 515            )
 516            for k, vs in self.args.items()
 517        }
 518        args["comments"] = self.comments
 519        args["type"] = self.type
 520        args = {k: v for k, v in args.items() if v or not hide_missing}
 521
 522        right = ", ".join(f"{k}: {v}" for k, v in args.items())
 523        right += ")"
 524
 525        return indent + left + right
 526
 527    def transform(self, fun, *args, copy=True, **kwargs):
 528        """
 529        Recursively visits all tree nodes (excluding already transformed ones)
 530        and applies the given transformation function to each node.
 531
 532        Args:
 533            fun (function): a function which takes a node as an argument and returns a
 534                new transformed node or the same node without modifications. If the function
 535                returns None, then the corresponding node will be removed from the syntax tree.
 536            copy (bool): if set to True a new tree instance is constructed, otherwise the tree is
 537                modified in place.
 538
 539        Returns:
 540            The transformed tree.
 541        """
 542        node = self.copy() if copy else self
 543        new_node = fun(node, *args, **kwargs)
 544
 545        if new_node is None or not isinstance(new_node, Expression):
 546            return new_node
 547        if new_node is not node:
 548            new_node.parent = node.parent
 549            return new_node
 550
 551        replace_children(new_node, lambda child: child.transform(fun, *args, copy=False, **kwargs))
 552        return new_node
 553
 554    @t.overload
 555    def replace(self, expression: E) -> E:
 556        ...
 557
 558    @t.overload
 559    def replace(self, expression: None) -> None:
 560        ...
 561
 562    def replace(self, expression):
 563        """
 564        Swap out this expression with a new expression.
 565
 566        For example::
 567
 568            >>> tree = Select().select("x").from_("tbl")
 569            >>> tree.find(Column).replace(Column(this="y"))
 570            (COLUMN this: y)
 571            >>> tree.sql()
 572            'SELECT y FROM tbl'
 573
 574        Args:
 575            expression: new node
 576
 577        Returns:
 578            The new expression or expressions.
 579        """
 580        if not self.parent:
 581            return expression
 582
 583        parent = self.parent
 584        self.parent = None
 585
 586        replace_children(parent, lambda child: expression if child is self else child)
 587        return expression
 588
 589    def pop(self: E) -> E:
 590        """
 591        Remove this expression from its AST.
 592
 593        Returns:
 594            The popped expression.
 595        """
 596        self.replace(None)
 597        return self
 598
 599    def assert_is(self, type_: t.Type[E]) -> E:
 600        """
 601        Assert that this `Expression` is an instance of `type_`.
 602
 603        If it is NOT an instance of `type_`, this raises an assertion error.
 604        Otherwise, this returns this expression.
 605
 606        Examples:
 607            This is useful for type security in chained expressions:
 608
 609            >>> import sqlglot
 610            >>> sqlglot.parse_one("SELECT x from y").assert_is(Select).select("z").sql()
 611            'SELECT x, z FROM y'
 612        """
 613        assert isinstance(self, type_)
 614        return self
 615
 616    def error_messages(self, args: t.Optional[t.Sequence] = None) -> t.List[str]:
 617        """
 618        Checks if this expression is valid (e.g. all mandatory args are set).
 619
 620        Args:
 621            args: a sequence of values that were used to instantiate a Func expression. This is used
 622                to check that the provided arguments don't exceed the function argument limit.
 623
 624        Returns:
 625            A list of error messages for all possible errors that were found.
 626        """
 627        errors: t.List[str] = []
 628
 629        for k in self.args:
 630            if k not in self.arg_types:
 631                errors.append(f"Unexpected keyword: '{k}' for {self.__class__}")
 632        for k, mandatory in self.arg_types.items():
 633            v = self.args.get(k)
 634            if mandatory and (v is None or (isinstance(v, list) and not v)):
 635                errors.append(f"Required keyword: '{k}' missing for {self.__class__}")
 636
 637        if (
 638            args
 639            and isinstance(self, Func)
 640            and len(args) > len(self.arg_types)
 641            and not self.is_var_len_args
 642        ):
 643            errors.append(
 644                f"The number of provided arguments ({len(args)}) is greater than "
 645                f"the maximum number of supported arguments ({len(self.arg_types)})"
 646            )
 647
 648        return errors
 649
 650    def dump(self):
 651        """
 652        Dump this Expression to a JSON-serializable dict.
 653        """
 654        from sqlglot.serde import dump
 655
 656        return dump(self)
 657
 658    @classmethod
 659    def load(cls, obj):
 660        """
 661        Load a dict (as returned by `Expression.dump`) into an Expression instance.
 662        """
 663        from sqlglot.serde import load
 664
 665        return load(obj)
 666
 667
 668IntoType = t.Union[
 669    str,
 670    t.Type[Expression],
 671    t.Collection[t.Union[str, t.Type[Expression]]],
 672]
 673ExpOrStr = t.Union[str, Expression]
 674
 675
 676class Condition(Expression):
 677    def and_(
 678        self,
 679        *expressions: t.Optional[ExpOrStr],
 680        dialect: DialectType = None,
 681        copy: bool = True,
 682        **opts,
 683    ) -> Condition:
 684        """
 685        AND this condition with one or multiple expressions.
 686
 687        Example:
 688            >>> condition("x=1").and_("y=1").sql()
 689            'x = 1 AND y = 1'
 690
 691        Args:
 692            *expressions: the SQL code strings to parse.
 693                If an `Expression` instance is passed, it will be used as-is.
 694            dialect: the dialect used to parse the input expression.
 695            copy: whether or not to copy the involved expressions (only applies to Expressions).
 696            opts: other options to use to parse the input expressions.
 697
 698        Returns:
 699            The new And condition.
 700        """
 701        return and_(self, *expressions, dialect=dialect, copy=copy, **opts)
 702
 703    def or_(
 704        self,
 705        *expressions: t.Optional[ExpOrStr],
 706        dialect: DialectType = None,
 707        copy: bool = True,
 708        **opts,
 709    ) -> Condition:
 710        """
 711        OR this condition with one or multiple expressions.
 712
 713        Example:
 714            >>> condition("x=1").or_("y=1").sql()
 715            'x = 1 OR y = 1'
 716
 717        Args:
 718            *expressions: the SQL code strings to parse.
 719                If an `Expression` instance is passed, it will be used as-is.
 720            dialect: the dialect used to parse the input expression.
 721            copy: whether or not to copy the involved expressions (only applies to Expressions).
 722            opts: other options to use to parse the input expressions.
 723
 724        Returns:
 725            The new Or condition.
 726        """
 727        return or_(self, *expressions, dialect=dialect, copy=copy, **opts)
 728
 729    def not_(self, copy: bool = True):
 730        """
 731        Wrap this condition with NOT.
 732
 733        Example:
 734            >>> condition("x=1").not_().sql()
 735            'NOT x = 1'
 736
 737        Args:
 738            copy: whether or not to copy this object.
 739
 740        Returns:
 741            The new Not instance.
 742        """
 743        return not_(self, copy=copy)
 744
 745    def as_(
 746        self,
 747        alias: str | Identifier,
 748        quoted: t.Optional[bool] = None,
 749        dialect: DialectType = None,
 750        copy: bool = True,
 751        **opts,
 752    ) -> Alias:
 753        return alias_(self, alias, quoted=quoted, dialect=dialect, copy=copy, **opts)
 754
 755    def _binop(self, klass: t.Type[E], other: t.Any, reverse: bool = False) -> E:
 756        this = self.copy()
 757        other = convert(other, copy=True)
 758        if not isinstance(this, klass) and not isinstance(other, klass):
 759            this = _wrap(this, Binary)
 760            other = _wrap(other, Binary)
 761        if reverse:
 762            return klass(this=other, expression=this)
 763        return klass(this=this, expression=other)
 764
 765    def __getitem__(self, other: ExpOrStr | t.Tuple[ExpOrStr]):
 766        return Bracket(
 767            this=self.copy(), expressions=[convert(e, copy=True) for e in ensure_list(other)]
 768        )
 769
 770    def isin(
 771        self,
 772        *expressions: t.Any,
 773        query: t.Optional[ExpOrStr] = None,
 774        unnest: t.Optional[ExpOrStr] | t.Collection[ExpOrStr] = None,
 775        copy: bool = True,
 776        **opts,
 777    ) -> In:
 778        return In(
 779            this=maybe_copy(self, copy),
 780            expressions=[convert(e, copy=copy) for e in expressions],
 781            query=maybe_parse(query, copy=copy, **opts) if query else None,
 782            unnest=Unnest(
 783                expressions=[
 784                    maybe_parse(t.cast(ExpOrStr, e), copy=copy, **opts) for e in ensure_list(unnest)
 785                ]
 786            )
 787            if unnest
 788            else None,
 789        )
 790
 791    def between(self, low: t.Any, high: t.Any, copy: bool = True, **opts) -> Between:
 792        return Between(
 793            this=maybe_copy(self, copy),
 794            low=convert(low, copy=copy, **opts),
 795            high=convert(high, copy=copy, **opts),
 796        )
 797
 798    def is_(self, other: ExpOrStr) -> Is:
 799        return self._binop(Is, other)
 800
 801    def like(self, other: ExpOrStr) -> Like:
 802        return self._binop(Like, other)
 803
 804    def ilike(self, other: ExpOrStr) -> ILike:
 805        return self._binop(ILike, other)
 806
 807    def eq(self, other: t.Any) -> EQ:
 808        return self._binop(EQ, other)
 809
 810    def neq(self, other: t.Any) -> NEQ:
 811        return self._binop(NEQ, other)
 812
 813    def rlike(self, other: ExpOrStr) -> RegexpLike:
 814        return self._binop(RegexpLike, other)
 815
 816    def __lt__(self, other: t.Any) -> LT:
 817        return self._binop(LT, other)
 818
 819    def __le__(self, other: t.Any) -> LTE:
 820        return self._binop(LTE, other)
 821
 822    def __gt__(self, other: t.Any) -> GT:
 823        return self._binop(GT, other)
 824
 825    def __ge__(self, other: t.Any) -> GTE:
 826        return self._binop(GTE, other)
 827
 828    def __add__(self, other: t.Any) -> Add:
 829        return self._binop(Add, other)
 830
 831    def __radd__(self, other: t.Any) -> Add:
 832        return self._binop(Add, other, reverse=True)
 833
 834    def __sub__(self, other: t.Any) -> Sub:
 835        return self._binop(Sub, other)
 836
 837    def __rsub__(self, other: t.Any) -> Sub:
 838        return self._binop(Sub, other, reverse=True)
 839
 840    def __mul__(self, other: t.Any) -> Mul:
 841        return self._binop(Mul, other)
 842
 843    def __rmul__(self, other: t.Any) -> Mul:
 844        return self._binop(Mul, other, reverse=True)
 845
 846    def __truediv__(self, other: t.Any) -> Div:
 847        return self._binop(Div, other)
 848
 849    def __rtruediv__(self, other: t.Any) -> Div:
 850        return self._binop(Div, other, reverse=True)
 851
 852    def __floordiv__(self, other: t.Any) -> IntDiv:
 853        return self._binop(IntDiv, other)
 854
 855    def __rfloordiv__(self, other: t.Any) -> IntDiv:
 856        return self._binop(IntDiv, other, reverse=True)
 857
 858    def __mod__(self, other: t.Any) -> Mod:
 859        return self._binop(Mod, other)
 860
 861    def __rmod__(self, other: t.Any) -> Mod:
 862        return self._binop(Mod, other, reverse=True)
 863
 864    def __pow__(self, other: t.Any) -> Pow:
 865        return self._binop(Pow, other)
 866
 867    def __rpow__(self, other: t.Any) -> Pow:
 868        return self._binop(Pow, other, reverse=True)
 869
 870    def __and__(self, other: t.Any) -> And:
 871        return self._binop(And, other)
 872
 873    def __rand__(self, other: t.Any) -> And:
 874        return self._binop(And, other, reverse=True)
 875
 876    def __or__(self, other: t.Any) -> Or:
 877        return self._binop(Or, other)
 878
 879    def __ror__(self, other: t.Any) -> Or:
 880        return self._binop(Or, other, reverse=True)
 881
 882    def __neg__(self) -> Neg:
 883        return Neg(this=_wrap(self.copy(), Binary))
 884
 885    def __invert__(self) -> Not:
 886        return not_(self.copy())
 887
 888
 889class Predicate(Condition):
 890    """Relationships like x = y, x > 1, x >= y."""
 891
 892
 893class DerivedTable(Expression):
 894    @property
 895    def selects(self) -> t.List[Expression]:
 896        return self.this.selects if isinstance(self.this, Subqueryable) else []
 897
 898    @property
 899    def named_selects(self) -> t.List[str]:
 900        return [select.output_name for select in self.selects]
 901
 902
 903class Unionable(Expression):
 904    def union(
 905        self, expression: ExpOrStr, distinct: bool = True, dialect: DialectType = None, **opts
 906    ) -> Unionable:
 907        """
 908        Builds a UNION expression.
 909
 910        Example:
 911            >>> import sqlglot
 912            >>> sqlglot.parse_one("SELECT * FROM foo").union("SELECT * FROM bla").sql()
 913            'SELECT * FROM foo UNION SELECT * FROM bla'
 914
 915        Args:
 916            expression: the SQL code string.
 917                If an `Expression` instance is passed, it will be used as-is.
 918            distinct: set the DISTINCT flag if and only if this is true.
 919            dialect: the dialect used to parse the input expression.
 920            opts: other options to use to parse the input expressions.
 921
 922        Returns:
 923            The new Union expression.
 924        """
 925        return union(left=self, right=expression, distinct=distinct, dialect=dialect, **opts)
 926
 927    def intersect(
 928        self, expression: ExpOrStr, distinct: bool = True, dialect: DialectType = None, **opts
 929    ) -> Unionable:
 930        """
 931        Builds an INTERSECT expression.
 932
 933        Example:
 934            >>> import sqlglot
 935            >>> sqlglot.parse_one("SELECT * FROM foo").intersect("SELECT * FROM bla").sql()
 936            'SELECT * FROM foo INTERSECT SELECT * FROM bla'
 937
 938        Args:
 939            expression: the SQL code string.
 940                If an `Expression` instance is passed, it will be used as-is.
 941            distinct: set the DISTINCT flag if and only if this is true.
 942            dialect: the dialect used to parse the input expression.
 943            opts: other options to use to parse the input expressions.
 944
 945        Returns:
 946            The new Intersect expression.
 947        """
 948        return intersect(left=self, right=expression, distinct=distinct, dialect=dialect, **opts)
 949
 950    def except_(
 951        self, expression: ExpOrStr, distinct: bool = True, dialect: DialectType = None, **opts
 952    ) -> Unionable:
 953        """
 954        Builds an EXCEPT expression.
 955
 956        Example:
 957            >>> import sqlglot
 958            >>> sqlglot.parse_one("SELECT * FROM foo").except_("SELECT * FROM bla").sql()
 959            'SELECT * FROM foo EXCEPT SELECT * FROM bla'
 960
 961        Args:
 962            expression: the SQL code string.
 963                If an `Expression` instance is passed, it will be used as-is.
 964            distinct: set the DISTINCT flag if and only if this is true.
 965            dialect: the dialect used to parse the input expression.
 966            opts: other options to use to parse the input expressions.
 967
 968        Returns:
 969            The new Except expression.
 970        """
 971        return except_(left=self, right=expression, distinct=distinct, dialect=dialect, **opts)
 972
 973
 974class UDTF(DerivedTable, Unionable):
 975    @property
 976    def selects(self) -> t.List[Expression]:
 977        alias = self.args.get("alias")
 978        return alias.columns if alias else []
 979
 980
 981class Cache(Expression):
 982    arg_types = {
 983        "with": False,
 984        "this": True,
 985        "lazy": False,
 986        "options": False,
 987        "expression": False,
 988    }
 989
 990
 991class Uncache(Expression):
 992    arg_types = {"this": True, "exists": False}
 993
 994
 995class DDL(Expression):
 996    @property
 997    def ctes(self):
 998        with_ = self.args.get("with")
 999        if not with_:
1000            return []
1001        return with_.expressions
1002
1003    @property
1004    def named_selects(self) -> t.List[str]:
1005        if isinstance(self.expression, Subqueryable):
1006            return self.expression.named_selects
1007        return []
1008
1009    @property
1010    def selects(self) -> t.List[Expression]:
1011        if isinstance(self.expression, Subqueryable):
1012            return self.expression.selects
1013        return []
1014
1015
1016class Create(DDL):
1017    arg_types = {
1018        "with": False,
1019        "this": True,
1020        "kind": True,
1021        "expression": False,
1022        "exists": False,
1023        "properties": False,
1024        "replace": False,
1025        "unique": False,
1026        "indexes": False,
1027        "no_schema_binding": False,
1028        "begin": False,
1029        "clone": False,
1030    }
1031
1032
1033# https://docs.snowflake.com/en/sql-reference/sql/create-clone
1034class Clone(Expression):
1035    arg_types = {
1036        "this": True,
1037        "when": False,
1038        "kind": False,
1039        "shallow": False,
1040        "expression": False,
1041    }
1042
1043
1044class Describe(Expression):
1045    arg_types = {"this": True, "kind": False, "expressions": False}
1046
1047
1048class Pragma(Expression):
1049    pass
1050
1051
1052class Set(Expression):
1053    arg_types = {"expressions": False, "unset": False, "tag": False}
1054
1055
1056class SetItem(Expression):
1057    arg_types = {
1058        "this": False,
1059        "expressions": False,
1060        "kind": False,
1061        "collate": False,  # MySQL SET NAMES statement
1062        "global": False,
1063    }
1064
1065
1066class Show(Expression):
1067    arg_types = {
1068        "this": True,
1069        "target": False,
1070        "offset": False,
1071        "limit": False,
1072        "like": False,
1073        "where": False,
1074        "db": False,
1075        "scope": False,
1076        "scope_kind": False,
1077        "full": False,
1078        "mutex": False,
1079        "query": False,
1080        "channel": False,
1081        "global": False,
1082        "log": False,
1083        "position": False,
1084        "types": False,
1085    }
1086
1087
1088class UserDefinedFunction(Expression):
1089    arg_types = {"this": True, "expressions": False, "wrapped": False}
1090
1091
1092class CharacterSet(Expression):
1093    arg_types = {"this": True, "default": False}
1094
1095
1096class With(Expression):
1097    arg_types = {"expressions": True, "recursive": False}
1098
1099    @property
1100    def recursive(self) -> bool:
1101        return bool(self.args.get("recursive"))
1102
1103
1104class WithinGroup(Expression):
1105    arg_types = {"this": True, "expression": False}
1106
1107
1108class CTE(DerivedTable):
1109    arg_types = {"this": True, "alias": True}
1110
1111
1112class TableAlias(Expression):
1113    arg_types = {"this": False, "columns": False}
1114
1115    @property
1116    def columns(self):
1117        return self.args.get("columns") or []
1118
1119
1120class BitString(Condition):
1121    pass
1122
1123
1124class HexString(Condition):
1125    pass
1126
1127
1128class ByteString(Condition):
1129    pass
1130
1131
1132class RawString(Condition):
1133    pass
1134
1135
1136class Column(Condition):
1137    arg_types = {"this": True, "table": False, "db": False, "catalog": False, "join_mark": False}
1138
1139    @property
1140    def table(self) -> str:
1141        return self.text("table")
1142
1143    @property
1144    def db(self) -> str:
1145        return self.text("db")
1146
1147    @property
1148    def catalog(self) -> str:
1149        return self.text("catalog")
1150
1151    @property
1152    def output_name(self) -> str:
1153        return self.name
1154
1155    @property
1156    def parts(self) -> t.List[Identifier]:
1157        """Return the parts of a column in order catalog, db, table, name."""
1158        return [
1159            t.cast(Identifier, self.args[part])
1160            for part in ("catalog", "db", "table", "this")
1161            if self.args.get(part)
1162        ]
1163
1164    def to_dot(self) -> Dot:
1165        """Converts the column into a dot expression."""
1166        parts = self.parts
1167        parent = self.parent
1168
1169        while parent:
1170            if isinstance(parent, Dot):
1171                parts.append(parent.expression)
1172            parent = parent.parent
1173
1174        return Dot.build(deepcopy(parts))
1175
1176
1177class ColumnPosition(Expression):
1178    arg_types = {"this": False, "position": True}
1179
1180
1181class ColumnDef(Expression):
1182    arg_types = {
1183        "this": True,
1184        "kind": False,
1185        "constraints": False,
1186        "exists": False,
1187        "position": False,
1188    }
1189
1190    @property
1191    def constraints(self) -> t.List[ColumnConstraint]:
1192        return self.args.get("constraints") or []
1193
1194
1195class AlterColumn(Expression):
1196    arg_types = {
1197        "this": True,
1198        "dtype": False,
1199        "collate": False,
1200        "using": False,
1201        "default": False,
1202        "drop": False,
1203    }
1204
1205
1206class RenameTable(Expression):
1207    pass
1208
1209
1210class Comment(Expression):
1211    arg_types = {"this": True, "kind": True, "expression": True, "exists": False}
1212
1213
1214class Comprehension(Expression):
1215    arg_types = {"this": True, "expression": True, "iterator": True, "condition": False}
1216
1217
1218# https://clickhouse.com/docs/en/engines/table-engines/mergetree-family/mergetree#mergetree-table-ttl
1219class MergeTreeTTLAction(Expression):
1220    arg_types = {
1221        "this": True,
1222        "delete": False,
1223        "recompress": False,
1224        "to_disk": False,
1225        "to_volume": False,
1226    }
1227
1228
1229# https://clickhouse.com/docs/en/engines/table-engines/mergetree-family/mergetree#mergetree-table-ttl
1230class MergeTreeTTL(Expression):
1231    arg_types = {
1232        "expressions": True,
1233        "where": False,
1234        "group": False,
1235        "aggregates": False,
1236    }
1237
1238
1239# https://dev.mysql.com/doc/refman/8.0/en/create-table.html
1240class IndexConstraintOption(Expression):
1241    arg_types = {
1242        "key_block_size": False,
1243        "using": False,
1244        "parser": False,
1245        "comment": False,
1246        "visible": False,
1247        "engine_attr": False,
1248        "secondary_engine_attr": False,
1249    }
1250
1251
1252class ColumnConstraint(Expression):
1253    arg_types = {"this": False, "kind": True}
1254
1255    @property
1256    def kind(self) -> ColumnConstraintKind:
1257        return self.args["kind"]
1258
1259
1260class ColumnConstraintKind(Expression):
1261    pass
1262
1263
1264class AutoIncrementColumnConstraint(ColumnConstraintKind):
1265    pass
1266
1267
1268class CaseSpecificColumnConstraint(ColumnConstraintKind):
1269    arg_types = {"not_": True}
1270
1271
1272class CharacterSetColumnConstraint(ColumnConstraintKind):
1273    arg_types = {"this": True}
1274
1275
1276class CheckColumnConstraint(ColumnConstraintKind):
1277    pass
1278
1279
1280class ClusteredColumnConstraint(ColumnConstraintKind):
1281    pass
1282
1283
1284class CollateColumnConstraint(ColumnConstraintKind):
1285    pass
1286
1287
1288class CommentColumnConstraint(ColumnConstraintKind):
1289    pass
1290
1291
1292class CompressColumnConstraint(ColumnConstraintKind):
1293    pass
1294
1295
1296class DateFormatColumnConstraint(ColumnConstraintKind):
1297    arg_types = {"this": True}
1298
1299
1300class DefaultColumnConstraint(ColumnConstraintKind):
1301    pass
1302
1303
1304class EncodeColumnConstraint(ColumnConstraintKind):
1305    pass
1306
1307
1308class GeneratedAsIdentityColumnConstraint(ColumnConstraintKind):
1309    # this: True -> ALWAYS, this: False -> BY DEFAULT
1310    arg_types = {
1311        "this": False,
1312        "expression": False,
1313        "on_null": False,
1314        "start": False,
1315        "increment": False,
1316        "minvalue": False,
1317        "maxvalue": False,
1318        "cycle": False,
1319    }
1320
1321
1322# https://dev.mysql.com/doc/refman/8.0/en/create-table.html
1323class IndexColumnConstraint(ColumnConstraintKind):
1324    arg_types = {"this": False, "schema": True, "kind": False, "type": False, "options": False}
1325
1326
1327class InlineLengthColumnConstraint(ColumnConstraintKind):
1328    pass
1329
1330
1331class NonClusteredColumnConstraint(ColumnConstraintKind):
1332    pass
1333
1334
1335class NotForReplicationColumnConstraint(ColumnConstraintKind):
1336    arg_types = {}
1337
1338
1339class NotNullColumnConstraint(ColumnConstraintKind):
1340    arg_types = {"allow_null": False}
1341
1342
1343# https://dev.mysql.com/doc/refman/5.7/en/timestamp-initialization.html
1344class OnUpdateColumnConstraint(ColumnConstraintKind):
1345    pass
1346
1347
1348class PrimaryKeyColumnConstraint(ColumnConstraintKind):
1349    arg_types = {"desc": False}
1350
1351
1352class TitleColumnConstraint(ColumnConstraintKind):
1353    pass
1354
1355
1356class UniqueColumnConstraint(ColumnConstraintKind):
1357    arg_types = {"this": False}
1358
1359
1360class UppercaseColumnConstraint(ColumnConstraintKind):
1361    arg_types: t.Dict[str, t.Any] = {}
1362
1363
1364class PathColumnConstraint(ColumnConstraintKind):
1365    pass
1366
1367
1368# computed column expression
1369# https://learn.microsoft.com/en-us/sql/t-sql/statements/create-table-transact-sql?view=sql-server-ver16
1370class ComputedColumnConstraint(ColumnConstraintKind):
1371    arg_types = {"this": True, "persisted": False, "not_null": False}
1372
1373
1374class Constraint(Expression):
1375    arg_types = {"this": True, "expressions": True}
1376
1377
1378class Delete(Expression):
1379    arg_types = {
1380        "with": False,
1381        "this": False,
1382        "using": False,
1383        "where": False,
1384        "returning": False,
1385        "limit": False,
1386        "tables": False,  # Multiple-Table Syntax (MySQL)
1387    }
1388
1389    def delete(
1390        self,
1391        table: ExpOrStr,
1392        dialect: DialectType = None,
1393        copy: bool = True,
1394        **opts,
1395    ) -> Delete:
1396        """
1397        Create a DELETE expression or replace the table on an existing DELETE expression.
1398
1399        Example:
1400            >>> delete("tbl").sql()
1401            'DELETE FROM tbl'
1402
1403        Args:
1404            table: the table from which to delete.
1405            dialect: the dialect used to parse the input expression.
1406            copy: if `False`, modify this expression instance in-place.
1407            opts: other options to use to parse the input expressions.
1408
1409        Returns:
1410            Delete: the modified expression.
1411        """
1412        return _apply_builder(
1413            expression=table,
1414            instance=self,
1415            arg="this",
1416            dialect=dialect,
1417            into=Table,
1418            copy=copy,
1419            **opts,
1420        )
1421
1422    def where(
1423        self,
1424        *expressions: t.Optional[ExpOrStr],
1425        append: bool = True,
1426        dialect: DialectType = None,
1427        copy: bool = True,
1428        **opts,
1429    ) -> Delete:
1430        """
1431        Append to or set the WHERE expressions.
1432
1433        Example:
1434            >>> delete("tbl").where("x = 'a' OR x < 'b'").sql()
1435            "DELETE FROM tbl WHERE x = 'a' OR x < 'b'"
1436
1437        Args:
1438            *expressions: the SQL code strings to parse.
1439                If an `Expression` instance is passed, it will be used as-is.
1440                Multiple expressions are combined with an AND operator.
1441            append: if `True`, AND the new expressions to any existing expression.
1442                Otherwise, this resets the expression.
1443            dialect: the dialect used to parse the input expressions.
1444            copy: if `False`, modify this expression instance in-place.
1445            opts: other options to use to parse the input expressions.
1446
1447        Returns:
1448            Delete: the modified expression.
1449        """
1450        return _apply_conjunction_builder(
1451            *expressions,
1452            instance=self,
1453            arg="where",
1454            append=append,
1455            into=Where,
1456            dialect=dialect,
1457            copy=copy,
1458            **opts,
1459        )
1460
1461    def returning(
1462        self,
1463        expression: ExpOrStr,
1464        dialect: DialectType = None,
1465        copy: bool = True,
1466        **opts,
1467    ) -> Delete:
1468        """
1469        Set the RETURNING expression. Not supported by all dialects.
1470
1471        Example:
1472            >>> delete("tbl").returning("*", dialect="postgres").sql()
1473            'DELETE FROM tbl RETURNING *'
1474
1475        Args:
1476            expression: the SQL code strings to parse.
1477                If an `Expression` instance is passed, it will be used as-is.
1478            dialect: the dialect used to parse the input expressions.
1479            copy: if `False`, modify this expression instance in-place.
1480            opts: other options to use to parse the input expressions.
1481
1482        Returns:
1483            Delete: the modified expression.
1484        """
1485        return _apply_builder(
1486            expression=expression,
1487            instance=self,
1488            arg="returning",
1489            prefix="RETURNING",
1490            dialect=dialect,
1491            copy=copy,
1492            into=Returning,
1493            **opts,
1494        )
1495
1496
1497class Drop(Expression):
1498    arg_types = {
1499        "this": False,
1500        "kind": False,
1501        "exists": False,
1502        "temporary": False,
1503        "materialized": False,
1504        "cascade": False,
1505        "constraints": False,
1506        "purge": False,
1507    }
1508
1509
1510class Filter(Expression):
1511    arg_types = {"this": True, "expression": True}
1512
1513
1514class Check(Expression):
1515    pass
1516
1517
1518# https://docs.snowflake.com/en/sql-reference/constructs/connect-by
1519class Connect(Expression):
1520    arg_types = {"start": False, "connect": True}
1521
1522
1523class Prior(Expression):
1524    pass
1525
1526
1527class Directory(Expression):
1528    # https://spark.apache.org/docs/3.0.0-preview/sql-ref-syntax-dml-insert-overwrite-directory-hive.html
1529    arg_types = {"this": True, "local": False, "row_format": False}
1530
1531
1532class ForeignKey(Expression):
1533    arg_types = {
1534        "expressions": True,
1535        "reference": False,
1536        "delete": False,
1537        "update": False,
1538    }
1539
1540
1541class ColumnPrefix(Expression):
1542    arg_types = {"this": True, "expression": True}
1543
1544
1545class PrimaryKey(Expression):
1546    arg_types = {"expressions": True, "options": False}
1547
1548
1549# https://www.postgresql.org/docs/9.1/sql-selectinto.html
1550# https://docs.aws.amazon.com/redshift/latest/dg/r_SELECT_INTO.html#r_SELECT_INTO-examples
1551class Into(Expression):
1552    arg_types = {"this": True, "temporary": False, "unlogged": False}
1553
1554
1555class From(Expression):
1556    @property
1557    def name(self) -> str:
1558        return self.this.name
1559
1560    @property
1561    def alias_or_name(self) -> str:
1562        return self.this.alias_or_name
1563
1564
1565class Having(Expression):
1566    pass
1567
1568
1569class Hint(Expression):
1570    arg_types = {"expressions": True}
1571
1572
1573class JoinHint(Expression):
1574    arg_types = {"this": True, "expressions": True}
1575
1576
1577class Identifier(Expression):
1578    arg_types = {"this": True, "quoted": False, "global": False, "temporary": False}
1579
1580    @property
1581    def quoted(self) -> bool:
1582        return bool(self.args.get("quoted"))
1583
1584    @property
1585    def hashable_args(self) -> t.Any:
1586        return (self.this, self.quoted)
1587
1588    @property
1589    def output_name(self) -> str:
1590        return self.name
1591
1592
1593class Index(Expression):
1594    arg_types = {
1595        "this": False,
1596        "table": False,
1597        "using": False,
1598        "where": False,
1599        "columns": False,
1600        "unique": False,
1601        "primary": False,
1602        "amp": False,  # teradata
1603        "partition_by": False,  # teradata
1604    }
1605
1606
1607class Insert(DDL):
1608    arg_types = {
1609        "with": False,
1610        "this": True,
1611        "expression": False,
1612        "conflict": False,
1613        "returning": False,
1614        "overwrite": False,
1615        "exists": False,
1616        "partition": False,
1617        "alternative": False,
1618        "where": False,
1619        "ignore": False,
1620        "by_name": False,
1621    }
1622
1623    def with_(
1624        self,
1625        alias: ExpOrStr,
1626        as_: ExpOrStr,
1627        recursive: t.Optional[bool] = None,
1628        append: bool = True,
1629        dialect: DialectType = None,
1630        copy: bool = True,
1631        **opts,
1632    ) -> Insert:
1633        """
1634        Append to or set the common table expressions.
1635
1636        Example:
1637            >>> insert("SELECT x FROM cte", "t").with_("cte", as_="SELECT * FROM tbl").sql()
1638            'WITH cte AS (SELECT * FROM tbl) INSERT INTO t SELECT x FROM cte'
1639
1640        Args:
1641            alias: the SQL code string to parse as the table name.
1642                If an `Expression` instance is passed, this is used as-is.
1643            as_: the SQL code string to parse as the table expression.
1644                If an `Expression` instance is passed, it will be used as-is.
1645            recursive: set the RECURSIVE part of the expression. Defaults to `False`.
1646            append: if `True`, add to any existing expressions.
1647                Otherwise, this resets the expressions.
1648            dialect: the dialect used to parse the input expression.
1649            copy: if `False`, modify this expression instance in-place.
1650            opts: other options to use to parse the input expressions.
1651
1652        Returns:
1653            The modified expression.
1654        """
1655        return _apply_cte_builder(
1656            self, alias, as_, recursive=recursive, append=append, dialect=dialect, copy=copy, **opts
1657        )
1658
1659
1660class OnConflict(Expression):
1661    arg_types = {
1662        "duplicate": False,
1663        "expressions": False,
1664        "nothing": False,
1665        "key": False,
1666        "constraint": False,
1667    }
1668
1669
1670class Returning(Expression):
1671    arg_types = {"expressions": True, "into": False}
1672
1673
1674# https://dev.mysql.com/doc/refman/8.0/en/charset-introducer.html
1675class Introducer(Expression):
1676    arg_types = {"this": True, "expression": True}
1677
1678
1679# national char, like n'utf8'
1680class National(Expression):
1681    pass
1682
1683
1684class LoadData(Expression):
1685    arg_types = {
1686        "this": True,
1687        "local": False,
1688        "overwrite": False,
1689        "inpath": True,
1690        "partition": False,
1691        "input_format": False,
1692        "serde": False,
1693    }
1694
1695
1696class Partition(Expression):
1697    arg_types = {"expressions": True}
1698
1699
1700class Fetch(Expression):
1701    arg_types = {
1702        "direction": False,
1703        "count": False,
1704        "percent": False,
1705        "with_ties": False,
1706    }
1707
1708
1709class Group(Expression):
1710    arg_types = {
1711        "expressions": False,
1712        "grouping_sets": False,
1713        "cube": False,
1714        "rollup": False,
1715        "totals": False,
1716        "all": False,
1717    }
1718
1719
1720class Lambda(Expression):
1721    arg_types = {"this": True, "expressions": True}
1722
1723
1724class Limit(Expression):
1725    arg_types = {"this": False, "expression": True, "offset": False}
1726
1727
1728class Literal(Condition):
1729    arg_types = {"this": True, "is_string": True}
1730
1731    @property
1732    def hashable_args(self) -> t.Any:
1733        return (self.this, self.args.get("is_string"))
1734
1735    @classmethod
1736    def number(cls, number) -> Literal:
1737        return cls(this=str(number), is_string=False)
1738
1739    @classmethod
1740    def string(cls, string) -> Literal:
1741        return cls(this=str(string), is_string=True)
1742
1743    @property
1744    def output_name(self) -> str:
1745        return self.name
1746
1747
1748class Join(Expression):
1749    arg_types = {
1750        "this": True,
1751        "on": False,
1752        "side": False,
1753        "kind": False,
1754        "using": False,
1755        "method": False,
1756        "global": False,
1757        "hint": False,
1758    }
1759
1760    @property
1761    def method(self) -> str:
1762        return self.text("method").upper()
1763
1764    @property
1765    def kind(self) -> str:
1766        return self.text("kind").upper()
1767
1768    @property
1769    def side(self) -> str:
1770        return self.text("side").upper()
1771
1772    @property
1773    def hint(self) -> str:
1774        return self.text("hint").upper()
1775
1776    @property
1777    def alias_or_name(self) -> str:
1778        return self.this.alias_or_name
1779
1780    def on(
1781        self,
1782        *expressions: t.Optional[ExpOrStr],
1783        append: bool = True,
1784        dialect: DialectType = None,
1785        copy: bool = True,
1786        **opts,
1787    ) -> Join:
1788        """
1789        Append to or set the ON expressions.
1790
1791        Example:
1792            >>> import sqlglot
1793            >>> sqlglot.parse_one("JOIN x", into=Join).on("y = 1").sql()
1794            'JOIN x ON y = 1'
1795
1796        Args:
1797            *expressions: the SQL code strings to parse.
1798                If an `Expression` instance is passed, it will be used as-is.
1799                Multiple expressions are combined with an AND operator.
1800            append: if `True`, AND the new expressions to any existing expression.
1801                Otherwise, this resets the expression.
1802            dialect: the dialect used to parse the input expressions.
1803            copy: if `False`, modify this expression instance in-place.
1804            opts: other options to use to parse the input expressions.
1805
1806        Returns:
1807            The modified Join expression.
1808        """
1809        join = _apply_conjunction_builder(
1810            *expressions,
1811            instance=self,
1812            arg="on",
1813            append=append,
1814            dialect=dialect,
1815            copy=copy,
1816            **opts,
1817        )
1818
1819        if join.kind == "CROSS":
1820            join.set("kind", None)
1821
1822        return join
1823
1824    def using(
1825        self,
1826        *expressions: t.Optional[ExpOrStr],
1827        append: bool = True,
1828        dialect: DialectType = None,
1829        copy: bool = True,
1830        **opts,
1831    ) -> Join:
1832        """
1833        Append to or set the USING expressions.
1834
1835        Example:
1836            >>> import sqlglot
1837            >>> sqlglot.parse_one("JOIN x", into=Join).using("foo", "bla").sql()
1838            'JOIN x USING (foo, bla)'
1839
1840        Args:
1841            *expressions: the SQL code strings to parse.
1842                If an `Expression` instance is passed, it will be used as-is.
1843            append: if `True`, concatenate the new expressions to the existing "using" list.
1844                Otherwise, this resets the expression.
1845            dialect: the dialect used to parse the input expressions.
1846            copy: if `False`, modify this expression instance in-place.
1847            opts: other options to use to parse the input expressions.
1848
1849        Returns:
1850            The modified Join expression.
1851        """
1852        join = _apply_list_builder(
1853            *expressions,
1854            instance=self,
1855            arg="using",
1856            append=append,
1857            dialect=dialect,
1858            copy=copy,
1859            **opts,
1860        )
1861
1862        if join.kind == "CROSS":
1863            join.set("kind", None)
1864
1865        return join
1866
1867
1868class Lateral(UDTF):
1869    arg_types = {"this": True, "view": False, "outer": False, "alias": False}
1870
1871
1872class MatchRecognize(Expression):
1873    arg_types = {
1874        "partition_by": False,
1875        "order": False,
1876        "measures": False,
1877        "rows": False,
1878        "after": False,
1879        "pattern": False,
1880        "define": False,
1881        "alias": False,
1882    }
1883
1884
1885# Clickhouse FROM FINAL modifier
1886# https://clickhouse.com/docs/en/sql-reference/statements/select/from/#final-modifier
1887class Final(Expression):
1888    pass
1889
1890
1891class Offset(Expression):
1892    arg_types = {"this": False, "expression": True}
1893
1894
1895class Order(Expression):
1896    arg_types = {"this": False, "expressions": True}
1897
1898
1899# hive specific sorts
1900# https://cwiki.apache.org/confluence/display/Hive/LanguageManual+SortBy
1901class Cluster(Order):
1902    pass
1903
1904
1905class Distribute(Order):
1906    pass
1907
1908
1909class Sort(Order):
1910    pass
1911
1912
1913class Ordered(Expression):
1914    arg_types = {"this": True, "desc": True, "nulls_first": True}
1915
1916
1917class Property(Expression):
1918    arg_types = {"this": True, "value": True}
1919
1920
1921class AlgorithmProperty(Property):
1922    arg_types = {"this": True}
1923
1924
1925class AutoIncrementProperty(Property):
1926    arg_types = {"this": True}
1927
1928
1929class BlockCompressionProperty(Property):
1930    arg_types = {"autotemp": False, "always": False, "default": True, "manual": True, "never": True}
1931
1932
1933class CharacterSetProperty(Property):
1934    arg_types = {"this": True, "default": True}
1935
1936
1937class ChecksumProperty(Property):
1938    arg_types = {"on": False, "default": False}
1939
1940
1941class CollateProperty(Property):
1942    arg_types = {"this": True}
1943
1944
1945class CopyGrantsProperty(Property):
1946    arg_types = {}
1947
1948
1949class DataBlocksizeProperty(Property):
1950    arg_types = {
1951        "size": False,
1952        "units": False,
1953        "minimum": False,
1954        "maximum": False,
1955        "default": False,
1956    }
1957
1958
1959class DefinerProperty(Property):
1960    arg_types = {"this": True}
1961
1962
1963class DistKeyProperty(Property):
1964    arg_types = {"this": True}
1965
1966
1967class DistStyleProperty(Property):
1968    arg_types = {"this": True}
1969
1970
1971class EngineProperty(Property):
1972    arg_types = {"this": True}
1973
1974
1975class HeapProperty(Property):
1976    arg_types = {}
1977
1978
1979class ToTableProperty(Property):
1980    arg_types = {"this": True}
1981
1982
1983class ExecuteAsProperty(Property):
1984    arg_types = {"this": True}
1985
1986
1987class ExternalProperty(Property):
1988    arg_types = {"this": False}
1989
1990
1991class FallbackProperty(Property):
1992    arg_types = {"no": True, "protection": False}
1993
1994
1995class FileFormatProperty(Property):
1996    arg_types = {"this": True}
1997
1998
1999class FreespaceProperty(Property):
2000    arg_types = {"this": True, "percent": False}
2001
2002
2003class InputOutputFormat(Expression):
2004    arg_types = {"input_format": False, "output_format": False}
2005
2006
2007class IsolatedLoadingProperty(Property):
2008    arg_types = {
2009        "no": True,
2010        "concurrent": True,
2011        "for_all": True,
2012        "for_insert": True,
2013        "for_none": True,
2014    }
2015
2016
2017class JournalProperty(Property):
2018    arg_types = {
2019        "no": False,
2020        "dual": False,
2021        "before": False,
2022        "local": False,
2023        "after": False,
2024    }
2025
2026
2027class LanguageProperty(Property):
2028    arg_types = {"this": True}
2029
2030
2031# spark ddl
2032class ClusteredByProperty(Property):
2033    arg_types = {"expressions": True, "sorted_by": False, "buckets": True}
2034
2035
2036class DictProperty(Property):
2037    arg_types = {"this": True, "kind": True, "settings": False}
2038
2039
2040class DictSubProperty(Property):
2041    pass
2042
2043
2044class DictRange(Property):
2045    arg_types = {"this": True, "min": True, "max": True}
2046
2047
2048# Clickhouse CREATE ... ON CLUSTER modifier
2049# https://clickhouse.com/docs/en/sql-reference/distributed-ddl
2050class OnCluster(Property):
2051    arg_types = {"this": True}
2052
2053
2054class LikeProperty(Property):
2055    arg_types = {"this": True, "expressions": False}
2056
2057
2058class LocationProperty(Property):
2059    arg_types = {"this": True}
2060
2061
2062class LockingProperty(Property):
2063    arg_types = {
2064        "this": False,
2065        "kind": True,
2066        "for_or_in": True,
2067        "lock_type": True,
2068        "override": False,
2069    }
2070
2071
2072class LogProperty(Property):
2073    arg_types = {"no": True}
2074
2075
2076class MaterializedProperty(Property):
2077    arg_types = {"this": False}
2078
2079
2080class MergeBlockRatioProperty(Property):
2081    arg_types = {"this": False, "no": False, "default": False, "percent": False}
2082
2083
2084class NoPrimaryIndexProperty(Property):
2085    arg_types = {}
2086
2087
2088class OnProperty(Property):
2089    arg_types = {"this": True}
2090
2091
2092class OnCommitProperty(Property):
2093    arg_types = {"delete": False}
2094
2095
2096class PartitionedByProperty(Property):
2097    arg_types = {"this": True}
2098
2099
2100class ReturnsProperty(Property):
2101    arg_types = {"this": True, "is_table": False, "table": False}
2102
2103
2104class RowFormatProperty(Property):
2105    arg_types = {"this": True}
2106
2107
2108class RowFormatDelimitedProperty(Property):
2109    # https://cwiki.apache.org/confluence/display/hive/languagemanual+dml
2110    arg_types = {
2111        "fields": False,
2112        "escaped": False,
2113        "collection_items": False,
2114        "map_keys": False,
2115        "lines": False,
2116        "null": False,
2117        "serde": False,
2118    }
2119
2120
2121class RowFormatSerdeProperty(Property):
2122    arg_types = {"this": True, "serde_properties": False}
2123
2124
2125# https://spark.apache.org/docs/3.1.2/sql-ref-syntax-qry-select-transform.html
2126class QueryTransform(Expression):
2127    arg_types = {
2128        "expressions": True,
2129        "command_script": True,
2130        "schema": False,
2131        "row_format_before": False,
2132        "record_writer": False,
2133        "row_format_after": False,
2134        "record_reader": False,
2135    }
2136
2137
2138class SchemaCommentProperty(Property):
2139    arg_types = {"this": True}
2140
2141
2142class SerdeProperties(Property):
2143    arg_types = {"expressions": True}
2144
2145
2146class SetProperty(Property):
2147    arg_types = {"multi": True}
2148
2149
2150class SettingsProperty(Property):
2151    arg_types = {"expressions": True}
2152
2153
2154class SortKeyProperty(Property):
2155    arg_types = {"this": True, "compound": False}
2156
2157
2158class SqlSecurityProperty(Property):
2159    arg_types = {"definer": True}
2160
2161
2162class StabilityProperty(Property):
2163    arg_types = {"this": True}
2164
2165
2166class TemporaryProperty(Property):
2167    arg_types = {}
2168
2169
2170class TransientProperty(Property):
2171    arg_types = {"this": False}
2172
2173
2174class VolatileProperty(Property):
2175    arg_types = {"this": False}
2176
2177
2178class WithDataProperty(Property):
2179    arg_types = {"no": True, "statistics": False}
2180
2181
2182class WithJournalTableProperty(Property):
2183    arg_types = {"this": True}
2184
2185
2186class Properties(Expression):
2187    arg_types = {"expressions": True}
2188
2189    NAME_TO_PROPERTY = {
2190        "ALGORITHM": AlgorithmProperty,
2191        "AUTO_INCREMENT": AutoIncrementProperty,
2192        "CHARACTER SET": CharacterSetProperty,
2193        "CLUSTERED_BY": ClusteredByProperty,
2194        "COLLATE": CollateProperty,
2195        "COMMENT": SchemaCommentProperty,
2196        "DEFINER": DefinerProperty,
2197        "DISTKEY": DistKeyProperty,
2198        "DISTSTYLE": DistStyleProperty,
2199        "ENGINE": EngineProperty,
2200        "EXECUTE AS": ExecuteAsProperty,
2201        "FORMAT": FileFormatProperty,
2202        "LANGUAGE": LanguageProperty,
2203        "LOCATION": LocationProperty,
2204        "PARTITIONED_BY": PartitionedByProperty,
2205        "RETURNS": ReturnsProperty,
2206        "ROW_FORMAT": RowFormatProperty,
2207        "SORTKEY": SortKeyProperty,
2208    }
2209
2210    PROPERTY_TO_NAME = {v: k for k, v in NAME_TO_PROPERTY.items()}
2211
2212    # CREATE property locations
2213    # Form: schema specified
2214    #   create [POST_CREATE]
2215    #     table a [POST_NAME]
2216    #     (b int) [POST_SCHEMA]
2217    #     with ([POST_WITH])
2218    #     index (b) [POST_INDEX]
2219    #
2220    # Form: alias selection
2221    #   create [POST_CREATE]
2222    #     table a [POST_NAME]
2223    #     as [POST_ALIAS] (select * from b) [POST_EXPRESSION]
2224    #     index (c) [POST_INDEX]
2225    class Location(AutoName):
2226        POST_CREATE = auto()
2227        POST_NAME = auto()
2228        POST_SCHEMA = auto()
2229        POST_WITH = auto()
2230        POST_ALIAS = auto()
2231        POST_EXPRESSION = auto()
2232        POST_INDEX = auto()
2233        UNSUPPORTED = auto()
2234
2235    @classmethod
2236    def from_dict(cls, properties_dict: t.Dict) -> Properties:
2237        expressions = []
2238        for key, value in properties_dict.items():
2239            property_cls = cls.NAME_TO_PROPERTY.get(key.upper())
2240            if property_cls:
2241                expressions.append(property_cls(this=convert(value)))
2242            else:
2243                expressions.append(Property(this=Literal.string(key), value=convert(value)))
2244
2245        return cls(expressions=expressions)
2246
2247
2248class Qualify(Expression):
2249    pass
2250
2251
2252# https://www.ibm.com/docs/en/ias?topic=procedures-return-statement-in-sql
2253class Return(Expression):
2254    pass
2255
2256
2257class Reference(Expression):
2258    arg_types = {"this": True, "expressions": False, "options": False}
2259
2260
2261class Tuple(Expression):
2262    arg_types = {"expressions": False}
2263
2264    def isin(
2265        self,
2266        *expressions: t.Any,
2267        query: t.Optional[ExpOrStr] = None,
2268        unnest: t.Optional[ExpOrStr] | t.Collection[ExpOrStr] = None,
2269        copy: bool = True,
2270        **opts,
2271    ) -> In:
2272        return In(
2273            this=maybe_copy(self, copy),
2274            expressions=[convert(e, copy=copy) for e in expressions],
2275            query=maybe_parse(query, copy=copy, **opts) if query else None,
2276            unnest=Unnest(
2277                expressions=[
2278                    maybe_parse(t.cast(ExpOrStr, e), copy=copy, **opts) for e in ensure_list(unnest)
2279                ]
2280            )
2281            if unnest
2282            else None,
2283        )
2284
2285
2286class Subqueryable(Unionable):
2287    def subquery(self, alias: t.Optional[ExpOrStr] = None, copy: bool = True) -> Subquery:
2288        """
2289        Convert this expression to an aliased expression that can be used as a Subquery.
2290
2291        Example:
2292            >>> subquery = Select().select("x").from_("tbl").subquery()
2293            >>> Select().select("x").from_(subquery).sql()
2294            'SELECT x FROM (SELECT x FROM tbl)'
2295
2296        Args:
2297            alias (str | Identifier): an optional alias for the subquery
2298            copy (bool): if `False`, modify this expression instance in-place.
2299
2300        Returns:
2301            Alias: the subquery
2302        """
2303        instance = maybe_copy(self, copy)
2304        if not isinstance(alias, Expression):
2305            alias = TableAlias(this=to_identifier(alias)) if alias else None
2306
2307        return Subquery(this=instance, alias=alias)
2308
2309    def limit(
2310        self, expression: ExpOrStr | int, dialect: DialectType = None, copy: bool = True, **opts
2311    ) -> Select:
2312        raise NotImplementedError
2313
2314    @property
2315    def ctes(self):
2316        with_ = self.args.get("with")
2317        if not with_:
2318            return []
2319        return with_.expressions
2320
2321    @property
2322    def selects(self) -> t.List[Expression]:
2323        raise NotImplementedError("Subqueryable objects must implement `selects`")
2324
2325    @property
2326    def named_selects(self) -> t.List[str]:
2327        raise NotImplementedError("Subqueryable objects must implement `named_selects`")
2328
2329    def select(
2330        self,
2331        *expressions: t.Optional[ExpOrStr],
2332        append: bool = True,
2333        dialect: DialectType = None,
2334        copy: bool = True,
2335        **opts,
2336    ) -> Subqueryable:
2337        raise NotImplementedError("Subqueryable objects must implement `select`")
2338
2339    def with_(
2340        self,
2341        alias: ExpOrStr,
2342        as_: ExpOrStr,
2343        recursive: t.Optional[bool] = None,
2344        append: bool = True,
2345        dialect: DialectType = None,
2346        copy: bool = True,
2347        **opts,
2348    ) -> Subqueryable:
2349        """
2350        Append to or set the common table expressions.
2351
2352        Example:
2353            >>> Select().with_("tbl2", as_="SELECT * FROM tbl").select("x").from_("tbl2").sql()
2354            'WITH tbl2 AS (SELECT * FROM tbl) SELECT x FROM tbl2'
2355
2356        Args:
2357            alias: the SQL code string to parse as the table name.
2358                If an `Expression` instance is passed, this is used as-is.
2359            as_: the SQL code string to parse as the table expression.
2360                If an `Expression` instance is passed, it will be used as-is.
2361            recursive: set the RECURSIVE part of the expression. Defaults to `False`.
2362            append: if `True`, add to any existing expressions.
2363                Otherwise, this resets the expressions.
2364            dialect: the dialect used to parse the input expression.
2365            copy: if `False`, modify this expression instance in-place.
2366            opts: other options to use to parse the input expressions.
2367
2368        Returns:
2369            The modified expression.
2370        """
2371        return _apply_cte_builder(
2372            self, alias, as_, recursive=recursive, append=append, dialect=dialect, copy=copy, **opts
2373        )
2374
2375
2376QUERY_MODIFIERS = {
2377    "match": False,
2378    "laterals": False,
2379    "joins": False,
2380    "connect": False,
2381    "pivots": False,
2382    "where": False,
2383    "group": False,
2384    "having": False,
2385    "qualify": False,
2386    "windows": False,
2387    "distribute": False,
2388    "sort": False,
2389    "cluster": False,
2390    "order": False,
2391    "limit": False,
2392    "offset": False,
2393    "locks": False,
2394    "sample": False,
2395    "settings": False,
2396    "format": False,
2397}
2398
2399
2400# https://learn.microsoft.com/en-us/sql/t-sql/queries/hints-transact-sql-table?view=sql-server-ver16
2401class WithTableHint(Expression):
2402    arg_types = {"expressions": True}
2403
2404
2405# https://dev.mysql.com/doc/refman/8.0/en/index-hints.html
2406class IndexTableHint(Expression):
2407    arg_types = {"this": True, "expressions": False, "target": False}
2408
2409
2410class Table(Expression):
2411    arg_types = {
2412        "this": True,
2413        "alias": False,
2414        "db": False,
2415        "catalog": False,
2416        "laterals": False,
2417        "joins": False,
2418        "pivots": False,
2419        "hints": False,
2420        "system_time": False,
2421        "version": False,
2422    }
2423
2424    @property
2425    def name(self) -> str:
2426        if isinstance(self.this, Func):
2427            return ""
2428        return self.this.name
2429
2430    @property
2431    def db(self) -> str:
2432        return self.text("db")
2433
2434    @property
2435    def catalog(self) -> str:
2436        return self.text("catalog")
2437
2438    @property
2439    def selects(self) -> t.List[Expression]:
2440        return []
2441
2442    @property
2443    def named_selects(self) -> t.List[str]:
2444        return []
2445
2446    @property
2447    def parts(self) -> t.List[Identifier]:
2448        """Return the parts of a table in order catalog, db, table."""
2449        parts: t.List[Identifier] = []
2450
2451        for arg in ("catalog", "db", "this"):
2452            part = self.args.get(arg)
2453
2454            if isinstance(part, Identifier):
2455                parts.append(part)
2456            elif isinstance(part, Dot):
2457                parts.extend(part.flatten())
2458
2459        return parts
2460
2461
2462class Union(Subqueryable):
2463    arg_types = {
2464        "with": False,
2465        "this": True,
2466        "expression": True,
2467        "distinct": False,
2468        "by_name": False,
2469        **QUERY_MODIFIERS,
2470    }
2471
2472    def limit(
2473        self, expression: ExpOrStr | int, dialect: DialectType = None, copy: bool = True, **opts
2474    ) -> Select:
2475        """
2476        Set the LIMIT expression.
2477
2478        Example:
2479            >>> select("1").union(select("1")).limit(1).sql()
2480            'SELECT * FROM (SELECT 1 UNION SELECT 1) AS _l_0 LIMIT 1'
2481
2482        Args:
2483            expression: the SQL code string to parse.
2484                This can also be an integer.
2485                If a `Limit` instance is passed, this is used as-is.
2486                If another `Expression` instance is passed, it will be wrapped in a `Limit`.
2487            dialect: the dialect used to parse the input expression.
2488            copy: if `False`, modify this expression instance in-place.
2489            opts: other options to use to parse the input expressions.
2490
2491        Returns:
2492            The limited subqueryable.
2493        """
2494        return (
2495            select("*")
2496            .from_(self.subquery(alias="_l_0", copy=copy))
2497            .limit(expression, dialect=dialect, copy=False, **opts)
2498        )
2499
2500    def select(
2501        self,
2502        *expressions: t.Optional[ExpOrStr],
2503        append: bool = True,
2504        dialect: DialectType = None,
2505        copy: bool = True,
2506        **opts,
2507    ) -> Union:
2508        """Append to or set the SELECT of the union recursively.
2509
2510        Example:
2511            >>> from sqlglot import parse_one
2512            >>> parse_one("select a from x union select a from y union select a from z").select("b").sql()
2513            'SELECT a, b FROM x UNION SELECT a, b FROM y UNION SELECT a, b FROM z'
2514
2515        Args:
2516            *expressions: the SQL code strings to parse.
2517                If an `Expression` instance is passed, it will be used as-is.
2518            append: if `True`, add to any existing expressions.
2519                Otherwise, this resets the expressions.
2520            dialect: the dialect used to parse the input expressions.
2521            copy: if `False`, modify this expression instance in-place.
2522            opts: other options to use to parse the input expressions.
2523
2524        Returns:
2525            Union: the modified expression.
2526        """
2527        this = self.copy() if copy else self
2528        this.this.unnest().select(*expressions, append=append, dialect=dialect, copy=False, **opts)
2529        this.expression.unnest().select(
2530            *expressions, append=append, dialect=dialect, copy=False, **opts
2531        )
2532        return this
2533
2534    @property
2535    def named_selects(self) -> t.List[str]:
2536        return self.this.unnest().named_selects
2537
2538    @property
2539    def is_star(self) -> bool:
2540        return self.this.is_star or self.expression.is_star
2541
2542    @property
2543    def selects(self) -> t.List[Expression]:
2544        return self.this.unnest().selects
2545
2546    @property
2547    def left(self):
2548        return self.this
2549
2550    @property
2551    def right(self):
2552        return self.expression
2553
2554
2555class Except(Union):
2556    pass
2557
2558
2559class Intersect(Union):
2560    pass
2561
2562
2563class Unnest(UDTF):
2564    arg_types = {
2565        "expressions": True,
2566        "ordinality": False,
2567        "alias": False,
2568        "offset": False,
2569    }
2570
2571
2572class Update(Expression):
2573    arg_types = {
2574        "with": False,
2575        "this": False,
2576        "expressions": True,
2577        "from": False,
2578        "where": False,
2579        "returning": False,
2580        "order": False,
2581        "limit": False,
2582    }
2583
2584
2585class Values(UDTF):
2586    arg_types = {
2587        "expressions": True,
2588        "ordinality": False,
2589        "alias": False,
2590    }
2591
2592
2593class Var(Expression):
2594    pass
2595
2596
2597class Version(Expression):
2598    """
2599    Time travel, iceberg, bigquery etc
2600    https://trino.io/docs/current/connector/iceberg.html?highlight=snapshot#using-snapshots
2601    https://www.databricks.com/blog/2019/02/04/introducing-delta-time-travel-for-large-scale-data-lakes.html
2602    https://cloud.google.com/bigquery/docs/reference/standard-sql/query-syntax#for_system_time_as_of
2603    https://learn.microsoft.com/en-us/sql/relational-databases/tables/querying-data-in-a-system-versioned-temporal-table?view=sql-server-ver16
2604    this is either TIMESTAMP or VERSION
2605    kind is ("AS OF", "BETWEEN")
2606    """
2607
2608    arg_types = {"this": True, "kind": True, "expression": False}
2609
2610
2611class Schema(Expression):
2612    arg_types = {"this": False, "expressions": False}
2613
2614
2615# https://dev.mysql.com/doc/refman/8.0/en/select.html
2616# https://docs.oracle.com/en/database/oracle/oracle-database/19/sqlrf/SELECT.html
2617class Lock(Expression):
2618    arg_types = {"update": True, "expressions": False, "wait": False}
2619
2620
2621class Select(Subqueryable):
2622    arg_types = {
2623        "with": False,
2624        "kind": False,
2625        "expressions": False,
2626        "hint": False,
2627        "distinct": False,
2628        "into": False,
2629        "from": False,
2630        **QUERY_MODIFIERS,
2631    }
2632
2633    def from_(
2634        self, expression: ExpOrStr, dialect: DialectType = None, copy: bool = True, **opts
2635    ) -> Select:
2636        """
2637        Set the FROM expression.
2638
2639        Example:
2640            >>> Select().from_("tbl").select("x").sql()
2641            'SELECT x FROM tbl'
2642
2643        Args:
2644            expression : the SQL code strings to parse.
2645                If a `From` instance is passed, this is used as-is.
2646                If another `Expression` instance is passed, it will be wrapped in a `From`.
2647            dialect: the dialect used to parse the input expression.
2648            copy: if `False`, modify this expression instance in-place.
2649            opts: other options to use to parse the input expressions.
2650
2651        Returns:
2652            The modified Select expression.
2653        """
2654        return _apply_builder(
2655            expression=expression,
2656            instance=self,
2657            arg="from",
2658            into=From,
2659            prefix="FROM",
2660            dialect=dialect,
2661            copy=copy,
2662            **opts,
2663        )
2664
2665    def group_by(
2666        self,
2667        *expressions: t.Optional[ExpOrStr],
2668        append: bool = True,
2669        dialect: DialectType = None,
2670        copy: bool = True,
2671        **opts,
2672    ) -> Select:
2673        """
2674        Set the GROUP BY expression.
2675
2676        Example:
2677            >>> Select().from_("tbl").select("x", "COUNT(1)").group_by("x").sql()
2678            'SELECT x, COUNT(1) FROM tbl GROUP BY x'
2679
2680        Args:
2681            *expressions: the SQL code strings to parse.
2682                If a `Group` instance is passed, this is used as-is.
2683                If another `Expression` instance is passed, it will be wrapped in a `Group`.
2684                If nothing is passed in then a group by is not applied to the expression
2685            append: if `True`, add to any existing expressions.
2686                Otherwise, this flattens all the `Group` expression into a single expression.
2687            dialect: the dialect used to parse the input expression.
2688            copy: if `False`, modify this expression instance in-place.
2689            opts: other options to use to parse the input expressions.
2690
2691        Returns:
2692            The modified Select expression.
2693        """
2694        if not expressions:
2695            return self if not copy else self.copy()
2696
2697        return _apply_child_list_builder(
2698            *expressions,
2699            instance=self,
2700            arg="group",
2701            append=append,
2702            copy=copy,
2703            prefix="GROUP BY",
2704            into=Group,
2705            dialect=dialect,
2706            **opts,
2707        )
2708
2709    def order_by(
2710        self,
2711        *expressions: t.Optional[ExpOrStr],
2712        append: bool = True,
2713        dialect: DialectType = None,
2714        copy: bool = True,
2715        **opts,
2716    ) -> Select:
2717        """
2718        Set the ORDER BY expression.
2719
2720        Example:
2721            >>> Select().from_("tbl").select("x").order_by("x DESC").sql()
2722            'SELECT x FROM tbl ORDER BY x DESC'
2723
2724        Args:
2725            *expressions: the SQL code strings to parse.
2726                If a `Group` instance is passed, this is used as-is.
2727                If another `Expression` instance is passed, it will be wrapped in a `Order`.
2728            append: if `True`, add to any existing expressions.
2729                Otherwise, this flattens all the `Order` expression into a single expression.
2730            dialect: the dialect used to parse the input expression.
2731            copy: if `False`, modify this expression instance in-place.
2732            opts: other options to use to parse the input expressions.
2733
2734        Returns:
2735            The modified Select expression.
2736        """
2737        return _apply_child_list_builder(
2738            *expressions,
2739            instance=self,
2740            arg="order",
2741            append=append,
2742            copy=copy,
2743            prefix="ORDER BY",
2744            into=Order,
2745            dialect=dialect,
2746            **opts,
2747        )
2748
2749    def sort_by(
2750        self,
2751        *expressions: t.Optional[ExpOrStr],
2752        append: bool = True,
2753        dialect: DialectType = None,
2754        copy: bool = True,
2755        **opts,
2756    ) -> Select:
2757        """
2758        Set the SORT BY expression.
2759
2760        Example:
2761            >>> Select().from_("tbl").select("x").sort_by("x DESC").sql(dialect="hive")
2762            'SELECT x FROM tbl SORT BY x DESC'
2763
2764        Args:
2765            *expressions: the SQL code strings to parse.
2766                If a `Group` instance is passed, this is used as-is.
2767                If another `Expression` instance is passed, it will be wrapped in a `SORT`.
2768            append: if `True`, add to any existing expressions.
2769                Otherwise, this flattens all the `Order` expression into a single expression.
2770            dialect: the dialect used to parse the input expression.
2771            copy: if `False`, modify this expression instance in-place.
2772            opts: other options to use to parse the input expressions.
2773
2774        Returns:
2775            The modified Select expression.
2776        """
2777        return _apply_child_list_builder(
2778            *expressions,
2779            instance=self,
2780            arg="sort",
2781            append=append,
2782            copy=copy,
2783            prefix="SORT BY",
2784            into=Sort,
2785            dialect=dialect,
2786            **opts,
2787        )
2788
2789    def cluster_by(
2790        self,
2791        *expressions: t.Optional[ExpOrStr],
2792        append: bool = True,
2793        dialect: DialectType = None,
2794        copy: bool = True,
2795        **opts,
2796    ) -> Select:
2797        """
2798        Set the CLUSTER BY expression.
2799
2800        Example:
2801            >>> Select().from_("tbl").select("x").cluster_by("x DESC").sql(dialect="hive")
2802            'SELECT x FROM tbl CLUSTER BY x DESC'
2803
2804        Args:
2805            *expressions: the SQL code strings to parse.
2806                If a `Group` instance is passed, this is used as-is.
2807                If another `Expression` instance is passed, it will be wrapped in a `Cluster`.
2808            append: if `True`, add to any existing expressions.
2809                Otherwise, this flattens all the `Order` expression into a single expression.
2810            dialect: the dialect used to parse the input expression.
2811            copy: if `False`, modify this expression instance in-place.
2812            opts: other options to use to parse the input expressions.
2813
2814        Returns:
2815            The modified Select expression.
2816        """
2817        return _apply_child_list_builder(
2818            *expressions,
2819            instance=self,
2820            arg="cluster",
2821            append=append,
2822            copy=copy,
2823            prefix="CLUSTER BY",
2824            into=Cluster,
2825            dialect=dialect,
2826            **opts,
2827        )
2828
2829    def limit(
2830        self, expression: ExpOrStr | int, dialect: DialectType = None, copy: bool = True, **opts
2831    ) -> Select:
2832        """
2833        Set the LIMIT expression.
2834
2835        Example:
2836            >>> Select().from_("tbl").select("x").limit(10).sql()
2837            'SELECT x FROM tbl LIMIT 10'
2838
2839        Args:
2840            expression: the SQL code string to parse.
2841                This can also be an integer.
2842                If a `Limit` instance is passed, this is used as-is.
2843                If another `Expression` instance is passed, it will be wrapped in a `Limit`.
2844            dialect: the dialect used to parse the input expression.
2845            copy: if `False`, modify this expression instance in-place.
2846            opts: other options to use to parse the input expressions.
2847
2848        Returns:
2849            Select: the modified expression.
2850        """
2851        return _apply_builder(
2852            expression=expression,
2853            instance=self,
2854            arg="limit",
2855            into=Limit,
2856            prefix="LIMIT",
2857            dialect=dialect,
2858            copy=copy,
2859            **opts,
2860        )
2861
2862    def offset(
2863        self, expression: ExpOrStr | int, dialect: DialectType = None, copy: bool = True, **opts
2864    ) -> Select:
2865        """
2866        Set the OFFSET expression.
2867
2868        Example:
2869            >>> Select().from_("tbl").select("x").offset(10).sql()
2870            'SELECT x FROM tbl OFFSET 10'
2871
2872        Args:
2873            expression: the SQL code string to parse.
2874                This can also be an integer.
2875                If a `Offset` instance is passed, this is used as-is.
2876                If another `Expression` instance is passed, it will be wrapped in a `Offset`.
2877            dialect: the dialect used to parse the input expression.
2878            copy: if `False`, modify this expression instance in-place.
2879            opts: other options to use to parse the input expressions.
2880
2881        Returns:
2882            The modified Select expression.
2883        """
2884        return _apply_builder(
2885            expression=expression,
2886            instance=self,
2887            arg="offset",
2888            into=Offset,
2889            prefix="OFFSET",
2890            dialect=dialect,
2891            copy=copy,
2892            **opts,
2893        )
2894
2895    def select(
2896        self,
2897        *expressions: t.Optional[ExpOrStr],
2898        append: bool = True,
2899        dialect: DialectType = None,
2900        copy: bool = True,
2901        **opts,
2902    ) -> Select:
2903        """
2904        Append to or set the SELECT expressions.
2905
2906        Example:
2907            >>> Select().select("x", "y").sql()
2908            'SELECT x, y'
2909
2910        Args:
2911            *expressions: the SQL code strings to parse.
2912                If an `Expression` instance is passed, it will be used as-is.
2913            append: if `True`, add to any existing expressions.
2914                Otherwise, this resets the expressions.
2915            dialect: the dialect used to parse the input expressions.
2916            copy: if `False`, modify this expression instance in-place.
2917            opts: other options to use to parse the input expressions.
2918
2919        Returns:
2920            The modified Select expression.
2921        """
2922        return _apply_list_builder(
2923            *expressions,
2924            instance=self,
2925            arg="expressions",
2926            append=append,
2927            dialect=dialect,
2928            copy=copy,
2929            **opts,
2930        )
2931
2932    def lateral(
2933        self,
2934        *expressions: t.Optional[ExpOrStr],
2935        append: bool = True,
2936        dialect: DialectType = None,
2937        copy: bool = True,
2938        **opts,
2939    ) -> Select:
2940        """
2941        Append to or set the LATERAL expressions.
2942
2943        Example:
2944            >>> Select().select("x").lateral("OUTER explode(y) tbl2 AS z").from_("tbl").sql()
2945            'SELECT x FROM tbl LATERAL VIEW OUTER EXPLODE(y) tbl2 AS z'
2946
2947        Args:
2948            *expressions: the SQL code strings to parse.
2949                If an `Expression` instance is passed, it will be used as-is.
2950            append: if `True`, add to any existing expressions.
2951                Otherwise, this resets the expressions.
2952            dialect: the dialect used to parse the input expressions.
2953            copy: if `False`, modify this expression instance in-place.
2954            opts: other options to use to parse the input expressions.
2955
2956        Returns:
2957            The modified Select expression.
2958        """
2959        return _apply_list_builder(
2960            *expressions,
2961            instance=self,
2962            arg="laterals",
2963            append=append,
2964            into=Lateral,
2965            prefix="LATERAL VIEW",
2966            dialect=dialect,
2967            copy=copy,
2968            **opts,
2969        )
2970
2971    def join(
2972        self,
2973        expression: ExpOrStr,
2974        on: t.Optional[ExpOrStr] = None,
2975        using: t.Optional[ExpOrStr | t.Collection[ExpOrStr]] = None,
2976        append: bool = True,
2977        join_type: t.Optional[str] = None,
2978        join_alias: t.Optional[Identifier | str] = None,
2979        dialect: DialectType = None,
2980        copy: bool = True,
2981        **opts,
2982    ) -> Select:
2983        """
2984        Append to or set the JOIN expressions.
2985
2986        Example:
2987            >>> Select().select("*").from_("tbl").join("tbl2", on="tbl1.y = tbl2.y").sql()
2988            'SELECT * FROM tbl JOIN tbl2 ON tbl1.y = tbl2.y'
2989
2990            >>> Select().select("1").from_("a").join("b", using=["x", "y", "z"]).sql()
2991            'SELECT 1 FROM a JOIN b USING (x, y, z)'
2992
2993            Use `join_type` to change the type of join:
2994
2995            >>> Select().select("*").from_("tbl").join("tbl2", on="tbl1.y = tbl2.y", join_type="left outer").sql()
2996            'SELECT * FROM tbl LEFT OUTER JOIN tbl2 ON tbl1.y = tbl2.y'
2997
2998        Args:
2999            expression: the SQL code string to parse.
3000                If an `Expression` instance is passed, it will be used as-is.
3001            on: optionally specify the join "on" criteria as a SQL string.
3002                If an `Expression` instance is passed, it will be used as-is.
3003            using: optionally specify the join "using" criteria as a SQL string.
3004                If an `Expression` instance is passed, it will be used as-is.
3005            append: if `True`, add to any existing expressions.
3006                Otherwise, this resets the expressions.
3007            join_type: if set, alter the parsed join type.
3008            join_alias: an optional alias for the joined source.
3009            dialect: the dialect used to parse the input expressions.
3010            copy: if `False`, modify this expression instance in-place.
3011            opts: other options to use to parse the input expressions.
3012
3013        Returns:
3014            Select: the modified expression.
3015        """
3016        parse_args: t.Dict[str, t.Any] = {"dialect": dialect, **opts}
3017
3018        try:
3019            expression = maybe_parse(expression, into=Join, prefix="JOIN", **parse_args)
3020        except ParseError:
3021            expression = maybe_parse(expression, into=(Join, Expression), **parse_args)
3022
3023        join = expression if isinstance(expression, Join) else Join(this=expression)
3024
3025        if isinstance(join.this, Select):
3026            join.this.replace(join.this.subquery())
3027
3028        if join_type:
3029            method: t.Optional[Token]
3030            side: t.Optional[Token]
3031            kind: t.Optional[Token]
3032
3033            method, side, kind = maybe_parse(join_type, into="JOIN_TYPE", **parse_args)  # type: ignore
3034
3035            if method:
3036                join.set("method", method.text)
3037            if side:
3038                join.set("side", side.text)
3039            if kind:
3040                join.set("kind", kind.text)
3041
3042        if on:
3043            on = and_(*ensure_list(on), dialect=dialect, copy=copy, **opts)
3044            join.set("on", on)
3045
3046        if using:
3047            join = _apply_list_builder(
3048                *ensure_list(using),
3049                instance=join,
3050                arg="using",
3051                append=append,
3052                copy=copy,
3053                into=Identifier,
3054                **opts,
3055            )
3056
3057        if join_alias:
3058            join.set("this", alias_(join.this, join_alias, table=True))
3059
3060        return _apply_list_builder(
3061            join,
3062            instance=self,
3063            arg="joins",
3064            append=append,
3065            copy=copy,
3066            **opts,
3067        )
3068
3069    def where(
3070        self,
3071        *expressions: t.Optional[ExpOrStr],
3072        append: bool = True,
3073        dialect: DialectType = None,
3074        copy: bool = True,
3075        **opts,
3076    ) -> Select:
3077        """
3078        Append to or set the WHERE expressions.
3079
3080        Example:
3081            >>> Select().select("x").from_("tbl").where("x = 'a' OR x < 'b'").sql()
3082            "SELECT x FROM tbl WHERE x = 'a' OR x < 'b'"
3083
3084        Args:
3085            *expressions: the SQL code strings to parse.
3086                If an `Expression` instance is passed, it will be used as-is.
3087                Multiple expressions are combined with an AND operator.
3088            append: if `True`, AND the new expressions to any existing expression.
3089                Otherwise, this resets the expression.
3090            dialect: the dialect used to parse the input expressions.
3091            copy: if `False`, modify this expression instance in-place.
3092            opts: other options to use to parse the input expressions.
3093
3094        Returns:
3095            Select: the modified expression.
3096        """
3097        return _apply_conjunction_builder(
3098            *expressions,
3099            instance=self,
3100            arg="where",
3101            append=append,
3102            into=Where,
3103            dialect=dialect,
3104            copy=copy,
3105            **opts,
3106        )
3107
3108    def having(
3109        self,
3110        *expressions: t.Optional[ExpOrStr],
3111        append: bool = True,
3112        dialect: DialectType = None,
3113        copy: bool = True,
3114        **opts,
3115    ) -> Select:
3116        """
3117        Append to or set the HAVING expressions.
3118
3119        Example:
3120            >>> Select().select("x", "COUNT(y)").from_("tbl").group_by("x").having("COUNT(y) > 3").sql()
3121            'SELECT x, COUNT(y) FROM tbl GROUP BY x HAVING COUNT(y) > 3'
3122
3123        Args:
3124            *expressions: the SQL code strings to parse.
3125                If an `Expression` instance is passed, it will be used as-is.
3126                Multiple expressions are combined with an AND operator.
3127            append: if `True`, AND the new expressions to any existing expression.
3128                Otherwise, this resets the expression.
3129            dialect: the dialect used to parse the input expressions.
3130            copy: if `False`, modify this expression instance in-place.
3131            opts: other options to use to parse the input expressions.
3132
3133        Returns:
3134            The modified Select expression.
3135        """
3136        return _apply_conjunction_builder(
3137            *expressions,
3138            instance=self,
3139            arg="having",
3140            append=append,
3141            into=Having,
3142            dialect=dialect,
3143            copy=copy,
3144            **opts,
3145        )
3146
3147    def window(
3148        self,
3149        *expressions: t.Optional[ExpOrStr],
3150        append: bool = True,
3151        dialect: DialectType = None,
3152        copy: bool = True,
3153        **opts,
3154    ) -> Select:
3155        return _apply_list_builder(
3156            *expressions,
3157            instance=self,
3158            arg="windows",
3159            append=append,
3160            into=Window,
3161            dialect=dialect,
3162            copy=copy,
3163            **opts,
3164        )
3165
3166    def qualify(
3167        self,
3168        *expressions: t.Optional[ExpOrStr],
3169        append: bool = True,
3170        dialect: DialectType = None,
3171        copy: bool = True,
3172        **opts,
3173    ) -> Select:
3174        return _apply_conjunction_builder(
3175            *expressions,
3176            instance=self,
3177            arg="qualify",
3178            append=append,
3179            into=Qualify,
3180            dialect=dialect,
3181            copy=copy,
3182            **opts,
3183        )
3184
3185    def distinct(
3186        self, *ons: t.Optional[ExpOrStr], distinct: bool = True, copy: bool = True
3187    ) -> Select:
3188        """
3189        Set the OFFSET expression.
3190
3191        Example:
3192            >>> Select().from_("tbl").select("x").distinct().sql()
3193            'SELECT DISTINCT x FROM tbl'
3194
3195        Args:
3196            ons: the expressions to distinct on
3197            distinct: whether the Select should be distinct
3198            copy: if `False`, modify this expression instance in-place.
3199
3200        Returns:
3201            Select: the modified expression.
3202        """
3203        instance = maybe_copy(self, copy)
3204        on = Tuple(expressions=[maybe_parse(on, copy=copy) for on in ons if on]) if ons else None
3205        instance.set("distinct", Distinct(on=on) if distinct else None)
3206        return instance
3207
3208    def ctas(
3209        self,
3210        table: ExpOrStr,
3211        properties: t.Optional[t.Dict] = None,
3212        dialect: DialectType = None,
3213        copy: bool = True,
3214        **opts,
3215    ) -> Create:
3216        """
3217        Convert this expression to a CREATE TABLE AS statement.
3218
3219        Example:
3220            >>> Select().select("*").from_("tbl").ctas("x").sql()
3221            'CREATE TABLE x AS SELECT * FROM tbl'
3222
3223        Args:
3224            table: the SQL code string to parse as the table name.
3225                If another `Expression` instance is passed, it will be used as-is.
3226            properties: an optional mapping of table properties
3227            dialect: the dialect used to parse the input table.
3228            copy: if `False`, modify this expression instance in-place.
3229            opts: other options to use to parse the input table.
3230
3231        Returns:
3232            The new Create expression.
3233        """
3234        instance = maybe_copy(self, copy)
3235        table_expression = maybe_parse(
3236            table,
3237            into=Table,
3238            dialect=dialect,
3239            **opts,
3240        )
3241        properties_expression = None
3242        if properties:
3243            properties_expression = Properties.from_dict(properties)
3244
3245        return Create(
3246            this=table_expression,
3247            kind="table",
3248            expression=instance,
3249            properties=properties_expression,
3250        )
3251
3252    def lock(self, update: bool = True, copy: bool = True) -> Select:
3253        """
3254        Set the locking read mode for this expression.
3255
3256        Examples:
3257            >>> Select().select("x").from_("tbl").where("x = 'a'").lock().sql("mysql")
3258            "SELECT x FROM tbl WHERE x = 'a' FOR UPDATE"
3259
3260            >>> Select().select("x").from_("tbl").where("x = 'a'").lock(update=False).sql("mysql")
3261            "SELECT x FROM tbl WHERE x = 'a' FOR SHARE"
3262
3263        Args:
3264            update: if `True`, the locking type will be `FOR UPDATE`, else it will be `FOR SHARE`.
3265            copy: if `False`, modify this expression instance in-place.
3266
3267        Returns:
3268            The modified expression.
3269        """
3270        inst = maybe_copy(self, copy)
3271        inst.set("locks", [Lock(update=update)])
3272
3273        return inst
3274
3275    def hint(self, *hints: ExpOrStr, dialect: DialectType = None, copy: bool = True) -> Select:
3276        """
3277        Set hints for this expression.
3278
3279        Examples:
3280            >>> Select().select("x").from_("tbl").hint("BROADCAST(y)").sql(dialect="spark")
3281            'SELECT /*+ BROADCAST(y) */ x FROM tbl'
3282
3283        Args:
3284            hints: The SQL code strings to parse as the hints.
3285                If an `Expression` instance is passed, it will be used as-is.
3286            dialect: The dialect used to parse the hints.
3287            copy: If `False`, modify this expression instance in-place.
3288
3289        Returns:
3290            The modified expression.
3291        """
3292        inst = maybe_copy(self, copy)
3293        inst.set(
3294            "hint", Hint(expressions=[maybe_parse(h, copy=copy, dialect=dialect) for h in hints])
3295        )
3296
3297        return inst
3298
3299    @property
3300    def named_selects(self) -> t.List[str]:
3301        return [e.output_name for e in self.expressions if e.alias_or_name]
3302
3303    @property
3304    def is_star(self) -> bool:
3305        return any(expression.is_star for expression in self.expressions)
3306
3307    @property
3308    def selects(self) -> t.List[Expression]:
3309        return self.expressions
3310
3311
3312class Subquery(DerivedTable, Unionable):
3313    arg_types = {
3314        "this": True,
3315        "alias": False,
3316        "with": False,
3317        **QUERY_MODIFIERS,
3318    }
3319
3320    def unnest(self):
3321        """
3322        Returns the first non subquery.
3323        """
3324        expression = self
3325        while isinstance(expression, Subquery):
3326            expression = expression.this
3327        return expression
3328
3329    def unwrap(self) -> Subquery:
3330        expression = self
3331        while expression.same_parent and expression.is_wrapper:
3332            expression = t.cast(Subquery, expression.parent)
3333        return expression
3334
3335    @property
3336    def is_wrapper(self) -> bool:
3337        """
3338        Whether this Subquery acts as a simple wrapper around another expression.
3339
3340        SELECT * FROM (((SELECT * FROM t)))
3341                      ^
3342                      This corresponds to a "wrapper" Subquery node
3343        """
3344        return all(v is None for k, v in self.args.items() if k != "this")
3345
3346    @property
3347    def is_star(self) -> bool:
3348        return self.this.is_star
3349
3350    @property
3351    def output_name(self) -> str:
3352        return self.alias
3353
3354
3355class TableSample(Expression):
3356    arg_types = {
3357        "this": False,
3358        "expressions": False,
3359        "method": False,
3360        "bucket_numerator": False,
3361        "bucket_denominator": False,
3362        "bucket_field": False,
3363        "percent": False,
3364        "rows": False,
3365        "size": False,
3366        "seed": False,
3367        "kind": False,
3368    }
3369
3370
3371class Tag(Expression):
3372    """Tags are used for generating arbitrary sql like SELECT <span>x</span>."""
3373
3374    arg_types = {
3375        "this": False,
3376        "prefix": False,
3377        "postfix": False,
3378    }
3379
3380
3381# Represents both the standard SQL PIVOT operator and DuckDB's "simplified" PIVOT syntax
3382# https://duckdb.org/docs/sql/statements/pivot
3383class Pivot(Expression):
3384    arg_types = {
3385        "this": False,
3386        "alias": False,
3387        "expressions": True,
3388        "field": False,
3389        "unpivot": False,
3390        "using": False,
3391        "group": False,
3392        "columns": False,
3393        "include_nulls": False,
3394    }
3395
3396
3397class Window(Condition):
3398    arg_types = {
3399        "this": True,
3400        "partition_by": False,
3401        "order": False,
3402        "spec": False,
3403        "alias": False,
3404        "over": False,
3405        "first": False,
3406    }
3407
3408
3409class WindowSpec(Expression):
3410    arg_types = {
3411        "kind": False,
3412        "start": False,
3413        "start_side": False,
3414        "end": False,
3415        "end_side": False,
3416    }
3417
3418
3419class Where(Expression):
3420    pass
3421
3422
3423class Star(Expression):
3424    arg_types = {"except": False, "replace": False}
3425
3426    @property
3427    def name(self) -> str:
3428        return "*"
3429
3430    @property
3431    def output_name(self) -> str:
3432        return self.name
3433
3434
3435class Parameter(Condition):
3436    arg_types = {"this": True, "wrapped": False}
3437
3438
3439class SessionParameter(Condition):
3440    arg_types = {"this": True, "kind": False}
3441
3442
3443class Placeholder(Condition):
3444    arg_types = {"this": False, "kind": False}
3445
3446
3447class Null(Condition):
3448    arg_types: t.Dict[str, t.Any] = {}
3449
3450    @property
3451    def name(self) -> str:
3452        return "NULL"
3453
3454
3455class Boolean(Condition):
3456    pass
3457
3458
3459class DataTypeParam(Expression):
3460    arg_types = {"this": True, "expression": False}
3461
3462
3463class DataType(Expression):
3464    arg_types = {
3465        "this": True,
3466        "expressions": False,
3467        "nested": False,
3468        "values": False,
3469        "prefix": False,
3470        "kind": False,
3471    }
3472
3473    class Type(AutoName):
3474        ARRAY = auto()
3475        BIGDECIMAL = auto()
3476        BIGINT = auto()
3477        BIGSERIAL = auto()
3478        BINARY = auto()
3479        BIT = auto()
3480        BOOLEAN = auto()
3481        CHAR = auto()
3482        DATE = auto()
3483        DATEMULTIRANGE = auto()
3484        DATERANGE = auto()
3485        DATETIME = auto()
3486        DATETIME64 = auto()
3487        DECIMAL = auto()
3488        DOUBLE = auto()
3489        ENUM = auto()
3490        ENUM8 = auto()
3491        ENUM16 = auto()
3492        FIXEDSTRING = auto()
3493        FLOAT = auto()
3494        GEOGRAPHY = auto()
3495        GEOMETRY = auto()
3496        HLLSKETCH = auto()
3497        HSTORE = auto()
3498        IMAGE = auto()
3499        INET = auto()
3500        INT = auto()
3501        INT128 = auto()
3502        INT256 = auto()
3503        INT4MULTIRANGE = auto()
3504        INT4RANGE = auto()
3505        INT8MULTIRANGE = auto()
3506        INT8RANGE = auto()
3507        INTERVAL = auto()
3508        IPADDRESS = auto()
3509        IPPREFIX = auto()
3510        JSON = auto()
3511        JSONB = auto()
3512        LONGBLOB = auto()
3513        LONGTEXT = auto()
3514        LOWCARDINALITY = auto()
3515        MAP = auto()
3516        MEDIUMBLOB = auto()
3517        MEDIUMINT = auto()
3518        MEDIUMTEXT = auto()
3519        MONEY = auto()
3520        NCHAR = auto()
3521        NESTED = auto()
3522        NULL = auto()
3523        NULLABLE = auto()
3524        NUMMULTIRANGE = auto()
3525        NUMRANGE = auto()
3526        NVARCHAR = auto()
3527        OBJECT = auto()
3528        ROWVERSION = auto()
3529        SERIAL = auto()
3530        SET = auto()
3531        SMALLINT = auto()
3532        SMALLMONEY = auto()
3533        SMALLSERIAL = auto()
3534        STRUCT = auto()
3535        SUPER = auto()
3536        TEXT = auto()
3537        TINYBLOB = auto()
3538        TINYTEXT = auto()
3539        TIME = auto()
3540        TIMETZ = auto()
3541        TIMESTAMP = auto()
3542        TIMESTAMPLTZ = auto()
3543        TIMESTAMPTZ = auto()
3544        TINYINT = auto()
3545        TSMULTIRANGE = auto()
3546        TSRANGE = auto()
3547        TSTZMULTIRANGE = auto()
3548        TSTZRANGE = auto()
3549        UBIGINT = auto()
3550        UINT = auto()
3551        UINT128 = auto()
3552        UINT256 = auto()
3553        UMEDIUMINT = auto()
3554        UNIQUEIDENTIFIER = auto()
3555        UNKNOWN = auto()  # Sentinel value, useful for type annotation
3556        USERDEFINED = "USER-DEFINED"
3557        USMALLINT = auto()
3558        UTINYINT = auto()
3559        UUID = auto()
3560        VARBINARY = auto()
3561        VARCHAR = auto()
3562        VARIANT = auto()
3563        XML = auto()
3564        YEAR = auto()
3565
3566    TEXT_TYPES = {
3567        Type.CHAR,
3568        Type.NCHAR,
3569        Type.VARCHAR,
3570        Type.NVARCHAR,
3571        Type.TEXT,
3572    }
3573
3574    INTEGER_TYPES = {
3575        Type.INT,
3576        Type.TINYINT,
3577        Type.SMALLINT,
3578        Type.BIGINT,
3579        Type.INT128,
3580        Type.INT256,
3581    }
3582
3583    FLOAT_TYPES = {
3584        Type.FLOAT,
3585        Type.DOUBLE,
3586    }
3587
3588    NUMERIC_TYPES = {
3589        *INTEGER_TYPES,
3590        *FLOAT_TYPES,
3591    }
3592
3593    TEMPORAL_TYPES = {
3594        Type.TIME,
3595        Type.TIMETZ,
3596        Type.TIMESTAMP,
3597        Type.TIMESTAMPTZ,
3598        Type.TIMESTAMPLTZ,
3599        Type.DATE,
3600        Type.DATETIME,
3601        Type.DATETIME64,
3602    }
3603
3604    @classmethod
3605    def build(
3606        cls,
3607        dtype: str | DataType | DataType.Type,
3608        dialect: DialectType = None,
3609        udt: bool = False,
3610        **kwargs,
3611    ) -> DataType:
3612        """
3613        Constructs a DataType object.
3614
3615        Args:
3616            dtype: the data type of interest.
3617            dialect: the dialect to use for parsing `dtype`, in case it's a string.
3618            udt: when set to True, `dtype` will be used as-is if it can't be parsed into a
3619                DataType, thus creating a user-defined type.
3620            kawrgs: additional arguments to pass in the constructor of DataType.
3621
3622        Returns:
3623            The constructed DataType object.
3624        """
3625        from sqlglot import parse_one
3626
3627        if isinstance(dtype, str):
3628            if dtype.upper() == "UNKNOWN":
3629                return DataType(this=DataType.Type.UNKNOWN, **kwargs)
3630
3631            try:
3632                data_type_exp = parse_one(dtype, read=dialect, into=DataType)
3633            except ParseError:
3634                if udt:
3635                    return DataType(this=DataType.Type.USERDEFINED, kind=dtype, **kwargs)
3636                raise
3637        elif isinstance(dtype, DataType.Type):
3638            data_type_exp = DataType(this=dtype)
3639        elif isinstance(dtype, DataType):
3640            return dtype
3641        else:
3642            raise ValueError(f"Invalid data type: {type(dtype)}. Expected str or DataType.Type")
3643
3644        return DataType(**{**data_type_exp.args, **kwargs})
3645
3646    def is_type(self, *dtypes: str | DataType | DataType.Type) -> bool:
3647        """
3648        Checks whether this DataType matches one of the provided data types. Nested types or precision
3649        will be compared using "structural equivalence" semantics, so e.g. array<int> != array<float>.
3650
3651        Args:
3652            dtypes: the data types to compare this DataType to.
3653
3654        Returns:
3655            True, if and only if there is a type in `dtypes` which is equal to this DataType.
3656        """
3657        for dtype in dtypes:
3658            other = DataType.build(dtype, udt=True)
3659
3660            if (
3661                other.expressions
3662                or self.this == DataType.Type.USERDEFINED
3663                or other.this == DataType.Type.USERDEFINED
3664            ):
3665                matches = self == other
3666            else:
3667                matches = self.this == other.this
3668
3669            if matches:
3670                return True
3671        return False
3672
3673
3674# https://www.postgresql.org/docs/15/datatype-pseudo.html
3675class PseudoType(Expression):
3676    pass
3677
3678
3679# https://www.postgresql.org/docs/15/datatype-oid.html
3680class ObjectIdentifier(Expression):
3681    pass
3682
3683
3684# WHERE x <OP> EXISTS|ALL|ANY|SOME(SELECT ...)
3685class SubqueryPredicate(Predicate):
3686    pass
3687
3688
3689class All(SubqueryPredicate):
3690    pass
3691
3692
3693class Any(SubqueryPredicate):
3694    pass
3695
3696
3697class Exists(SubqueryPredicate):
3698    pass
3699
3700
3701# Commands to interact with the databases or engines. For most of the command
3702# expressions we parse whatever comes after the command's name as a string.
3703class Command(Expression):
3704    arg_types = {"this": True, "expression": False}
3705
3706
3707class Transaction(Expression):
3708    arg_types = {"this": False, "modes": False, "mark": False}
3709
3710
3711class Commit(Expression):
3712    arg_types = {"chain": False, "this": False, "durability": False}
3713
3714
3715class Rollback(Expression):
3716    arg_types = {"savepoint": False, "this": False}
3717
3718
3719class AlterTable(Expression):
3720    arg_types = {"this": True, "actions": True, "exists": False, "only": False}
3721
3722
3723class AddConstraint(Expression):
3724    arg_types = {"this": False, "expression": False, "enforced": False}
3725
3726
3727class DropPartition(Expression):
3728    arg_types = {"expressions": True, "exists": False}
3729
3730
3731# Binary expressions like (ADD a b)
3732class Binary(Condition):
3733    arg_types = {"this": True, "expression": True}
3734
3735    @property
3736    def left(self):
3737        return self.this
3738
3739    @property
3740    def right(self):
3741        return self.expression
3742
3743
3744class Add(Binary):
3745    pass
3746
3747
3748class Connector(Binary):
3749    pass
3750
3751
3752class And(Connector):
3753    pass
3754
3755
3756class Or(Connector):
3757    pass
3758
3759
3760class BitwiseAnd(Binary):
3761    pass
3762
3763
3764class BitwiseLeftShift(Binary):
3765    pass
3766
3767
3768class BitwiseOr(Binary):
3769    pass
3770
3771
3772class BitwiseRightShift(Binary):
3773    pass
3774
3775
3776class BitwiseXor(Binary):
3777    pass
3778
3779
3780class Div(Binary):
3781    pass
3782
3783
3784class Overlaps(Binary):
3785    pass
3786
3787
3788class Dot(Binary):
3789    @property
3790    def name(self) -> str:
3791        return self.expression.name
3792
3793    @property
3794    def output_name(self) -> str:
3795        return self.name
3796
3797    @classmethod
3798    def build(self, expressions: t.Sequence[Expression]) -> Dot:
3799        """Build a Dot object with a sequence of expressions."""
3800        if len(expressions) < 2:
3801            raise ValueError(f"Dot requires >= 2 expressions.")
3802
3803        return t.cast(Dot, reduce(lambda x, y: Dot(this=x, expression=y), expressions))
3804
3805
3806class DPipe(Binary):
3807    pass
3808
3809
3810class SafeDPipe(DPipe):
3811    pass
3812
3813
3814class EQ(Binary, Predicate):
3815    pass
3816
3817
3818class NullSafeEQ(Binary, Predicate):
3819    pass
3820
3821
3822class NullSafeNEQ(Binary, Predicate):
3823    pass
3824
3825
3826class Distance(Binary):
3827    pass
3828
3829
3830class Escape(Binary):
3831    pass
3832
3833
3834class Glob(Binary, Predicate):
3835    pass
3836
3837
3838class GT(Binary, Predicate):
3839    pass
3840
3841
3842class GTE(Binary, Predicate):
3843    pass
3844
3845
3846class ILike(Binary, Predicate):
3847    pass
3848
3849
3850class ILikeAny(Binary, Predicate):
3851    pass
3852
3853
3854class IntDiv(Binary):
3855    pass
3856
3857
3858class Is(Binary, Predicate):
3859    pass
3860
3861
3862class Kwarg(Binary):
3863    """Kwarg in special functions like func(kwarg => y)."""
3864
3865
3866class Like(Binary, Predicate):
3867    pass
3868
3869
3870class LikeAny(Binary, Predicate):
3871    pass
3872
3873
3874class LT(Binary, Predicate):
3875    pass
3876
3877
3878class LTE(Binary, Predicate):
3879    pass
3880
3881
3882class Mod(Binary):
3883    pass
3884
3885
3886class Mul(Binary):
3887    pass
3888
3889
3890class NEQ(Binary, Predicate):
3891    pass
3892
3893
3894class SimilarTo(Binary, Predicate):
3895    pass
3896
3897
3898class Slice(Binary):
3899    arg_types = {"this": False, "expression": False}
3900
3901
3902class Sub(Binary):
3903    pass
3904
3905
3906class ArrayOverlaps(Binary):
3907    pass
3908
3909
3910# Unary Expressions
3911# (NOT a)
3912class Unary(Condition):
3913    pass
3914
3915
3916class BitwiseNot(Unary):
3917    pass
3918
3919
3920class Not(Unary):
3921    pass
3922
3923
3924class Paren(Unary):
3925    arg_types = {"this": True, "with": False}
3926
3927    @property
3928    def output_name(self) -> str:
3929        return self.this.name
3930
3931
3932class Neg(Unary):
3933    pass
3934
3935
3936class Alias(Expression):
3937    arg_types = {"this": True, "alias": False}
3938
3939    @property
3940    def output_name(self) -> str:
3941        return self.alias
3942
3943
3944class Aliases(Expression):
3945    arg_types = {"this": True, "expressions": True}
3946
3947    @property
3948    def aliases(self):
3949        return self.expressions
3950
3951
3952class AtTimeZone(Expression):
3953    arg_types = {"this": True, "zone": True}
3954
3955
3956class Between(Predicate):
3957    arg_types = {"this": True, "low": True, "high": True}
3958
3959
3960class Bracket(Condition):
3961    arg_types = {"this": True, "expressions": True}
3962
3963    @property
3964    def output_name(self) -> str:
3965        if len(self.expressions) == 1:
3966            return self.expressions[0].output_name
3967
3968        return super().output_name
3969
3970
3971class SafeBracket(Bracket):
3972    """Represents array lookup where OOB index yields NULL instead of causing a failure."""
3973
3974
3975class Distinct(Expression):
3976    arg_types = {"expressions": False, "on": False}
3977
3978
3979class In(Predicate):
3980    arg_types = {
3981        "this": True,
3982        "expressions": False,
3983        "query": False,
3984        "unnest": False,
3985        "field": False,
3986        "is_global": False,
3987    }
3988
3989
3990class TimeUnit(Expression):
3991    """Automatically converts unit arg into a var."""
3992
3993    arg_types = {"unit": False}
3994
3995    def __init__(self, **args):
3996        unit = args.get("unit")
3997        if isinstance(unit, (Column, Literal)):
3998            args["unit"] = Var(this=unit.name)
3999        elif isinstance(unit, Week):
4000            unit.set("this", Var(this=unit.this.name))
4001
4002        super().__init__(**args)
4003
4004
4005# https://www.oracletutorial.com/oracle-basics/oracle-interval/
4006# https://trino.io/docs/current/language/types.html#interval-day-to-second
4007# https://docs.databricks.com/en/sql/language-manual/data-types/interval-type.html
4008class IntervalSpan(Expression):
4009    arg_types = {"this": True, "expression": True}
4010
4011
4012class Interval(TimeUnit):
4013    arg_types = {"this": False, "unit": False}
4014
4015    @property
4016    def unit(self) -> t.Optional[Var]:
4017        return self.args.get("unit")
4018
4019
4020class IgnoreNulls(Expression):
4021    pass
4022
4023
4024class RespectNulls(Expression):
4025    pass
4026
4027
4028# Functions
4029class Func(Condition):
4030    """
4031    The base class for all function expressions.
4032
4033    Attributes:
4034        is_var_len_args (bool): if set to True the last argument defined in arg_types will be
4035            treated as a variable length argument and the argument's value will be stored as a list.
4036        _sql_names (list): determines the SQL name (1st item in the list) and aliases (subsequent items)
4037            for this function expression. These values are used to map this node to a name during parsing
4038            as well as to provide the function's name during SQL string generation. By default the SQL
4039            name is set to the expression's class name transformed to snake case.
4040    """
4041
4042    is_var_len_args = False
4043
4044    @classmethod
4045    def from_arg_list(cls, args):
4046        if cls.is_var_len_args:
4047            all_arg_keys = list(cls.arg_types)
4048            # If this function supports variable length argument treat the last argument as such.
4049            non_var_len_arg_keys = all_arg_keys[:-1] if cls.is_var_len_args else all_arg_keys
4050            num_non_var = len(non_var_len_arg_keys)
4051
4052            args_dict = {arg_key: arg for arg, arg_key in zip(args, non_var_len_arg_keys)}
4053            args_dict[all_arg_keys[-1]] = args[num_non_var:]
4054        else:
4055            args_dict = {arg_key: arg for arg, arg_key in zip(args, cls.arg_types)}
4056
4057        return cls(**args_dict)
4058
4059    @classmethod
4060    def sql_names(cls):
4061        if cls is Func:
4062            raise NotImplementedError(
4063                "SQL name is only supported by concrete function implementations"
4064            )
4065        if "_sql_names" not in cls.__dict__:
4066            cls._sql_names = [camel_to_snake_case(cls.__name__)]
4067        return cls._sql_names
4068
4069    @classmethod
4070    def sql_name(cls):
4071        return cls.sql_names()[0]
4072
4073    @classmethod
4074    def default_parser_mappings(cls):
4075        return {name: cls.from_arg_list for name in cls.sql_names()}
4076
4077
4078class AggFunc(Func):
4079    pass
4080
4081
4082class ParameterizedAgg(AggFunc):
4083    arg_types = {"this": True, "expressions": True, "params": True}
4084
4085
4086class Abs(Func):
4087    pass
4088
4089
4090# https://spark.apache.org/docs/latest/api/sql/index.html#transform
4091class Transform(Func):
4092    arg_types = {"this": True, "expression": True}
4093
4094
4095class Anonymous(Func):
4096    arg_types = {"this": True, "expressions": False}
4097    is_var_len_args = True
4098
4099
4100# https://docs.snowflake.com/en/sql-reference/functions/hll
4101# https://docs.aws.amazon.com/redshift/latest/dg/r_HLL_function.html
4102class Hll(AggFunc):
4103    arg_types = {"this": True, "expressions": False}
4104    is_var_len_args = True
4105
4106
4107class ApproxDistinct(AggFunc):
4108    arg_types = {"this": True, "accuracy": False}
4109    _sql_names = ["APPROX_DISTINCT", "APPROX_COUNT_DISTINCT"]
4110
4111
4112class Array(Func):
4113    arg_types = {"expressions": False}
4114    is_var_len_args = True
4115
4116
4117# https://docs.snowflake.com/en/sql-reference/functions/to_char
4118class ToChar(Func):
4119    arg_types = {"this": True, "format": False}
4120
4121
4122class GenerateSeries(Func):
4123    arg_types = {"start": True, "end": True, "step": False}
4124
4125
4126class ArrayAgg(AggFunc):
4127    pass
4128
4129
4130class ArrayAll(Func):
4131    arg_types = {"this": True, "expression": True}
4132
4133
4134class ArrayAny(Func):
4135    arg_types = {"this": True, "expression": True}
4136
4137
4138class ArrayConcat(Func):
4139    _sql_names = ["ARRAY_CONCAT", "ARRAY_CAT"]
4140    arg_types = {"this": True, "expressions": False}
4141    is_var_len_args = True
4142
4143
4144class ArrayContains(Binary, Func):
4145    pass
4146
4147
4148class ArrayContained(Binary):
4149    pass
4150
4151
4152class ArrayFilter(Func):
4153    arg_types = {"this": True, "expression": True}
4154    _sql_names = ["FILTER", "ARRAY_FILTER"]
4155
4156
4157class ArrayJoin(Func):
4158    arg_types = {"this": True, "expression": True, "null": False}
4159
4160
4161class ArraySize(Func):
4162    arg_types = {"this": True, "expression": False}
4163
4164
4165class ArraySort(Func):
4166    arg_types = {"this": True, "expression": False}
4167
4168
4169class ArraySum(Func):
4170    pass
4171
4172
4173class ArrayUnionAgg(AggFunc):
4174    pass
4175
4176
4177class Avg(AggFunc):
4178    pass
4179
4180
4181class AnyValue(AggFunc):
4182    arg_types = {"this": True, "having": False, "max": False, "ignore_nulls": False}
4183
4184
4185class First(Func):
4186    arg_types = {"this": True, "ignore_nulls": False}
4187
4188
4189class Last(Func):
4190    arg_types = {"this": True, "ignore_nulls": False}
4191
4192
4193class Case(Func):
4194    arg_types = {"this": False, "ifs": True, "default": False}
4195
4196    def when(self, condition: ExpOrStr, then: ExpOrStr, copy: bool = True, **opts) -> Case:
4197        instance = maybe_copy(self, copy)
4198        instance.append(
4199            "ifs",
4200            If(
4201                this=maybe_parse(condition, copy=copy, **opts),
4202                true=maybe_parse(then, copy=copy, **opts),
4203            ),
4204        )
4205        return instance
4206
4207    def else_(self, condition: ExpOrStr, copy: bool = True, **opts) -> Case:
4208        instance = maybe_copy(self, copy)
4209        instance.set("default", maybe_parse(condition, copy=copy, **opts))
4210        return instance
4211
4212
4213class Cast(Func):
4214    arg_types = {"this": True, "to": True, "format": False}
4215
4216    @property
4217    def name(self) -> str:
4218        return self.this.name
4219
4220    @property
4221    def to(self) -> DataType:
4222        return self.args["to"]
4223
4224    @property
4225    def output_name(self) -> str:
4226        return self.name
4227
4228    def is_type(self, *dtypes: str | DataType | DataType.Type) -> bool:
4229        """
4230        Checks whether this Cast's DataType matches one of the provided data types. Nested types
4231        like arrays or structs will be compared using "structural equivalence" semantics, so e.g.
4232        array<int> != array<float>.
4233
4234        Args:
4235            dtypes: the data types to compare this Cast's DataType to.
4236
4237        Returns:
4238            True, if and only if there is a type in `dtypes` which is equal to this Cast's DataType.
4239        """
4240        return self.to.is_type(*dtypes)
4241
4242
4243class TryCast(Cast):
4244    pass
4245
4246
4247class CastToStrType(Func):
4248    arg_types = {"this": True, "to": True}
4249
4250
4251class Collate(Binary):
4252    pass
4253
4254
4255class Ceil(Func):
4256    arg_types = {"this": True, "decimals": False}
4257    _sql_names = ["CEIL", "CEILING"]
4258
4259
4260class Coalesce(Func):
4261    arg_types = {"this": True, "expressions": False}
4262    is_var_len_args = True
4263    _sql_names = ["COALESCE", "IFNULL", "NVL"]
4264
4265
4266class Concat(Func):
4267    arg_types = {"expressions": True}
4268    is_var_len_args = True
4269
4270
4271class SafeConcat(Concat):
4272    pass
4273
4274
4275class ConcatWs(Concat):
4276    _sql_names = ["CONCAT_WS"]
4277
4278
4279class Count(AggFunc):
4280    arg_types = {"this": False, "expressions": False}
4281    is_var_len_args = True
4282
4283
4284class CountIf(AggFunc):
4285    pass
4286
4287
4288class CurrentDate(Func):
4289    arg_types = {"this": False}
4290
4291
4292class CurrentDatetime(Func):
4293    arg_types = {"this": False}
4294
4295
4296class CurrentTime(Func):
4297    arg_types = {"this": False}
4298
4299
4300class CurrentTimestamp(Func):
4301    arg_types = {"this": False}
4302
4303
4304class CurrentUser(Func):
4305    arg_types = {"this": False}
4306
4307
4308class DateAdd(Func, TimeUnit):
4309    arg_types = {"this": True, "expression": True, "unit": False}
4310
4311
4312class DateSub(Func, TimeUnit):
4313    arg_types = {"this": True, "expression": True, "unit": False}
4314
4315
4316class DateDiff(Func, TimeUnit):
4317    _sql_names = ["DATEDIFF", "DATE_DIFF"]
4318    arg_types = {"this": True, "expression": True, "unit": False}
4319
4320
4321class DateTrunc(Func):
4322    arg_types = {"unit": True, "this": True, "zone": False}
4323
4324
4325class DatetimeAdd(Func, TimeUnit):
4326    arg_types = {"this": True, "expression": True, "unit": False}
4327
4328
4329class DatetimeSub(Func, TimeUnit):
4330    arg_types = {"this": True, "expression": True, "unit": False}
4331
4332
4333class DatetimeDiff(Func, TimeUnit):
4334    arg_types = {"this": True, "expression": True, "unit": False}
4335
4336
4337class DatetimeTrunc(Func, TimeUnit):
4338    arg_types = {"this": True, "unit": True, "zone": False}
4339
4340
4341class DayOfWeek(Func):
4342    _sql_names = ["DAY_OF_WEEK", "DAYOFWEEK"]
4343
4344
4345class DayOfMonth(Func):
4346    _sql_names = ["DAY_OF_MONTH", "DAYOFMONTH"]
4347
4348
4349class DayOfYear(Func):
4350    _sql_names = ["DAY_OF_YEAR", "DAYOFYEAR"]
4351
4352
4353class WeekOfYear(Func):
4354    _sql_names = ["WEEK_OF_YEAR", "WEEKOFYEAR"]
4355
4356
4357class MonthsBetween(Func):
4358    arg_types = {"this": True, "expression": True, "roundoff": False}
4359
4360
4361class LastDateOfMonth(Func):
4362    pass
4363
4364
4365class Extract(Func):
4366    arg_types = {"this": True, "expression": True}
4367
4368
4369class TimestampAdd(Func, TimeUnit):
4370    arg_types = {"this": True, "expression": True, "unit": False}
4371
4372
4373class TimestampSub(Func, TimeUnit):
4374    arg_types = {"this": True, "expression": True, "unit": False}
4375
4376
4377class TimestampDiff(Func, TimeUnit):
4378    arg_types = {"this": True, "expression": True, "unit": False}
4379
4380
4381class TimestampTrunc(Func, TimeUnit):
4382    arg_types = {"this": True, "unit": True, "zone": False}
4383
4384
4385class TimeAdd(Func, TimeUnit):
4386    arg_types = {"this": True, "expression": True, "unit": False}
4387
4388
4389class TimeSub(Func, TimeUnit):
4390    arg_types = {"this": True, "expression": True, "unit": False}
4391
4392
4393class TimeDiff(Func, TimeUnit):
4394    arg_types = {"this": True, "expression": True, "unit": False}
4395
4396
4397class TimeTrunc(Func, TimeUnit):
4398    arg_types = {"this": True, "unit": True, "zone": False}
4399
4400
4401class DateFromParts(Func):
4402    _sql_names = ["DATEFROMPARTS"]
4403    arg_types = {"year": True, "month": True, "day": True}
4404
4405
4406class DateStrToDate(Func):
4407    pass
4408
4409
4410class DateToDateStr(Func):
4411    pass
4412
4413
4414class DateToDi(Func):
4415    pass
4416
4417
4418# https://cloud.google.com/bigquery/docs/reference/standard-sql/date_functions#date
4419class Date(Func):
4420    arg_types = {"this": True, "zone": False}
4421
4422
4423class Day(Func):
4424    pass
4425
4426
4427class Decode(Func):
4428    arg_types = {"this": True, "charset": True, "replace": False}
4429
4430
4431class DiToDate(Func):
4432    pass
4433
4434
4435class Encode(Func):
4436    arg_types = {"this": True, "charset": True}
4437
4438
4439class Exp(Func):
4440    pass
4441
4442
4443class Explode(Func):
4444    pass
4445
4446
4447class Floor(Func):
4448    arg_types = {"this": True, "decimals": False}
4449
4450
4451class FromBase64(Func):
4452    pass
4453
4454
4455class ToBase64(Func):
4456    pass
4457
4458
4459class Greatest(Func):
4460    arg_types = {"this": True, "expressions": False}
4461    is_var_len_args = True
4462
4463
4464class GroupConcat(AggFunc):
4465    arg_types = {"this": True, "separator": False}
4466
4467
4468class Hex(Func):
4469    pass
4470
4471
4472class Xor(Connector, Func):
4473    arg_types = {"this": False, "expression": False, "expressions": False}
4474
4475
4476class If(Func):
4477    arg_types = {"this": True, "true": True, "false": False}
4478
4479
4480class Initcap(Func):
4481    arg_types = {"this": True, "expression": False}
4482
4483
4484class IsNan(Func):
4485    _sql_names = ["IS_NAN", "ISNAN"]
4486
4487
4488class FormatJson(Expression):
4489    pass
4490
4491
4492class JSONKeyValue(Expression):
4493    arg_types = {"this": True, "expression": True}
4494
4495
4496class JSONObject(Func):
4497    arg_types = {
4498        "expressions": False,
4499        "null_handling": False,
4500        "unique_keys": False,
4501        "return_type": False,
4502        "encoding": False,
4503    }
4504
4505
4506# https://docs.oracle.com/en/database/oracle/oracle-database/19/sqlrf/JSON_ARRAY.html
4507class JSONArray(Func):
4508    arg_types = {
4509        "expressions": True,
4510        "null_handling": False,
4511        "return_type": False,
4512        "strict": False,
4513    }
4514
4515
4516# https://docs.oracle.com/en/database/oracle/oracle-database/19/sqlrf/JSON_ARRAYAGG.html
4517class JSONArrayAgg(Func):
4518    arg_types = {
4519        "this": True,
4520        "order": False,
4521        "null_handling": False,
4522        "return_type": False,
4523        "strict": False,
4524    }
4525
4526
4527# https://docs.oracle.com/en/database/oracle/oracle-database/19/sqlrf/JSON_TABLE.html
4528# Note: parsing of JSON column definitions is currently incomplete.
4529class JSONColumnDef(Expression):
4530    arg_types = {"this": True, "kind": False, "path": False}
4531
4532
4533# # https://docs.oracle.com/en/database/oracle/oracle-database/19/sqlrf/JSON_TABLE.html
4534class JSONTable(Func):
4535    arg_types = {
4536        "this": True,
4537        "expressions": True,
4538        "path": False,
4539        "error_handling": False,
4540        "empty_handling": False,
4541    }
4542
4543
4544class OpenJSONColumnDef(Expression):
4545    arg_types = {"this": True, "kind": True, "path": False, "as_json": False}
4546
4547
4548class OpenJSON(Func):
4549    arg_types = {"this": True, "path": False, "expressions": False}
4550
4551
4552class JSONBContains(Binary):
4553    _sql_names = ["JSONB_CONTAINS"]
4554
4555
4556class JSONExtract(Binary, Func):
4557    _sql_names = ["JSON_EXTRACT"]
4558
4559
4560class JSONExtractScalar(JSONExtract):
4561    _sql_names = ["JSON_EXTRACT_SCALAR"]
4562
4563
4564class JSONBExtract(JSONExtract):
4565    _sql_names = ["JSONB_EXTRACT"]
4566
4567
4568class JSONBExtractScalar(JSONExtract):
4569    _sql_names = ["JSONB_EXTRACT_SCALAR"]
4570
4571
4572class JSONFormat(Func):
4573    arg_types = {"this": False, "options": False}
4574    _sql_names = ["JSON_FORMAT"]
4575
4576
4577# https://dev.mysql.com/doc/refman/8.0/en/json-search-functions.html#operator_member-of
4578class JSONArrayContains(Binary, Predicate, Func):
4579    _sql_names = ["JSON_ARRAY_CONTAINS"]
4580
4581
4582class Least(Func):
4583    arg_types = {"this": True, "expressions": False}
4584    is_var_len_args = True
4585
4586
4587class Left(Func):
4588    arg_types = {"this": True, "expression": True}
4589
4590
4591class Right(Func):
4592    arg_types = {"this": True, "expression": True}
4593
4594
4595class Length(Func):
4596    _sql_names = ["LENGTH", "LEN"]
4597
4598
4599class Levenshtein(Func):
4600    arg_types = {
4601        "this": True,
4602        "expression": False,
4603        "ins_cost": False,
4604        "del_cost": False,
4605        "sub_cost": False,
4606    }
4607
4608
4609class Ln(Func):
4610    pass
4611
4612
4613class Log(Func):
4614    arg_types = {"this": True, "expression": False}
4615
4616
4617class Log2(Func):
4618    pass
4619
4620
4621class Log10(Func):
4622    pass
4623
4624
4625class LogicalOr(AggFunc):
4626    _sql_names = ["LOGICAL_OR", "BOOL_OR", "BOOLOR_AGG"]
4627
4628
4629class LogicalAnd(AggFunc):
4630    _sql_names = ["LOGICAL_AND", "BOOL_AND", "BOOLAND_AGG"]
4631
4632
4633class Lower(Func):
4634    _sql_names = ["LOWER", "LCASE"]
4635
4636
4637class Map(Func):
4638    arg_types = {"keys": False, "values": False}
4639
4640
4641class MapFromEntries(Func):
4642    pass
4643
4644
4645class StarMap(Func):
4646    pass
4647
4648
4649class VarMap(Func):
4650    arg_types = {"keys": True, "values": True}
4651    is_var_len_args = True
4652
4653    @property
4654    def keys(self) -> t.List[Expression]:
4655        return self.args["keys"].expressions
4656
4657    @property
4658    def values(self) -> t.List[Expression]:
4659        return self.args["values"].expressions
4660
4661
4662# https://dev.mysql.com/doc/refman/8.0/en/fulltext-search.html
4663class MatchAgainst(Func):
4664    arg_types = {"this": True, "expressions": True, "modifier": False}
4665
4666
4667class Max(AggFunc):
4668    arg_types = {"this": True, "expressions": False}
4669    is_var_len_args = True
4670
4671
4672class MD5(Func):
4673    _sql_names = ["MD5"]
4674
4675
4676# Represents the variant of the MD5 function that returns a binary value
4677class MD5Digest(Func):
4678    _sql_names = ["MD5_DIGEST"]
4679
4680
4681class Min(AggFunc):
4682    arg_types = {"this": True, "expressions": False}
4683    is_var_len_args = True
4684
4685
4686class Month(Func):
4687    pass
4688
4689
4690class Nvl2(Func):
4691    arg_types = {"this": True, "true": True, "false": False}
4692
4693
4694class Posexplode(Func):
4695    pass
4696
4697
4698class Pow(Binary, Func):
4699    _sql_names = ["POWER", "POW"]
4700
4701
4702class PercentileCont(AggFunc):
4703    arg_types = {"this": True, "expression": False}
4704
4705
4706class PercentileDisc(AggFunc):
4707    arg_types = {"this": True, "expression": False}
4708
4709
4710class Quantile(AggFunc):
4711    arg_types = {"this": True, "quantile": True}
4712
4713
4714class ApproxQuantile(Quantile):
4715    arg_types = {"this": True, "quantile": True, "accuracy": False, "weight": False}
4716
4717
4718class RangeN(Func):
4719    arg_types = {"this": True, "expressions": True, "each": False}
4720
4721
4722class ReadCSV(Func):
4723    _sql_names = ["READ_CSV"]
4724    is_var_len_args = True
4725    arg_types = {"this": True, "expressions": False}
4726
4727
4728class Reduce(Func):
4729    arg_types = {"this": True, "initial": True, "merge": True, "finish": False}
4730
4731
4732class RegexpExtract(Func):
4733    arg_types = {
4734        "this": True,
4735        "expression": True,
4736        "position": False,
4737        "occurrence": False,
4738        "parameters": False,
4739        "group": False,
4740    }
4741
4742
4743class RegexpReplace(Func):
4744    arg_types = {
4745        "this": True,
4746        "expression": True,
4747        "replacement": True,
4748        "position": False,
4749        "occurrence": False,
4750        "parameters": False,
4751    }
4752
4753
4754class RegexpLike(Binary, Func):
4755    arg_types = {"this": True, "expression": True, "flag": False}
4756
4757
4758class RegexpILike(Func):
4759    arg_types = {"this": True, "expression": True, "flag": False}
4760
4761
4762# https://spark.apache.org/docs/latest/api/python/reference/pyspark.sql/api/pyspark.sql.functions.split.html
4763# limit is the number of times a pattern is applied
4764class RegexpSplit(Func):
4765    arg_types = {"this": True, "expression": True, "limit": False}
4766
4767
4768class Repeat(Func):
4769    arg_types = {"this": True, "times": True}
4770
4771
4772class Round(Func):
4773    arg_types = {"this": True, "decimals": False}
4774
4775
4776class RowNumber(Func):
4777    arg_types: t.Dict[str, t.Any] = {}
4778
4779
4780class SafeDivide(Func):
4781    arg_types = {"this": True, "expression": True}
4782
4783
4784class SetAgg(AggFunc):
4785    pass
4786
4787
4788class SHA(Func):
4789    _sql_names = ["SHA", "SHA1"]
4790
4791
4792class SHA2(Func):
4793    _sql_names = ["SHA2"]
4794    arg_types = {"this": True, "length": False}
4795
4796
4797class SortArray(Func):
4798    arg_types = {"this": True, "asc": False}
4799
4800
4801class Split(Func):
4802    arg_types = {"this": True, "expression": True, "limit": False}
4803
4804
4805# Start may be omitted in the case of postgres
4806# https://www.postgresql.org/docs/9.1/functions-string.html @ Table 9-6
4807class Substring(Func):
4808    arg_types = {"this": True, "start": False, "length": False}
4809
4810
4811class StandardHash(Func):
4812    arg_types = {"this": True, "expression": False}
4813
4814
4815class StartsWith(Func):
4816    _sql_names = ["STARTS_WITH", "STARTSWITH"]
4817    arg_types = {"this": True, "expression": True}
4818
4819
4820class StrPosition(Func):
4821    arg_types = {
4822        "this": True,
4823        "substr": True,
4824        "position": False,
4825        "instance": False,
4826    }
4827
4828
4829class StrToDate(Func):
4830    arg_types = {"this": True, "format": True}
4831
4832
4833class StrToTime(Func):
4834    arg_types = {"this": True, "format": True, "zone": False}
4835
4836
4837# Spark allows unix_timestamp()
4838# https://spark.apache.org/docs/3.1.3/api/python/reference/api/pyspark.sql.functions.unix_timestamp.html
4839class StrToUnix(Func):
4840    arg_types = {"this": False, "format": False}
4841
4842
4843# https://prestodb.io/docs/current/functions/string.html
4844# https://spark.apache.org/docs/latest/api/sql/index.html#str_to_map
4845class StrToMap(Func):
4846    arg_types = {
4847        "this": True,
4848        "pair_delim": False,
4849        "key_value_delim": False,
4850        "duplicate_resolution_callback": False,
4851    }
4852
4853
4854class NumberToStr(Func):
4855    arg_types = {"this": True, "format": True, "culture": False}
4856
4857
4858class FromBase(Func):
4859    arg_types = {"this": True, "expression": True}
4860
4861
4862class Struct(Func):
4863    arg_types = {"expressions": True}
4864    is_var_len_args = True
4865
4866
4867class StructExtract(Func):
4868    arg_types = {"this": True, "expression": True}
4869
4870
4871# https://learn.microsoft.com/en-us/sql/t-sql/functions/stuff-transact-sql?view=sql-server-ver16
4872# https://docs.snowflake.com/en/sql-reference/functions/insert
4873class Stuff(Func):
4874    _sql_names = ["STUFF", "INSERT"]
4875    arg_types = {"this": True, "start": True, "length": True, "expression": True}
4876
4877
4878class Sum(AggFunc):
4879    pass
4880
4881
4882class Sqrt(Func):
4883    pass
4884
4885
4886class Stddev(AggFunc):
4887    pass
4888
4889
4890class StddevPop(AggFunc):
4891    pass
4892
4893
4894class StddevSamp(AggFunc):
4895    pass
4896
4897
4898class TimeToStr(Func):
4899    arg_types = {"this": True, "format": True, "culture": False}
4900
4901
4902class TimeToTimeStr(Func):
4903    pass
4904
4905
4906class TimeToUnix(Func):
4907    pass
4908
4909
4910class TimeStrToDate(Func):
4911    pass
4912
4913
4914class TimeStrToTime(Func):
4915    pass
4916
4917
4918class TimeStrToUnix(Func):
4919    pass
4920
4921
4922class Trim(Func):
4923    arg_types = {
4924        "this": True,
4925        "expression": False,
4926        "position": False,
4927        "collation": False,
4928    }
4929
4930
4931class TsOrDsAdd(Func, TimeUnit):
4932    arg_types = {"this": True, "expression": True, "unit": False}
4933
4934
4935class TsOrDsToDateStr(Func):
4936    pass
4937
4938
4939class TsOrDsToDate(Func):
4940    arg_types = {"this": True, "format": False}
4941
4942
4943class TsOrDiToDi(Func):
4944    pass
4945
4946
4947class Unhex(Func):
4948    pass
4949
4950
4951class UnixToStr(Func):
4952    arg_types = {"this": True, "format": False}
4953
4954
4955# https://prestodb.io/docs/current/functions/datetime.html
4956# presto has weird zone/hours/minutes
4957class UnixToTime(Func):
4958    arg_types = {"this": True, "scale": False, "zone": False, "hours": False, "minutes": False}
4959
4960    SECONDS = Literal.string("seconds")
4961    MILLIS = Literal.string("millis")
4962    MICROS = Literal.string("micros")
4963
4964
4965class UnixToTimeStr(Func):
4966    pass
4967
4968
4969class Upper(Func):
4970    _sql_names = ["UPPER", "UCASE"]
4971
4972
4973class Variance(AggFunc):
4974    _sql_names = ["VARIANCE", "VARIANCE_SAMP", "VAR_SAMP"]
4975
4976
4977class VariancePop(AggFunc):
4978    _sql_names = ["VARIANCE_POP", "VAR_POP"]
4979
4980
4981class Week(Func):
4982    arg_types = {"this": True, "mode": False}
4983
4984
4985class XMLTable(Func):
4986    arg_types = {"this": True, "passing": False, "columns": False, "by_ref": False}
4987
4988
4989class Year(Func):
4990    pass
4991
4992
4993class Use(Expression):
4994    arg_types = {"this": True, "kind": False}
4995
4996
4997class Merge(Expression):
4998    arg_types = {"this": True, "using": True, "on": True, "expressions": True}
4999
5000
5001class When(Func):
5002    arg_types = {"matched": True, "source": False, "condition": False, "then": True}
5003
5004
5005# https://docs.oracle.com/javadb/10.8.3.0/ref/rrefsqljnextvaluefor.html
5006# https://learn.microsoft.com/en-us/sql/t-sql/functions/next-value-for-transact-sql?view=sql-server-ver16
5007class NextValueFor(Func):
5008    arg_types = {"this": True, "order": False}
5009
5010
5011def _norm_arg(arg):
5012    return arg.lower() if type(arg) is str else arg
5013
5014
5015ALL_FUNCTIONS = subclasses(__name__, Func, (AggFunc, Anonymous, Func))
5016
5017
5018# Helpers
5019@t.overload
5020def maybe_parse(
5021    sql_or_expression: ExpOrStr,
5022    *,
5023    into: t.Type[E],
5024    dialect: DialectType = None,
5025    prefix: t.Optional[str] = None,
5026    copy: bool = False,
5027    **opts,
5028) -> E:
5029    ...
5030
5031
5032@t.overload
5033def maybe_parse(
5034    sql_or_expression: str | E,
5035    *,
5036    into: t.Optional[IntoType] = None,
5037    dialect: DialectType = None,
5038    prefix: t.Optional[str] = None,
5039    copy: bool = False,
5040    **opts,
5041) -> E:
5042    ...
5043
5044
5045def maybe_parse(
5046    sql_or_expression: ExpOrStr,
5047    *,
5048    into: t.Optional[IntoType] = None,
5049    dialect: DialectType = None,
5050    prefix: t.Optional[str] = None,
5051    copy: bool = False,
5052    **opts,
5053) -> Expression:
5054    """Gracefully handle a possible string or expression.
5055
5056    Example:
5057        >>> maybe_parse("1")
5058        (LITERAL this: 1, is_string: False)
5059        >>> maybe_parse(to_identifier("x"))
5060        (IDENTIFIER this: x, quoted: False)
5061
5062    Args:
5063        sql_or_expression: the SQL code string or an expression
5064        into: the SQLGlot Expression to parse into
5065        dialect: the dialect used to parse the input expressions (in the case that an
5066            input expression is a SQL string).
5067        prefix: a string to prefix the sql with before it gets parsed
5068            (automatically includes a space)
5069        copy: whether or not to copy the expression.
5070        **opts: other options to use to parse the input expressions (again, in the case
5071            that an input expression is a SQL string).
5072
5073    Returns:
5074        Expression: the parsed or given expression.
5075    """
5076    if isinstance(sql_or_expression, Expression):
5077        if copy:
5078            return sql_or_expression.copy()
5079        return sql_or_expression
5080
5081    if sql_or_expression is None:
5082        raise ParseError(f"SQL cannot be None")
5083
5084    import sqlglot
5085
5086    sql = str(sql_or_expression)
5087    if prefix:
5088        sql = f"{prefix} {sql}"
5089
5090    return sqlglot.parse_one(sql, read=dialect, into=into, **opts)
5091
5092
5093@t.overload
5094def maybe_copy(instance: None, copy: bool = True) -> None:
5095    ...
5096
5097
5098@t.overload
5099def maybe_copy(instance: E, copy: bool = True) -> E:
5100    ...
5101
5102
5103def maybe_copy(instance, copy=True):
5104    return instance.copy() if copy and instance else instance
5105
5106
5107def _is_wrong_expression(expression, into):
5108    return isinstance(expression, Expression) and not isinstance(expression, into)
5109
5110
5111def _apply_builder(
5112    expression,
5113    instance,
5114    arg,
5115    copy=True,
5116    prefix=None,
5117    into=None,
5118    dialect=None,
5119    **opts,
5120):
5121    if _is_wrong_expression(expression, into):
5122        expression = into(this=expression)
5123    instance = maybe_copy(instance, copy)
5124    expression = maybe_parse(
5125        sql_or_expression=expression,
5126        prefix=prefix,
5127        into=into,
5128        dialect=dialect,
5129        **opts,
5130    )
5131    instance.set(arg, expression)
5132    return instance
5133
5134
5135def _apply_child_list_builder(
5136    *expressions,
5137    instance,
5138    arg,
5139    append=True,
5140    copy=True,
5141    prefix=None,
5142    into=None,
5143    dialect=None,
5144    properties=None,
5145    **opts,
5146):
5147    instance = maybe_copy(instance, copy)
5148    parsed = []
5149    for expression in expressions:
5150        if expression is not None:
5151            if _is_wrong_expression(expression, into):
5152                expression = into(expressions=[expression])
5153
5154            expression = maybe_parse(
5155                expression,
5156                into=into,
5157                dialect=dialect,
5158                prefix=prefix,
5159                **opts,
5160            )
5161            parsed.extend(expression.expressions)
5162
5163    existing = instance.args.get(arg)
5164    if append and existing:
5165        parsed = existing.expressions + parsed
5166
5167    child = into(expressions=parsed)
5168    for k, v in (properties or {}).items():
5169        child.set(k, v)
5170    instance.set(arg, child)
5171
5172    return instance
5173
5174
5175def _apply_list_builder(
5176    *expressions,
5177    instance,
5178    arg,
5179    append=True,
5180    copy=True,
5181    prefix=None,
5182    into=None,
5183    dialect=None,
5184    **opts,
5185):
5186    inst = maybe_copy(instance, copy)
5187
5188    expressions = [
5189        maybe_parse(
5190            sql_or_expression=expression,
5191            into=into,
5192            prefix=prefix,
5193            dialect=dialect,
5194            **opts,
5195        )
5196        for expression in expressions
5197        if expression is not None
5198    ]
5199
5200    existing_expressions = inst.args.get(arg)
5201    if append and existing_expressions:
5202        expressions = existing_expressions + expressions
5203
5204    inst.set(arg, expressions)
5205    return inst
5206
5207
5208def _apply_conjunction_builder(
5209    *expressions,
5210    instance,
5211    arg,
5212    into=None,
5213    append=True,
5214    copy=True,
5215    dialect=None,
5216    **opts,
5217):
5218    expressions = [exp for exp in expressions if exp is not None and exp != ""]
5219    if not expressions:
5220        return instance
5221
5222    inst = maybe_copy(instance, copy)
5223
5224    existing = inst.args.get(arg)
5225    if append and existing is not None:
5226        expressions = [existing.this if into else existing] + list(expressions)
5227
5228    node = and_(*expressions, dialect=dialect, copy=copy, **opts)
5229
5230    inst.set(arg, into(this=node) if into else node)
5231    return inst
5232
5233
5234def _apply_cte_builder(
5235    instance: E,
5236    alias: ExpOrStr,
5237    as_: ExpOrStr,
5238    recursive: t.Optional[bool] = None,
5239    append: bool = True,
5240    dialect: DialectType = None,
5241    copy: bool = True,
5242    **opts,
5243) -> E:
5244    alias_expression = maybe_parse(alias, dialect=dialect, into=TableAlias, **opts)
5245    as_expression = maybe_parse(as_, dialect=dialect, **opts)
5246    cte = CTE(this=as_expression, alias=alias_expression)
5247    return _apply_child_list_builder(
5248        cte,
5249        instance=instance,
5250        arg="with",
5251        append=append,
5252        copy=copy,
5253        into=With,
5254        properties={"recursive": recursive or False},
5255    )
5256
5257
5258def _combine(
5259    expressions: t.Sequence[t.Optional[ExpOrStr]],
5260    operator: t.Type[Connector],
5261    dialect: DialectType = None,
5262    copy: bool = True,
5263    **opts,
5264) -> Expression:
5265    conditions = [
5266        condition(expression, dialect=dialect, copy=copy, **opts)
5267        for expression in expressions
5268        if expression is not None
5269    ]
5270
5271    this, *rest = conditions
5272    if rest:
5273        this = _wrap(this, Connector)
5274    for expression in rest:
5275        this = operator(this=this, expression=_wrap(expression, Connector))
5276
5277    return this
5278
5279
5280def _wrap(expression: E, kind: t.Type[Expression]) -> E | Paren:
5281    return Paren(this=expression) if isinstance(expression, kind) else expression
5282
5283
5284def union(
5285    left: ExpOrStr, right: ExpOrStr, distinct: bool = True, dialect: DialectType = None, **opts
5286) -> Union:
5287    """
5288    Initializes a syntax tree from one UNION expression.
5289
5290    Example:
5291        >>> union("SELECT * FROM foo", "SELECT * FROM bla").sql()
5292        'SELECT * FROM foo UNION SELECT * FROM bla'
5293
5294    Args:
5295        left: the SQL code string corresponding to the left-hand side.
5296            If an `Expression` instance is passed, it will be used as-is.
5297        right: the SQL code string corresponding to the right-hand side.
5298            If an `Expression` instance is passed, it will be used as-is.
5299        distinct: set the DISTINCT flag if and only if this is true.
5300        dialect: the dialect used to parse the input expression.
5301        opts: other options to use to parse the input expressions.
5302
5303    Returns:
5304        The new Union instance.
5305    """
5306    left = maybe_parse(sql_or_expression=left, dialect=dialect, **opts)
5307    right = maybe_parse(sql_or_expression=right, dialect=dialect, **opts)
5308
5309    return Union(this=left, expression=right, distinct=distinct)
5310
5311
5312def intersect(
5313    left: ExpOrStr, right: ExpOrStr, distinct: bool = True, dialect: DialectType = None, **opts
5314) -> Intersect:
5315    """
5316    Initializes a syntax tree from one INTERSECT expression.
5317
5318    Example:
5319        >>> intersect("SELECT * FROM foo", "SELECT * FROM bla").sql()
5320        'SELECT * FROM foo INTERSECT SELECT * FROM bla'
5321
5322    Args:
5323        left: the SQL code string corresponding to the left-hand side.
5324            If an `Expression` instance is passed, it will be used as-is.
5325        right: the SQL code string corresponding to the right-hand side.
5326            If an `Expression` instance is passed, it will be used as-is.
5327        distinct: set the DISTINCT flag if and only if this is true.
5328        dialect: the dialect used to parse the input expression.
5329        opts: other options to use to parse the input expressions.
5330
5331    Returns:
5332        The new Intersect instance.
5333    """
5334    left = maybe_parse(sql_or_expression=left, dialect=dialect, **opts)
5335    right = maybe_parse(sql_or_expression=right, dialect=dialect, **opts)
5336
5337    return Intersect(this=left, expression=right, distinct=distinct)
5338
5339
5340def except_(
5341    left: ExpOrStr, right: ExpOrStr, distinct: bool = True, dialect: DialectType = None, **opts
5342) -> Except:
5343    """
5344    Initializes a syntax tree from one EXCEPT expression.
5345
5346    Example:
5347        >>> except_("SELECT * FROM foo", "SELECT * FROM bla").sql()
5348        'SELECT * FROM foo EXCEPT SELECT * FROM bla'
5349
5350    Args:
5351        left: the SQL code string corresponding to the left-hand side.
5352            If an `Expression` instance is passed, it will be used as-is.
5353        right: the SQL code string corresponding to the right-hand side.
5354            If an `Expression` instance is passed, it will be used as-is.
5355        distinct: set the DISTINCT flag if and only if this is true.
5356        dialect: the dialect used to parse the input expression.
5357        opts: other options to use to parse the input expressions.
5358
5359    Returns:
5360        The new Except instance.
5361    """
5362    left = maybe_parse(sql_or_expression=left, dialect=dialect, **opts)
5363    right = maybe_parse(sql_or_expression=right, dialect=dialect, **opts)
5364
5365    return Except(this=left, expression=right, distinct=distinct)
5366
5367
5368def select(*expressions: ExpOrStr, dialect: DialectType = None, **opts) -> Select:
5369    """
5370    Initializes a syntax tree from one or multiple SELECT expressions.
5371
5372    Example:
5373        >>> select("col1", "col2").from_("tbl").sql()
5374        'SELECT col1, col2 FROM tbl'
5375
5376    Args:
5377        *expressions: the SQL code string to parse as the expressions of a
5378            SELECT statement. If an Expression instance is passed, this is used as-is.
5379        dialect: the dialect used to parse the input expressions (in the case that an
5380            input expression is a SQL string).
5381        **opts: other options to use to parse the input expressions (again, in the case
5382            that an input expression is a SQL string).
5383
5384    Returns:
5385        Select: the syntax tree for the SELECT statement.
5386    """
5387    return Select().select(*expressions, dialect=dialect, **opts)
5388
5389
5390def from_(expression: ExpOrStr, dialect: DialectType = None, **opts) -> Select:
5391    """
5392    Initializes a syntax tree from a FROM expression.
5393
5394    Example:
5395        >>> from_("tbl").select("col1", "col2").sql()
5396        'SELECT col1, col2 FROM tbl'
5397
5398    Args:
5399        *expression: the SQL code string to parse as the FROM expressions of a
5400            SELECT statement. If an Expression instance is passed, this is used as-is.
5401        dialect: the dialect used to parse the input expression (in the case that the
5402            input expression is a SQL string).
5403        **opts: other options to use to parse the input expressions (again, in the case
5404            that the input expression is a SQL string).
5405
5406    Returns:
5407        Select: the syntax tree for the SELECT statement.
5408    """
5409    return Select().from_(expression, dialect=dialect, **opts)
5410
5411
5412def update(
5413    table: str | Table,
5414    properties: dict,
5415    where: t.Optional[ExpOrStr] = None,
5416    from_: t.Optional[ExpOrStr] = None,
5417    dialect: DialectType = None,
5418    **opts,
5419) -> Update:
5420    """
5421    Creates an update statement.
5422
5423    Example:
5424        >>> update("my_table", {"x": 1, "y": "2", "z": None}, from_="baz", where="id > 1").sql()
5425        "UPDATE my_table SET x = 1, y = '2', z = NULL FROM baz WHERE id > 1"
5426
5427    Args:
5428        *properties: dictionary of properties to set which are
5429            auto converted to sql objects eg None -> NULL
5430        where: sql conditional parsed into a WHERE statement
5431        from_: sql statement parsed into a FROM statement
5432        dialect: the dialect used to parse the input expressions.
5433        **opts: other options to use to parse the input expressions.
5434
5435    Returns:
5436        Update: the syntax tree for the UPDATE statement.
5437    """
5438    update_expr = Update(this=maybe_parse(table, into=Table, dialect=dialect))
5439    update_expr.set(
5440        "expressions",
5441        [
5442            EQ(this=maybe_parse(k, dialect=dialect, **opts), expression=convert(v))
5443            for k, v in properties.items()
5444        ],
5445    )
5446    if from_:
5447        update_expr.set(
5448            "from",
5449            maybe_parse(from_, into=From, dialect=dialect, prefix="FROM", **opts),
5450        )
5451    if isinstance(where, Condition):
5452        where = Where(this=where)
5453    if where:
5454        update_expr.set(
5455            "where",
5456            maybe_parse(where, into=Where, dialect=dialect, prefix="WHERE", **opts),
5457        )
5458    return update_expr
5459
5460
5461def delete(
5462    table: ExpOrStr,
5463    where: t.Optional[ExpOrStr] = None,
5464    returning: t.Optional[ExpOrStr] = None,
5465    dialect: DialectType = None,
5466    **opts,
5467) -> Delete:
5468    """
5469    Builds a delete statement.
5470
5471    Example:
5472        >>> delete("my_table", where="id > 1").sql()
5473        'DELETE FROM my_table WHERE id > 1'
5474
5475    Args:
5476        where: sql conditional parsed into a WHERE statement
5477        returning: sql conditional parsed into a RETURNING statement
5478        dialect: the dialect used to parse the input expressions.
5479        **opts: other options to use to parse the input expressions.
5480
5481    Returns:
5482        Delete: the syntax tree for the DELETE statement.
5483    """
5484    delete_expr = Delete().delete(table, dialect=dialect, copy=False, **opts)
5485    if where:
5486        delete_expr = delete_expr.where(where, dialect=dialect, copy=False, **opts)
5487    if returning:
5488        delete_expr = delete_expr.returning(returning, dialect=dialect, copy=False, **opts)
5489    return delete_expr
5490
5491
5492def insert(
5493    expression: ExpOrStr,
5494    into: ExpOrStr,
5495    columns: t.Optional[t.Sequence[ExpOrStr]] = None,
5496    overwrite: t.Optional[bool] = None,
5497    dialect: DialectType = None,
5498    copy: bool = True,
5499    **opts,
5500) -> Insert:
5501    """
5502    Builds an INSERT statement.
5503
5504    Example:
5505        >>> insert("VALUES (1, 2, 3)", "tbl").sql()
5506        'INSERT INTO tbl VALUES (1, 2, 3)'
5507
5508    Args:
5509        expression: the sql string or expression of the INSERT statement
5510        into: the tbl to insert data to.
5511        columns: optionally the table's column names.
5512        overwrite: whether to INSERT OVERWRITE or not.
5513        dialect: the dialect used to parse the input expressions.
5514        copy: whether or not to copy the expression.
5515        **opts: other options to use to parse the input expressions.
5516
5517    Returns:
5518        Insert: the syntax tree for the INSERT statement.
5519    """
5520    expr = maybe_parse(expression, dialect=dialect, copy=copy, **opts)
5521    this: Table | Schema = maybe_parse(into, into=Table, dialect=dialect, copy=copy, **opts)
5522
5523    if columns:
5524        this = _apply_list_builder(
5525            *columns,
5526            instance=Schema(this=this),
5527            arg="expressions",
5528            into=Identifier,
5529            copy=False,
5530            dialect=dialect,
5531            **opts,
5532        )
5533
5534    return Insert(this=this, expression=expr, overwrite=overwrite)
5535
5536
5537def condition(
5538    expression: ExpOrStr, dialect: DialectType = None, copy: bool = True, **opts
5539) -> Condition:
5540    """
5541    Initialize a logical condition expression.
5542
5543    Example:
5544        >>> condition("x=1").sql()
5545        'x = 1'
5546
5547        This is helpful for composing larger logical syntax trees:
5548        >>> where = condition("x=1")
5549        >>> where = where.and_("y=1")
5550        >>> Select().from_("tbl").select("*").where(where).sql()
5551        'SELECT * FROM tbl WHERE x = 1 AND y = 1'
5552
5553    Args:
5554        *expression: the SQL code string to parse.
5555            If an Expression instance is passed, this is used as-is.
5556        dialect: the dialect used to parse the input expression (in the case that the
5557            input expression is a SQL string).
5558        copy: Whether or not to copy `expression` (only applies to expressions).
5559        **opts: other options to use to parse the input expressions (again, in the case
5560            that the input expression is a SQL string).
5561
5562    Returns:
5563        The new Condition instance
5564    """
5565    return maybe_parse(
5566        expression,
5567        into=Condition,
5568        dialect=dialect,
5569        copy=copy,
5570        **opts,
5571    )
5572
5573
5574def and_(
5575    *expressions: t.Optional[ExpOrStr], dialect: DialectType = None, copy: bool = True, **opts
5576) -> Condition:
5577    """
5578    Combine multiple conditions with an AND logical operator.
5579
5580    Example:
5581        >>> and_("x=1", and_("y=1", "z=1")).sql()
5582        'x = 1 AND (y = 1 AND z = 1)'
5583
5584    Args:
5585        *expressions: the SQL code strings to parse.
5586            If an Expression instance is passed, this is used as-is.
5587        dialect: the dialect used to parse the input expression.
5588        copy: whether or not to copy `expressions` (only applies to Expressions).
5589        **opts: other options to use to parse the input expressions.
5590
5591    Returns:
5592        And: the new condition
5593    """
5594    return t.cast(Condition, _combine(expressions, And, dialect, copy=copy, **opts))
5595
5596
5597def or_(
5598    *expressions: t.Optional[ExpOrStr], dialect: DialectType = None, copy: bool = True, **opts
5599) -> Condition:
5600    """
5601    Combine multiple conditions with an OR logical operator.
5602
5603    Example:
5604        >>> or_("x=1", or_("y=1", "z=1")).sql()
5605        'x = 1 OR (y = 1 OR z = 1)'
5606
5607    Args:
5608        *expressions: the SQL code strings to parse.
5609            If an Expression instance is passed, this is used as-is.
5610        dialect: the dialect used to parse the input expression.
5611        copy: whether or not to copy `expressions` (only applies to Expressions).
5612        **opts: other options to use to parse the input expressions.
5613
5614    Returns:
5615        Or: the new condition
5616    """
5617    return t.cast(Condition, _combine(expressions, Or, dialect, copy=copy, **opts))
5618
5619
5620def not_(expression: ExpOrStr, dialect: DialectType = None, copy: bool = True, **opts) -> Not:
5621    """
5622    Wrap a condition with a NOT operator.
5623
5624    Example:
5625        >>> not_("this_suit='black'").sql()
5626        "NOT this_suit = 'black'"
5627
5628    Args:
5629        expression: the SQL code string to parse.
5630            If an Expression instance is passed, this is used as-is.
5631        dialect: the dialect used to parse the input expression.
5632        copy: whether to copy the expression or not.
5633        **opts: other options to use to parse the input expressions.
5634
5635    Returns:
5636        The new condition.
5637    """
5638    this = condition(
5639        expression,
5640        dialect=dialect,
5641        copy=copy,
5642        **opts,
5643    )
5644    return Not(this=_wrap(this, Connector))
5645
5646
5647def paren(expression: ExpOrStr, copy: bool = True) -> Paren:
5648    """
5649    Wrap an expression in parentheses.
5650
5651    Example:
5652        >>> paren("5 + 3").sql()
5653        '(5 + 3)'
5654
5655    Args:
5656        expression: the SQL code string to parse.
5657            If an Expression instance is passed, this is used as-is.
5658        copy: whether to copy the expression or not.
5659
5660    Returns:
5661        The wrapped expression.
5662    """
5663    return Paren(this=maybe_parse(expression, copy=copy))
5664
5665
5666SAFE_IDENTIFIER_RE = re.compile(r"^[_a-zA-Z][\w]*$")
5667
5668
5669@t.overload
5670def to_identifier(name: None, quoted: t.Optional[bool] = None, copy: bool = True) -> None:
5671    ...
5672
5673
5674@t.overload
5675def to_identifier(
5676    name: str | Identifier, quoted: t.Optional[bool] = None, copy: bool = True
5677) -> Identifier:
5678    ...
5679
5680
5681def to_identifier(name, quoted=None, copy=True):
5682    """Builds an identifier.
5683
5684    Args:
5685        name: The name to turn into an identifier.
5686        quoted: Whether or not force quote the identifier.
5687        copy: Whether or not to copy a passed in Identefier node.
5688
5689    Returns:
5690        The identifier ast node.
5691    """
5692
5693    if name is None:
5694        return None
5695
5696    if isinstance(name, Identifier):
5697        identifier = maybe_copy(name, copy)
5698    elif isinstance(name, str):
5699        identifier = Identifier(
5700            this=name,
5701            quoted=not SAFE_IDENTIFIER_RE.match(name) if quoted is None else quoted,
5702        )
5703    else:
5704        raise ValueError(f"Name needs to be a string or an Identifier, got: {name.__class__}")
5705    return identifier
5706
5707
5708INTERVAL_STRING_RE = re.compile(r"\s*([0-9]+)\s*([a-zA-Z]+)\s*")
5709
5710
5711def to_interval(interval: str | Literal) -> Interval:
5712    """Builds an interval expression from a string like '1 day' or '5 months'."""
5713    if isinstance(interval, Literal):
5714        if not interval.is_string:
5715            raise ValueError("Invalid interval string.")
5716
5717        interval = interval.this
5718
5719    interval_parts = INTERVAL_STRING_RE.match(interval)  # type: ignore
5720
5721    if not interval_parts:
5722        raise ValueError("Invalid interval string.")
5723
5724    return Interval(
5725        this=Literal.string(interval_parts.group(1)),
5726        unit=Var(this=interval_parts.group(2)),
5727    )
5728
5729
5730@t.overload
5731def to_table(sql_path: str | Table, **kwargs) -> Table:
5732    ...
5733
5734
5735@t.overload
5736def to_table(sql_path: None, **kwargs) -> None:
5737    ...
5738
5739
5740def to_table(
5741    sql_path: t.Optional[str | Table], dialect: DialectType = None, **kwargs
5742) -> t.Optional[Table]:
5743    """
5744    Create a table expression from a `[catalog].[schema].[table]` sql path. Catalog and schema are optional.
5745    If a table is passed in then that table is returned.
5746
5747    Args:
5748        sql_path: a `[catalog].[schema].[table]` string.
5749        dialect: the source dialect according to which the table name will be parsed.
5750        kwargs: the kwargs to instantiate the resulting `Table` expression with.
5751
5752    Returns:
5753        A table expression.
5754    """
5755    if sql_path is None or isinstance(sql_path, Table):
5756        return sql_path
5757    if not isinstance(sql_path, str):
5758        raise ValueError(f"Invalid type provided for a table: {type(sql_path)}")
5759
5760    table = maybe_parse(sql_path, into=Table, dialect=dialect)
5761    if table:
5762        for k, v in kwargs.items():
5763            table.set(k, v)
5764
5765    return table
5766
5767
5768def to_column(sql_path: str | Column, **kwargs) -> Column:
5769    """
5770    Create a column from a `[table].[column]` sql path. Schema is optional.
5771
5772    If a column is passed in then that column is returned.
5773
5774    Args:
5775        sql_path: `[table].[column]` string
5776    Returns:
5777        Table: A column expression
5778    """
5779    if sql_path is None or isinstance(sql_path, Column):
5780        return sql_path
5781    if not isinstance(sql_path, str):
5782        raise ValueError(f"Invalid type provided for column: {type(sql_path)}")
5783    return column(*reversed(sql_path.split(".")), **kwargs)  # type: ignore
5784
5785
5786def alias_(
5787    expression: ExpOrStr,
5788    alias: str | Identifier,
5789    table: bool | t.Sequence[str | Identifier] = False,
5790    quoted: t.Optional[bool] = None,
5791    dialect: DialectType = None,
5792    copy: bool = True,
5793    **opts,
5794):
5795    """Create an Alias expression.
5796
5797    Example:
5798        >>> alias_('foo', 'bar').sql()
5799        'foo AS bar'
5800
5801        >>> alias_('(select 1, 2)', 'bar', table=['a', 'b']).sql()
5802        '(SELECT 1, 2) AS bar(a, b)'
5803
5804    Args:
5805        expression: the SQL code strings to parse.
5806            If an Expression instance is passed, this is used as-is.
5807        alias: the alias name to use. If the name has
5808            special characters it is quoted.
5809        table: Whether or not to create a table alias, can also be a list of columns.
5810        quoted: whether or not to quote the alias
5811        dialect: the dialect used to parse the input expression.
5812        copy: Whether or not to copy the expression.
5813        **opts: other options to use to parse the input expressions.
5814
5815    Returns:
5816        Alias: the aliased expression
5817    """
5818    exp = maybe_parse(expression, dialect=dialect, copy=copy, **opts)
5819    alias = to_identifier(alias, quoted=quoted)
5820
5821    if table:
5822        table_alias = TableAlias(this=alias)
5823        exp.set("alias", table_alias)
5824
5825        if not isinstance(table, bool):
5826            for column in table:
5827                table_alias.append("columns", to_identifier(column, quoted=quoted))
5828
5829        return exp
5830
5831    # We don't set the "alias" arg for Window expressions, because that would add an IDENTIFIER node in
5832    # the AST, representing a "named_window" [1] construct (eg. bigquery). What we want is an ALIAS node
5833    # for the complete Window expression.
5834    #
5835    # [1]: https://cloud.google.com/bigquery/docs/reference/standard-sql/window-function-calls
5836
5837    if "alias" in exp.arg_types and not isinstance(exp, Window):
5838        exp.set("alias", alias)
5839        return exp
5840    return Alias(this=exp, alias=alias)
5841
5842
5843def subquery(
5844    expression: ExpOrStr,
5845    alias: t.Optional[Identifier | str] = None,
5846    dialect: DialectType = None,
5847    **opts,
5848) -> Select:
5849    """
5850    Build a subquery expression.
5851
5852    Example:
5853        >>> subquery('select x from tbl', 'bar').select('x').sql()
5854        'SELECT x FROM (SELECT x FROM tbl) AS bar'
5855
5856    Args:
5857        expression: the SQL code strings to parse.
5858            If an Expression instance is passed, this is used as-is.
5859        alias: the alias name to use.
5860        dialect: the dialect used to parse the input expression.
5861        **opts: other options to use to parse the input expressions.
5862
5863    Returns:
5864        A new Select instance with the subquery expression included.
5865    """
5866
5867    expression = maybe_parse(expression, dialect=dialect, **opts).subquery(alias)
5868    return Select().from_(expression, dialect=dialect, **opts)
5869
5870
5871def column(
5872    col: str | Identifier,
5873    table: t.Optional[str | Identifier] = None,
5874    db: t.Optional[str | Identifier] = None,
5875    catalog: t.Optional[str | Identifier] = None,
5876    quoted: t.Optional[bool] = None,
5877) -> Column:
5878    """
5879    Build a Column.
5880
5881    Args:
5882        col: Column name.
5883        table: Table name.
5884        db: Database name.
5885        catalog: Catalog name.
5886        quoted: Whether to force quotes on the column's identifiers.
5887
5888    Returns:
5889        The new Column instance.
5890    """
5891    return Column(
5892        this=to_identifier(col, quoted=quoted),
5893        table=to_identifier(table, quoted=quoted),
5894        db=to_identifier(db, quoted=quoted),
5895        catalog=to_identifier(catalog, quoted=quoted),
5896    )
5897
5898
5899def cast(expression: ExpOrStr, to: str | DataType | DataType.Type, **opts) -> Cast:
5900    """Cast an expression to a data type.
5901
5902    Example:
5903        >>> cast('x + 1', 'int').sql()
5904        'CAST(x + 1 AS INT)'
5905
5906    Args:
5907        expression: The expression to cast.
5908        to: The datatype to cast to.
5909
5910    Returns:
5911        The new Cast instance.
5912    """
5913    expression = maybe_parse(expression, **opts)
5914    return Cast(this=expression, to=DataType.build(to, **opts))
5915
5916
5917def table_(
5918    table: Identifier | str,
5919    db: t.Optional[Identifier | str] = None,
5920    catalog: t.Optional[Identifier | str] = None,
5921    quoted: t.Optional[bool] = None,
5922    alias: t.Optional[Identifier | str] = None,
5923) -> Table:
5924    """Build a Table.
5925
5926    Args:
5927        table: Table name.
5928        db: Database name.
5929        catalog: Catalog name.
5930        quote: Whether to force quotes on the table's identifiers.
5931        alias: Table's alias.
5932
5933    Returns:
5934        The new Table instance.
5935    """
5936    return Table(
5937        this=to_identifier(table, quoted=quoted) if table else None,
5938        db=to_identifier(db, quoted=quoted) if db else None,
5939        catalog=to_identifier(catalog, quoted=quoted) if catalog else None,
5940        alias=TableAlias(this=to_identifier(alias)) if alias else None,
5941    )
5942
5943
5944def values(
5945    values: t.Iterable[t.Tuple[t.Any, ...]],
5946    alias: t.Optional[str] = None,
5947    columns: t.Optional[t.Iterable[str] | t.Dict[str, DataType]] = None,
5948) -> Values:
5949    """Build VALUES statement.
5950
5951    Example:
5952        >>> values([(1, '2')]).sql()
5953        "VALUES (1, '2')"
5954
5955    Args:
5956        values: values statements that will be converted to SQL
5957        alias: optional alias
5958        columns: Optional list of ordered column names or ordered dictionary of column names to types.
5959         If either are provided then an alias is also required.
5960
5961    Returns:
5962        Values: the Values expression object
5963    """
5964    if columns and not alias:
5965        raise ValueError("Alias is required when providing columns")
5966
5967    return Values(
5968        expressions=[convert(tup) for tup in values],
5969        alias=(
5970            TableAlias(this=to_identifier(alias), columns=[to_identifier(x) for x in columns])
5971            if columns
5972            else (TableAlias(this=to_identifier(alias)) if alias else None)
5973        ),
5974    )
5975
5976
5977def var(name: t.Optional[ExpOrStr]) -> Var:
5978    """Build a SQL variable.
5979
5980    Example:
5981        >>> repr(var('x'))
5982        '(VAR this: x)'
5983
5984        >>> repr(var(column('x', table='y')))
5985        '(VAR this: x)'
5986
5987    Args:
5988        name: The name of the var or an expression who's name will become the var.
5989
5990    Returns:
5991        The new variable node.
5992    """
5993    if not name:
5994        raise ValueError("Cannot convert empty name into var.")
5995
5996    if isinstance(name, Expression):
5997        name = name.name
5998    return Var(this=name)
5999
6000
6001def rename_table(old_name: str | Table, new_name: str | Table) -> AlterTable:
6002    """Build ALTER TABLE... RENAME... expression
6003
6004    Args:
6005        old_name: The old name of the table
6006        new_name: The new name of the table
6007
6008    Returns:
6009        Alter table expression
6010    """
6011    old_table = to_table(old_name)
6012    new_table = to_table(new_name)
6013    return AlterTable(
6014        this=old_table,
6015        actions=[
6016            RenameTable(this=new_table),
6017        ],
6018    )
6019
6020
6021def convert(value: t.Any, copy: bool = False) -> Expression:
6022    """Convert a python value into an expression object.
6023
6024    Raises an error if a conversion is not possible.
6025
6026    Args:
6027        value: A python object.
6028        copy: Whether or not to copy `value` (only applies to Expressions and collections).
6029
6030    Returns:
6031        Expression: the equivalent expression object.
6032    """
6033    if isinstance(value, Expression):
6034        return maybe_copy(value, copy)
6035    if isinstance(value, str):
6036        return Literal.string(value)
6037    if isinstance(value, bool):
6038        return Boolean(this=value)
6039    if value is None or (isinstance(value, float) and math.isnan(value)):
6040        return NULL
6041    if isinstance(value, numbers.Number):
6042        return Literal.number(value)
6043    if isinstance(value, datetime.datetime):
6044        datetime_literal = Literal.string(
6045            (value if value.tzinfo else value.replace(tzinfo=datetime.timezone.utc)).isoformat()
6046        )
6047        return TimeStrToTime(this=datetime_literal)
6048    if isinstance(value, datetime.date):
6049        date_literal = Literal.string(value.strftime("%Y-%m-%d"))
6050        return DateStrToDate(this=date_literal)
6051    if isinstance(value, tuple):
6052        return Tuple(expressions=[convert(v, copy=copy) for v in value])
6053    if isinstance(value, list):
6054        return Array(expressions=[convert(v, copy=copy) for v in value])
6055    if isinstance(value, dict):
6056        return Map(
6057            keys=Array(expressions=[convert(k, copy=copy) for k in value]),
6058            values=Array(expressions=[convert(v, copy=copy) for v in value.values()]),
6059        )
6060    raise ValueError(f"Cannot convert {value}")
6061
6062
6063def replace_children(expression: Expression, fun: t.Callable, *args, **kwargs) -> None:
6064    """
6065    Replace children of an expression with the result of a lambda fun(child) -> exp.
6066    """
6067    for k, v in expression.args.items():
6068        is_list_arg = type(v) is list
6069
6070        child_nodes = v if is_list_arg else [v]
6071        new_child_nodes = []
6072
6073        for cn in child_nodes:
6074            if isinstance(cn, Expression):
6075                for child_node in ensure_collection(fun(cn, *args, **kwargs)):
6076                    new_child_nodes.append(child_node)
6077                    child_node.parent = expression
6078                    child_node.arg_key = k
6079            else:
6080                new_child_nodes.append(cn)
6081
6082        expression.args[k] = new_child_nodes if is_list_arg else seq_get(new_child_nodes, 0)
6083
6084
6085def column_table_names(expression: Expression, exclude: str = "") -> t.Set[str]:
6086    """
6087    Return all table names referenced through columns in an expression.
6088
6089    Example:
6090        >>> import sqlglot
6091        >>> sorted(column_table_names(sqlglot.parse_one("a.b AND c.d AND c.e")))
6092        ['a', 'c']
6093
6094    Args:
6095        expression: expression to find table names.
6096        exclude: a table name to exclude
6097
6098    Returns:
6099        A list of unique names.
6100    """
6101    return {
6102        table
6103        for table in (column.table for column in expression.find_all(Column))
6104        if table and table != exclude
6105    }
6106
6107
6108def table_name(table: Table | str, dialect: DialectType = None) -> str:
6109    """Get the full name of a table as a string.
6110
6111    Args:
6112        table: Table expression node or string.
6113        dialect: The dialect to generate the table name for.
6114
6115    Examples:
6116        >>> from sqlglot import exp, parse_one
6117        >>> table_name(parse_one("select * from a.b.c").find(exp.Table))
6118        'a.b.c'
6119
6120    Returns:
6121        The table name.
6122    """
6123
6124    table = maybe_parse(table, into=Table)
6125
6126    if not table:
6127        raise ValueError(f"Cannot parse {table}")
6128
6129    return ".".join(
6130        part.sql(dialect=dialect, identify=True)
6131        if not SAFE_IDENTIFIER_RE.match(part.name)
6132        else part.name
6133        for part in table.parts
6134    )
6135
6136
6137def replace_tables(expression: E, mapping: t.Dict[str, str], copy: bool = True) -> E:
6138    """Replace all tables in expression according to the mapping.
6139
6140    Args:
6141        expression: expression node to be transformed and replaced.
6142        mapping: mapping of table names.
6143        copy: whether or not to copy the expression.
6144
6145    Examples:
6146        >>> from sqlglot import exp, parse_one
6147        >>> replace_tables(parse_one("select * from a.b"), {"a.b": "c"}).sql()
6148        'SELECT * FROM c'
6149
6150    Returns:
6151        The mapped expression.
6152    """
6153
6154    def _replace_tables(node: Expression) -> Expression:
6155        if isinstance(node, Table):
6156            new_name = mapping.get(table_name(node))
6157            if new_name:
6158                return to_table(
6159                    new_name,
6160                    **{k: v for k, v in node.args.items() if k not in ("this", "db", "catalog")},
6161                )
6162        return node
6163
6164    return expression.transform(_replace_tables, copy=copy)
6165
6166
6167def replace_placeholders(expression: Expression, *args, **kwargs) -> Expression:
6168    """Replace placeholders in an expression.
6169
6170    Args:
6171        expression: expression node to be transformed and replaced.
6172        args: positional names that will substitute unnamed placeholders in the given order.
6173        kwargs: keyword arguments that will substitute named placeholders.
6174
6175    Examples:
6176        >>> from sqlglot import exp, parse_one
6177        >>> replace_placeholders(
6178        ...     parse_one("select * from :tbl where ? = ?"),
6179        ...     exp.to_identifier("str_col"), "b", tbl=exp.to_identifier("foo")
6180        ... ).sql()
6181        "SELECT * FROM foo WHERE str_col = 'b'"
6182
6183    Returns:
6184        The mapped expression.
6185    """
6186
6187    def _replace_placeholders(node: Expression, args, **kwargs) -> Expression:
6188        if isinstance(node, Placeholder):
6189            if node.name:
6190                new_name = kwargs.get(node.name)
6191                if new_name:
6192                    return convert(new_name)
6193            else:
6194                try:
6195                    return convert(next(args))
6196                except StopIteration:
6197                    pass
6198        return node
6199
6200    return expression.transform(_replace_placeholders, iter(args), **kwargs)
6201
6202
6203def expand(
6204    expression: Expression, sources: t.Dict[str, Subqueryable], copy: bool = True
6205) -> Expression:
6206    """Transforms an expression by expanding all referenced sources into subqueries.
6207
6208    Examples:
6209        >>> from sqlglot import parse_one
6210        >>> expand(parse_one("select * from x AS z"), {"x": parse_one("select * from y")}).sql()
6211        'SELECT * FROM (SELECT * FROM y) AS z /* source: x */'
6212
6213        >>> expand(parse_one("select * from x AS z"), {"x": parse_one("select * from y"), "y": parse_one("select * from z")}).sql()
6214        'SELECT * FROM (SELECT * FROM (SELECT * FROM z) AS y /* source: y */) AS z /* source: x */'
6215
6216    Args:
6217        expression: The expression to expand.
6218        sources: A dictionary of name to Subqueryables.
6219        copy: Whether or not to copy the expression during transformation. Defaults to True.
6220
6221    Returns:
6222        The transformed expression.
6223    """
6224
6225    def _expand(node: Expression):
6226        if isinstance(node, Table):
6227            name = table_name(node)
6228            source = sources.get(name)
6229            if source:
6230                subquery = source.subquery(node.alias or name)
6231                subquery.comments = [f"source: {name}"]
6232                return subquery.transform(_expand, copy=False)
6233        return node
6234
6235    return expression.transform(_expand, copy=copy)
6236
6237
6238def func(name: str, *args, dialect: DialectType = None, **kwargs) -> Func:
6239    """
6240    Returns a Func expression.
6241
6242    Examples:
6243        >>> func("abs", 5).sql()
6244        'ABS(5)'
6245
6246        >>> func("cast", this=5, to=DataType.build("DOUBLE")).sql()
6247        'CAST(5 AS DOUBLE)'
6248
6249    Args:
6250        name: the name of the function to build.
6251        args: the args used to instantiate the function of interest.
6252        dialect: the source dialect.
6253        kwargs: the kwargs used to instantiate the function of interest.
6254
6255    Note:
6256        The arguments `args` and `kwargs` are mutually exclusive.
6257
6258    Returns:
6259        An instance of the function of interest, or an anonymous function, if `name` doesn't
6260        correspond to an existing `sqlglot.expressions.Func` class.
6261    """
6262    if args and kwargs:
6263        raise ValueError("Can't use both args and kwargs to instantiate a function.")
6264
6265    from sqlglot.dialects.dialect import Dialect
6266
6267    converted: t.List[Expression] = [maybe_parse(arg, dialect=dialect) for arg in args]
6268    kwargs = {key: maybe_parse(value, dialect=dialect) for key, value in kwargs.items()}
6269
6270    parser = Dialect.get_or_raise(dialect)().parser()
6271    from_args_list = parser.FUNCTIONS.get(name.upper())
6272
6273    if from_args_list:
6274        function = from_args_list(converted) if converted else from_args_list.__self__(**kwargs)  # type: ignore
6275    else:
6276        kwargs = kwargs or {"expressions": converted}
6277        function = Anonymous(this=name, **kwargs)
6278
6279    for error_message in function.error_messages(converted):
6280        raise ValueError(error_message)
6281
6282    return function
6283
6284
6285def true() -> Boolean:
6286    """
6287    Returns a true Boolean expression.
6288    """
6289    return Boolean(this=True)
6290
6291
6292def false() -> Boolean:
6293    """
6294    Returns a false Boolean expression.
6295    """
6296    return Boolean(this=False)
6297
6298
6299def null() -> Null:
6300    """
6301    Returns a Null expression.
6302    """
6303    return Null()
6304
6305
6306# TODO: deprecate this
6307TRUE = Boolean(this=True)
6308FALSE = Boolean(this=False)
6309NULL = Null()