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