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