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