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