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, "options": False}
1937
1938
1939class TitleColumnConstraint(ColumnConstraintKind):
1940    pass
1941
1942
1943class UniqueColumnConstraint(ColumnConstraintKind):
1944    arg_types = {
1945        "this": False,
1946        "index_type": False,
1947        "on_conflict": False,
1948        "nulls": False,
1949        "options": False,
1950    }
1951
1952
1953class UppercaseColumnConstraint(ColumnConstraintKind):
1954    arg_types: t.Dict[str, t.Any] = {}
1955
1956
1957# https://docs.risingwave.com/processing/watermarks#syntax
1958class WatermarkColumnConstraint(Expression):
1959    arg_types = {"this": True, "expression": True}
1960
1961
1962class PathColumnConstraint(ColumnConstraintKind):
1963    pass
1964
1965
1966# https://docs.snowflake.com/en/sql-reference/sql/create-table
1967class ProjectionPolicyColumnConstraint(ColumnConstraintKind):
1968    pass
1969
1970
1971# computed column expression
1972# https://learn.microsoft.com/en-us/sql/t-sql/statements/create-table-transact-sql?view=sql-server-ver16
1973class ComputedColumnConstraint(ColumnConstraintKind):
1974    arg_types = {"this": True, "persisted": False, "not_null": False}
1975
1976
1977class Constraint(Expression):
1978    arg_types = {"this": True, "expressions": True}
1979
1980
1981class Delete(DML):
1982    arg_types = {
1983        "with": False,
1984        "this": False,
1985        "using": False,
1986        "where": False,
1987        "returning": False,
1988        "limit": False,
1989        "tables": False,  # Multiple-Table Syntax (MySQL)
1990        "cluster": False,  # Clickhouse
1991    }
1992
1993    def delete(
1994        self,
1995        table: ExpOrStr,
1996        dialect: DialectType = None,
1997        copy: bool = True,
1998        **opts,
1999    ) -> Delete:
2000        """
2001        Create a DELETE expression or replace the table on an existing DELETE expression.
2002
2003        Example:
2004            >>> delete("tbl").sql()
2005            'DELETE FROM tbl'
2006
2007        Args:
2008            table: the table from which to delete.
2009            dialect: the dialect used to parse the input expression.
2010            copy: if `False`, modify this expression instance in-place.
2011            opts: other options to use to parse the input expressions.
2012
2013        Returns:
2014            Delete: the modified expression.
2015        """
2016        return _apply_builder(
2017            expression=table,
2018            instance=self,
2019            arg="this",
2020            dialect=dialect,
2021            into=Table,
2022            copy=copy,
2023            **opts,
2024        )
2025
2026    def where(
2027        self,
2028        *expressions: t.Optional[ExpOrStr],
2029        append: bool = True,
2030        dialect: DialectType = None,
2031        copy: bool = True,
2032        **opts,
2033    ) -> Delete:
2034        """
2035        Append to or set the WHERE expressions.
2036
2037        Example:
2038            >>> delete("tbl").where("x = 'a' OR x < 'b'").sql()
2039            "DELETE FROM tbl WHERE x = 'a' OR x < 'b'"
2040
2041        Args:
2042            *expressions: the SQL code strings to parse.
2043                If an `Expression` instance is passed, it will be used as-is.
2044                Multiple expressions are combined with an AND operator.
2045            append: if `True`, AND the new expressions to any existing expression.
2046                Otherwise, this resets the expression.
2047            dialect: the dialect used to parse the input expressions.
2048            copy: if `False`, modify this expression instance in-place.
2049            opts: other options to use to parse the input expressions.
2050
2051        Returns:
2052            Delete: the modified expression.
2053        """
2054        return _apply_conjunction_builder(
2055            *expressions,
2056            instance=self,
2057            arg="where",
2058            append=append,
2059            into=Where,
2060            dialect=dialect,
2061            copy=copy,
2062            **opts,
2063        )
2064
2065
2066class Drop(Expression):
2067    arg_types = {
2068        "this": False,
2069        "kind": False,
2070        "expressions": False,
2071        "exists": False,
2072        "temporary": False,
2073        "materialized": False,
2074        "cascade": False,
2075        "constraints": False,
2076        "purge": False,
2077        "cluster": False,
2078        "concurrently": False,
2079    }
2080
2081    @property
2082    def kind(self) -> t.Optional[str]:
2083        kind = self.args.get("kind")
2084        return kind and kind.upper()
2085
2086
2087# https://cloud.google.com/bigquery/docs/reference/standard-sql/export-statements
2088class Export(Expression):
2089    arg_types = {"this": True, "connection": False, "options": True}
2090
2091
2092class Filter(Expression):
2093    arg_types = {"this": True, "expression": True}
2094
2095
2096class Check(Expression):
2097    pass
2098
2099
2100class Changes(Expression):
2101    arg_types = {"information": True, "at_before": False, "end": False}
2102
2103
2104# https://docs.snowflake.com/en/sql-reference/constructs/connect-by
2105class Connect(Expression):
2106    arg_types = {"start": False, "connect": True, "nocycle": False}
2107
2108
2109class CopyParameter(Expression):
2110    arg_types = {"this": True, "expression": False, "expressions": False}
2111
2112
2113class Copy(DML):
2114    arg_types = {
2115        "this": True,
2116        "kind": True,
2117        "files": True,
2118        "credentials": False,
2119        "format": False,
2120        "params": False,
2121    }
2122
2123
2124class Credentials(Expression):
2125    arg_types = {
2126        "credentials": False,
2127        "encryption": False,
2128        "storage": False,
2129        "iam_role": False,
2130        "region": False,
2131    }
2132
2133
2134class Prior(Expression):
2135    pass
2136
2137
2138class Directory(Expression):
2139    # https://spark.apache.org/docs/3.0.0-preview/sql-ref-syntax-dml-insert-overwrite-directory-hive.html
2140    arg_types = {"this": True, "local": False, "row_format": False}
2141
2142
2143class ForeignKey(Expression):
2144    arg_types = {
2145        "expressions": False,
2146        "reference": False,
2147        "delete": False,
2148        "update": False,
2149        "options": False,
2150    }
2151
2152
2153class ColumnPrefix(Expression):
2154    arg_types = {"this": True, "expression": True}
2155
2156
2157class PrimaryKey(Expression):
2158    arg_types = {"expressions": True, "options": False}
2159
2160
2161# https://www.postgresql.org/docs/9.1/sql-selectinto.html
2162# https://docs.aws.amazon.com/redshift/latest/dg/r_SELECT_INTO.html#r_SELECT_INTO-examples
2163class Into(Expression):
2164    arg_types = {
2165        "this": False,
2166        "temporary": False,
2167        "unlogged": False,
2168        "bulk_collect": False,
2169        "expressions": False,
2170    }
2171
2172
2173class From(Expression):
2174    @property
2175    def name(self) -> str:
2176        return self.this.name
2177
2178    @property
2179    def alias_or_name(self) -> str:
2180        return self.this.alias_or_name
2181
2182
2183class Having(Expression):
2184    pass
2185
2186
2187class Hint(Expression):
2188    arg_types = {"expressions": True}
2189
2190
2191class JoinHint(Expression):
2192    arg_types = {"this": True, "expressions": True}
2193
2194
2195class Identifier(Expression):
2196    arg_types = {"this": True, "quoted": False, "global": False, "temporary": False}
2197
2198    @property
2199    def quoted(self) -> bool:
2200        return bool(self.args.get("quoted"))
2201
2202    @property
2203    def hashable_args(self) -> t.Any:
2204        return (self.this, self.quoted)
2205
2206    @property
2207    def output_name(self) -> str:
2208        return self.name
2209
2210
2211# https://www.postgresql.org/docs/current/indexes-opclass.html
2212class Opclass(Expression):
2213    arg_types = {"this": True, "expression": True}
2214
2215
2216class Index(Expression):
2217    arg_types = {
2218        "this": False,
2219        "table": False,
2220        "unique": False,
2221        "primary": False,
2222        "amp": False,  # teradata
2223        "params": False,
2224    }
2225
2226
2227class IndexParameters(Expression):
2228    arg_types = {
2229        "using": False,
2230        "include": False,
2231        "columns": False,
2232        "with_storage": False,
2233        "partition_by": False,
2234        "tablespace": False,
2235        "where": False,
2236        "on": False,
2237    }
2238
2239
2240class Insert(DDL, DML):
2241    arg_types = {
2242        "hint": False,
2243        "with": False,
2244        "is_function": False,
2245        "this": False,
2246        "expression": False,
2247        "conflict": False,
2248        "returning": False,
2249        "overwrite": False,
2250        "exists": False,
2251        "alternative": False,
2252        "where": False,
2253        "ignore": False,
2254        "by_name": False,
2255        "stored": False,
2256        "partition": False,
2257        "settings": False,
2258        "source": False,
2259    }
2260
2261    def with_(
2262        self,
2263        alias: ExpOrStr,
2264        as_: ExpOrStr,
2265        recursive: t.Optional[bool] = None,
2266        materialized: t.Optional[bool] = None,
2267        append: bool = True,
2268        dialect: DialectType = None,
2269        copy: bool = True,
2270        **opts,
2271    ) -> Insert:
2272        """
2273        Append to or set the common table expressions.
2274
2275        Example:
2276            >>> insert("SELECT x FROM cte", "t").with_("cte", as_="SELECT * FROM tbl").sql()
2277            'WITH cte AS (SELECT * FROM tbl) INSERT INTO t SELECT x FROM cte'
2278
2279        Args:
2280            alias: the SQL code string to parse as the table name.
2281                If an `Expression` instance is passed, this is used as-is.
2282            as_: the SQL code string to parse as the table expression.
2283                If an `Expression` instance is passed, it will be used as-is.
2284            recursive: set the RECURSIVE part of the expression. Defaults to `False`.
2285            materialized: set the MATERIALIZED part of the expression.
2286            append: if `True`, add to any existing expressions.
2287                Otherwise, this resets the expressions.
2288            dialect: the dialect used to parse the input expression.
2289            copy: if `False`, modify this expression instance in-place.
2290            opts: other options to use to parse the input expressions.
2291
2292        Returns:
2293            The modified expression.
2294        """
2295        return _apply_cte_builder(
2296            self,
2297            alias,
2298            as_,
2299            recursive=recursive,
2300            materialized=materialized,
2301            append=append,
2302            dialect=dialect,
2303            copy=copy,
2304            **opts,
2305        )
2306
2307
2308class ConditionalInsert(Expression):
2309    arg_types = {"this": True, "expression": False, "else_": False}
2310
2311
2312class MultitableInserts(Expression):
2313    arg_types = {"expressions": True, "kind": True, "source": True}
2314
2315
2316class OnConflict(Expression):
2317    arg_types = {
2318        "duplicate": False,
2319        "expressions": False,
2320        "action": False,
2321        "conflict_keys": False,
2322        "constraint": False,
2323        "where": False,
2324    }
2325
2326
2327class OnCondition(Expression):
2328    arg_types = {"error": False, "empty": False, "null": False}
2329
2330
2331class Returning(Expression):
2332    arg_types = {"expressions": True, "into": False}
2333
2334
2335# https://dev.mysql.com/doc/refman/8.0/en/charset-introducer.html
2336class Introducer(Expression):
2337    arg_types = {"this": True, "expression": True}
2338
2339
2340# national char, like n'utf8'
2341class National(Expression):
2342    pass
2343
2344
2345class LoadData(Expression):
2346    arg_types = {
2347        "this": True,
2348        "local": False,
2349        "overwrite": False,
2350        "inpath": True,
2351        "partition": False,
2352        "input_format": False,
2353        "serde": False,
2354    }
2355
2356
2357class Partition(Expression):
2358    arg_types = {"expressions": True, "subpartition": False}
2359
2360
2361class PartitionRange(Expression):
2362    arg_types = {"this": True, "expression": True}
2363
2364
2365# https://clickhouse.com/docs/en/sql-reference/statements/alter/partition#how-to-set-partition-expression
2366class PartitionId(Expression):
2367    pass
2368
2369
2370class Fetch(Expression):
2371    arg_types = {
2372        "direction": False,
2373        "count": False,
2374        "limit_options": False,
2375    }
2376
2377
2378class Grant(Expression):
2379    arg_types = {
2380        "privileges": True,
2381        "kind": False,
2382        "securable": True,
2383        "principals": True,
2384        "grant_option": False,
2385    }
2386
2387
2388class Group(Expression):
2389    arg_types = {
2390        "expressions": False,
2391        "grouping_sets": False,
2392        "cube": False,
2393        "rollup": False,
2394        "totals": False,
2395        "all": False,
2396    }
2397
2398
2399class Cube(Expression):
2400    arg_types = {"expressions": False}
2401
2402
2403class Rollup(Expression):
2404    arg_types = {"expressions": False}
2405
2406
2407class GroupingSets(Expression):
2408    arg_types = {"expressions": True}
2409
2410
2411class Lambda(Expression):
2412    arg_types = {"this": True, "expressions": True}
2413
2414
2415class Limit(Expression):
2416    arg_types = {
2417        "this": False,
2418        "expression": True,
2419        "offset": False,
2420        "limit_options": False,
2421        "expressions": False,
2422    }
2423
2424
2425class LimitOptions(Expression):
2426    arg_types = {
2427        "percent": False,
2428        "rows": False,
2429        "with_ties": False,
2430    }
2431
2432
2433class Literal(Condition):
2434    arg_types = {"this": True, "is_string": True}
2435
2436    @property
2437    def hashable_args(self) -> t.Any:
2438        return (self.this, self.args.get("is_string"))
2439
2440    @classmethod
2441    def number(cls, number) -> Literal:
2442        return cls(this=str(number), is_string=False)
2443
2444    @classmethod
2445    def string(cls, string) -> Literal:
2446        return cls(this=str(string), is_string=True)
2447
2448    @property
2449    def output_name(self) -> str:
2450        return self.name
2451
2452    def to_py(self) -> int | str | Decimal:
2453        if self.is_number:
2454            try:
2455                return int(self.this)
2456            except ValueError:
2457                return Decimal(self.this)
2458        return self.this
2459
2460
2461class Join(Expression):
2462    arg_types = {
2463        "this": True,
2464        "on": False,
2465        "side": False,
2466        "kind": False,
2467        "using": False,
2468        "method": False,
2469        "global": False,
2470        "hint": False,
2471        "match_condition": False,  # Snowflake
2472        "expressions": False,
2473    }
2474
2475    @property
2476    def method(self) -> str:
2477        return self.text("method").upper()
2478
2479    @property
2480    def kind(self) -> str:
2481        return self.text("kind").upper()
2482
2483    @property
2484    def side(self) -> str:
2485        return self.text("side").upper()
2486
2487    @property
2488    def hint(self) -> str:
2489        return self.text("hint").upper()
2490
2491    @property
2492    def alias_or_name(self) -> str:
2493        return self.this.alias_or_name
2494
2495    @property
2496    def is_semi_or_anti_join(self) -> bool:
2497        return self.kind in ("SEMI", "ANTI")
2498
2499    def on(
2500        self,
2501        *expressions: t.Optional[ExpOrStr],
2502        append: bool = True,
2503        dialect: DialectType = None,
2504        copy: bool = True,
2505        **opts,
2506    ) -> Join:
2507        """
2508        Append to or set the ON expressions.
2509
2510        Example:
2511            >>> import sqlglot
2512            >>> sqlglot.parse_one("JOIN x", into=Join).on("y = 1").sql()
2513            'JOIN x ON y = 1'
2514
2515        Args:
2516            *expressions: the SQL code strings to parse.
2517                If an `Expression` instance is passed, it will be used as-is.
2518                Multiple expressions are combined with an AND operator.
2519            append: if `True`, AND the new expressions to any existing expression.
2520                Otherwise, this resets the expression.
2521            dialect: the dialect used to parse the input expressions.
2522            copy: if `False`, modify this expression instance in-place.
2523            opts: other options to use to parse the input expressions.
2524
2525        Returns:
2526            The modified Join expression.
2527        """
2528        join = _apply_conjunction_builder(
2529            *expressions,
2530            instance=self,
2531            arg="on",
2532            append=append,
2533            dialect=dialect,
2534            copy=copy,
2535            **opts,
2536        )
2537
2538        if join.kind == "CROSS":
2539            join.set("kind", None)
2540
2541        return join
2542
2543    def using(
2544        self,
2545        *expressions: t.Optional[ExpOrStr],
2546        append: bool = True,
2547        dialect: DialectType = None,
2548        copy: bool = True,
2549        **opts,
2550    ) -> Join:
2551        """
2552        Append to or set the USING expressions.
2553
2554        Example:
2555            >>> import sqlglot
2556            >>> sqlglot.parse_one("JOIN x", into=Join).using("foo", "bla").sql()
2557            'JOIN x USING (foo, bla)'
2558
2559        Args:
2560            *expressions: the SQL code strings to parse.
2561                If an `Expression` instance is passed, it will be used as-is.
2562            append: if `True`, concatenate the new expressions to the existing "using" list.
2563                Otherwise, this resets the expression.
2564            dialect: the dialect used to parse the input expressions.
2565            copy: if `False`, modify this expression instance in-place.
2566            opts: other options to use to parse the input expressions.
2567
2568        Returns:
2569            The modified Join expression.
2570        """
2571        join = _apply_list_builder(
2572            *expressions,
2573            instance=self,
2574            arg="using",
2575            append=append,
2576            dialect=dialect,
2577            copy=copy,
2578            **opts,
2579        )
2580
2581        if join.kind == "CROSS":
2582            join.set("kind", None)
2583
2584        return join
2585
2586
2587class Lateral(UDTF):
2588    arg_types = {
2589        "this": True,
2590        "view": False,
2591        "outer": False,
2592        "alias": False,
2593        "cross_apply": False,  # True -> CROSS APPLY, False -> OUTER APPLY
2594        "ordinality": False,
2595    }
2596
2597
2598# https://docs.snowflake.com/sql-reference/literals-table
2599# https://docs.snowflake.com/en/sql-reference/functions-table#using-a-table-function
2600class TableFromRows(UDTF):
2601    arg_types = {
2602        "this": True,
2603        "alias": False,
2604        "joins": False,
2605        "pivots": False,
2606        "sample": False,
2607    }
2608
2609
2610class MatchRecognizeMeasure(Expression):
2611    arg_types = {
2612        "this": True,
2613        "window_frame": False,
2614    }
2615
2616
2617class MatchRecognize(Expression):
2618    arg_types = {
2619        "partition_by": False,
2620        "order": False,
2621        "measures": False,
2622        "rows": False,
2623        "after": False,
2624        "pattern": False,
2625        "define": False,
2626        "alias": False,
2627    }
2628
2629
2630# Clickhouse FROM FINAL modifier
2631# https://clickhouse.com/docs/en/sql-reference/statements/select/from/#final-modifier
2632class Final(Expression):
2633    pass
2634
2635
2636class Offset(Expression):
2637    arg_types = {"this": False, "expression": True, "expressions": False}
2638
2639
2640class Order(Expression):
2641    arg_types = {"this": False, "expressions": True, "siblings": False}
2642
2643
2644# https://clickhouse.com/docs/en/sql-reference/statements/select/order-by#order-by-expr-with-fill-modifier
2645class WithFill(Expression):
2646    arg_types = {
2647        "from": False,
2648        "to": False,
2649        "step": False,
2650        "interpolate": False,
2651    }
2652
2653
2654# hive specific sorts
2655# https://cwiki.apache.org/confluence/display/Hive/LanguageManual+SortBy
2656class Cluster(Order):
2657    pass
2658
2659
2660class Distribute(Order):
2661    pass
2662
2663
2664class Sort(Order):
2665    pass
2666
2667
2668class Ordered(Expression):
2669    arg_types = {"this": True, "desc": False, "nulls_first": True, "with_fill": False}
2670
2671    @property
2672    def name(self) -> str:
2673        return self.this.name
2674
2675
2676class Property(Expression):
2677    arg_types = {"this": True, "value": True}
2678
2679
2680class GrantPrivilege(Expression):
2681    arg_types = {"this": True, "expressions": False}
2682
2683
2684class GrantPrincipal(Expression):
2685    arg_types = {"this": True, "kind": False}
2686
2687
2688class AllowedValuesProperty(Expression):
2689    arg_types = {"expressions": True}
2690
2691
2692class AlgorithmProperty(Property):
2693    arg_types = {"this": True}
2694
2695
2696class AutoIncrementProperty(Property):
2697    arg_types = {"this": True}
2698
2699
2700# https://docs.aws.amazon.com/prescriptive-guidance/latest/materialized-views-redshift/refreshing-materialized-views.html
2701class AutoRefreshProperty(Property):
2702    arg_types = {"this": True}
2703
2704
2705class BackupProperty(Property):
2706    arg_types = {"this": True}
2707
2708
2709class BlockCompressionProperty(Property):
2710    arg_types = {
2711        "autotemp": False,
2712        "always": False,
2713        "default": False,
2714        "manual": False,
2715        "never": False,
2716    }
2717
2718
2719class CharacterSetProperty(Property):
2720    arg_types = {"this": True, "default": True}
2721
2722
2723class ChecksumProperty(Property):
2724    arg_types = {"on": False, "default": False}
2725
2726
2727class CollateProperty(Property):
2728    arg_types = {"this": True, "default": False}
2729
2730
2731class CopyGrantsProperty(Property):
2732    arg_types = {}
2733
2734
2735class DataBlocksizeProperty(Property):
2736    arg_types = {
2737        "size": False,
2738        "units": False,
2739        "minimum": False,
2740        "maximum": False,
2741        "default": False,
2742    }
2743
2744
2745class DataDeletionProperty(Property):
2746    arg_types = {"on": True, "filter_col": False, "retention_period": False}
2747
2748
2749class DefinerProperty(Property):
2750    arg_types = {"this": True}
2751
2752
2753class DistKeyProperty(Property):
2754    arg_types = {"this": True}
2755
2756
2757# https://docs.starrocks.io/docs/sql-reference/sql-statements/data-definition/CREATE_TABLE/#distribution_desc
2758# https://doris.apache.org/docs/sql-manual/sql-statements/Data-Definition-Statements/Create/CREATE-TABLE?_highlight=create&_highlight=table#distribution_desc
2759class DistributedByProperty(Property):
2760    arg_types = {"expressions": False, "kind": True, "buckets": False, "order": False}
2761
2762
2763class DistStyleProperty(Property):
2764    arg_types = {"this": True}
2765
2766
2767class DuplicateKeyProperty(Property):
2768    arg_types = {"expressions": True}
2769
2770
2771class EngineProperty(Property):
2772    arg_types = {"this": True}
2773
2774
2775class HeapProperty(Property):
2776    arg_types = {}
2777
2778
2779class ToTableProperty(Property):
2780    arg_types = {"this": True}
2781
2782
2783class ExecuteAsProperty(Property):
2784    arg_types = {"this": True}
2785
2786
2787class ExternalProperty(Property):
2788    arg_types = {"this": False}
2789
2790
2791class FallbackProperty(Property):
2792    arg_types = {"no": True, "protection": False}
2793
2794
2795class FileFormatProperty(Property):
2796    arg_types = {"this": False, "expressions": False}
2797
2798
2799class CredentialsProperty(Property):
2800    arg_types = {"expressions": True}
2801
2802
2803class FreespaceProperty(Property):
2804    arg_types = {"this": True, "percent": False}
2805
2806
2807class GlobalProperty(Property):
2808    arg_types = {}
2809
2810
2811class IcebergProperty(Property):
2812    arg_types = {}
2813
2814
2815class InheritsProperty(Property):
2816    arg_types = {"expressions": True}
2817
2818
2819class InputModelProperty(Property):
2820    arg_types = {"this": True}
2821
2822
2823class OutputModelProperty(Property):
2824    arg_types = {"this": True}
2825
2826
2827class IsolatedLoadingProperty(Property):
2828    arg_types = {"no": False, "concurrent": False, "target": False}
2829
2830
2831class JournalProperty(Property):
2832    arg_types = {
2833        "no": False,
2834        "dual": False,
2835        "before": False,
2836        "local": False,
2837        "after": False,
2838    }
2839
2840
2841class LanguageProperty(Property):
2842    arg_types = {"this": True}
2843
2844
2845# spark ddl
2846class ClusteredByProperty(Property):
2847    arg_types = {"expressions": True, "sorted_by": False, "buckets": True}
2848
2849
2850class DictProperty(Property):
2851    arg_types = {"this": True, "kind": True, "settings": False}
2852
2853
2854class DictSubProperty(Property):
2855    pass
2856
2857
2858class DictRange(Property):
2859    arg_types = {"this": True, "min": True, "max": True}
2860
2861
2862class DynamicProperty(Property):
2863    arg_types = {}
2864
2865
2866# Clickhouse CREATE ... ON CLUSTER modifier
2867# https://clickhouse.com/docs/en/sql-reference/distributed-ddl
2868class OnCluster(Property):
2869    arg_types = {"this": True}
2870
2871
2872# Clickhouse EMPTY table "property"
2873class EmptyProperty(Property):
2874    arg_types = {}
2875
2876
2877class LikeProperty(Property):
2878    arg_types = {"this": True, "expressions": False}
2879
2880
2881class LocationProperty(Property):
2882    arg_types = {"this": True}
2883
2884
2885class LockProperty(Property):
2886    arg_types = {"this": True}
2887
2888
2889class LockingProperty(Property):
2890    arg_types = {
2891        "this": False,
2892        "kind": True,
2893        "for_or_in": False,
2894        "lock_type": True,
2895        "override": False,
2896    }
2897
2898
2899class LogProperty(Property):
2900    arg_types = {"no": True}
2901
2902
2903class MaterializedProperty(Property):
2904    arg_types = {"this": False}
2905
2906
2907class MergeBlockRatioProperty(Property):
2908    arg_types = {"this": False, "no": False, "default": False, "percent": False}
2909
2910
2911class NoPrimaryIndexProperty(Property):
2912    arg_types = {}
2913
2914
2915class OnProperty(Property):
2916    arg_types = {"this": True}
2917
2918
2919class OnCommitProperty(Property):
2920    arg_types = {"delete": False}
2921
2922
2923class PartitionedByProperty(Property):
2924    arg_types = {"this": True}
2925
2926
2927class PartitionedByBucket(Property):
2928    arg_types = {"this": True, "expression": True}
2929
2930
2931class PartitionByTruncate(Property):
2932    arg_types = {"this": True, "expression": True}
2933
2934
2935# https://docs.starrocks.io/docs/sql-reference/sql-statements/table_bucket_part_index/CREATE_TABLE/
2936class PartitionByRangeProperty(Property):
2937    arg_types = {"partition_expressions": True, "create_expressions": True}
2938
2939
2940# https://docs.starrocks.io/docs/table_design/data_distribution/#range-partitioning
2941class PartitionByRangePropertyDynamic(Expression):
2942    arg_types = {"this": False, "start": True, "end": True, "every": True}
2943
2944
2945# https://docs.starrocks.io/docs/sql-reference/sql-statements/table_bucket_part_index/CREATE_TABLE/
2946class UniqueKeyProperty(Property):
2947    arg_types = {"expressions": True}
2948
2949
2950# https://www.postgresql.org/docs/current/sql-createtable.html
2951class PartitionBoundSpec(Expression):
2952    # this -> IN / MODULUS, expression -> REMAINDER, from_expressions -> FROM (...), to_expressions -> TO (...)
2953    arg_types = {
2954        "this": False,
2955        "expression": False,
2956        "from_expressions": False,
2957        "to_expressions": False,
2958    }
2959
2960
2961class PartitionedOfProperty(Property):
2962    # this -> parent_table (schema), expression -> FOR VALUES ... / DEFAULT
2963    arg_types = {"this": True, "expression": True}
2964
2965
2966class StreamingTableProperty(Property):
2967    arg_types = {}
2968
2969
2970class RemoteWithConnectionModelProperty(Property):
2971    arg_types = {"this": True}
2972
2973
2974class ReturnsProperty(Property):
2975    arg_types = {"this": False, "is_table": False, "table": False, "null": False}
2976
2977
2978class StrictProperty(Property):
2979    arg_types = {}
2980
2981
2982class RowFormatProperty(Property):
2983    arg_types = {"this": True}
2984
2985
2986class RowFormatDelimitedProperty(Property):
2987    # https://cwiki.apache.org/confluence/display/hive/languagemanual+dml
2988    arg_types = {
2989        "fields": False,
2990        "escaped": False,
2991        "collection_items": False,
2992        "map_keys": False,
2993        "lines": False,
2994        "null": False,
2995        "serde": False,
2996    }
2997
2998
2999class RowFormatSerdeProperty(Property):
3000    arg_types = {"this": True, "serde_properties": False}
3001
3002
3003# https://spark.apache.org/docs/3.1.2/sql-ref-syntax-qry-select-transform.html
3004class QueryTransform(Expression):
3005    arg_types = {
3006        "expressions": True,
3007        "command_script": True,
3008        "schema": False,
3009        "row_format_before": False,
3010        "record_writer": False,
3011        "row_format_after": False,
3012        "record_reader": False,
3013    }
3014
3015
3016class SampleProperty(Property):
3017    arg_types = {"this": True}
3018
3019
3020# https://prestodb.io/docs/current/sql/create-view.html#synopsis
3021class SecurityProperty(Property):
3022    arg_types = {"this": True}
3023
3024
3025class SchemaCommentProperty(Property):
3026    arg_types = {"this": True}
3027
3028
3029class SerdeProperties(Property):
3030    arg_types = {"expressions": True, "with": False}
3031
3032
3033class SetProperty(Property):
3034    arg_types = {"multi": True}
3035
3036
3037class SharingProperty(Property):
3038    arg_types = {"this": False}
3039
3040
3041class SetConfigProperty(Property):
3042    arg_types = {"this": True}
3043
3044
3045class SettingsProperty(Property):
3046    arg_types = {"expressions": True}
3047
3048
3049class SortKeyProperty(Property):
3050    arg_types = {"this": True, "compound": False}
3051
3052
3053class SqlReadWriteProperty(Property):
3054    arg_types = {"this": True}
3055
3056
3057class SqlSecurityProperty(Property):
3058    arg_types = {"definer": True}
3059
3060
3061class StabilityProperty(Property):
3062    arg_types = {"this": True}
3063
3064
3065class StorageHandlerProperty(Property):
3066    arg_types = {"this": True}
3067
3068
3069class TemporaryProperty(Property):
3070    arg_types = {"this": False}
3071
3072
3073class SecureProperty(Property):
3074    arg_types = {}
3075
3076
3077# https://docs.snowflake.com/en/sql-reference/sql/create-table
3078class Tags(ColumnConstraintKind, Property):
3079    arg_types = {"expressions": True}
3080
3081
3082class TransformModelProperty(Property):
3083    arg_types = {"expressions": True}
3084
3085
3086class TransientProperty(Property):
3087    arg_types = {"this": False}
3088
3089
3090class UnloggedProperty(Property):
3091    arg_types = {}
3092
3093
3094# https://docs.snowflake.com/en/sql-reference/sql/create-table#create-table-using-template
3095class UsingTemplateProperty(Property):
3096    arg_types = {"this": True}
3097
3098
3099# https://learn.microsoft.com/en-us/sql/t-sql/statements/create-view-transact-sql?view=sql-server-ver16
3100class ViewAttributeProperty(Property):
3101    arg_types = {"this": True}
3102
3103
3104class VolatileProperty(Property):
3105    arg_types = {"this": False}
3106
3107
3108class WithDataProperty(Property):
3109    arg_types = {"no": True, "statistics": False}
3110
3111
3112class WithJournalTableProperty(Property):
3113    arg_types = {"this": True}
3114
3115
3116class WithSchemaBindingProperty(Property):
3117    arg_types = {"this": True}
3118
3119
3120class WithSystemVersioningProperty(Property):
3121    arg_types = {
3122        "on": False,
3123        "this": False,
3124        "data_consistency": False,
3125        "retention_period": False,
3126        "with": True,
3127    }
3128
3129
3130class WithProcedureOptions(Property):
3131    arg_types = {"expressions": True}
3132
3133
3134class EncodeProperty(Property):
3135    arg_types = {"this": True, "properties": False, "key": False}
3136
3137
3138class IncludeProperty(Property):
3139    arg_types = {"this": True, "alias": False, "column_def": False}
3140
3141
3142class ForceProperty(Property):
3143    arg_types = {}
3144
3145
3146class Properties(Expression):
3147    arg_types = {"expressions": True}
3148
3149    NAME_TO_PROPERTY = {
3150        "ALGORITHM": AlgorithmProperty,
3151        "AUTO_INCREMENT": AutoIncrementProperty,
3152        "CHARACTER SET": CharacterSetProperty,
3153        "CLUSTERED_BY": ClusteredByProperty,
3154        "COLLATE": CollateProperty,
3155        "COMMENT": SchemaCommentProperty,
3156        "CREDENTIALS": CredentialsProperty,
3157        "DEFINER": DefinerProperty,
3158        "DISTKEY": DistKeyProperty,
3159        "DISTRIBUTED_BY": DistributedByProperty,
3160        "DISTSTYLE": DistStyleProperty,
3161        "ENGINE": EngineProperty,
3162        "EXECUTE AS": ExecuteAsProperty,
3163        "FORMAT": FileFormatProperty,
3164        "LANGUAGE": LanguageProperty,
3165        "LOCATION": LocationProperty,
3166        "LOCK": LockProperty,
3167        "PARTITIONED_BY": PartitionedByProperty,
3168        "RETURNS": ReturnsProperty,
3169        "ROW_FORMAT": RowFormatProperty,
3170        "SORTKEY": SortKeyProperty,
3171        "ENCODE": EncodeProperty,
3172        "INCLUDE": IncludeProperty,
3173    }
3174
3175    PROPERTY_TO_NAME = {v: k for k, v in NAME_TO_PROPERTY.items()}
3176
3177    # CREATE property locations
3178    # Form: schema specified
3179    #   create [POST_CREATE]
3180    #     table a [POST_NAME]
3181    #     (b int) [POST_SCHEMA]
3182    #     with ([POST_WITH])
3183    #     index (b) [POST_INDEX]
3184    #
3185    # Form: alias selection
3186    #   create [POST_CREATE]
3187    #     table a [POST_NAME]
3188    #     as [POST_ALIAS] (select * from b) [POST_EXPRESSION]
3189    #     index (c) [POST_INDEX]
3190    class Location(AutoName):
3191        POST_CREATE = auto()
3192        POST_NAME = auto()
3193        POST_SCHEMA = auto()
3194        POST_WITH = auto()
3195        POST_ALIAS = auto()
3196        POST_EXPRESSION = auto()
3197        POST_INDEX = auto()
3198        UNSUPPORTED = auto()
3199
3200    @classmethod
3201    def from_dict(cls, properties_dict: t.Dict) -> Properties:
3202        expressions = []
3203        for key, value in properties_dict.items():
3204            property_cls = cls.NAME_TO_PROPERTY.get(key.upper())
3205            if property_cls:
3206                expressions.append(property_cls(this=convert(value)))
3207            else:
3208                expressions.append(Property(this=Literal.string(key), value=convert(value)))
3209
3210        return cls(expressions=expressions)
3211
3212
3213class Qualify(Expression):
3214    pass
3215
3216
3217class InputOutputFormat(Expression):
3218    arg_types = {"input_format": False, "output_format": False}
3219
3220
3221# https://www.ibm.com/docs/en/ias?topic=procedures-return-statement-in-sql
3222class Return(Expression):
3223    pass
3224
3225
3226class Reference(Expression):
3227    arg_types = {"this": True, "expressions": False, "options": False}
3228
3229
3230class Tuple(Expression):
3231    arg_types = {"expressions": False}
3232
3233    def isin(
3234        self,
3235        *expressions: t.Any,
3236        query: t.Optional[ExpOrStr] = None,
3237        unnest: t.Optional[ExpOrStr] | t.Collection[ExpOrStr] = None,
3238        copy: bool = True,
3239        **opts,
3240    ) -> In:
3241        return In(
3242            this=maybe_copy(self, copy),
3243            expressions=[convert(e, copy=copy) for e in expressions],
3244            query=maybe_parse(query, copy=copy, **opts) if query else None,
3245            unnest=(
3246                Unnest(
3247                    expressions=[
3248                        maybe_parse(t.cast(ExpOrStr, e), copy=copy, **opts)
3249                        for e in ensure_list(unnest)
3250                    ]
3251                )
3252                if unnest
3253                else None
3254            ),
3255        )
3256
3257
3258QUERY_MODIFIERS = {
3259    "match": False,
3260    "laterals": False,
3261    "joins": False,
3262    "connect": False,
3263    "pivots": False,
3264    "prewhere": False,
3265    "where": False,
3266    "group": False,
3267    "having": False,
3268    "qualify": False,
3269    "windows": False,
3270    "distribute": False,
3271    "sort": False,
3272    "cluster": False,
3273    "order": False,
3274    "limit": False,
3275    "offset": False,
3276    "locks": False,
3277    "sample": False,
3278    "settings": False,
3279    "format": False,
3280    "options": False,
3281}
3282
3283
3284# https://learn.microsoft.com/en-us/sql/t-sql/queries/option-clause-transact-sql?view=sql-server-ver16
3285# https://learn.microsoft.com/en-us/sql/t-sql/queries/hints-transact-sql-query?view=sql-server-ver16
3286class QueryOption(Expression):
3287    arg_types = {"this": True, "expression": False}
3288
3289
3290# https://learn.microsoft.com/en-us/sql/t-sql/queries/hints-transact-sql-table?view=sql-server-ver16
3291class WithTableHint(Expression):
3292    arg_types = {"expressions": True}
3293
3294
3295# https://dev.mysql.com/doc/refman/8.0/en/index-hints.html
3296class IndexTableHint(Expression):
3297    arg_types = {"this": True, "expressions": False, "target": False}
3298
3299
3300# https://docs.snowflake.com/en/sql-reference/constructs/at-before
3301class HistoricalData(Expression):
3302    arg_types = {"this": True, "kind": True, "expression": True}
3303
3304
3305# https://docs.snowflake.com/en/sql-reference/sql/put
3306class Put(Expression):
3307    arg_types = {"this": True, "target": True, "properties": False}
3308
3309
3310class Table(Expression):
3311    arg_types = {
3312        "this": False,
3313        "alias": False,
3314        "db": False,
3315        "catalog": False,
3316        "laterals": False,
3317        "joins": False,
3318        "pivots": False,
3319        "hints": False,
3320        "system_time": False,
3321        "version": False,
3322        "format": False,
3323        "pattern": False,
3324        "ordinality": False,
3325        "when": False,
3326        "only": False,
3327        "partition": False,
3328        "changes": False,
3329        "rows_from": False,
3330        "sample": False,
3331    }
3332
3333    @property
3334    def name(self) -> str:
3335        if not self.this or isinstance(self.this, Func):
3336            return ""
3337        return self.this.name
3338
3339    @property
3340    def db(self) -> str:
3341        return self.text("db")
3342
3343    @property
3344    def catalog(self) -> str:
3345        return self.text("catalog")
3346
3347    @property
3348    def selects(self) -> t.List[Expression]:
3349        return []
3350
3351    @property
3352    def named_selects(self) -> t.List[str]:
3353        return []
3354
3355    @property
3356    def parts(self) -> t.List[Expression]:
3357        """Return the parts of a table in order catalog, db, table."""
3358        parts: t.List[Expression] = []
3359
3360        for arg in ("catalog", "db", "this"):
3361            part = self.args.get(arg)
3362
3363            if isinstance(part, Dot):
3364                parts.extend(part.flatten())
3365            elif isinstance(part, Expression):
3366                parts.append(part)
3367
3368        return parts
3369
3370    def to_column(self, copy: bool = True) -> Expression:
3371        parts = self.parts
3372        last_part = parts[-1]
3373
3374        if isinstance(last_part, Identifier):
3375            col: Expression = column(*reversed(parts[0:4]), fields=parts[4:], copy=copy)  # type: ignore
3376        else:
3377            # This branch will be reached if a function or array is wrapped in a `Table`
3378            col = last_part
3379
3380        alias = self.args.get("alias")
3381        if alias:
3382            col = alias_(col, alias.this, copy=copy)
3383
3384        return col
3385
3386
3387class SetOperation(Query):
3388    arg_types = {
3389        "with": False,
3390        "this": True,
3391        "expression": True,
3392        "distinct": False,
3393        "by_name": False,
3394        "side": False,
3395        "kind": False,
3396        "on": False,
3397        **QUERY_MODIFIERS,
3398    }
3399
3400    def select(
3401        self: S,
3402        *expressions: t.Optional[ExpOrStr],
3403        append: bool = True,
3404        dialect: DialectType = None,
3405        copy: bool = True,
3406        **opts,
3407    ) -> S:
3408        this = maybe_copy(self, copy)
3409        this.this.unnest().select(*expressions, append=append, dialect=dialect, copy=False, **opts)
3410        this.expression.unnest().select(
3411            *expressions, append=append, dialect=dialect, copy=False, **opts
3412        )
3413        return this
3414
3415    @property
3416    def named_selects(self) -> t.List[str]:
3417        return self.this.unnest().named_selects
3418
3419    @property
3420    def is_star(self) -> bool:
3421        return self.this.is_star or self.expression.is_star
3422
3423    @property
3424    def selects(self) -> t.List[Expression]:
3425        return self.this.unnest().selects
3426
3427    @property
3428    def left(self) -> Query:
3429        return self.this
3430
3431    @property
3432    def right(self) -> Query:
3433        return self.expression
3434
3435    @property
3436    def kind(self) -> str:
3437        return self.text("kind").upper()
3438
3439    @property
3440    def side(self) -> str:
3441        return self.text("side").upper()
3442
3443
3444class Union(SetOperation):
3445    pass
3446
3447
3448class Except(SetOperation):
3449    pass
3450
3451
3452class Intersect(SetOperation):
3453    pass
3454
3455
3456class Update(DML):
3457    arg_types = {
3458        "with": False,
3459        "this": False,
3460        "expressions": True,
3461        "from": False,
3462        "where": False,
3463        "returning": False,
3464        "order": False,
3465        "limit": False,
3466    }
3467
3468    def table(
3469        self, expression: ExpOrStr, dialect: DialectType = None, copy: bool = True, **opts
3470    ) -> Update:
3471        """
3472        Set the table to update.
3473
3474        Example:
3475            >>> Update().table("my_table").set_("x = 1").sql()
3476            'UPDATE my_table SET x = 1'
3477
3478        Args:
3479            expression : the SQL code strings to parse.
3480                If a `Table` instance is passed, this is used as-is.
3481                If another `Expression` instance is passed, it will be wrapped in a `Table`.
3482            dialect: the dialect used to parse the input expression.
3483            copy: if `False`, modify this expression instance in-place.
3484            opts: other options to use to parse the input expressions.
3485
3486        Returns:
3487            The modified Update expression.
3488        """
3489        return _apply_builder(
3490            expression=expression,
3491            instance=self,
3492            arg="this",
3493            into=Table,
3494            prefix=None,
3495            dialect=dialect,
3496            copy=copy,
3497            **opts,
3498        )
3499
3500    def set_(
3501        self,
3502        *expressions: ExpOrStr,
3503        append: bool = True,
3504        dialect: DialectType = None,
3505        copy: bool = True,
3506        **opts,
3507    ) -> Update:
3508        """
3509        Append to or set the SET expressions.
3510
3511        Example:
3512            >>> Update().table("my_table").set_("x = 1").sql()
3513            'UPDATE my_table SET x = 1'
3514
3515        Args:
3516            *expressions: the SQL code strings to parse.
3517                If `Expression` instance(s) are passed, they will be used as-is.
3518                Multiple expressions are combined with a comma.
3519            append: if `True`, add the new expressions to any existing SET expressions.
3520                Otherwise, this resets the expressions.
3521            dialect: the dialect used to parse the input expressions.
3522            copy: if `False`, modify this expression instance in-place.
3523            opts: other options to use to parse the input expressions.
3524        """
3525        return _apply_list_builder(
3526            *expressions,
3527            instance=self,
3528            arg="expressions",
3529            append=append,
3530            into=Expression,
3531            prefix=None,
3532            dialect=dialect,
3533            copy=copy,
3534            **opts,
3535        )
3536
3537    def where(
3538        self,
3539        *expressions: t.Optional[ExpOrStr],
3540        append: bool = True,
3541        dialect: DialectType = None,
3542        copy: bool = True,
3543        **opts,
3544    ) -> Select:
3545        """
3546        Append to or set the WHERE expressions.
3547
3548        Example:
3549            >>> Update().table("tbl").set_("x = 1").where("x = 'a' OR x < 'b'").sql()
3550            "UPDATE tbl SET x = 1 WHERE x = 'a' OR x < 'b'"
3551
3552        Args:
3553            *expressions: the SQL code strings to parse.
3554                If an `Expression` instance is passed, it will be used as-is.
3555                Multiple expressions are combined with an AND operator.
3556            append: if `True`, AND the new expressions to any existing expression.
3557                Otherwise, this resets the expression.
3558            dialect: the dialect used to parse the input expressions.
3559            copy: if `False`, modify this expression instance in-place.
3560            opts: other options to use to parse the input expressions.
3561
3562        Returns:
3563            Select: the modified expression.
3564        """
3565        return _apply_conjunction_builder(
3566            *expressions,
3567            instance=self,
3568            arg="where",
3569            append=append,
3570            into=Where,
3571            dialect=dialect,
3572            copy=copy,
3573            **opts,
3574        )
3575
3576    def from_(
3577        self,
3578        expression: t.Optional[ExpOrStr] = None,
3579        dialect: DialectType = None,
3580        copy: bool = True,
3581        **opts,
3582    ) -> Update:
3583        """
3584        Set the FROM expression.
3585
3586        Example:
3587            >>> Update().table("my_table").set_("x = 1").from_("baz").sql()
3588            'UPDATE my_table SET x = 1 FROM baz'
3589
3590        Args:
3591            expression : the SQL code strings to parse.
3592                If a `From` instance is passed, this is used as-is.
3593                If another `Expression` instance is passed, it will be wrapped in a `From`.
3594                If nothing is passed in then a from is not applied to the expression
3595            dialect: the dialect used to parse the input expression.
3596            copy: if `False`, modify this expression instance in-place.
3597            opts: other options to use to parse the input expressions.
3598
3599        Returns:
3600            The modified Update expression.
3601        """
3602        if not expression:
3603            return maybe_copy(self, copy)
3604
3605        return _apply_builder(
3606            expression=expression,
3607            instance=self,
3608            arg="from",
3609            into=From,
3610            prefix="FROM",
3611            dialect=dialect,
3612            copy=copy,
3613            **opts,
3614        )
3615
3616    def with_(
3617        self,
3618        alias: ExpOrStr,
3619        as_: ExpOrStr,
3620        recursive: t.Optional[bool] = None,
3621        materialized: t.Optional[bool] = None,
3622        append: bool = True,
3623        dialect: DialectType = None,
3624        copy: bool = True,
3625        **opts,
3626    ) -> Update:
3627        """
3628        Append to or set the common table expressions.
3629
3630        Example:
3631            >>> Update().table("my_table").set_("x = 1").from_("baz").with_("baz", "SELECT id FROM foo").sql()
3632            'WITH baz AS (SELECT id FROM foo) UPDATE my_table SET x = 1 FROM baz'
3633
3634        Args:
3635            alias: the SQL code string to parse as the table name.
3636                If an `Expression` instance is passed, this is used as-is.
3637            as_: the SQL code string to parse as the table expression.
3638                If an `Expression` instance is passed, it will be used as-is.
3639            recursive: set the RECURSIVE part of the expression. Defaults to `False`.
3640            materialized: set the MATERIALIZED part of the expression.
3641            append: if `True`, add to any existing expressions.
3642                Otherwise, this resets the expressions.
3643            dialect: the dialect used to parse the input expression.
3644            copy: if `False`, modify this expression instance in-place.
3645            opts: other options to use to parse the input expressions.
3646
3647        Returns:
3648            The modified expression.
3649        """
3650        return _apply_cte_builder(
3651            self,
3652            alias,
3653            as_,
3654            recursive=recursive,
3655            materialized=materialized,
3656            append=append,
3657            dialect=dialect,
3658            copy=copy,
3659            **opts,
3660        )
3661
3662
3663class Values(UDTF):
3664    arg_types = {"expressions": True, "alias": False}
3665
3666
3667class Var(Expression):
3668    pass
3669
3670
3671class Version(Expression):
3672    """
3673    Time travel, iceberg, bigquery etc
3674    https://trino.io/docs/current/connector/iceberg.html?highlight=snapshot#using-snapshots
3675    https://www.databricks.com/blog/2019/02/04/introducing-delta-time-travel-for-large-scale-data-lakes.html
3676    https://cloud.google.com/bigquery/docs/reference/standard-sql/query-syntax#for_system_time_as_of
3677    https://learn.microsoft.com/en-us/sql/relational-databases/tables/querying-data-in-a-system-versioned-temporal-table?view=sql-server-ver16
3678    this is either TIMESTAMP or VERSION
3679    kind is ("AS OF", "BETWEEN")
3680    """
3681
3682    arg_types = {"this": True, "kind": True, "expression": False}
3683
3684
3685class Schema(Expression):
3686    arg_types = {"this": False, "expressions": False}
3687
3688
3689# https://dev.mysql.com/doc/refman/8.0/en/select.html
3690# https://docs.oracle.com/en/database/oracle/oracle-database/19/sqlrf/SELECT.html
3691class Lock(Expression):
3692    arg_types = {"update": True, "expressions": False, "wait": False}
3693
3694
3695class Select(Query):
3696    arg_types = {
3697        "with": False,
3698        "kind": False,
3699        "expressions": False,
3700        "hint": False,
3701        "distinct": False,
3702        "into": False,
3703        "from": False,
3704        "operation_modifiers": False,
3705        **QUERY_MODIFIERS,
3706    }
3707
3708    def from_(
3709        self, expression: ExpOrStr, dialect: DialectType = None, copy: bool = True, **opts
3710    ) -> Select:
3711        """
3712        Set the FROM expression.
3713
3714        Example:
3715            >>> Select().from_("tbl").select("x").sql()
3716            'SELECT x FROM tbl'
3717
3718        Args:
3719            expression : the SQL code strings to parse.
3720                If a `From` instance is passed, this is used as-is.
3721                If another `Expression` instance is passed, it will be wrapped in a `From`.
3722            dialect: the dialect used to parse the input expression.
3723            copy: if `False`, modify this expression instance in-place.
3724            opts: other options to use to parse the input expressions.
3725
3726        Returns:
3727            The modified Select expression.
3728        """
3729        return _apply_builder(
3730            expression=expression,
3731            instance=self,
3732            arg="from",
3733            into=From,
3734            prefix="FROM",
3735            dialect=dialect,
3736            copy=copy,
3737            **opts,
3738        )
3739
3740    def group_by(
3741        self,
3742        *expressions: t.Optional[ExpOrStr],
3743        append: bool = True,
3744        dialect: DialectType = None,
3745        copy: bool = True,
3746        **opts,
3747    ) -> Select:
3748        """
3749        Set the GROUP BY expression.
3750
3751        Example:
3752            >>> Select().from_("tbl").select("x", "COUNT(1)").group_by("x").sql()
3753            'SELECT x, COUNT(1) FROM tbl GROUP BY x'
3754
3755        Args:
3756            *expressions: the SQL code strings to parse.
3757                If a `Group` instance is passed, this is used as-is.
3758                If another `Expression` instance is passed, it will be wrapped in a `Group`.
3759                If nothing is passed in then a group by is not applied to the expression
3760            append: if `True`, add to any existing expressions.
3761                Otherwise, this flattens all the `Group` expression into a single expression.
3762            dialect: the dialect used to parse the input expression.
3763            copy: if `False`, modify this expression instance in-place.
3764            opts: other options to use to parse the input expressions.
3765
3766        Returns:
3767            The modified Select expression.
3768        """
3769        if not expressions:
3770            return self if not copy else self.copy()
3771
3772        return _apply_child_list_builder(
3773            *expressions,
3774            instance=self,
3775            arg="group",
3776            append=append,
3777            copy=copy,
3778            prefix="GROUP BY",
3779            into=Group,
3780            dialect=dialect,
3781            **opts,
3782        )
3783
3784    def sort_by(
3785        self,
3786        *expressions: t.Optional[ExpOrStr],
3787        append: bool = True,
3788        dialect: DialectType = None,
3789        copy: bool = True,
3790        **opts,
3791    ) -> Select:
3792        """
3793        Set the SORT BY expression.
3794
3795        Example:
3796            >>> Select().from_("tbl").select("x").sort_by("x DESC").sql(dialect="hive")
3797            'SELECT x FROM tbl SORT BY x DESC'
3798
3799        Args:
3800            *expressions: the SQL code strings to parse.
3801                If a `Group` instance is passed, this is used as-is.
3802                If another `Expression` instance is passed, it will be wrapped in a `SORT`.
3803            append: if `True`, add to any existing expressions.
3804                Otherwise, this flattens all the `Order` expression into a single expression.
3805            dialect: the dialect used to parse the input expression.
3806            copy: if `False`, modify this expression instance in-place.
3807            opts: other options to use to parse the input expressions.
3808
3809        Returns:
3810            The modified Select expression.
3811        """
3812        return _apply_child_list_builder(
3813            *expressions,
3814            instance=self,
3815            arg="sort",
3816            append=append,
3817            copy=copy,
3818            prefix="SORT BY",
3819            into=Sort,
3820            dialect=dialect,
3821            **opts,
3822        )
3823
3824    def cluster_by(
3825        self,
3826        *expressions: t.Optional[ExpOrStr],
3827        append: bool = True,
3828        dialect: DialectType = None,
3829        copy: bool = True,
3830        **opts,
3831    ) -> Select:
3832        """
3833        Set the CLUSTER BY expression.
3834
3835        Example:
3836            >>> Select().from_("tbl").select("x").cluster_by("x DESC").sql(dialect="hive")
3837            'SELECT x FROM tbl CLUSTER BY x DESC'
3838
3839        Args:
3840            *expressions: the SQL code strings to parse.
3841                If a `Group` instance is passed, this is used as-is.
3842                If another `Expression` instance is passed, it will be wrapped in a `Cluster`.
3843            append: if `True`, add to any existing expressions.
3844                Otherwise, this flattens all the `Order` expression into a single expression.
3845            dialect: the dialect used to parse the input expression.
3846            copy: if `False`, modify this expression instance in-place.
3847            opts: other options to use to parse the input expressions.
3848
3849        Returns:
3850            The modified Select expression.
3851        """
3852        return _apply_child_list_builder(
3853            *expressions,
3854            instance=self,
3855            arg="cluster",
3856            append=append,
3857            copy=copy,
3858            prefix="CLUSTER BY",
3859            into=Cluster,
3860            dialect=dialect,
3861            **opts,
3862        )
3863
3864    def select(
3865        self,
3866        *expressions: t.Optional[ExpOrStr],
3867        append: bool = True,
3868        dialect: DialectType = None,
3869        copy: bool = True,
3870        **opts,
3871    ) -> Select:
3872        return _apply_list_builder(
3873            *expressions,
3874            instance=self,
3875            arg="expressions",
3876            append=append,
3877            dialect=dialect,
3878            into=Expression,
3879            copy=copy,
3880            **opts,
3881        )
3882
3883    def lateral(
3884        self,
3885        *expressions: t.Optional[ExpOrStr],
3886        append: bool = True,
3887        dialect: DialectType = None,
3888        copy: bool = True,
3889        **opts,
3890    ) -> Select:
3891        """
3892        Append to or set the LATERAL expressions.
3893
3894        Example:
3895            >>> Select().select("x").lateral("OUTER explode(y) tbl2 AS z").from_("tbl").sql()
3896            'SELECT x FROM tbl LATERAL VIEW OUTER EXPLODE(y) tbl2 AS z'
3897
3898        Args:
3899            *expressions: the SQL code strings to parse.
3900                If an `Expression` instance is passed, it will be used as-is.
3901            append: if `True`, add to any existing expressions.
3902                Otherwise, this resets the expressions.
3903            dialect: the dialect used to parse the input expressions.
3904            copy: if `False`, modify this expression instance in-place.
3905            opts: other options to use to parse the input expressions.
3906
3907        Returns:
3908            The modified Select expression.
3909        """
3910        return _apply_list_builder(
3911            *expressions,
3912            instance=self,
3913            arg="laterals",
3914            append=append,
3915            into=Lateral,
3916            prefix="LATERAL VIEW",
3917            dialect=dialect,
3918            copy=copy,
3919            **opts,
3920        )
3921
3922    def join(
3923        self,
3924        expression: ExpOrStr,
3925        on: t.Optional[ExpOrStr] = None,
3926        using: t.Optional[ExpOrStr | t.Collection[ExpOrStr]] = None,
3927        append: bool = True,
3928        join_type: t.Optional[str] = None,
3929        join_alias: t.Optional[Identifier | str] = None,
3930        dialect: DialectType = None,
3931        copy: bool = True,
3932        **opts,
3933    ) -> Select:
3934        """
3935        Append to or set the JOIN expressions.
3936
3937        Example:
3938            >>> Select().select("*").from_("tbl").join("tbl2", on="tbl1.y = tbl2.y").sql()
3939            'SELECT * FROM tbl JOIN tbl2 ON tbl1.y = tbl2.y'
3940
3941            >>> Select().select("1").from_("a").join("b", using=["x", "y", "z"]).sql()
3942            'SELECT 1 FROM a JOIN b USING (x, y, z)'
3943
3944            Use `join_type` to change the type of join:
3945
3946            >>> Select().select("*").from_("tbl").join("tbl2", on="tbl1.y = tbl2.y", join_type="left outer").sql()
3947            'SELECT * FROM tbl LEFT OUTER JOIN tbl2 ON tbl1.y = tbl2.y'
3948
3949        Args:
3950            expression: the SQL code string to parse.
3951                If an `Expression` instance is passed, it will be used as-is.
3952            on: optionally specify the join "on" criteria as a SQL string.
3953                If an `Expression` instance is passed, it will be used as-is.
3954            using: optionally specify the join "using" criteria as a SQL string.
3955                If an `Expression` instance is passed, it will be used as-is.
3956            append: if `True`, add to any existing expressions.
3957                Otherwise, this resets the expressions.
3958            join_type: if set, alter the parsed join type.
3959            join_alias: an optional alias for the joined source.
3960            dialect: the dialect used to parse the input expressions.
3961            copy: if `False`, modify this expression instance in-place.
3962            opts: other options to use to parse the input expressions.
3963
3964        Returns:
3965            Select: the modified expression.
3966        """
3967        parse_args: t.Dict[str, t.Any] = {"dialect": dialect, **opts}
3968
3969        try:
3970            expression = maybe_parse(expression, into=Join, prefix="JOIN", **parse_args)
3971        except ParseError:
3972            expression = maybe_parse(expression, into=(Join, Expression), **parse_args)
3973
3974        join = expression if isinstance(expression, Join) else Join(this=expression)
3975
3976        if isinstance(join.this, Select):
3977            join.this.replace(join.this.subquery())
3978
3979        if join_type:
3980            method: t.Optional[Token]
3981            side: t.Optional[Token]
3982            kind: t.Optional[Token]
3983
3984            method, side, kind = maybe_parse(join_type, into="JOIN_TYPE", **parse_args)  # type: ignore
3985
3986            if method:
3987                join.set("method", method.text)
3988            if side:
3989                join.set("side", side.text)
3990            if kind:
3991                join.set("kind", kind.text)
3992
3993        if on:
3994            on = and_(*ensure_list(on), dialect=dialect, copy=copy, **opts)
3995            join.set("on", on)
3996
3997        if using:
3998            join = _apply_list_builder(
3999                *ensure_list(using),
4000                instance=join,
4001                arg="using",
4002                append=append,
4003                copy=copy,
4004                into=Identifier,
4005                **opts,
4006            )
4007
4008        if join_alias:
4009            join.set("this", alias_(join.this, join_alias, table=True))
4010
4011        return _apply_list_builder(
4012            join,
4013            instance=self,
4014            arg="joins",
4015            append=append,
4016            copy=copy,
4017            **opts,
4018        )
4019
4020    def where(
4021        self,
4022        *expressions: t.Optional[ExpOrStr],
4023        append: bool = True,
4024        dialect: DialectType = None,
4025        copy: bool = True,
4026        **opts,
4027    ) -> Select:
4028        """
4029        Append to or set the WHERE expressions.
4030
4031        Example:
4032            >>> Select().select("x").from_("tbl").where("x = 'a' OR x < 'b'").sql()
4033            "SELECT x FROM tbl WHERE x = 'a' OR x < 'b'"
4034
4035        Args:
4036            *expressions: the SQL code strings to parse.
4037                If an `Expression` instance is passed, it will be used as-is.
4038                Multiple expressions are combined with an AND operator.
4039            append: if `True`, AND the new expressions to any existing expression.
4040                Otherwise, this resets the expression.
4041            dialect: the dialect used to parse the input expressions.
4042            copy: if `False`, modify this expression instance in-place.
4043            opts: other options to use to parse the input expressions.
4044
4045        Returns:
4046            Select: the modified expression.
4047        """
4048        return _apply_conjunction_builder(
4049            *expressions,
4050            instance=self,
4051            arg="where",
4052            append=append,
4053            into=Where,
4054            dialect=dialect,
4055            copy=copy,
4056            **opts,
4057        )
4058
4059    def having(
4060        self,
4061        *expressions: t.Optional[ExpOrStr],
4062        append: bool = True,
4063        dialect: DialectType = None,
4064        copy: bool = True,
4065        **opts,
4066    ) -> Select:
4067        """
4068        Append to or set the HAVING expressions.
4069
4070        Example:
4071            >>> Select().select("x", "COUNT(y)").from_("tbl").group_by("x").having("COUNT(y) > 3").sql()
4072            'SELECT x, COUNT(y) FROM tbl GROUP BY x HAVING COUNT(y) > 3'
4073
4074        Args:
4075            *expressions: the SQL code strings to parse.
4076                If an `Expression` instance is passed, it will be used as-is.
4077                Multiple expressions are combined with an AND operator.
4078            append: if `True`, AND the new expressions to any existing expression.
4079                Otherwise, this resets the expression.
4080            dialect: the dialect used to parse the input expressions.
4081            copy: if `False`, modify this expression instance in-place.
4082            opts: other options to use to parse the input expressions.
4083
4084        Returns:
4085            The modified Select expression.
4086        """
4087        return _apply_conjunction_builder(
4088            *expressions,
4089            instance=self,
4090            arg="having",
4091            append=append,
4092            into=Having,
4093            dialect=dialect,
4094            copy=copy,
4095            **opts,
4096        )
4097
4098    def window(
4099        self,
4100        *expressions: t.Optional[ExpOrStr],
4101        append: bool = True,
4102        dialect: DialectType = None,
4103        copy: bool = True,
4104        **opts,
4105    ) -> Select:
4106        return _apply_list_builder(
4107            *expressions,
4108            instance=self,
4109            arg="windows",
4110            append=append,
4111            into=Window,
4112            dialect=dialect,
4113            copy=copy,
4114            **opts,
4115        )
4116
4117    def qualify(
4118        self,
4119        *expressions: t.Optional[ExpOrStr],
4120        append: bool = True,
4121        dialect: DialectType = None,
4122        copy: bool = True,
4123        **opts,
4124    ) -> Select:
4125        return _apply_conjunction_builder(
4126            *expressions,
4127            instance=self,
4128            arg="qualify",
4129            append=append,
4130            into=Qualify,
4131            dialect=dialect,
4132            copy=copy,
4133            **opts,
4134        )
4135
4136    def distinct(
4137        self, *ons: t.Optional[ExpOrStr], distinct: bool = True, copy: bool = True
4138    ) -> Select:
4139        """
4140        Set the OFFSET expression.
4141
4142        Example:
4143            >>> Select().from_("tbl").select("x").distinct().sql()
4144            'SELECT DISTINCT x FROM tbl'
4145
4146        Args:
4147            ons: the expressions to distinct on
4148            distinct: whether the Select should be distinct
4149            copy: if `False`, modify this expression instance in-place.
4150
4151        Returns:
4152            Select: the modified expression.
4153        """
4154        instance = maybe_copy(self, copy)
4155        on = Tuple(expressions=[maybe_parse(on, copy=copy) for on in ons if on]) if ons else None
4156        instance.set("distinct", Distinct(on=on) if distinct else None)
4157        return instance
4158
4159    def ctas(
4160        self,
4161        table: ExpOrStr,
4162        properties: t.Optional[t.Dict] = None,
4163        dialect: DialectType = None,
4164        copy: bool = True,
4165        **opts,
4166    ) -> Create:
4167        """
4168        Convert this expression to a CREATE TABLE AS statement.
4169
4170        Example:
4171            >>> Select().select("*").from_("tbl").ctas("x").sql()
4172            'CREATE TABLE x AS SELECT * FROM tbl'
4173
4174        Args:
4175            table: the SQL code string to parse as the table name.
4176                If another `Expression` instance is passed, it will be used as-is.
4177            properties: an optional mapping of table properties
4178            dialect: the dialect used to parse the input table.
4179            copy: if `False`, modify this expression instance in-place.
4180            opts: other options to use to parse the input table.
4181
4182        Returns:
4183            The new Create expression.
4184        """
4185        instance = maybe_copy(self, copy)
4186        table_expression = maybe_parse(table, into=Table, dialect=dialect, **opts)
4187
4188        properties_expression = None
4189        if properties:
4190            properties_expression = Properties.from_dict(properties)
4191
4192        return Create(
4193            this=table_expression,
4194            kind="TABLE",
4195            expression=instance,
4196            properties=properties_expression,
4197        )
4198
4199    def lock(self, update: bool = True, copy: bool = True) -> Select:
4200        """
4201        Set the locking read mode for this expression.
4202
4203        Examples:
4204            >>> Select().select("x").from_("tbl").where("x = 'a'").lock().sql("mysql")
4205            "SELECT x FROM tbl WHERE x = 'a' FOR UPDATE"
4206
4207            >>> Select().select("x").from_("tbl").where("x = 'a'").lock(update=False).sql("mysql")
4208            "SELECT x FROM tbl WHERE x = 'a' FOR SHARE"
4209
4210        Args:
4211            update: if `True`, the locking type will be `FOR UPDATE`, else it will be `FOR SHARE`.
4212            copy: if `False`, modify this expression instance in-place.
4213
4214        Returns:
4215            The modified expression.
4216        """
4217        inst = maybe_copy(self, copy)
4218        inst.set("locks", [Lock(update=update)])
4219
4220        return inst
4221
4222    def hint(self, *hints: ExpOrStr, dialect: DialectType = None, copy: bool = True) -> Select:
4223        """
4224        Set hints for this expression.
4225
4226        Examples:
4227            >>> Select().select("x").from_("tbl").hint("BROADCAST(y)").sql(dialect="spark")
4228            'SELECT /*+ BROADCAST(y) */ x FROM tbl'
4229
4230        Args:
4231            hints: The SQL code strings to parse as the hints.
4232                If an `Expression` instance is passed, it will be used as-is.
4233            dialect: The dialect used to parse the hints.
4234            copy: If `False`, modify this expression instance in-place.
4235
4236        Returns:
4237            The modified expression.
4238        """
4239        inst = maybe_copy(self, copy)
4240        inst.set(
4241            "hint", Hint(expressions=[maybe_parse(h, copy=copy, dialect=dialect) for h in hints])
4242        )
4243
4244        return inst
4245
4246    @property
4247    def named_selects(self) -> t.List[str]:
4248        return [e.output_name for e in self.expressions if e.alias_or_name]
4249
4250    @property
4251    def is_star(self) -> bool:
4252        return any(expression.is_star for expression in self.expressions)
4253
4254    @property
4255    def selects(self) -> t.List[Expression]:
4256        return self.expressions
4257
4258
4259UNWRAPPED_QUERIES = (Select, SetOperation)
4260
4261
4262class Subquery(DerivedTable, Query):
4263    arg_types = {
4264        "this": True,
4265        "alias": False,
4266        "with": False,
4267        **QUERY_MODIFIERS,
4268    }
4269
4270    def unnest(self):
4271        """Returns the first non subquery."""
4272        expression = self
4273        while isinstance(expression, Subquery):
4274            expression = expression.this
4275        return expression
4276
4277    def unwrap(self) -> Subquery:
4278        expression = self
4279        while expression.same_parent and expression.is_wrapper:
4280            expression = t.cast(Subquery, expression.parent)
4281        return expression
4282
4283    def select(
4284        self,
4285        *expressions: t.Optional[ExpOrStr],
4286        append: bool = True,
4287        dialect: DialectType = None,
4288        copy: bool = True,
4289        **opts,
4290    ) -> Subquery:
4291        this = maybe_copy(self, copy)
4292        this.unnest().select(*expressions, append=append, dialect=dialect, copy=False, **opts)
4293        return this
4294
4295    @property
4296    def is_wrapper(self) -> bool:
4297        """
4298        Whether this Subquery acts as a simple wrapper around another expression.
4299
4300        SELECT * FROM (((SELECT * FROM t)))
4301                      ^
4302                      This corresponds to a "wrapper" Subquery node
4303        """
4304        return all(v is None for k, v in self.args.items() if k != "this")
4305
4306    @property
4307    def is_star(self) -> bool:
4308        return self.this.is_star
4309
4310    @property
4311    def output_name(self) -> str:
4312        return self.alias
4313
4314
4315class TableSample(Expression):
4316    arg_types = {
4317        "expressions": False,
4318        "method": False,
4319        "bucket_numerator": False,
4320        "bucket_denominator": False,
4321        "bucket_field": False,
4322        "percent": False,
4323        "rows": False,
4324        "size": False,
4325        "seed": False,
4326    }
4327
4328
4329class Tag(Expression):
4330    """Tags are used for generating arbitrary sql like SELECT <span>x</span>."""
4331
4332    arg_types = {
4333        "this": False,
4334        "prefix": False,
4335        "postfix": False,
4336    }
4337
4338
4339# Represents both the standard SQL PIVOT operator and DuckDB's "simplified" PIVOT syntax
4340# https://duckdb.org/docs/sql/statements/pivot
4341class Pivot(Expression):
4342    arg_types = {
4343        "this": False,
4344        "alias": False,
4345        "expressions": False,
4346        "fields": False,
4347        "unpivot": False,
4348        "using": False,
4349        "group": False,
4350        "columns": False,
4351        "include_nulls": False,
4352        "default_on_null": False,
4353        "into": False,
4354    }
4355
4356    @property
4357    def unpivot(self) -> bool:
4358        return bool(self.args.get("unpivot"))
4359
4360    @property
4361    def fields(self) -> t.List[Expression]:
4362        return self.args.get("fields", [])
4363
4364
4365# https://duckdb.org/docs/sql/statements/unpivot#simplified-unpivot-syntax
4366# UNPIVOT ... INTO [NAME <col_name> VALUE <col_value>][...,]
4367class UnpivotColumns(Expression):
4368    arg_types = {"this": True, "expressions": True}
4369
4370
4371class Window(Condition):
4372    arg_types = {
4373        "this": True,
4374        "partition_by": False,
4375        "order": False,
4376        "spec": False,
4377        "alias": False,
4378        "over": False,
4379        "first": False,
4380    }
4381
4382
4383class WindowSpec(Expression):
4384    arg_types = {
4385        "kind": False,
4386        "start": False,
4387        "start_side": False,
4388        "end": False,
4389        "end_side": False,
4390    }
4391
4392
4393class PreWhere(Expression):
4394    pass
4395
4396
4397class Where(Expression):
4398    pass
4399
4400
4401class Star(Expression):
4402    arg_types = {"except": False, "replace": False, "rename": False}
4403
4404    @property
4405    def name(self) -> str:
4406        return "*"
4407
4408    @property
4409    def output_name(self) -> str:
4410        return self.name
4411
4412
4413class Parameter(Condition):
4414    arg_types = {"this": True, "expression": False}
4415
4416
4417class SessionParameter(Condition):
4418    arg_types = {"this": True, "kind": False}
4419
4420
4421class Placeholder(Condition):
4422    arg_types = {"this": False, "kind": False}
4423
4424    @property
4425    def name(self) -> str:
4426        return self.this or "?"
4427
4428
4429class Null(Condition):
4430    arg_types: t.Dict[str, t.Any] = {}
4431
4432    @property
4433    def name(self) -> str:
4434        return "NULL"
4435
4436    def to_py(self) -> Lit[None]:
4437        return None
4438
4439
4440class Boolean(Condition):
4441    def to_py(self) -> bool:
4442        return self.this
4443
4444
4445class DataTypeParam(Expression):
4446    arg_types = {"this": True, "expression": False}
4447
4448    @property
4449    def name(self) -> str:
4450        return self.this.name
4451
4452
4453# The `nullable` arg is helpful when transpiling types from other dialects to ClickHouse, which
4454# assumes non-nullable types by default. Values `None` and `True` mean the type is nullable.
4455class DataType(Expression):
4456    arg_types = {
4457        "this": True,
4458        "expressions": False,
4459        "nested": False,
4460        "values": False,
4461        "prefix": False,
4462        "kind": False,
4463        "nullable": False,
4464    }
4465
4466    class Type(AutoName):
4467        ARRAY = auto()
4468        AGGREGATEFUNCTION = auto()
4469        SIMPLEAGGREGATEFUNCTION = auto()
4470        BIGDECIMAL = auto()
4471        BIGINT = auto()
4472        BIGSERIAL = auto()
4473        BINARY = auto()
4474        BIT = auto()
4475        BLOB = auto()
4476        BOOLEAN = auto()
4477        BPCHAR = auto()
4478        CHAR = auto()
4479        DATE = auto()
4480        DATE32 = auto()
4481        DATEMULTIRANGE = auto()
4482        DATERANGE = auto()
4483        DATETIME = auto()
4484        DATETIME2 = auto()
4485        DATETIME64 = auto()
4486        DECIMAL = auto()
4487        DECIMAL32 = auto()
4488        DECIMAL64 = auto()
4489        DECIMAL128 = auto()
4490        DECIMAL256 = auto()
4491        DOUBLE = auto()
4492        DYNAMIC = auto()
4493        ENUM = auto()
4494        ENUM8 = auto()
4495        ENUM16 = auto()
4496        FIXEDSTRING = auto()
4497        FLOAT = auto()
4498        GEOGRAPHY = auto()
4499        GEOMETRY = auto()
4500        POINT = auto()
4501        RING = auto()
4502        LINESTRING = auto()
4503        MULTILINESTRING = auto()
4504        POLYGON = auto()
4505        MULTIPOLYGON = auto()
4506        HLLSKETCH = auto()
4507        HSTORE = auto()
4508        IMAGE = auto()
4509        INET = auto()
4510        INT = auto()
4511        INT128 = auto()
4512        INT256 = auto()
4513        INT4MULTIRANGE = auto()
4514        INT4RANGE = auto()
4515        INT8MULTIRANGE = auto()
4516        INT8RANGE = auto()
4517        INTERVAL = auto()
4518        IPADDRESS = auto()
4519        IPPREFIX = auto()
4520        IPV4 = auto()
4521        IPV6 = auto()
4522        JSON = auto()
4523        JSONB = auto()
4524        LIST = auto()
4525        LONGBLOB = auto()
4526        LONGTEXT = auto()
4527        LOWCARDINALITY = auto()
4528        MAP = auto()
4529        MEDIUMBLOB = auto()
4530        MEDIUMINT = auto()
4531        MEDIUMTEXT = auto()
4532        MONEY = auto()
4533        NAME = auto()
4534        NCHAR = auto()
4535        NESTED = auto()
4536        NOTHING = auto()
4537        NULL = auto()
4538        NUMMULTIRANGE = auto()
4539        NUMRANGE = auto()
4540        NVARCHAR = auto()
4541        OBJECT = auto()
4542        RANGE = auto()
4543        ROWVERSION = auto()
4544        SERIAL = auto()
4545        SET = auto()
4546        SMALLDATETIME = auto()
4547        SMALLINT = auto()
4548        SMALLMONEY = auto()
4549        SMALLSERIAL = auto()
4550        STRUCT = auto()
4551        SUPER = auto()
4552        TEXT = auto()
4553        TINYBLOB = auto()
4554        TINYTEXT = auto()
4555        TIME = auto()
4556        TIMETZ = auto()
4557        TIMESTAMP = auto()
4558        TIMESTAMPNTZ = auto()
4559        TIMESTAMPLTZ = auto()
4560        TIMESTAMPTZ = auto()
4561        TIMESTAMP_S = auto()
4562        TIMESTAMP_MS = auto()
4563        TIMESTAMP_NS = auto()
4564        TINYINT = auto()
4565        TSMULTIRANGE = auto()
4566        TSRANGE = auto()
4567        TSTZMULTIRANGE = auto()
4568        TSTZRANGE = auto()
4569        UBIGINT = auto()
4570        UINT = auto()
4571        UINT128 = auto()
4572        UINT256 = auto()
4573        UMEDIUMINT = auto()
4574        UDECIMAL = auto()
4575        UDOUBLE = auto()
4576        UNION = auto()
4577        UNKNOWN = auto()  # Sentinel value, useful for type annotation
4578        USERDEFINED = "USER-DEFINED"
4579        USMALLINT = auto()
4580        UTINYINT = auto()
4581        UUID = auto()
4582        VARBINARY = auto()
4583        VARCHAR = auto()
4584        VARIANT = auto()
4585        VECTOR = auto()
4586        XML = auto()
4587        YEAR = auto()
4588        TDIGEST = auto()
4589
4590    STRUCT_TYPES = {
4591        Type.NESTED,
4592        Type.OBJECT,
4593        Type.STRUCT,
4594        Type.UNION,
4595    }
4596
4597    ARRAY_TYPES = {
4598        Type.ARRAY,
4599        Type.LIST,
4600    }
4601
4602    NESTED_TYPES = {
4603        *STRUCT_TYPES,
4604        *ARRAY_TYPES,
4605        Type.MAP,
4606    }
4607
4608    TEXT_TYPES = {
4609        Type.CHAR,
4610        Type.NCHAR,
4611        Type.NVARCHAR,
4612        Type.TEXT,
4613        Type.VARCHAR,
4614        Type.NAME,
4615    }
4616
4617    SIGNED_INTEGER_TYPES = {
4618        Type.BIGINT,
4619        Type.INT,
4620        Type.INT128,
4621        Type.INT256,
4622        Type.MEDIUMINT,
4623        Type.SMALLINT,
4624        Type.TINYINT,
4625    }
4626
4627    UNSIGNED_INTEGER_TYPES = {
4628        Type.UBIGINT,
4629        Type.UINT,
4630        Type.UINT128,
4631        Type.UINT256,
4632        Type.UMEDIUMINT,
4633        Type.USMALLINT,
4634        Type.UTINYINT,
4635    }
4636
4637    INTEGER_TYPES = {
4638        *SIGNED_INTEGER_TYPES,
4639        *UNSIGNED_INTEGER_TYPES,
4640        Type.BIT,
4641    }
4642
4643    FLOAT_TYPES = {
4644        Type.DOUBLE,
4645        Type.FLOAT,
4646    }
4647
4648    REAL_TYPES = {
4649        *FLOAT_TYPES,
4650        Type.BIGDECIMAL,
4651        Type.DECIMAL,
4652        Type.DECIMAL32,
4653        Type.DECIMAL64,
4654        Type.DECIMAL128,
4655        Type.DECIMAL256,
4656        Type.MONEY,
4657        Type.SMALLMONEY,
4658        Type.UDECIMAL,
4659        Type.UDOUBLE,
4660    }
4661
4662    NUMERIC_TYPES = {
4663        *INTEGER_TYPES,
4664        *REAL_TYPES,
4665    }
4666
4667    TEMPORAL_TYPES = {
4668        Type.DATE,
4669        Type.DATE32,
4670        Type.DATETIME,
4671        Type.DATETIME2,
4672        Type.DATETIME64,
4673        Type.SMALLDATETIME,
4674        Type.TIME,
4675        Type.TIMESTAMP,
4676        Type.TIMESTAMPNTZ,
4677        Type.TIMESTAMPLTZ,
4678        Type.TIMESTAMPTZ,
4679        Type.TIMESTAMP_MS,
4680        Type.TIMESTAMP_NS,
4681        Type.TIMESTAMP_S,
4682        Type.TIMETZ,
4683    }
4684
4685    @classmethod
4686    def build(
4687        cls,
4688        dtype: DATA_TYPE,
4689        dialect: DialectType = None,
4690        udt: bool = False,
4691        copy: bool = True,
4692        **kwargs,
4693    ) -> DataType:
4694        """
4695        Constructs a DataType object.
4696
4697        Args:
4698            dtype: the data type of interest.
4699            dialect: the dialect to use for parsing `dtype`, in case it's a string.
4700            udt: when set to True, `dtype` will be used as-is if it can't be parsed into a
4701                DataType, thus creating a user-defined type.
4702            copy: whether to copy the data type.
4703            kwargs: additional arguments to pass in the constructor of DataType.
4704
4705        Returns:
4706            The constructed DataType object.
4707        """
4708        from sqlglot import parse_one
4709
4710        if isinstance(dtype, str):
4711            if dtype.upper() == "UNKNOWN":
4712                return DataType(this=DataType.Type.UNKNOWN, **kwargs)
4713
4714            try:
4715                data_type_exp = parse_one(
4716                    dtype, read=dialect, into=DataType, error_level=ErrorLevel.IGNORE
4717                )
4718            except ParseError:
4719                if udt:
4720                    return DataType(this=DataType.Type.USERDEFINED, kind=dtype, **kwargs)
4721                raise
4722        elif isinstance(dtype, DataType.Type):
4723            data_type_exp = DataType(this=dtype)
4724        elif isinstance(dtype, DataType):
4725            return maybe_copy(dtype, copy)
4726        else:
4727            raise ValueError(f"Invalid data type: {type(dtype)}. Expected str or DataType.Type")
4728
4729        return DataType(**{**data_type_exp.args, **kwargs})
4730
4731    def is_type(self, *dtypes: DATA_TYPE, check_nullable: bool = False) -> bool:
4732        """
4733        Checks whether this DataType matches one of the provided data types. Nested types or precision
4734        will be compared using "structural equivalence" semantics, so e.g. array<int> != array<float>.
4735
4736        Args:
4737            dtypes: the data types to compare this DataType to.
4738            check_nullable: whether to take the NULLABLE type constructor into account for the comparison.
4739                If false, it means that NULLABLE<INT> is equivalent to INT.
4740
4741        Returns:
4742            True, if and only if there is a type in `dtypes` which is equal to this DataType.
4743        """
4744        self_is_nullable = self.args.get("nullable")
4745        for dtype in dtypes:
4746            other_type = DataType.build(dtype, copy=False, udt=True)
4747            other_is_nullable = other_type.args.get("nullable")
4748            if (
4749                other_type.expressions
4750                or (check_nullable and (self_is_nullable or other_is_nullable))
4751                or self.this == DataType.Type.USERDEFINED
4752                or other_type.this == DataType.Type.USERDEFINED
4753            ):
4754                matches = self == other_type
4755            else:
4756                matches = self.this == other_type.this
4757
4758            if matches:
4759                return True
4760        return False
4761
4762
4763DATA_TYPE = t.Union[str, DataType, DataType.Type]
4764
4765
4766# https://www.postgresql.org/docs/15/datatype-pseudo.html
4767class PseudoType(DataType):
4768    arg_types = {"this": True}
4769
4770
4771# https://www.postgresql.org/docs/15/datatype-oid.html
4772class ObjectIdentifier(DataType):
4773    arg_types = {"this": True}
4774
4775
4776# WHERE x <OP> EXISTS|ALL|ANY|SOME(SELECT ...)
4777class SubqueryPredicate(Predicate):
4778    pass
4779
4780
4781class All(SubqueryPredicate):
4782    pass
4783
4784
4785class Any(SubqueryPredicate):
4786    pass
4787
4788
4789# Commands to interact with the databases or engines. For most of the command
4790# expressions we parse whatever comes after the command's name as a string.
4791class Command(Expression):
4792    arg_types = {"this": True, "expression": False}
4793
4794
4795class Transaction(Expression):
4796    arg_types = {"this": False, "modes": False, "mark": False}
4797
4798
4799class Commit(Expression):
4800    arg_types = {"chain": False, "this": False, "durability": False}
4801
4802
4803class Rollback(Expression):
4804    arg_types = {"savepoint": False, "this": False}
4805
4806
4807class Alter(Expression):
4808    arg_types = {
4809        "this": True,
4810        "kind": True,
4811        "actions": True,
4812        "exists": False,
4813        "only": False,
4814        "options": False,
4815        "cluster": False,
4816        "not_valid": False,
4817    }
4818
4819    @property
4820    def kind(self) -> t.Optional[str]:
4821        kind = self.args.get("kind")
4822        return kind and kind.upper()
4823
4824    @property
4825    def actions(self) -> t.List[Expression]:
4826        return self.args.get("actions") or []
4827
4828
4829class Analyze(Expression):
4830    arg_types = {
4831        "kind": False,
4832        "this": False,
4833        "options": False,
4834        "mode": False,
4835        "partition": False,
4836        "expression": False,
4837        "properties": False,
4838    }
4839
4840
4841class AnalyzeStatistics(Expression):
4842    arg_types = {
4843        "kind": True,
4844        "option": False,
4845        "this": False,
4846        "expressions": False,
4847    }
4848
4849
4850class AnalyzeHistogram(Expression):
4851    arg_types = {
4852        "this": True,
4853        "expressions": True,
4854        "expression": False,
4855        "update_options": False,
4856    }
4857
4858
4859class AnalyzeSample(Expression):
4860    arg_types = {"kind": True, "sample": True}
4861
4862
4863class AnalyzeListChainedRows(Expression):
4864    arg_types = {"expression": False}
4865
4866
4867class AnalyzeDelete(Expression):
4868    arg_types = {"kind": False}
4869
4870
4871class AnalyzeWith(Expression):
4872    arg_types = {"expressions": True}
4873
4874
4875class AnalyzeValidate(Expression):
4876    arg_types = {
4877        "kind": True,
4878        "this": False,
4879        "expression": False,
4880    }
4881
4882
4883class AnalyzeColumns(Expression):
4884    pass
4885
4886
4887class UsingData(Expression):
4888    pass
4889
4890
4891class AddConstraint(Expression):
4892    arg_types = {"expressions": True}
4893
4894
4895class AttachOption(Expression):
4896    arg_types = {"this": True, "expression": False}
4897
4898
4899class DropPartition(Expression):
4900    arg_types = {"expressions": True, "exists": False}
4901
4902
4903# https://clickhouse.com/docs/en/sql-reference/statements/alter/partition#replace-partition
4904class ReplacePartition(Expression):
4905    arg_types = {"expression": True, "source": True}
4906
4907
4908# Binary expressions like (ADD a b)
4909class Binary(Condition):
4910    arg_types = {"this": True, "expression": True}
4911
4912    @property
4913    def left(self) -> Expression:
4914        return self.this
4915
4916    @property
4917    def right(self) -> Expression:
4918        return self.expression
4919
4920
4921class Add(Binary):
4922    pass
4923
4924
4925class Connector(Binary):
4926    pass
4927
4928
4929class BitwiseAnd(Binary):
4930    pass
4931
4932
4933class BitwiseLeftShift(Binary):
4934    pass
4935
4936
4937class BitwiseOr(Binary):
4938    pass
4939
4940
4941class BitwiseRightShift(Binary):
4942    pass
4943
4944
4945class BitwiseXor(Binary):
4946    pass
4947
4948
4949class Div(Binary):
4950    arg_types = {"this": True, "expression": True, "typed": False, "safe": False}
4951
4952
4953class Overlaps(Binary):
4954    pass
4955
4956
4957class Dot(Binary):
4958    @property
4959    def is_star(self) -> bool:
4960        return self.expression.is_star
4961
4962    @property
4963    def name(self) -> str:
4964        return self.expression.name
4965
4966    @property
4967    def output_name(self) -> str:
4968        return self.name
4969
4970    @classmethod
4971    def build(self, expressions: t.Sequence[Expression]) -> Dot:
4972        """Build a Dot object with a sequence of expressions."""
4973        if len(expressions) < 2:
4974            raise ValueError("Dot requires >= 2 expressions.")
4975
4976        return t.cast(Dot, reduce(lambda x, y: Dot(this=x, expression=y), expressions))
4977
4978    @property
4979    def parts(self) -> t.List[Expression]:
4980        """Return the parts of a table / column in order catalog, db, table."""
4981        this, *parts = self.flatten()
4982
4983        parts.reverse()
4984
4985        for arg in COLUMN_PARTS:
4986            part = this.args.get(arg)
4987
4988            if isinstance(part, Expression):
4989                parts.append(part)
4990
4991        parts.reverse()
4992        return parts
4993
4994
4995class DPipe(Binary):
4996    arg_types = {"this": True, "expression": True, "safe": False}
4997
4998
4999class EQ(Binary, Predicate):
5000    pass
5001
5002
5003class NullSafeEQ(Binary, Predicate):
5004    pass
5005
5006
5007class NullSafeNEQ(Binary, Predicate):
5008    pass
5009
5010
5011# Represents e.g. := in DuckDB which is mostly used for setting parameters
5012class PropertyEQ(Binary):
5013    pass
5014
5015
5016class Distance(Binary):
5017    pass
5018
5019
5020class Escape(Binary):
5021    pass
5022
5023
5024class Glob(Binary, Predicate):
5025    pass
5026
5027
5028class GT(Binary, Predicate):
5029    pass
5030
5031
5032class GTE(Binary, Predicate):
5033    pass
5034
5035
5036class ILike(Binary, Predicate):
5037    pass
5038
5039
5040class ILikeAny(Binary, Predicate):
5041    pass
5042
5043
5044class IntDiv(Binary):
5045    pass
5046
5047
5048class Is(Binary, Predicate):
5049    pass
5050
5051
5052class Kwarg(Binary):
5053    """Kwarg in special functions like func(kwarg => y)."""
5054
5055
5056class Like(Binary, Predicate):
5057    pass
5058
5059
5060class LikeAny(Binary, Predicate):
5061    pass
5062
5063
5064class LT(Binary, Predicate):
5065    pass
5066
5067
5068class LTE(Binary, Predicate):
5069    pass
5070
5071
5072class Mod(Binary):
5073    pass
5074
5075
5076class Mul(Binary):
5077    pass
5078
5079
5080class NEQ(Binary, Predicate):
5081    pass
5082
5083
5084# https://www.postgresql.org/docs/current/ddl-schemas.html#DDL-SCHEMAS-PATH
5085class Operator(Binary):
5086    arg_types = {"this": True, "operator": True, "expression": True}
5087
5088
5089class SimilarTo(Binary, Predicate):
5090    pass
5091
5092
5093class Slice(Binary):
5094    arg_types = {"this": False, "expression": False}
5095
5096
5097class Sub(Binary):
5098    pass
5099
5100
5101# Unary Expressions
5102# (NOT a)
5103class Unary(Condition):
5104    pass
5105
5106
5107class BitwiseNot(Unary):
5108    pass
5109
5110
5111class Not(Unary):
5112    pass
5113
5114
5115class Paren(Unary):
5116    @property
5117    def output_name(self) -> str:
5118        return self.this.name
5119
5120
5121class Neg(Unary):
5122    def to_py(self) -> int | Decimal:
5123        if self.is_number:
5124            return self.this.to_py() * -1
5125        return super().to_py()
5126
5127
5128class Alias(Expression):
5129    arg_types = {"this": True, "alias": False}
5130
5131    @property
5132    def output_name(self) -> str:
5133        return self.alias
5134
5135
5136# BigQuery requires the UNPIVOT column list aliases to be either strings or ints, but
5137# other dialects require identifiers. This enables us to transpile between them easily.
5138class PivotAlias(Alias):
5139    pass
5140
5141
5142# Represents Snowflake's ANY [ ORDER BY ... ] syntax
5143# https://docs.snowflake.com/en/sql-reference/constructs/pivot
5144class PivotAny(Expression):
5145    arg_types = {"this": False}
5146
5147
5148class Aliases(Expression):
5149    arg_types = {"this": True, "expressions": True}
5150
5151    @property
5152    def aliases(self):
5153        return self.expressions
5154
5155
5156# https://docs.aws.amazon.com/redshift/latest/dg/query-super.html
5157class AtIndex(Expression):
5158    arg_types = {"this": True, "expression": True}
5159
5160
5161class AtTimeZone(Expression):
5162    arg_types = {"this": True, "zone": True}
5163
5164
5165class FromTimeZone(Expression):
5166    arg_types = {"this": True, "zone": True}
5167
5168
5169class Between(Predicate):
5170    arg_types = {"this": True, "low": True, "high": True}
5171
5172
5173class Bracket(Condition):
5174    # https://cloud.google.com/bigquery/docs/reference/standard-sql/operators#array_subscript_operator
5175    arg_types = {
5176        "this": True,
5177        "expressions": True,
5178        "offset": False,
5179        "safe": False,
5180        "returns_list_for_maps": False,
5181    }
5182
5183    @property
5184    def output_name(self) -> str:
5185        if len(self.expressions) == 1:
5186            return self.expressions[0].output_name
5187
5188        return super().output_name
5189
5190
5191class Distinct(Expression):
5192    arg_types = {"expressions": False, "on": False}
5193
5194
5195class In(Predicate):
5196    arg_types = {
5197        "this": True,
5198        "expressions": False,
5199        "query": False,
5200        "unnest": False,
5201        "field": False,
5202        "is_global": False,
5203    }
5204
5205
5206# https://cloud.google.com/bigquery/docs/reference/standard-sql/procedural-language#for-in
5207class ForIn(Expression):
5208    arg_types = {"this": True, "expression": True}
5209
5210
5211class TimeUnit(Expression):
5212    """Automatically converts unit arg into a var."""
5213
5214    arg_types = {"unit": False}
5215
5216    UNABBREVIATED_UNIT_NAME = {
5217        "D": "DAY",
5218        "H": "HOUR",
5219        "M": "MINUTE",
5220        "MS": "MILLISECOND",
5221        "NS": "NANOSECOND",
5222        "Q": "QUARTER",
5223        "S": "SECOND",
5224        "US": "MICROSECOND",
5225        "W": "WEEK",
5226        "Y": "YEAR",
5227    }
5228
5229    VAR_LIKE = (Column, Literal, Var)
5230
5231    def __init__(self, **args):
5232        unit = args.get("unit")
5233        if isinstance(unit, self.VAR_LIKE):
5234            args["unit"] = Var(
5235                this=(self.UNABBREVIATED_UNIT_NAME.get(unit.name) or unit.name).upper()
5236            )
5237        elif isinstance(unit, Week):
5238            unit.set("this", Var(this=unit.this.name.upper()))
5239
5240        super().__init__(**args)
5241
5242    @property
5243    def unit(self) -> t.Optional[Var | IntervalSpan]:
5244        return self.args.get("unit")
5245
5246
5247class IntervalOp(TimeUnit):
5248    arg_types = {"unit": False, "expression": True}
5249
5250    def interval(self):
5251        return Interval(
5252            this=self.expression.copy(),
5253            unit=self.unit.copy() if self.unit else None,
5254        )
5255
5256
5257# https://www.oracletutorial.com/oracle-basics/oracle-interval/
5258# https://trino.io/docs/current/language/types.html#interval-day-to-second
5259# https://docs.databricks.com/en/sql/language-manual/data-types/interval-type.html
5260class IntervalSpan(DataType):
5261    arg_types = {"this": True, "expression": True}
5262
5263
5264class Interval(TimeUnit):
5265    arg_types = {"this": False, "unit": False}
5266
5267
5268class IgnoreNulls(Expression):
5269    pass
5270
5271
5272class RespectNulls(Expression):
5273    pass
5274
5275
5276# https://cloud.google.com/bigquery/docs/reference/standard-sql/aggregate-function-calls#max_min_clause
5277class HavingMax(Expression):
5278    arg_types = {"this": True, "expression": True, "max": True}
5279
5280
5281# Functions
5282class Func(Condition):
5283    """
5284    The base class for all function expressions.
5285
5286    Attributes:
5287        is_var_len_args (bool): if set to True the last argument defined in arg_types will be
5288            treated as a variable length argument and the argument's value will be stored as a list.
5289        _sql_names (list): the SQL name (1st item in the list) and aliases (subsequent items) for this
5290            function expression. These values are used to map this node to a name during parsing as
5291            well as to provide the function's name during SQL string generation. By default the SQL
5292            name is set to the expression's class name transformed to snake case.
5293    """
5294
5295    is_var_len_args = False
5296
5297    @classmethod
5298    def from_arg_list(cls, args):
5299        if cls.is_var_len_args:
5300            all_arg_keys = list(cls.arg_types)
5301            # If this function supports variable length argument treat the last argument as such.
5302            non_var_len_arg_keys = all_arg_keys[:-1] if cls.is_var_len_args else all_arg_keys
5303            num_non_var = len(non_var_len_arg_keys)
5304
5305            args_dict = {arg_key: arg for arg, arg_key in zip(args, non_var_len_arg_keys)}
5306            args_dict[all_arg_keys[-1]] = args[num_non_var:]
5307        else:
5308            args_dict = {arg_key: arg for arg, arg_key in zip(args, cls.arg_types)}
5309
5310        return cls(**args_dict)
5311
5312    @classmethod
5313    def sql_names(cls):
5314        if cls is Func:
5315            raise NotImplementedError(
5316                "SQL name is only supported by concrete function implementations"
5317            )
5318        if "_sql_names" not in cls.__dict__:
5319            cls._sql_names = [camel_to_snake_case(cls.__name__)]
5320        return cls._sql_names
5321
5322    @classmethod
5323    def sql_name(cls):
5324        return cls.sql_names()[0]
5325
5326    @classmethod
5327    def default_parser_mappings(cls):
5328        return {name: cls.from_arg_list for name in cls.sql_names()}
5329
5330
5331class AggFunc(Func):
5332    pass
5333
5334
5335class ParameterizedAgg(AggFunc):
5336    arg_types = {"this": True, "expressions": True, "params": True}
5337
5338
5339class Abs(Func):
5340    pass
5341
5342
5343class ArgMax(AggFunc):
5344    arg_types = {"this": True, "expression": True, "count": False}
5345    _sql_names = ["ARG_MAX", "ARGMAX", "MAX_BY"]
5346
5347
5348class ArgMin(AggFunc):
5349    arg_types = {"this": True, "expression": True, "count": False}
5350    _sql_names = ["ARG_MIN", "ARGMIN", "MIN_BY"]
5351
5352
5353class ApproxTopK(AggFunc):
5354    arg_types = {"this": True, "expression": False, "counters": False}
5355
5356
5357class Flatten(Func):
5358    pass
5359
5360
5361# https://spark.apache.org/docs/latest/api/sql/index.html#transform
5362class Transform(Func):
5363    arg_types = {"this": True, "expression": True}
5364
5365
5366class Anonymous(Func):
5367    arg_types = {"this": True, "expressions": False}
5368    is_var_len_args = True
5369
5370    @property
5371    def name(self) -> str:
5372        return self.this if isinstance(self.this, str) else self.this.name
5373
5374
5375class AnonymousAggFunc(AggFunc):
5376    arg_types = {"this": True, "expressions": False}
5377    is_var_len_args = True
5378
5379
5380# https://clickhouse.com/docs/en/sql-reference/aggregate-functions/combinators
5381class CombinedAggFunc(AnonymousAggFunc):
5382    arg_types = {"this": True, "expressions": False}
5383
5384
5385class CombinedParameterizedAgg(ParameterizedAgg):
5386    arg_types = {"this": True, "expressions": True, "params": True}
5387
5388
5389# https://docs.snowflake.com/en/sql-reference/functions/hll
5390# https://docs.aws.amazon.com/redshift/latest/dg/r_HLL_function.html
5391class Hll(AggFunc):
5392    arg_types = {"this": True, "expressions": False}
5393    is_var_len_args = True
5394
5395
5396class ApproxDistinct(AggFunc):
5397    arg_types = {"this": True, "accuracy": False}
5398    _sql_names = ["APPROX_DISTINCT", "APPROX_COUNT_DISTINCT"]
5399
5400
5401class Apply(Func):
5402    arg_types = {"this": True, "expression": True}
5403
5404
5405class Array(Func):
5406    arg_types = {"expressions": False, "bracket_notation": False}
5407    is_var_len_args = True
5408
5409
5410# https://docs.snowflake.com/en/sql-reference/functions/to_array
5411class ToArray(Func):
5412    pass
5413
5414
5415# https://materialize.com/docs/sql/types/list/
5416class List(Func):
5417    arg_types = {"expressions": False}
5418    is_var_len_args = True
5419
5420
5421# String pad, kind True -> LPAD, False -> RPAD
5422class Pad(Func):
5423    arg_types = {"this": True, "expression": True, "fill_pattern": False, "is_left": True}
5424
5425
5426# https://docs.snowflake.com/en/sql-reference/functions/to_char
5427# https://docs.oracle.com/en/database/oracle/oracle-database/23/sqlrf/TO_CHAR-number.html
5428class ToChar(Func):
5429    arg_types = {"this": True, "format": False, "nlsparam": False}
5430
5431
5432# https://docs.snowflake.com/en/sql-reference/functions/to_decimal
5433# https://docs.oracle.com/en/database/oracle/oracle-database/23/sqlrf/TO_NUMBER.html
5434class ToNumber(Func):
5435    arg_types = {
5436        "this": True,
5437        "format": False,
5438        "nlsparam": False,
5439        "precision": False,
5440        "scale": False,
5441    }
5442
5443
5444# https://docs.snowflake.com/en/sql-reference/functions/to_double
5445class ToDouble(Func):
5446    arg_types = {
5447        "this": True,
5448        "format": False,
5449    }
5450
5451
5452class Columns(Func):
5453    arg_types = {"this": True, "unpack": False}
5454
5455
5456# https://learn.microsoft.com/en-us/sql/t-sql/functions/cast-and-convert-transact-sql?view=sql-server-ver16#syntax
5457class Convert(Func):
5458    arg_types = {"this": True, "expression": True, "style": False}
5459
5460
5461class ConvertTimezone(Func):
5462    arg_types = {"source_tz": False, "target_tz": True, "timestamp": True}
5463
5464
5465class GenerateSeries(Func):
5466    arg_types = {"start": True, "end": True, "step": False, "is_end_exclusive": False}
5467
5468
5469# Postgres' GENERATE_SERIES function returns a row set, i.e. it implicitly explodes when it's
5470# used in a projection, so this expression is a helper that facilitates transpilation to other
5471# dialects. For example, we'd generate UNNEST(GENERATE_SERIES(...)) in DuckDB
5472class ExplodingGenerateSeries(GenerateSeries):
5473    pass
5474
5475
5476class ArrayAgg(AggFunc):
5477    arg_types = {"this": True, "nulls_excluded": False}
5478
5479
5480class ArrayUniqueAgg(AggFunc):
5481    pass
5482
5483
5484class ArrayAll(Func):
5485    arg_types = {"this": True, "expression": True}
5486
5487
5488# Represents Python's `any(f(x) for x in array)`, where `array` is `this` and `f` is `expression`
5489class ArrayAny(Func):
5490    arg_types = {"this": True, "expression": True}
5491
5492
5493class ArrayConcat(Func):
5494    _sql_names = ["ARRAY_CONCAT", "ARRAY_CAT"]
5495    arg_types = {"this": True, "expressions": False}
5496    is_var_len_args = True
5497
5498
5499class ArrayConstructCompact(Func):
5500    arg_types = {"expressions": True}
5501    is_var_len_args = True
5502
5503
5504class ArrayContains(Binary, Func):
5505    _sql_names = ["ARRAY_CONTAINS", "ARRAY_HAS"]
5506
5507
5508class ArrayContainsAll(Binary, Func):
5509    _sql_names = ["ARRAY_CONTAINS_ALL", "ARRAY_HAS_ALL"]
5510
5511
5512class ArrayFilter(Func):
5513    arg_types = {"this": True, "expression": True}
5514    _sql_names = ["FILTER", "ARRAY_FILTER"]
5515
5516
5517class ArrayToString(Func):
5518    arg_types = {"this": True, "expression": True, "null": False}
5519    _sql_names = ["ARRAY_TO_STRING", "ARRAY_JOIN"]
5520
5521
5522# https://cloud.google.com/bigquery/docs/reference/standard-sql/timestamp_functions#string
5523class String(Func):
5524    arg_types = {"this": True, "zone": False}
5525
5526
5527class StringToArray(Func):
5528    arg_types = {"this": True, "expression": True, "null": False}
5529    _sql_names = ["STRING_TO_ARRAY", "SPLIT_BY_STRING"]
5530
5531
5532class ArrayOverlaps(Binary, Func):
5533    pass
5534
5535
5536class ArraySize(Func):
5537    arg_types = {"this": True, "expression": False}
5538    _sql_names = ["ARRAY_SIZE", "ARRAY_LENGTH"]
5539
5540
5541class ArraySort(Func):
5542    arg_types = {"this": True, "expression": False}
5543
5544
5545class ArraySum(Func):
5546    arg_types = {"this": True, "expression": False}
5547
5548
5549class ArrayUnionAgg(AggFunc):
5550    pass
5551
5552
5553class Avg(AggFunc):
5554    pass
5555
5556
5557class AnyValue(AggFunc):
5558    pass
5559
5560
5561class Lag(AggFunc):
5562    arg_types = {"this": True, "offset": False, "default": False}
5563
5564
5565class Lead(AggFunc):
5566    arg_types = {"this": True, "offset": False, "default": False}
5567
5568
5569# some dialects have a distinction between first and first_value, usually first is an aggregate func
5570# and first_value is a window func
5571class First(AggFunc):
5572    pass
5573
5574
5575class Last(AggFunc):
5576    pass
5577
5578
5579class FirstValue(AggFunc):
5580    pass
5581
5582
5583class LastValue(AggFunc):
5584    pass
5585
5586
5587class NthValue(AggFunc):
5588    arg_types = {"this": True, "offset": True}
5589
5590
5591class Case(Func):
5592    arg_types = {"this": False, "ifs": True, "default": False}
5593
5594    def when(self, condition: ExpOrStr, then: ExpOrStr, copy: bool = True, **opts) -> Case:
5595        instance = maybe_copy(self, copy)
5596        instance.append(
5597            "ifs",
5598            If(
5599                this=maybe_parse(condition, copy=copy, **opts),
5600                true=maybe_parse(then, copy=copy, **opts),
5601            ),
5602        )
5603        return instance
5604
5605    def else_(self, condition: ExpOrStr, copy: bool = True, **opts) -> Case:
5606        instance = maybe_copy(self, copy)
5607        instance.set("default", maybe_parse(condition, copy=copy, **opts))
5608        return instance
5609
5610
5611class Cast(Func):
5612    arg_types = {
5613        "this": True,
5614        "to": True,
5615        "format": False,
5616        "safe": False,
5617        "action": False,
5618        "default": False,
5619    }
5620
5621    @property
5622    def name(self) -> str:
5623        return self.this.name
5624
5625    @property
5626    def to(self) -> DataType:
5627        return self.args["to"]
5628
5629    @property
5630    def output_name(self) -> str:
5631        return self.name
5632
5633    def is_type(self, *dtypes: DATA_TYPE) -> bool:
5634        """
5635        Checks whether this Cast's DataType matches one of the provided data types. Nested types
5636        like arrays or structs will be compared using "structural equivalence" semantics, so e.g.
5637        array<int> != array<float>.
5638
5639        Args:
5640            dtypes: the data types to compare this Cast's DataType to.
5641
5642        Returns:
5643            True, if and only if there is a type in `dtypes` which is equal to this Cast's DataType.
5644        """
5645        return self.to.is_type(*dtypes)
5646
5647
5648class TryCast(Cast):
5649    pass
5650
5651
5652# https://clickhouse.com/docs/sql-reference/data-types/newjson#reading-json-paths-as-sub-columns
5653class JSONCast(Cast):
5654    pass
5655
5656
5657class Try(Func):
5658    pass
5659
5660
5661class CastToStrType(Func):
5662    arg_types = {"this": True, "to": True}
5663
5664
5665class Collate(Binary, Func):
5666    pass
5667
5668
5669class Ceil(Func):
5670    arg_types = {"this": True, "decimals": False, "to": False}
5671    _sql_names = ["CEIL", "CEILING"]
5672
5673
5674class Coalesce(Func):
5675    arg_types = {"this": True, "expressions": False, "is_nvl": False}
5676    is_var_len_args = True
5677    _sql_names = ["COALESCE", "IFNULL", "NVL"]
5678
5679
5680class Chr(Func):
5681    arg_types = {"expressions": True, "charset": False}
5682    is_var_len_args = True
5683    _sql_names = ["CHR", "CHAR"]
5684
5685
5686class Concat(Func):
5687    arg_types = {"expressions": True, "safe": False, "coalesce": False}
5688    is_var_len_args = True
5689
5690
5691class ConcatWs(Concat):
5692    _sql_names = ["CONCAT_WS"]
5693
5694
5695class Contains(Func):
5696    arg_types = {"this": True, "expression": True}
5697
5698
5699# https://docs.oracle.com/cd/B13789_01/server.101/b10759/operators004.htm#i1035022
5700class ConnectByRoot(Func):
5701    pass
5702
5703
5704class Count(AggFunc):
5705    arg_types = {"this": False, "expressions": False, "big_int": False}
5706    is_var_len_args = True
5707
5708
5709class CountIf(AggFunc):
5710    _sql_names = ["COUNT_IF", "COUNTIF"]
5711
5712
5713# cube root
5714class Cbrt(Func):
5715    pass
5716
5717
5718class CurrentDate(Func):
5719    arg_types = {"this": False}
5720
5721
5722class CurrentDatetime(Func):
5723    arg_types = {"this": False}
5724
5725
5726class CurrentTime(Func):
5727    arg_types = {"this": False}
5728
5729
5730class CurrentTimestamp(Func):
5731    arg_types = {"this": False, "sysdate": False}
5732
5733
5734class CurrentSchema(Func):
5735    arg_types = {"this": False}
5736
5737
5738class CurrentUser(Func):
5739    arg_types = {"this": False}
5740
5741
5742class DateAdd(Func, IntervalOp):
5743    arg_types = {"this": True, "expression": True, "unit": False}
5744
5745
5746class DateBin(Func, IntervalOp):
5747    arg_types = {"this": True, "expression": True, "unit": False, "zone": False}
5748
5749
5750class DateSub(Func, IntervalOp):
5751    arg_types = {"this": True, "expression": True, "unit": False}
5752
5753
5754class DateDiff(Func, TimeUnit):
5755    _sql_names = ["DATEDIFF", "DATE_DIFF"]
5756    arg_types = {"this": True, "expression": True, "unit": False, "zone": False}
5757
5758
5759class DateTrunc(Func):
5760    arg_types = {"unit": True, "this": True, "zone": False}
5761
5762    def __init__(self, **args):
5763        # Across most dialects it's safe to unabbreviate the unit (e.g. 'Q' -> 'QUARTER') except Oracle
5764        # https://docs.oracle.com/en/database/oracle/oracle-database/21/sqlrf/ROUND-and-TRUNC-Date-Functions.html
5765        unabbreviate = args.pop("unabbreviate", True)
5766
5767        unit = args.get("unit")
5768        if isinstance(unit, TimeUnit.VAR_LIKE):
5769            unit_name = unit.name.upper()
5770            if unabbreviate and unit_name in TimeUnit.UNABBREVIATED_UNIT_NAME:
5771                unit_name = TimeUnit.UNABBREVIATED_UNIT_NAME[unit_name]
5772
5773            args["unit"] = Literal.string(unit_name)
5774        elif isinstance(unit, Week):
5775            unit.set("this", Literal.string(unit.this.name.upper()))
5776
5777        super().__init__(**args)
5778
5779    @property
5780    def unit(self) -> Expression:
5781        return self.args["unit"]
5782
5783
5784# https://cloud.google.com/bigquery/docs/reference/standard-sql/datetime_functions#datetime
5785# expression can either be time_expr or time_zone
5786class Datetime(Func):
5787    arg_types = {"this": True, "expression": False}
5788
5789
5790class DatetimeAdd(Func, IntervalOp):
5791    arg_types = {"this": True, "expression": True, "unit": False}
5792
5793
5794class DatetimeSub(Func, IntervalOp):
5795    arg_types = {"this": True, "expression": True, "unit": False}
5796
5797
5798class DatetimeDiff(Func, TimeUnit):
5799    arg_types = {"this": True, "expression": True, "unit": False}
5800
5801
5802class DatetimeTrunc(Func, TimeUnit):
5803    arg_types = {"this": True, "unit": True, "zone": False}
5804
5805
5806class DayOfWeek(Func):
5807    _sql_names = ["DAY_OF_WEEK", "DAYOFWEEK"]
5808
5809
5810# https://duckdb.org/docs/sql/functions/datepart.html#part-specifiers-only-usable-as-date-part-specifiers
5811# ISO day of week function in duckdb is ISODOW
5812class DayOfWeekIso(Func):
5813    _sql_names = ["DAYOFWEEK_ISO", "ISODOW"]
5814
5815
5816class DayOfMonth(Func):
5817    _sql_names = ["DAY_OF_MONTH", "DAYOFMONTH"]
5818
5819
5820class DayOfYear(Func):
5821    _sql_names = ["DAY_OF_YEAR", "DAYOFYEAR"]
5822
5823
5824class ToDays(Func):
5825    pass
5826
5827
5828class WeekOfYear(Func):
5829    _sql_names = ["WEEK_OF_YEAR", "WEEKOFYEAR"]
5830
5831
5832class MonthsBetween(Func):
5833    arg_types = {"this": True, "expression": True, "roundoff": False}
5834
5835
5836class MakeInterval(Func):
5837    arg_types = {
5838        "year": False,
5839        "month": False,
5840        "day": False,
5841        "hour": False,
5842        "minute": False,
5843        "second": False,
5844    }
5845
5846
5847class LastDay(Func, TimeUnit):
5848    _sql_names = ["LAST_DAY", "LAST_DAY_OF_MONTH"]
5849    arg_types = {"this": True, "unit": False}
5850
5851
5852class Extract(Func):
5853    arg_types = {"this": True, "expression": True}
5854
5855
5856class Exists(Func, SubqueryPredicate):
5857    arg_types = {"this": True, "expression": False}
5858
5859
5860class Timestamp(Func):
5861    arg_types = {"this": False, "zone": False, "with_tz": False}
5862
5863
5864class TimestampAdd(Func, TimeUnit):
5865    arg_types = {"this": True, "expression": True, "unit": False}
5866
5867
5868class TimestampSub(Func, TimeUnit):
5869    arg_types = {"this": True, "expression": True, "unit": False}
5870
5871
5872class TimestampDiff(Func, TimeUnit):
5873    _sql_names = ["TIMESTAMPDIFF", "TIMESTAMP_DIFF"]
5874    arg_types = {"this": True, "expression": True, "unit": False}
5875
5876
5877class TimestampTrunc(Func, TimeUnit):
5878    arg_types = {"this": True, "unit": True, "zone": False}
5879
5880
5881class TimeAdd(Func, TimeUnit):
5882    arg_types = {"this": True, "expression": True, "unit": False}
5883
5884
5885class TimeSub(Func, TimeUnit):
5886    arg_types = {"this": True, "expression": True, "unit": False}
5887
5888
5889class TimeDiff(Func, TimeUnit):
5890    arg_types = {"this": True, "expression": True, "unit": False}
5891
5892
5893class TimeTrunc(Func, TimeUnit):
5894    arg_types = {"this": True, "unit": True, "zone": False}
5895
5896
5897class DateFromParts(Func):
5898    _sql_names = ["DATE_FROM_PARTS", "DATEFROMPARTS"]
5899    arg_types = {"year": True, "month": True, "day": True}
5900
5901
5902class TimeFromParts(Func):
5903    _sql_names = ["TIME_FROM_PARTS", "TIMEFROMPARTS"]
5904    arg_types = {
5905        "hour": True,
5906        "min": True,
5907        "sec": True,
5908        "nano": False,
5909        "fractions": False,
5910        "precision": False,
5911    }
5912
5913
5914class DateStrToDate(Func):
5915    pass
5916
5917
5918class DateToDateStr(Func):
5919    pass
5920
5921
5922class DateToDi(Func):
5923    pass
5924
5925
5926# https://cloud.google.com/bigquery/docs/reference/standard-sql/date_functions#date
5927class Date(Func):
5928    arg_types = {"this": False, "zone": False, "expressions": False}
5929    is_var_len_args = True
5930
5931
5932class Day(Func):
5933    pass
5934
5935
5936class Decode(Func):
5937    arg_types = {"this": True, "charset": True, "replace": False}
5938
5939
5940class DiToDate(Func):
5941    pass
5942
5943
5944class Encode(Func):
5945    arg_types = {"this": True, "charset": True}
5946
5947
5948class Exp(Func):
5949    pass
5950
5951
5952# https://docs.snowflake.com/en/sql-reference/functions/flatten
5953class Explode(Func, UDTF):
5954    arg_types = {"this": True, "expressions": False}
5955    is_var_len_args = True
5956
5957
5958# https://spark.apache.org/docs/latest/api/sql/#inline
5959class Inline(Func):
5960    pass
5961
5962
5963class ExplodeOuter(Explode):
5964    pass
5965
5966
5967class Posexplode(Explode):
5968    pass
5969
5970
5971class PosexplodeOuter(Posexplode, ExplodeOuter):
5972    pass
5973
5974
5975class Unnest(Func, UDTF):
5976    arg_types = {
5977        "expressions": True,
5978        "alias": False,
5979        "offset": False,
5980        "explode_array": False,
5981    }
5982
5983    @property
5984    def selects(self) -> t.List[Expression]:
5985        columns = super().selects
5986        offset = self.args.get("offset")
5987        if offset:
5988            columns = columns + [to_identifier("offset") if offset is True else offset]
5989        return columns
5990
5991
5992class Floor(Func):
5993    arg_types = {"this": True, "decimals": False, "to": False}
5994
5995
5996class FromBase64(Func):
5997    pass
5998
5999
6000class FeaturesAtTime(Func):
6001    arg_types = {"this": True, "time": False, "num_rows": False, "ignore_feature_nulls": False}
6002
6003
6004class ToBase64(Func):
6005    pass
6006
6007
6008# https://trino.io/docs/current/functions/datetime.html#from_iso8601_timestamp
6009class FromISO8601Timestamp(Func):
6010    _sql_names = ["FROM_ISO8601_TIMESTAMP"]
6011
6012
6013class GapFill(Func):
6014    arg_types = {
6015        "this": True,
6016        "ts_column": True,
6017        "bucket_width": True,
6018        "partitioning_columns": False,
6019        "value_columns": False,
6020        "origin": False,
6021        "ignore_nulls": False,
6022    }
6023
6024
6025# https://cloud.google.com/bigquery/docs/reference/standard-sql/array_functions#generate_date_array
6026class GenerateDateArray(Func):
6027    arg_types = {"start": True, "end": True, "step": False}
6028
6029
6030# https://cloud.google.com/bigquery/docs/reference/standard-sql/array_functions#generate_timestamp_array
6031class GenerateTimestampArray(Func):
6032    arg_types = {"start": True, "end": True, "step": True}
6033
6034
6035class Greatest(Func):
6036    arg_types = {"this": True, "expressions": False}
6037    is_var_len_args = True
6038
6039
6040# Trino's `ON OVERFLOW TRUNCATE [filler_string] {WITH | WITHOUT} COUNT`
6041# https://trino.io/docs/current/functions/aggregate.html#listagg
6042class OverflowTruncateBehavior(Expression):
6043    arg_types = {"this": False, "with_count": True}
6044
6045
6046class GroupConcat(AggFunc):
6047    arg_types = {"this": True, "separator": False, "on_overflow": False}
6048
6049
6050class Hex(Func):
6051    pass
6052
6053
6054class LowerHex(Hex):
6055    pass
6056
6057
6058class And(Connector, Func):
6059    pass
6060
6061
6062class Or(Connector, Func):
6063    pass
6064
6065
6066class Xor(Connector, Func):
6067    arg_types = {"this": False, "expression": False, "expressions": False}
6068
6069
6070class If(Func):
6071    arg_types = {"this": True, "true": True, "false": False}
6072    _sql_names = ["IF", "IIF"]
6073
6074
6075class Nullif(Func):
6076    arg_types = {"this": True, "expression": True}
6077
6078
6079class Initcap(Func):
6080    arg_types = {"this": True, "expression": False}
6081
6082
6083class IsAscii(Func):
6084    pass
6085
6086
6087class IsNan(Func):
6088    _sql_names = ["IS_NAN", "ISNAN"]
6089
6090
6091# https://cloud.google.com/bigquery/docs/reference/standard-sql/json_functions#int64_for_json
6092class Int64(Func):
6093    pass
6094
6095
6096class IsInf(Func):
6097    _sql_names = ["IS_INF", "ISINF"]
6098
6099
6100# https://www.postgresql.org/docs/current/functions-json.html
6101class JSON(Expression):
6102    arg_types = {"this": False, "with": False, "unique": False}
6103
6104
6105class JSONPath(Expression):
6106    arg_types = {"expressions": True, "escape": False}
6107
6108    @property
6109    def output_name(self) -> str:
6110        last_segment = self.expressions[-1].this
6111        return last_segment if isinstance(last_segment, str) else ""
6112
6113
6114class JSONPathPart(Expression):
6115    arg_types = {}
6116
6117
6118class JSONPathFilter(JSONPathPart):
6119    arg_types = {"this": True}
6120
6121
6122class JSONPathKey(JSONPathPart):
6123    arg_types = {"this": True}
6124
6125
6126class JSONPathRecursive(JSONPathPart):
6127    arg_types = {"this": False}
6128
6129
6130class JSONPathRoot(JSONPathPart):
6131    pass
6132
6133
6134class JSONPathScript(JSONPathPart):
6135    arg_types = {"this": True}
6136
6137
6138class JSONPathSlice(JSONPathPart):
6139    arg_types = {"start": False, "end": False, "step": False}
6140
6141
6142class JSONPathSelector(JSONPathPart):
6143    arg_types = {"this": True}
6144
6145
6146class JSONPathSubscript(JSONPathPart):
6147    arg_types = {"this": True}
6148
6149
6150class JSONPathUnion(JSONPathPart):
6151    arg_types = {"expressions": True}
6152
6153
6154class JSONPathWildcard(JSONPathPart):
6155    pass
6156
6157
6158class FormatJson(Expression):
6159    pass
6160
6161
6162class JSONKeyValue(Expression):
6163    arg_types = {"this": True, "expression": True}
6164
6165
6166class JSONObject(Func):
6167    arg_types = {
6168        "expressions": False,
6169        "null_handling": False,
6170        "unique_keys": False,
6171        "return_type": False,
6172        "encoding": False,
6173    }
6174
6175
6176class JSONObjectAgg(AggFunc):
6177    arg_types = {
6178        "expressions": False,
6179        "null_handling": False,
6180        "unique_keys": False,
6181        "return_type": False,
6182        "encoding": False,
6183    }
6184
6185
6186# https://www.postgresql.org/docs/9.5/functions-aggregate.html
6187class JSONBObjectAgg(AggFunc):
6188    arg_types = {"this": True, "expression": True}
6189
6190
6191# https://docs.oracle.com/en/database/oracle/oracle-database/19/sqlrf/JSON_ARRAY.html
6192class JSONArray(Func):
6193    arg_types = {
6194        "expressions": True,
6195        "null_handling": False,
6196        "return_type": False,
6197        "strict": False,
6198    }
6199
6200
6201# https://docs.oracle.com/en/database/oracle/oracle-database/19/sqlrf/JSON_ARRAYAGG.html
6202class JSONArrayAgg(Func):
6203    arg_types = {
6204        "this": True,
6205        "order": False,
6206        "null_handling": False,
6207        "return_type": False,
6208        "strict": False,
6209    }
6210
6211
6212class JSONExists(Func):
6213    arg_types = {"this": True, "path": True, "passing": False, "on_condition": False}
6214
6215
6216# https://docs.oracle.com/en/database/oracle/oracle-database/19/sqlrf/JSON_TABLE.html
6217# Note: parsing of JSON column definitions is currently incomplete.
6218class JSONColumnDef(Expression):
6219    arg_types = {"this": False, "kind": False, "path": False, "nested_schema": False}
6220
6221
6222class JSONSchema(Expression):
6223    arg_types = {"expressions": True}
6224
6225
6226# https://dev.mysql.com/doc/refman/8.4/en/json-search-functions.html#function_json-value
6227class JSONValue(Expression):
6228    arg_types = {
6229        "this": True,
6230        "path": True,
6231        "returning": False,
6232        "on_condition": False,
6233    }
6234
6235
6236class JSONValueArray(Func):
6237    arg_types = {"this": True, "expression": False}
6238
6239
6240# # https://docs.oracle.com/en/database/oracle/oracle-database/19/sqlrf/JSON_TABLE.html
6241class JSONTable(Func):
6242    arg_types = {
6243        "this": True,
6244        "schema": True,
6245        "path": False,
6246        "error_handling": False,
6247        "empty_handling": False,
6248    }
6249
6250
6251# https://docs.snowflake.com/en/sql-reference/functions/object_insert
6252class ObjectInsert(Func):
6253    arg_types = {
6254        "this": True,
6255        "key": True,
6256        "value": True,
6257        "update_flag": False,
6258    }
6259
6260
6261class OpenJSONColumnDef(Expression):
6262    arg_types = {"this": True, "kind": True, "path": False, "as_json": False}
6263
6264
6265class OpenJSON(Func):
6266    arg_types = {"this": True, "path": False, "expressions": False}
6267
6268
6269class JSONBContains(Binary, Func):
6270    _sql_names = ["JSONB_CONTAINS"]
6271
6272
6273class JSONBExists(Func):
6274    arg_types = {"this": True, "path": True}
6275    _sql_names = ["JSONB_EXISTS"]
6276
6277
6278class JSONExtract(Binary, Func):
6279    arg_types = {
6280        "this": True,
6281        "expression": True,
6282        "only_json_types": False,
6283        "expressions": False,
6284        "variant_extract": False,
6285        "json_query": False,
6286        "option": False,
6287        "quote": False,
6288        "on_condition": False,
6289    }
6290    _sql_names = ["JSON_EXTRACT"]
6291    is_var_len_args = True
6292
6293    @property
6294    def output_name(self) -> str:
6295        return self.expression.output_name if not self.expressions else ""
6296
6297
6298# https://trino.io/docs/current/functions/json.html#json-query
6299class JSONExtractQuote(Expression):
6300    arg_types = {
6301        "option": True,
6302        "scalar": False,
6303    }
6304
6305
6306class JSONExtractArray(Func):
6307    arg_types = {"this": True, "expression": False}
6308    _sql_names = ["JSON_EXTRACT_ARRAY"]
6309
6310
6311class JSONExtractScalar(Binary, Func):
6312    arg_types = {"this": True, "expression": True, "only_json_types": False, "expressions": False}
6313    _sql_names = ["JSON_EXTRACT_SCALAR"]
6314    is_var_len_args = True
6315
6316    @property
6317    def output_name(self) -> str:
6318        return self.expression.output_name
6319
6320
6321class JSONBExtract(Binary, Func):
6322    _sql_names = ["JSONB_EXTRACT"]
6323
6324
6325class JSONBExtractScalar(Binary, Func):
6326    _sql_names = ["JSONB_EXTRACT_SCALAR"]
6327
6328
6329class JSONFormat(Func):
6330    arg_types = {"this": False, "options": False, "is_json": False}
6331    _sql_names = ["JSON_FORMAT"]
6332
6333
6334# https://dev.mysql.com/doc/refman/8.0/en/json-search-functions.html#operator_member-of
6335class JSONArrayContains(Binary, Predicate, Func):
6336    _sql_names = ["JSON_ARRAY_CONTAINS"]
6337
6338
6339class ParseJSON(Func):
6340    # BigQuery, Snowflake have PARSE_JSON, Presto has JSON_PARSE
6341    # Snowflake also has TRY_PARSE_JSON, which is represented using `safe`
6342    _sql_names = ["PARSE_JSON", "JSON_PARSE"]
6343    arg_types = {"this": True, "expression": False, "safe": False}
6344
6345
6346class Least(Func):
6347    arg_types = {"this": True, "expressions": False}
6348    is_var_len_args = True
6349
6350
6351class Left(Func):
6352    arg_types = {"this": True, "expression": True}
6353
6354
6355class Right(Func):
6356    arg_types = {"this": True, "expression": True}
6357
6358
6359class Length(Func):
6360    arg_types = {"this": True, "binary": False, "encoding": False}
6361    _sql_names = ["LENGTH", "LEN", "CHAR_LENGTH", "CHARACTER_LENGTH"]
6362
6363
6364class Levenshtein(Func):
6365    arg_types = {
6366        "this": True,
6367        "expression": False,
6368        "ins_cost": False,
6369        "del_cost": False,
6370        "sub_cost": False,
6371        "max_dist": False,
6372    }
6373
6374
6375class Ln(Func):
6376    pass
6377
6378
6379class Log(Func):
6380    arg_types = {"this": True, "expression": False}
6381
6382
6383class LogicalOr(AggFunc):
6384    _sql_names = ["LOGICAL_OR", "BOOL_OR", "BOOLOR_AGG"]
6385
6386
6387class LogicalAnd(AggFunc):
6388    _sql_names = ["LOGICAL_AND", "BOOL_AND", "BOOLAND_AGG"]
6389
6390
6391class Lower(Func):
6392    _sql_names = ["LOWER", "LCASE"]
6393
6394
6395class Map(Func):
6396    arg_types = {"keys": False, "values": False}
6397
6398    @property
6399    def keys(self) -> t.List[Expression]:
6400        keys = self.args.get("keys")
6401        return keys.expressions if keys else []
6402
6403    @property
6404    def values(self) -> t.List[Expression]:
6405        values = self.args.get("values")
6406        return values.expressions if values else []
6407
6408
6409# Represents the MAP {...} syntax in DuckDB - basically convert a struct to a MAP
6410class ToMap(Func):
6411    pass
6412
6413
6414class MapFromEntries(Func):
6415    pass
6416
6417
6418# https://learn.microsoft.com/en-us/sql/t-sql/language-elements/scope-resolution-operator-transact-sql?view=sql-server-ver16
6419class ScopeResolution(Expression):
6420    arg_types = {"this": False, "expression": True}
6421
6422
6423class Stream(Expression):
6424    pass
6425
6426
6427class StarMap(Func):
6428    pass
6429
6430
6431class VarMap(Func):
6432    arg_types = {"keys": True, "values": True}
6433    is_var_len_args = True
6434
6435    @property
6436    def keys(self) -> t.List[Expression]:
6437        return self.args["keys"].expressions
6438
6439    @property
6440    def values(self) -> t.List[Expression]:
6441        return self.args["values"].expressions
6442
6443
6444# https://dev.mysql.com/doc/refman/8.0/en/fulltext-search.html
6445class MatchAgainst(Func):
6446    arg_types = {"this": True, "expressions": True, "modifier": False}
6447
6448
6449class Max(AggFunc):
6450    arg_types = {"this": True, "expressions": False}
6451    is_var_len_args = True
6452
6453
6454class MD5(Func):
6455    _sql_names = ["MD5"]
6456
6457
6458# Represents the variant of the MD5 function that returns a binary value
6459class MD5Digest(Func):
6460    _sql_names = ["MD5_DIGEST"]
6461
6462
6463class Median(AggFunc):
6464    pass
6465
6466
6467class Min(AggFunc):
6468    arg_types = {"this": True, "expressions": False}
6469    is_var_len_args = True
6470
6471
6472class Month(Func):
6473    pass
6474
6475
6476class AddMonths(Func):
6477    arg_types = {"this": True, "expression": True}
6478
6479
6480class Nvl2(Func):
6481    arg_types = {"this": True, "true": True, "false": False}
6482
6483
6484class Normalize(Func):
6485    arg_types = {"this": True, "form": False}
6486
6487
6488class Overlay(Func):
6489    arg_types = {"this": True, "expression": True, "from": True, "for": False}
6490
6491
6492# https://cloud.google.com/bigquery/docs/reference/standard-sql/bigqueryml-syntax-predict#mlpredict_function
6493class Predict(Func):
6494    arg_types = {"this": True, "expression": True, "params_struct": False}
6495
6496
6497class Pow(Binary, Func):
6498    _sql_names = ["POWER", "POW"]
6499
6500
6501class PercentileCont(AggFunc):
6502    arg_types = {"this": True, "expression": False}
6503
6504
6505class PercentileDisc(AggFunc):
6506    arg_types = {"this": True, "expression": False}
6507
6508
6509class Quantile(AggFunc):
6510    arg_types = {"this": True, "quantile": True}
6511
6512
6513class ApproxQuantile(Quantile):
6514    arg_types = {"this": True, "quantile": True, "accuracy": False, "weight": False}
6515
6516
6517class Quarter(Func):
6518    pass
6519
6520
6521# https://docs.teradata.com/r/Enterprise_IntelliFlex_VMware/SQL-Functions-Expressions-and-Predicates/Arithmetic-Trigonometric-Hyperbolic-Operators/Functions/RANDOM/RANDOM-Function-Syntax
6522# teradata lower and upper bounds
6523class Rand(Func):
6524    _sql_names = ["RAND", "RANDOM"]
6525    arg_types = {"this": False, "lower": False, "upper": False}
6526
6527
6528class Randn(Func):
6529    arg_types = {"this": False}
6530
6531
6532class RangeN(Func):
6533    arg_types = {"this": True, "expressions": True, "each": False}
6534
6535
6536class ReadCSV(Func):
6537    _sql_names = ["READ_CSV"]
6538    is_var_len_args = True
6539    arg_types = {"this": True, "expressions": False}
6540
6541
6542class Reduce(Func):
6543    arg_types = {"this": True, "initial": True, "merge": True, "finish": False}
6544
6545
6546class RegexpExtract(Func):
6547    arg_types = {
6548        "this": True,
6549        "expression": True,
6550        "position": False,
6551        "occurrence": False,
6552        "parameters": False,
6553        "group": False,
6554    }
6555
6556
6557class RegexpExtractAll(Func):
6558    arg_types = {
6559        "this": True,
6560        "expression": True,
6561        "position": False,
6562        "occurrence": False,
6563        "parameters": False,
6564        "group": False,
6565    }
6566
6567
6568class RegexpReplace(Func):
6569    arg_types = {
6570        "this": True,
6571        "expression": True,
6572        "replacement": False,
6573        "position": False,
6574        "occurrence": False,
6575        "modifiers": False,
6576    }
6577
6578
6579class RegexpLike(Binary, Func):
6580    arg_types = {"this": True, "expression": True, "flag": False}
6581
6582
6583class RegexpILike(Binary, Func):
6584    arg_types = {"this": True, "expression": True, "flag": False}
6585
6586
6587# https://spark.apache.org/docs/latest/api/python/reference/pyspark.sql/api/pyspark.sql.functions.split.html
6588# limit is the number of times a pattern is applied
6589class RegexpSplit(Func):
6590    arg_types = {"this": True, "expression": True, "limit": False}
6591
6592
6593class Repeat(Func):
6594    arg_types = {"this": True, "times": True}
6595
6596
6597# https://learn.microsoft.com/en-us/sql/t-sql/functions/round-transact-sql?view=sql-server-ver16
6598# tsql third argument function == trunctaion if not 0
6599class Round(Func):
6600    arg_types = {"this": True, "decimals": False, "truncate": False}
6601
6602
6603class RowNumber(Func):
6604    arg_types = {"this": False}
6605
6606
6607class SafeDivide(Func):
6608    arg_types = {"this": True, "expression": True}
6609
6610
6611class SHA(Func):
6612    _sql_names = ["SHA", "SHA1"]
6613
6614
6615class SHA2(Func):
6616    _sql_names = ["SHA2"]
6617    arg_types = {"this": True, "length": False}
6618
6619
6620class Sign(Func):
6621    _sql_names = ["SIGN", "SIGNUM"]
6622
6623
6624class SortArray(Func):
6625    arg_types = {"this": True, "asc": False}
6626
6627
6628class Split(Func):
6629    arg_types = {"this": True, "expression": True, "limit": False}
6630
6631
6632# https://spark.apache.org/docs/latest/api/python/reference/pyspark.sql/api/pyspark.sql.functions.split_part.html
6633class SplitPart(Func):
6634    arg_types = {"this": True, "delimiter": True, "part_index": True}
6635
6636
6637# Start may be omitted in the case of postgres
6638# https://www.postgresql.org/docs/9.1/functions-string.html @ Table 9-6
6639class Substring(Func):
6640    _sql_names = ["SUBSTRING", "SUBSTR"]
6641    arg_types = {"this": True, "start": False, "length": False}
6642
6643
6644class StandardHash(Func):
6645    arg_types = {"this": True, "expression": False}
6646
6647
6648class StartsWith(Func):
6649    _sql_names = ["STARTS_WITH", "STARTSWITH"]
6650    arg_types = {"this": True, "expression": True}
6651
6652
6653class StrPosition(Func):
6654    arg_types = {
6655        "this": True,
6656        "substr": True,
6657        "position": False,
6658        "occurrence": False,
6659    }
6660
6661
6662class StrToDate(Func):
6663    arg_types = {"this": True, "format": False, "safe": False}
6664
6665
6666class StrToTime(Func):
6667    arg_types = {"this": True, "format": True, "zone": False, "safe": False}
6668
6669
6670# Spark allows unix_timestamp()
6671# https://spark.apache.org/docs/3.1.3/api/python/reference/api/pyspark.sql.functions.unix_timestamp.html
6672class StrToUnix(Func):
6673    arg_types = {"this": False, "format": False}
6674
6675
6676# https://prestodb.io/docs/current/functions/string.html
6677# https://spark.apache.org/docs/latest/api/sql/index.html#str_to_map
6678class StrToMap(Func):
6679    arg_types = {
6680        "this": True,
6681        "pair_delim": False,
6682        "key_value_delim": False,
6683        "duplicate_resolution_callback": False,
6684    }
6685
6686
6687class NumberToStr(Func):
6688    arg_types = {"this": True, "format": True, "culture": False}
6689
6690
6691class FromBase(Func):
6692    arg_types = {"this": True, "expression": True}
6693
6694
6695class Struct(Func):
6696    arg_types = {"expressions": False}
6697    is_var_len_args = True
6698
6699
6700class StructExtract(Func):
6701    arg_types = {"this": True, "expression": True}
6702
6703
6704# https://learn.microsoft.com/en-us/sql/t-sql/functions/stuff-transact-sql?view=sql-server-ver16
6705# https://docs.snowflake.com/en/sql-reference/functions/insert
6706class Stuff(Func):
6707    _sql_names = ["STUFF", "INSERT"]
6708    arg_types = {"this": True, "start": True, "length": True, "expression": True}
6709
6710
6711class Sum(AggFunc):
6712    pass
6713
6714
6715class Sqrt(Func):
6716    pass
6717
6718
6719class Stddev(AggFunc):
6720    _sql_names = ["STDDEV", "STDEV"]
6721
6722
6723class StddevPop(AggFunc):
6724    pass
6725
6726
6727class StddevSamp(AggFunc):
6728    pass
6729
6730
6731# https://cloud.google.com/bigquery/docs/reference/standard-sql/time_functions#time
6732class Time(Func):
6733    arg_types = {"this": False, "zone": False}
6734
6735
6736class TimeToStr(Func):
6737    arg_types = {"this": True, "format": True, "culture": False, "zone": False}
6738
6739
6740class TimeToTimeStr(Func):
6741    pass
6742
6743
6744class TimeToUnix(Func):
6745    pass
6746
6747
6748class TimeStrToDate(Func):
6749    pass
6750
6751
6752class TimeStrToTime(Func):
6753    arg_types = {"this": True, "zone": False}
6754
6755
6756class TimeStrToUnix(Func):
6757    pass
6758
6759
6760class Trim(Func):
6761    arg_types = {
6762        "this": True,
6763        "expression": False,
6764        "position": False,
6765        "collation": False,
6766    }
6767
6768
6769class TsOrDsAdd(Func, TimeUnit):
6770    # return_type is used to correctly cast the arguments of this expression when transpiling it
6771    arg_types = {"this": True, "expression": True, "unit": False, "return_type": False}
6772
6773    @property
6774    def return_type(self) -> DataType:
6775        return DataType.build(self.args.get("return_type") or DataType.Type.DATE)
6776
6777
6778class TsOrDsDiff(Func, TimeUnit):
6779    arg_types = {"this": True, "expression": True, "unit": False}
6780
6781
6782class TsOrDsToDateStr(Func):
6783    pass
6784
6785
6786class TsOrDsToDate(Func):
6787    arg_types = {"this": True, "format": False, "safe": False}
6788
6789
6790class TsOrDsToDatetime(Func):
6791    pass
6792
6793
6794class TsOrDsToTime(Func):
6795    arg_types = {"this": True, "format": False, "safe": False}
6796
6797
6798class TsOrDsToTimestamp(Func):
6799    pass
6800
6801
6802class TsOrDiToDi(Func):
6803    pass
6804
6805
6806class Unhex(Func):
6807    arg_types = {"this": True, "expression": False}
6808
6809
6810class Unicode(Func):
6811    pass
6812
6813
6814# https://cloud.google.com/bigquery/docs/reference/standard-sql/date_functions#unix_date
6815class UnixDate(Func):
6816    pass
6817
6818
6819class UnixToStr(Func):
6820    arg_types = {"this": True, "format": False}
6821
6822
6823# https://prestodb.io/docs/current/functions/datetime.html
6824# presto has weird zone/hours/minutes
6825class UnixToTime(Func):
6826    arg_types = {
6827        "this": True,
6828        "scale": False,
6829        "zone": False,
6830        "hours": False,
6831        "minutes": False,
6832        "format": False,
6833    }
6834
6835    SECONDS = Literal.number(0)
6836    DECIS = Literal.number(1)
6837    CENTIS = Literal.number(2)
6838    MILLIS = Literal.number(3)
6839    DECIMILLIS = Literal.number(4)
6840    CENTIMILLIS = Literal.number(5)
6841    MICROS = Literal.number(6)
6842    DECIMICROS = Literal.number(7)
6843    CENTIMICROS = Literal.number(8)
6844    NANOS = Literal.number(9)
6845
6846
6847class UnixToTimeStr(Func):
6848    pass
6849
6850
6851class UnixSeconds(Func):
6852    pass
6853
6854
6855class Uuid(Func):
6856    _sql_names = ["UUID", "GEN_RANDOM_UUID", "GENERATE_UUID", "UUID_STRING"]
6857
6858    arg_types = {"this": False, "name": False}
6859
6860
6861class TimestampFromParts(Func):
6862    _sql_names = ["TIMESTAMP_FROM_PARTS", "TIMESTAMPFROMPARTS"]
6863    arg_types = {
6864        "year": True,
6865        "month": True,
6866        "day": True,
6867        "hour": True,
6868        "min": True,
6869        "sec": True,
6870        "nano": False,
6871        "zone": False,
6872        "milli": False,
6873    }
6874
6875
6876class Upper(Func):
6877    _sql_names = ["UPPER", "UCASE"]
6878
6879
6880class Corr(Binary, AggFunc):
6881    pass
6882
6883
6884class Variance(AggFunc):
6885    _sql_names = ["VARIANCE", "VARIANCE_SAMP", "VAR_SAMP"]
6886
6887
6888class VariancePop(AggFunc):
6889    _sql_names = ["VARIANCE_POP", "VAR_POP"]
6890
6891
6892class CovarSamp(Binary, AggFunc):
6893    pass
6894
6895
6896class CovarPop(Binary, AggFunc):
6897    pass
6898
6899
6900class Week(Func):
6901    arg_types = {"this": True, "mode": False}
6902
6903
6904class XMLElement(Func):
6905    _sql_names = ["XMLELEMENT"]
6906    arg_types = {"this": True, "expressions": False}
6907
6908
6909class XMLTable(Func):
6910    arg_types = {
6911        "this": True,
6912        "namespaces": False,
6913        "passing": False,
6914        "columns": False,
6915        "by_ref": False,
6916    }
6917
6918
6919class XMLNamespace(Expression):
6920    pass
6921
6922
6923class Year(Func):
6924    pass
6925
6926
6927class Use(Expression):
6928    arg_types = {"this": False, "expressions": False, "kind": False}
6929
6930
6931class Merge(DML):
6932    arg_types = {
6933        "this": True,
6934        "using": True,
6935        "on": True,
6936        "whens": True,
6937        "with": False,
6938        "returning": False,
6939    }
6940
6941
6942class When(Expression):
6943    arg_types = {"matched": True, "source": False, "condition": False, "then": True}
6944
6945
6946class Whens(Expression):
6947    """Wraps around one or more WHEN [NOT] MATCHED [...] clauses."""
6948
6949    arg_types = {"expressions": True}
6950
6951
6952# https://docs.oracle.com/javadb/10.8.3.0/ref/rrefsqljnextvaluefor.html
6953# https://learn.microsoft.com/en-us/sql/t-sql/functions/next-value-for-transact-sql?view=sql-server-ver16
6954class NextValueFor(Func):
6955    arg_types = {"this": True, "order": False}
6956
6957
6958# Refers to a trailing semi-colon. This is only used to preserve trailing comments
6959# select 1; -- my comment
6960class Semicolon(Expression):
6961    arg_types = {}
6962
6963
6964def _norm_arg(arg):
6965    return arg.lower() if type(arg) is str else arg
6966
6967
6968ALL_FUNCTIONS = subclasses(__name__, Func, (AggFunc, Anonymous, Func))
6969FUNCTION_BY_NAME = {name: func for func in ALL_FUNCTIONS for name in func.sql_names()}
6970
6971JSON_PATH_PARTS = subclasses(__name__, JSONPathPart, (JSONPathPart,))
6972
6973PERCENTILES = (PercentileCont, PercentileDisc)
6974
6975
6976# Helpers
6977@t.overload
6978def maybe_parse(
6979    sql_or_expression: ExpOrStr,
6980    *,
6981    into: t.Type[E],
6982    dialect: DialectType = None,
6983    prefix: t.Optional[str] = None,
6984    copy: bool = False,
6985    **opts,
6986) -> E: ...
6987
6988
6989@t.overload
6990def maybe_parse(
6991    sql_or_expression: str | E,
6992    *,
6993    into: t.Optional[IntoType] = None,
6994    dialect: DialectType = None,
6995    prefix: t.Optional[str] = None,
6996    copy: bool = False,
6997    **opts,
6998) -> E: ...
6999
7000
7001def maybe_parse(
7002    sql_or_expression: ExpOrStr,
7003    *,
7004    into: t.Optional[IntoType] = None,
7005    dialect: DialectType = None,
7006    prefix: t.Optional[str] = None,
7007    copy: bool = False,
7008    **opts,
7009) -> Expression:
7010    """Gracefully handle a possible string or expression.
7011
7012    Example:
7013        >>> maybe_parse("1")
7014        Literal(this=1, is_string=False)
7015        >>> maybe_parse(to_identifier("x"))
7016        Identifier(this=x, quoted=False)
7017
7018    Args:
7019        sql_or_expression: the SQL code string or an expression
7020        into: the SQLGlot Expression to parse into
7021        dialect: the dialect used to parse the input expressions (in the case that an
7022            input expression is a SQL string).
7023        prefix: a string to prefix the sql with before it gets parsed
7024            (automatically includes a space)
7025        copy: whether to copy the expression.
7026        **opts: other options to use to parse the input expressions (again, in the case
7027            that an input expression is a SQL string).
7028
7029    Returns:
7030        Expression: the parsed or given expression.
7031    """
7032    if isinstance(sql_or_expression, Expression):
7033        if copy:
7034            return sql_or_expression.copy()
7035        return sql_or_expression
7036
7037    if sql_or_expression is None:
7038        raise ParseError("SQL cannot be None")
7039
7040    import sqlglot
7041
7042    sql = str(sql_or_expression)
7043    if prefix:
7044        sql = f"{prefix} {sql}"
7045
7046    return sqlglot.parse_one(sql, read=dialect, into=into, **opts)
7047
7048
7049@t.overload
7050def maybe_copy(instance: None, copy: bool = True) -> None: ...
7051
7052
7053@t.overload
7054def maybe_copy(instance: E, copy: bool = True) -> E: ...
7055
7056
7057def maybe_copy(instance, copy=True):
7058    return instance.copy() if copy and instance else instance
7059
7060
7061def _to_s(node: t.Any, verbose: bool = False, level: int = 0, repr_str: bool = False) -> str:
7062    """Generate a textual representation of an Expression tree"""
7063    indent = "\n" + ("  " * (level + 1))
7064    delim = f",{indent}"
7065
7066    if isinstance(node, Expression):
7067        args = {k: v for k, v in node.args.items() if (v is not None and v != []) or verbose}
7068
7069        if (node.type or verbose) and not isinstance(node, DataType):
7070            args["_type"] = node.type
7071        if node.comments or verbose:
7072            args["_comments"] = node.comments
7073
7074        if verbose:
7075            args["_id"] = id(node)
7076
7077        # Inline leaves for a more compact representation
7078        if node.is_leaf():
7079            indent = ""
7080            delim = ", "
7081
7082        repr_str = node.is_string or (isinstance(node, Identifier) and node.quoted)
7083        items = delim.join(
7084            [f"{k}={_to_s(v, verbose, level + 1, repr_str=repr_str)}" for k, v in args.items()]
7085        )
7086        return f"{node.__class__.__name__}({indent}{items})"
7087
7088    if isinstance(node, list):
7089        items = delim.join(_to_s(i, verbose, level + 1) for i in node)
7090        items = f"{indent}{items}" if items else ""
7091        return f"[{items}]"
7092
7093    # We use the representation of the string to avoid stripping out important whitespace
7094    if repr_str and isinstance(node, str):
7095        node = repr(node)
7096
7097    # Indent multiline strings to match the current level
7098    return indent.join(textwrap.dedent(str(node).strip("\n")).splitlines())
7099
7100
7101def _is_wrong_expression(expression, into):
7102    return isinstance(expression, Expression) and not isinstance(expression, into)
7103
7104
7105def _apply_builder(
7106    expression,
7107    instance,
7108    arg,
7109    copy=True,
7110    prefix=None,
7111    into=None,
7112    dialect=None,
7113    into_arg="this",
7114    **opts,
7115):
7116    if _is_wrong_expression(expression, into):
7117        expression = into(**{into_arg: expression})
7118    instance = maybe_copy(instance, copy)
7119    expression = maybe_parse(
7120        sql_or_expression=expression,
7121        prefix=prefix,
7122        into=into,
7123        dialect=dialect,
7124        **opts,
7125    )
7126    instance.set(arg, expression)
7127    return instance
7128
7129
7130def _apply_child_list_builder(
7131    *expressions,
7132    instance,
7133    arg,
7134    append=True,
7135    copy=True,
7136    prefix=None,
7137    into=None,
7138    dialect=None,
7139    properties=None,
7140    **opts,
7141):
7142    instance = maybe_copy(instance, copy)
7143    parsed = []
7144    properties = {} if properties is None else properties
7145
7146    for expression in expressions:
7147        if expression is not None:
7148            if _is_wrong_expression(expression, into):
7149                expression = into(expressions=[expression])
7150
7151            expression = maybe_parse(
7152                expression,
7153                into=into,
7154                dialect=dialect,
7155                prefix=prefix,
7156                **opts,
7157            )
7158            for k, v in expression.args.items():
7159                if k == "expressions":
7160                    parsed.extend(v)
7161                else:
7162                    properties[k] = v
7163
7164    existing = instance.args.get(arg)
7165    if append and existing:
7166        parsed = existing.expressions + parsed
7167
7168    child = into(expressions=parsed)
7169    for k, v in properties.items():
7170        child.set(k, v)
7171    instance.set(arg, child)
7172
7173    return instance
7174
7175
7176def _apply_list_builder(
7177    *expressions,
7178    instance,
7179    arg,
7180    append=True,
7181    copy=True,
7182    prefix=None,
7183    into=None,
7184    dialect=None,
7185    **opts,
7186):
7187    inst = maybe_copy(instance, copy)
7188
7189    expressions = [
7190        maybe_parse(
7191            sql_or_expression=expression,
7192            into=into,
7193            prefix=prefix,
7194            dialect=dialect,
7195            **opts,
7196        )
7197        for expression in expressions
7198        if expression is not None
7199    ]
7200
7201    existing_expressions = inst.args.get(arg)
7202    if append and existing_expressions:
7203        expressions = existing_expressions + expressions
7204
7205    inst.set(arg, expressions)
7206    return inst
7207
7208
7209def _apply_conjunction_builder(
7210    *expressions,
7211    instance,
7212    arg,
7213    into=None,
7214    append=True,
7215    copy=True,
7216    dialect=None,
7217    **opts,
7218):
7219    expressions = [exp for exp in expressions if exp is not None and exp != ""]
7220    if not expressions:
7221        return instance
7222
7223    inst = maybe_copy(instance, copy)
7224
7225    existing = inst.args.get(arg)
7226    if append and existing is not None:
7227        expressions = [existing.this if into else existing] + list(expressions)
7228
7229    node = and_(*expressions, dialect=dialect, copy=copy, **opts)
7230
7231    inst.set(arg, into(this=node) if into else node)
7232    return inst
7233
7234
7235def _apply_cte_builder(
7236    instance: E,
7237    alias: ExpOrStr,
7238    as_: ExpOrStr,
7239    recursive: t.Optional[bool] = None,
7240    materialized: t.Optional[bool] = None,
7241    append: bool = True,
7242    dialect: DialectType = None,
7243    copy: bool = True,
7244    scalar: bool = False,
7245    **opts,
7246) -> E:
7247    alias_expression = maybe_parse(alias, dialect=dialect, into=TableAlias, **opts)
7248    as_expression = maybe_parse(as_, dialect=dialect, copy=copy, **opts)
7249    if scalar and not isinstance(as_expression, Subquery):
7250        # scalar CTE must be wrapped in a subquery
7251        as_expression = Subquery(this=as_expression)
7252    cte = CTE(this=as_expression, alias=alias_expression, materialized=materialized, scalar=scalar)
7253    return _apply_child_list_builder(
7254        cte,
7255        instance=instance,
7256        arg="with",
7257        append=append,
7258        copy=copy,
7259        into=With,
7260        properties={"recursive": recursive or False},
7261    )
7262
7263
7264def _combine(
7265    expressions: t.Sequence[t.Optional[ExpOrStr]],
7266    operator: t.Type[Connector],
7267    dialect: DialectType = None,
7268    copy: bool = True,
7269    wrap: bool = True,
7270    **opts,
7271) -> Expression:
7272    conditions = [
7273        condition(expression, dialect=dialect, copy=copy, **opts)
7274        for expression in expressions
7275        if expression is not None
7276    ]
7277
7278    this, *rest = conditions
7279    if rest and wrap:
7280        this = _wrap(this, Connector)
7281    for expression in rest:
7282        this = operator(this=this, expression=_wrap(expression, Connector) if wrap else expression)
7283
7284    return this
7285
7286
7287@t.overload
7288def _wrap(expression: None, kind: t.Type[Expression]) -> None: ...
7289
7290
7291@t.overload
7292def _wrap(expression: E, kind: t.Type[Expression]) -> E | Paren: ...
7293
7294
7295def _wrap(expression: t.Optional[E], kind: t.Type[Expression]) -> t.Optional[E] | Paren:
7296    return Paren(this=expression) if isinstance(expression, kind) else expression
7297
7298
7299def _apply_set_operation(
7300    *expressions: ExpOrStr,
7301    set_operation: t.Type[S],
7302    distinct: bool = True,
7303    dialect: DialectType = None,
7304    copy: bool = True,
7305    **opts,
7306) -> S:
7307    return reduce(
7308        lambda x, y: set_operation(this=x, expression=y, distinct=distinct),
7309        (maybe_parse(e, dialect=dialect, copy=copy, **opts) for e in expressions),
7310    )
7311
7312
7313def union(
7314    *expressions: ExpOrStr,
7315    distinct: bool = True,
7316    dialect: DialectType = None,
7317    copy: bool = True,
7318    **opts,
7319) -> Union:
7320    """
7321    Initializes a syntax tree for the `UNION` operation.
7322
7323    Example:
7324        >>> union("SELECT * FROM foo", "SELECT * FROM bla").sql()
7325        'SELECT * FROM foo UNION SELECT * FROM bla'
7326
7327    Args:
7328        expressions: the SQL code strings, corresponding to the `UNION`'s operands.
7329            If `Expression` instances are passed, they will be used as-is.
7330        distinct: set the DISTINCT flag if and only if this is true.
7331        dialect: the dialect used to parse the input expression.
7332        copy: whether to copy the expression.
7333        opts: other options to use to parse the input expressions.
7334
7335    Returns:
7336        The new Union instance.
7337    """
7338    assert len(expressions) >= 2, "At least two expressions are required by `union`."
7339    return _apply_set_operation(
7340        *expressions, set_operation=Union, distinct=distinct, dialect=dialect, copy=copy, **opts
7341    )
7342
7343
7344def intersect(
7345    *expressions: ExpOrStr,
7346    distinct: bool = True,
7347    dialect: DialectType = None,
7348    copy: bool = True,
7349    **opts,
7350) -> Intersect:
7351    """
7352    Initializes a syntax tree for the `INTERSECT` operation.
7353
7354    Example:
7355        >>> intersect("SELECT * FROM foo", "SELECT * FROM bla").sql()
7356        'SELECT * FROM foo INTERSECT SELECT * FROM bla'
7357
7358    Args:
7359        expressions: the SQL code strings, corresponding to the `INTERSECT`'s operands.
7360            If `Expression` instances are passed, they will be used as-is.
7361        distinct: set the DISTINCT flag if and only if this is true.
7362        dialect: the dialect used to parse the input expression.
7363        copy: whether to copy the expression.
7364        opts: other options to use to parse the input expressions.
7365
7366    Returns:
7367        The new Intersect instance.
7368    """
7369    assert len(expressions) >= 2, "At least two expressions are required by `intersect`."
7370    return _apply_set_operation(
7371        *expressions, set_operation=Intersect, distinct=distinct, dialect=dialect, copy=copy, **opts
7372    )
7373
7374
7375def except_(
7376    *expressions: ExpOrStr,
7377    distinct: bool = True,
7378    dialect: DialectType = None,
7379    copy: bool = True,
7380    **opts,
7381) -> Except:
7382    """
7383    Initializes a syntax tree for the `EXCEPT` operation.
7384
7385    Example:
7386        >>> except_("SELECT * FROM foo", "SELECT * FROM bla").sql()
7387        'SELECT * FROM foo EXCEPT SELECT * FROM bla'
7388
7389    Args:
7390        expressions: the SQL code strings, corresponding to the `EXCEPT`'s operands.
7391            If `Expression` instances are passed, they will be used as-is.
7392        distinct: set the DISTINCT flag if and only if this is true.
7393        dialect: the dialect used to parse the input expression.
7394        copy: whether to copy the expression.
7395        opts: other options to use to parse the input expressions.
7396
7397    Returns:
7398        The new Except instance.
7399    """
7400    assert len(expressions) >= 2, "At least two expressions are required by `except_`."
7401    return _apply_set_operation(
7402        *expressions, set_operation=Except, distinct=distinct, dialect=dialect, copy=copy, **opts
7403    )
7404
7405
7406def select(*expressions: ExpOrStr, dialect: DialectType = None, **opts) -> Select:
7407    """
7408    Initializes a syntax tree from one or multiple SELECT expressions.
7409
7410    Example:
7411        >>> select("col1", "col2").from_("tbl").sql()
7412        'SELECT col1, col2 FROM tbl'
7413
7414    Args:
7415        *expressions: the SQL code string to parse as the expressions of a
7416            SELECT statement. If an Expression instance is passed, this is used as-is.
7417        dialect: the dialect used to parse the input expressions (in the case that an
7418            input expression is a SQL string).
7419        **opts: other options to use to parse the input expressions (again, in the case
7420            that an input expression is a SQL string).
7421
7422    Returns:
7423        Select: the syntax tree for the SELECT statement.
7424    """
7425    return Select().select(*expressions, dialect=dialect, **opts)
7426
7427
7428def from_(expression: ExpOrStr, dialect: DialectType = None, **opts) -> Select:
7429    """
7430    Initializes a syntax tree from a FROM expression.
7431
7432    Example:
7433        >>> from_("tbl").select("col1", "col2").sql()
7434        'SELECT col1, col2 FROM tbl'
7435
7436    Args:
7437        *expression: the SQL code string to parse as the FROM expressions of a
7438            SELECT statement. If an Expression instance is passed, this is used as-is.
7439        dialect: the dialect used to parse the input expression (in the case that the
7440            input expression is a SQL string).
7441        **opts: other options to use to parse the input expressions (again, in the case
7442            that the input expression is a SQL string).
7443
7444    Returns:
7445        Select: the syntax tree for the SELECT statement.
7446    """
7447    return Select().from_(expression, dialect=dialect, **opts)
7448
7449
7450def update(
7451    table: str | Table,
7452    properties: t.Optional[dict] = None,
7453    where: t.Optional[ExpOrStr] = None,
7454    from_: t.Optional[ExpOrStr] = None,
7455    with_: t.Optional[t.Dict[str, ExpOrStr]] = None,
7456    dialect: DialectType = None,
7457    **opts,
7458) -> Update:
7459    """
7460    Creates an update statement.
7461
7462    Example:
7463        >>> 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()
7464        "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"
7465
7466    Args:
7467        properties: dictionary of properties to SET which are
7468            auto converted to sql objects eg None -> NULL
7469        where: sql conditional parsed into a WHERE statement
7470        from_: sql statement parsed into a FROM statement
7471        with_: dictionary of CTE aliases / select statements to include in a WITH clause.
7472        dialect: the dialect used to parse the input expressions.
7473        **opts: other options to use to parse the input expressions.
7474
7475    Returns:
7476        Update: the syntax tree for the UPDATE statement.
7477    """
7478    update_expr = Update(this=maybe_parse(table, into=Table, dialect=dialect))
7479    if properties:
7480        update_expr.set(
7481            "expressions",
7482            [
7483                EQ(this=maybe_parse(k, dialect=dialect, **opts), expression=convert(v))
7484                for k, v in properties.items()
7485            ],
7486        )
7487    if from_:
7488        update_expr.set(
7489            "from",
7490            maybe_parse(from_, into=From, dialect=dialect, prefix="FROM", **opts),
7491        )
7492    if isinstance(where, Condition):
7493        where = Where(this=where)
7494    if where:
7495        update_expr.set(
7496            "where",
7497            maybe_parse(where, into=Where, dialect=dialect, prefix="WHERE", **opts),
7498        )
7499    if with_:
7500        cte_list = [
7501            alias_(CTE(this=maybe_parse(qry, dialect=dialect, **opts)), alias, table=True)
7502            for alias, qry in with_.items()
7503        ]
7504        update_expr.set(
7505            "with",
7506            With(expressions=cte_list),
7507        )
7508    return update_expr
7509
7510
7511def delete(
7512    table: ExpOrStr,
7513    where: t.Optional[ExpOrStr] = None,
7514    returning: t.Optional[ExpOrStr] = None,
7515    dialect: DialectType = None,
7516    **opts,
7517) -> Delete:
7518    """
7519    Builds a delete statement.
7520
7521    Example:
7522        >>> delete("my_table", where="id > 1").sql()
7523        'DELETE FROM my_table WHERE id > 1'
7524
7525    Args:
7526        where: sql conditional parsed into a WHERE statement
7527        returning: sql conditional parsed into a RETURNING statement
7528        dialect: the dialect used to parse the input expressions.
7529        **opts: other options to use to parse the input expressions.
7530
7531    Returns:
7532        Delete: the syntax tree for the DELETE statement.
7533    """
7534    delete_expr = Delete().delete(table, dialect=dialect, copy=False, **opts)
7535    if where:
7536        delete_expr = delete_expr.where(where, dialect=dialect, copy=False, **opts)
7537    if returning:
7538        delete_expr = delete_expr.returning(returning, dialect=dialect, copy=False, **opts)
7539    return delete_expr
7540
7541
7542def insert(
7543    expression: ExpOrStr,
7544    into: ExpOrStr,
7545    columns: t.Optional[t.Sequence[str | Identifier]] = None,
7546    overwrite: t.Optional[bool] = None,
7547    returning: t.Optional[ExpOrStr] = None,
7548    dialect: DialectType = None,
7549    copy: bool = True,
7550    **opts,
7551) -> Insert:
7552    """
7553    Builds an INSERT statement.
7554
7555    Example:
7556        >>> insert("VALUES (1, 2, 3)", "tbl").sql()
7557        'INSERT INTO tbl VALUES (1, 2, 3)'
7558
7559    Args:
7560        expression: the sql string or expression of the INSERT statement
7561        into: the tbl to insert data to.
7562        columns: optionally the table's column names.
7563        overwrite: whether to INSERT OVERWRITE or not.
7564        returning: sql conditional parsed into a RETURNING statement
7565        dialect: the dialect used to parse the input expressions.
7566        copy: whether to copy the expression.
7567        **opts: other options to use to parse the input expressions.
7568
7569    Returns:
7570        Insert: the syntax tree for the INSERT statement.
7571    """
7572    expr = maybe_parse(expression, dialect=dialect, copy=copy, **opts)
7573    this: Table | Schema = maybe_parse(into, into=Table, dialect=dialect, copy=copy, **opts)
7574
7575    if columns:
7576        this = Schema(this=this, expressions=[to_identifier(c, copy=copy) for c in columns])
7577
7578    insert = Insert(this=this, expression=expr, overwrite=overwrite)
7579
7580    if returning:
7581        insert = insert.returning(returning, dialect=dialect, copy=False, **opts)
7582
7583    return insert
7584
7585
7586def merge(
7587    *when_exprs: ExpOrStr,
7588    into: ExpOrStr,
7589    using: ExpOrStr,
7590    on: ExpOrStr,
7591    returning: t.Optional[ExpOrStr] = None,
7592    dialect: DialectType = None,
7593    copy: bool = True,
7594    **opts,
7595) -> Merge:
7596    """
7597    Builds a MERGE statement.
7598
7599    Example:
7600        >>> merge("WHEN MATCHED THEN UPDATE SET col1 = source_table.col1",
7601        ...       "WHEN NOT MATCHED THEN INSERT (col1) VALUES (source_table.col1)",
7602        ...       into="my_table",
7603        ...       using="source_table",
7604        ...       on="my_table.id = source_table.id").sql()
7605        '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)'
7606
7607    Args:
7608        *when_exprs: The WHEN clauses specifying actions for matched and unmatched rows.
7609        into: The target table to merge data into.
7610        using: The source table to merge data from.
7611        on: The join condition for the merge.
7612        returning: The columns to return from the merge.
7613        dialect: The dialect used to parse the input expressions.
7614        copy: Whether to copy the expression.
7615        **opts: Other options to use to parse the input expressions.
7616
7617    Returns:
7618        Merge: The syntax tree for the MERGE statement.
7619    """
7620    expressions: t.List[Expression] = []
7621    for when_expr in when_exprs:
7622        expression = maybe_parse(when_expr, dialect=dialect, copy=copy, into=Whens, **opts)
7623        expressions.extend([expression] if isinstance(expression, When) else expression.expressions)
7624
7625    merge = Merge(
7626        this=maybe_parse(into, dialect=dialect, copy=copy, **opts),
7627        using=maybe_parse(using, dialect=dialect, copy=copy, **opts),
7628        on=maybe_parse(on, dialect=dialect, copy=copy, **opts),
7629        whens=Whens(expressions=expressions),
7630    )
7631    if returning:
7632        merge = merge.returning(returning, dialect=dialect, copy=False, **opts)
7633
7634    return merge
7635
7636
7637def condition(
7638    expression: ExpOrStr, dialect: DialectType = None, copy: bool = True, **opts
7639) -> Condition:
7640    """
7641    Initialize a logical condition expression.
7642
7643    Example:
7644        >>> condition("x=1").sql()
7645        'x = 1'
7646
7647        This is helpful for composing larger logical syntax trees:
7648        >>> where = condition("x=1")
7649        >>> where = where.and_("y=1")
7650        >>> Select().from_("tbl").select("*").where(where).sql()
7651        'SELECT * FROM tbl WHERE x = 1 AND y = 1'
7652
7653    Args:
7654        *expression: the SQL code string to parse.
7655            If an Expression instance is passed, this is used as-is.
7656        dialect: the dialect used to parse the input expression (in the case that the
7657            input expression is a SQL string).
7658        copy: Whether to copy `expression` (only applies to expressions).
7659        **opts: other options to use to parse the input expressions (again, in the case
7660            that the input expression is a SQL string).
7661
7662    Returns:
7663        The new Condition instance
7664    """
7665    return maybe_parse(
7666        expression,
7667        into=Condition,
7668        dialect=dialect,
7669        copy=copy,
7670        **opts,
7671    )
7672
7673
7674def and_(
7675    *expressions: t.Optional[ExpOrStr],
7676    dialect: DialectType = None,
7677    copy: bool = True,
7678    wrap: bool = True,
7679    **opts,
7680) -> Condition:
7681    """
7682    Combine multiple conditions with an AND logical operator.
7683
7684    Example:
7685        >>> and_("x=1", and_("y=1", "z=1")).sql()
7686        'x = 1 AND (y = 1 AND z = 1)'
7687
7688    Args:
7689        *expressions: the SQL code strings to parse.
7690            If an Expression instance is passed, this is used as-is.
7691        dialect: the dialect used to parse the input expression.
7692        copy: whether to copy `expressions` (only applies to Expressions).
7693        wrap: whether to wrap the operands in `Paren`s. This is true by default to avoid
7694            precedence issues, but can be turned off when the produced AST is too deep and
7695            causes recursion-related issues.
7696        **opts: other options to use to parse the input expressions.
7697
7698    Returns:
7699        The new condition
7700    """
7701    return t.cast(Condition, _combine(expressions, And, dialect, copy=copy, wrap=wrap, **opts))
7702
7703
7704def or_(
7705    *expressions: t.Optional[ExpOrStr],
7706    dialect: DialectType = None,
7707    copy: bool = True,
7708    wrap: bool = True,
7709    **opts,
7710) -> Condition:
7711    """
7712    Combine multiple conditions with an OR logical operator.
7713
7714    Example:
7715        >>> or_("x=1", or_("y=1", "z=1")).sql()
7716        'x = 1 OR (y = 1 OR z = 1)'
7717
7718    Args:
7719        *expressions: the SQL code strings to parse.
7720            If an Expression instance is passed, this is used as-is.
7721        dialect: the dialect used to parse the input expression.
7722        copy: whether to copy `expressions` (only applies to Expressions).
7723        wrap: whether to wrap the operands in `Paren`s. This is true by default to avoid
7724            precedence issues, but can be turned off when the produced AST is too deep and
7725            causes recursion-related issues.
7726        **opts: other options to use to parse the input expressions.
7727
7728    Returns:
7729        The new condition
7730    """
7731    return t.cast(Condition, _combine(expressions, Or, dialect, copy=copy, wrap=wrap, **opts))
7732
7733
7734def xor(
7735    *expressions: t.Optional[ExpOrStr],
7736    dialect: DialectType = None,
7737    copy: bool = True,
7738    wrap: bool = True,
7739    **opts,
7740) -> Condition:
7741    """
7742    Combine multiple conditions with an XOR logical operator.
7743
7744    Example:
7745        >>> xor("x=1", xor("y=1", "z=1")).sql()
7746        'x = 1 XOR (y = 1 XOR z = 1)'
7747
7748    Args:
7749        *expressions: the SQL code strings to parse.
7750            If an Expression instance is passed, this is used as-is.
7751        dialect: the dialect used to parse the input expression.
7752        copy: whether to copy `expressions` (only applies to Expressions).
7753        wrap: whether to wrap the operands in `Paren`s. This is true by default to avoid
7754            precedence issues, but can be turned off when the produced AST is too deep and
7755            causes recursion-related issues.
7756        **opts: other options to use to parse the input expressions.
7757
7758    Returns:
7759        The new condition
7760    """
7761    return t.cast(Condition, _combine(expressions, Xor, dialect, copy=copy, wrap=wrap, **opts))
7762
7763
7764def not_(expression: ExpOrStr, dialect: DialectType = None, copy: bool = True, **opts) -> Not:
7765    """
7766    Wrap a condition with a NOT operator.
7767
7768    Example:
7769        >>> not_("this_suit='black'").sql()
7770        "NOT this_suit = 'black'"
7771
7772    Args:
7773        expression: the SQL code string to parse.
7774            If an Expression instance is passed, this is used as-is.
7775        dialect: the dialect used to parse the input expression.
7776        copy: whether to copy the expression or not.
7777        **opts: other options to use to parse the input expressions.
7778
7779    Returns:
7780        The new condition.
7781    """
7782    this = condition(
7783        expression,
7784        dialect=dialect,
7785        copy=copy,
7786        **opts,
7787    )
7788    return Not(this=_wrap(this, Connector))
7789
7790
7791def paren(expression: ExpOrStr, copy: bool = True) -> Paren:
7792    """
7793    Wrap an expression in parentheses.
7794
7795    Example:
7796        >>> paren("5 + 3").sql()
7797        '(5 + 3)'
7798
7799    Args:
7800        expression: the SQL code string to parse.
7801            If an Expression instance is passed, this is used as-is.
7802        copy: whether to copy the expression or not.
7803
7804    Returns:
7805        The wrapped expression.
7806    """
7807    return Paren(this=maybe_parse(expression, copy=copy))
7808
7809
7810SAFE_IDENTIFIER_RE: t.Pattern[str] = re.compile(r"^[_a-zA-Z][\w]*$")
7811
7812
7813@t.overload
7814def to_identifier(name: None, quoted: t.Optional[bool] = None, copy: bool = True) -> None: ...
7815
7816
7817@t.overload
7818def to_identifier(
7819    name: str | Identifier, quoted: t.Optional[bool] = None, copy: bool = True
7820) -> Identifier: ...
7821
7822
7823def to_identifier(name, quoted=None, copy=True):
7824    """Builds an identifier.
7825
7826    Args:
7827        name: The name to turn into an identifier.
7828        quoted: Whether to force quote the identifier.
7829        copy: Whether to copy name if it's an Identifier.
7830
7831    Returns:
7832        The identifier ast node.
7833    """
7834
7835    if name is None:
7836        return None
7837
7838    if isinstance(name, Identifier):
7839        identifier = maybe_copy(name, copy)
7840    elif isinstance(name, str):
7841        identifier = Identifier(
7842            this=name,
7843            quoted=not SAFE_IDENTIFIER_RE.match(name) if quoted is None else quoted,
7844        )
7845    else:
7846        raise ValueError(f"Name needs to be a string or an Identifier, got: {name.__class__}")
7847    return identifier
7848
7849
7850def parse_identifier(name: str | Identifier, dialect: DialectType = None) -> Identifier:
7851    """
7852    Parses a given string into an identifier.
7853
7854    Args:
7855        name: The name to parse into an identifier.
7856        dialect: The dialect to parse against.
7857
7858    Returns:
7859        The identifier ast node.
7860    """
7861    try:
7862        expression = maybe_parse(name, dialect=dialect, into=Identifier)
7863    except (ParseError, TokenError):
7864        expression = to_identifier(name)
7865
7866    return expression
7867
7868
7869INTERVAL_STRING_RE = re.compile(r"\s*(-?[0-9]+)\s*([a-zA-Z]+)\s*")
7870
7871
7872def to_interval(interval: str | Literal) -> Interval:
7873    """Builds an interval expression from a string like '1 day' or '5 months'."""
7874    if isinstance(interval, Literal):
7875        if not interval.is_string:
7876            raise ValueError("Invalid interval string.")
7877
7878        interval = interval.this
7879
7880    interval = maybe_parse(f"INTERVAL {interval}")
7881    assert isinstance(interval, Interval)
7882    return interval
7883
7884
7885def to_table(
7886    sql_path: str | Table, dialect: DialectType = None, copy: bool = True, **kwargs
7887) -> Table:
7888    """
7889    Create a table expression from a `[catalog].[schema].[table]` sql path. Catalog and schema are optional.
7890    If a table is passed in then that table is returned.
7891
7892    Args:
7893        sql_path: a `[catalog].[schema].[table]` string.
7894        dialect: the source dialect according to which the table name will be parsed.
7895        copy: Whether to copy a table if it is passed in.
7896        kwargs: the kwargs to instantiate the resulting `Table` expression with.
7897
7898    Returns:
7899        A table expression.
7900    """
7901    if isinstance(sql_path, Table):
7902        return maybe_copy(sql_path, copy=copy)
7903
7904    table = maybe_parse(sql_path, into=Table, dialect=dialect)
7905
7906    for k, v in kwargs.items():
7907        table.set(k, v)
7908
7909    return table
7910
7911
7912def to_column(
7913    sql_path: str | Column,
7914    quoted: t.Optional[bool] = None,
7915    dialect: DialectType = None,
7916    copy: bool = True,
7917    **kwargs,
7918) -> Column:
7919    """
7920    Create a column from a `[table].[column]` sql path. Table is optional.
7921    If a column is passed in then that column is returned.
7922
7923    Args:
7924        sql_path: a `[table].[column]` string.
7925        quoted: Whether or not to force quote identifiers.
7926        dialect: the source dialect according to which the column name will be parsed.
7927        copy: Whether to copy a column if it is passed in.
7928        kwargs: the kwargs to instantiate the resulting `Column` expression with.
7929
7930    Returns:
7931        A column expression.
7932    """
7933    if isinstance(sql_path, Column):
7934        return maybe_copy(sql_path, copy=copy)
7935
7936    try:
7937        col = maybe_parse(sql_path, into=Column, dialect=dialect)
7938    except ParseError:
7939        return column(*reversed(sql_path.split(".")), quoted=quoted, **kwargs)
7940
7941    for k, v in kwargs.items():
7942        col.set(k, v)
7943
7944    if quoted:
7945        for i in col.find_all(Identifier):
7946            i.set("quoted", True)
7947
7948    return col
7949
7950
7951def alias_(
7952    expression: ExpOrStr,
7953    alias: t.Optional[str | Identifier],
7954    table: bool | t.Sequence[str | Identifier] = False,
7955    quoted: t.Optional[bool] = None,
7956    dialect: DialectType = None,
7957    copy: bool = True,
7958    **opts,
7959):
7960    """Create an Alias expression.
7961
7962    Example:
7963        >>> alias_('foo', 'bar').sql()
7964        'foo AS bar'
7965
7966        >>> alias_('(select 1, 2)', 'bar', table=['a', 'b']).sql()
7967        '(SELECT 1, 2) AS bar(a, b)'
7968
7969    Args:
7970        expression: the SQL code strings to parse.
7971            If an Expression instance is passed, this is used as-is.
7972        alias: the alias name to use. If the name has
7973            special characters it is quoted.
7974        table: Whether to create a table alias, can also be a list of columns.
7975        quoted: whether to quote the alias
7976        dialect: the dialect used to parse the input expression.
7977        copy: Whether to copy the expression.
7978        **opts: other options to use to parse the input expressions.
7979
7980    Returns:
7981        Alias: the aliased expression
7982    """
7983    exp = maybe_parse(expression, dialect=dialect, copy=copy, **opts)
7984    alias = to_identifier(alias, quoted=quoted)
7985
7986    if table:
7987        table_alias = TableAlias(this=alias)
7988        exp.set("alias", table_alias)
7989
7990        if not isinstance(table, bool):
7991            for column in table:
7992                table_alias.append("columns", to_identifier(column, quoted=quoted))
7993
7994        return exp
7995
7996    # We don't set the "alias" arg for Window expressions, because that would add an IDENTIFIER node in
7997    # the AST, representing a "named_window" [1] construct (eg. bigquery). What we want is an ALIAS node
7998    # for the complete Window expression.
7999    #
8000    # [1]: https://cloud.google.com/bigquery/docs/reference/standard-sql/window-function-calls
8001
8002    if "alias" in exp.arg_types and not isinstance(exp, Window):
8003        exp.set("alias", alias)
8004        return exp
8005    return Alias(this=exp, alias=alias)
8006
8007
8008def subquery(
8009    expression: ExpOrStr,
8010    alias: t.Optional[Identifier | str] = None,
8011    dialect: DialectType = None,
8012    **opts,
8013) -> Select:
8014    """
8015    Build a subquery expression that's selected from.
8016
8017    Example:
8018        >>> subquery('select x from tbl', 'bar').select('x').sql()
8019        'SELECT x FROM (SELECT x FROM tbl) AS bar'
8020
8021    Args:
8022        expression: the SQL code strings to parse.
8023            If an Expression instance is passed, this is used as-is.
8024        alias: the alias name to use.
8025        dialect: the dialect used to parse the input expression.
8026        **opts: other options to use to parse the input expressions.
8027
8028    Returns:
8029        A new Select instance with the subquery expression included.
8030    """
8031
8032    expression = maybe_parse(expression, dialect=dialect, **opts).subquery(alias, **opts)
8033    return Select().from_(expression, dialect=dialect, **opts)
8034
8035
8036@t.overload
8037def column(
8038    col: str | Identifier,
8039    table: t.Optional[str | Identifier] = None,
8040    db: t.Optional[str | Identifier] = None,
8041    catalog: t.Optional[str | Identifier] = None,
8042    *,
8043    fields: t.Collection[t.Union[str, Identifier]],
8044    quoted: t.Optional[bool] = None,
8045    copy: bool = True,
8046) -> Dot:
8047    pass
8048
8049
8050@t.overload
8051def column(
8052    col: str | Identifier,
8053    table: t.Optional[str | Identifier] = None,
8054    db: t.Optional[str | Identifier] = None,
8055    catalog: t.Optional[str | Identifier] = None,
8056    *,
8057    fields: Lit[None] = None,
8058    quoted: t.Optional[bool] = None,
8059    copy: bool = True,
8060) -> Column:
8061    pass
8062
8063
8064def column(
8065    col,
8066    table=None,
8067    db=None,
8068    catalog=None,
8069    *,
8070    fields=None,
8071    quoted=None,
8072    copy=True,
8073):
8074    """
8075    Build a Column.
8076
8077    Args:
8078        col: Column name.
8079        table: Table name.
8080        db: Database name.
8081        catalog: Catalog name.
8082        fields: Additional fields using dots.
8083        quoted: Whether to force quotes on the column's identifiers.
8084        copy: Whether to copy identifiers if passed in.
8085
8086    Returns:
8087        The new Column instance.
8088    """
8089    this = Column(
8090        this=to_identifier(col, quoted=quoted, copy=copy),
8091        table=to_identifier(table, quoted=quoted, copy=copy),
8092        db=to_identifier(db, quoted=quoted, copy=copy),
8093        catalog=to_identifier(catalog, quoted=quoted, copy=copy),
8094    )
8095
8096    if fields:
8097        this = Dot.build(
8098            (this, *(to_identifier(field, quoted=quoted, copy=copy) for field in fields))
8099        )
8100    return this
8101
8102
8103def cast(
8104    expression: ExpOrStr, to: DATA_TYPE, copy: bool = True, dialect: DialectType = None, **opts
8105) -> Cast:
8106    """Cast an expression to a data type.
8107
8108    Example:
8109        >>> cast('x + 1', 'int').sql()
8110        'CAST(x + 1 AS INT)'
8111
8112    Args:
8113        expression: The expression to cast.
8114        to: The datatype to cast to.
8115        copy: Whether to copy the supplied expressions.
8116        dialect: The target dialect. This is used to prevent a re-cast in the following scenario:
8117            - The expression to be cast is already a exp.Cast expression
8118            - The existing cast is to a type that is logically equivalent to new type
8119
8120            For example, if :expression='CAST(x as DATETIME)' and :to=Type.TIMESTAMP,
8121            but in the target dialect DATETIME is mapped to TIMESTAMP, then we will NOT return `CAST(x (as DATETIME) as TIMESTAMP)`
8122            and instead just return the original expression `CAST(x as DATETIME)`.
8123
8124            This is to prevent it being output as a double cast `CAST(x (as TIMESTAMP) as TIMESTAMP)` once the DATETIME -> TIMESTAMP
8125            mapping is applied in the target dialect generator.
8126
8127    Returns:
8128        The new Cast instance.
8129    """
8130    expr = maybe_parse(expression, copy=copy, dialect=dialect, **opts)
8131    data_type = DataType.build(to, copy=copy, dialect=dialect, **opts)
8132
8133    # dont re-cast if the expression is already a cast to the correct type
8134    if isinstance(expr, Cast):
8135        from sqlglot.dialects.dialect import Dialect
8136
8137        target_dialect = Dialect.get_or_raise(dialect)
8138        type_mapping = target_dialect.generator_class.TYPE_MAPPING
8139
8140        existing_cast_type: DataType.Type = expr.to.this
8141        new_cast_type: DataType.Type = data_type.this
8142        types_are_equivalent = type_mapping.get(
8143            existing_cast_type, existing_cast_type.value
8144        ) == type_mapping.get(new_cast_type, new_cast_type.value)
8145
8146        if expr.is_type(data_type) or types_are_equivalent:
8147            return expr
8148
8149    expr = Cast(this=expr, to=data_type)
8150    expr.type = data_type
8151
8152    return expr
8153
8154
8155def table_(
8156    table: Identifier | str,
8157    db: t.Optional[Identifier | str] = None,
8158    catalog: t.Optional[Identifier | str] = None,
8159    quoted: t.Optional[bool] = None,
8160    alias: t.Optional[Identifier | str] = None,
8161) -> Table:
8162    """Build a Table.
8163
8164    Args:
8165        table: Table name.
8166        db: Database name.
8167        catalog: Catalog name.
8168        quote: Whether to force quotes on the table's identifiers.
8169        alias: Table's alias.
8170
8171    Returns:
8172        The new Table instance.
8173    """
8174    return Table(
8175        this=to_identifier(table, quoted=quoted) if table else None,
8176        db=to_identifier(db, quoted=quoted) if db else None,
8177        catalog=to_identifier(catalog, quoted=quoted) if catalog else None,
8178        alias=TableAlias(this=to_identifier(alias)) if alias else None,
8179    )
8180
8181
8182def values(
8183    values: t.Iterable[t.Tuple[t.Any, ...]],
8184    alias: t.Optional[str] = None,
8185    columns: t.Optional[t.Iterable[str] | t.Dict[str, DataType]] = None,
8186) -> Values:
8187    """Build VALUES statement.
8188
8189    Example:
8190        >>> values([(1, '2')]).sql()
8191        "VALUES (1, '2')"
8192
8193    Args:
8194        values: values statements that will be converted to SQL
8195        alias: optional alias
8196        columns: Optional list of ordered column names or ordered dictionary of column names to types.
8197         If either are provided then an alias is also required.
8198
8199    Returns:
8200        Values: the Values expression object
8201    """
8202    if columns and not alias:
8203        raise ValueError("Alias is required when providing columns")
8204
8205    return Values(
8206        expressions=[convert(tup) for tup in values],
8207        alias=(
8208            TableAlias(this=to_identifier(alias), columns=[to_identifier(x) for x in columns])
8209            if columns
8210            else (TableAlias(this=to_identifier(alias)) if alias else None)
8211        ),
8212    )
8213
8214
8215def var(name: t.Optional[ExpOrStr]) -> Var:
8216    """Build a SQL variable.
8217
8218    Example:
8219        >>> repr(var('x'))
8220        'Var(this=x)'
8221
8222        >>> repr(var(column('x', table='y')))
8223        'Var(this=x)'
8224
8225    Args:
8226        name: The name of the var or an expression who's name will become the var.
8227
8228    Returns:
8229        The new variable node.
8230    """
8231    if not name:
8232        raise ValueError("Cannot convert empty name into var.")
8233
8234    if isinstance(name, Expression):
8235        name = name.name
8236    return Var(this=name)
8237
8238
8239def rename_table(
8240    old_name: str | Table,
8241    new_name: str | Table,
8242    dialect: DialectType = None,
8243) -> Alter:
8244    """Build ALTER TABLE... RENAME... expression
8245
8246    Args:
8247        old_name: The old name of the table
8248        new_name: The new name of the table
8249        dialect: The dialect to parse the table.
8250
8251    Returns:
8252        Alter table expression
8253    """
8254    old_table = to_table(old_name, dialect=dialect)
8255    new_table = to_table(new_name, dialect=dialect)
8256    return Alter(
8257        this=old_table,
8258        kind="TABLE",
8259        actions=[
8260            AlterRename(this=new_table),
8261        ],
8262    )
8263
8264
8265def rename_column(
8266    table_name: str | Table,
8267    old_column_name: str | Column,
8268    new_column_name: str | Column,
8269    exists: t.Optional[bool] = None,
8270    dialect: DialectType = None,
8271) -> Alter:
8272    """Build ALTER TABLE... RENAME COLUMN... expression
8273
8274    Args:
8275        table_name: Name of the table
8276        old_column: The old name of the column
8277        new_column: The new name of the column
8278        exists: Whether to add the `IF EXISTS` clause
8279        dialect: The dialect to parse the table/column.
8280
8281    Returns:
8282        Alter table expression
8283    """
8284    table = to_table(table_name, dialect=dialect)
8285    old_column = to_column(old_column_name, dialect=dialect)
8286    new_column = to_column(new_column_name, dialect=dialect)
8287    return Alter(
8288        this=table,
8289        kind="TABLE",
8290        actions=[
8291            RenameColumn(this=old_column, to=new_column, exists=exists),
8292        ],
8293    )
8294
8295
8296def convert(value: t.Any, copy: bool = False) -> Expression:
8297    """Convert a python value into an expression object.
8298
8299    Raises an error if a conversion is not possible.
8300
8301    Args:
8302        value: A python object.
8303        copy: Whether to copy `value` (only applies to Expressions and collections).
8304
8305    Returns:
8306        The equivalent expression object.
8307    """
8308    if isinstance(value, Expression):
8309        return maybe_copy(value, copy)
8310    if isinstance(value, str):
8311        return Literal.string(value)
8312    if isinstance(value, bool):
8313        return Boolean(this=value)
8314    if value is None or (isinstance(value, float) and math.isnan(value)):
8315        return null()
8316    if isinstance(value, numbers.Number):
8317        return Literal.number(value)
8318    if isinstance(value, bytes):
8319        return HexString(this=value.hex())
8320    if isinstance(value, datetime.datetime):
8321        datetime_literal = Literal.string(value.isoformat(sep=" "))
8322
8323        tz = None
8324        if value.tzinfo:
8325            # this works for zoneinfo.ZoneInfo, pytz.timezone and datetime.datetime.utc to return IANA timezone names like "America/Los_Angeles"
8326            # instead of abbreviations like "PDT". This is for consistency with other timezone handling functions in SQLGlot
8327            tz = Literal.string(str(value.tzinfo))
8328
8329        return TimeStrToTime(this=datetime_literal, zone=tz)
8330    if isinstance(value, datetime.date):
8331        date_literal = Literal.string(value.strftime("%Y-%m-%d"))
8332        return DateStrToDate(this=date_literal)
8333    if isinstance(value, tuple):
8334        if hasattr(value, "_fields"):
8335            return Struct(
8336                expressions=[
8337                    PropertyEQ(
8338                        this=to_identifier(k), expression=convert(getattr(value, k), copy=copy)
8339                    )
8340                    for k in value._fields
8341                ]
8342            )
8343        return Tuple(expressions=[convert(v, copy=copy) for v in value])
8344    if isinstance(value, list):
8345        return Array(expressions=[convert(v, copy=copy) for v in value])
8346    if isinstance(value, dict):
8347        return Map(
8348            keys=Array(expressions=[convert(k, copy=copy) for k in value]),
8349            values=Array(expressions=[convert(v, copy=copy) for v in value.values()]),
8350        )
8351    if hasattr(value, "__dict__"):
8352        return Struct(
8353            expressions=[
8354                PropertyEQ(this=to_identifier(k), expression=convert(v, copy=copy))
8355                for k, v in value.__dict__.items()
8356            ]
8357        )
8358    raise ValueError(f"Cannot convert {value}")
8359
8360
8361def replace_children(expression: Expression, fun: t.Callable, *args, **kwargs) -> None:
8362    """
8363    Replace children of an expression with the result of a lambda fun(child) -> exp.
8364    """
8365    for k, v in tuple(expression.args.items()):
8366        is_list_arg = type(v) is list
8367
8368        child_nodes = v if is_list_arg else [v]
8369        new_child_nodes = []
8370
8371        for cn in child_nodes:
8372            if isinstance(cn, Expression):
8373                for child_node in ensure_collection(fun(cn, *args, **kwargs)):
8374                    new_child_nodes.append(child_node)
8375            else:
8376                new_child_nodes.append(cn)
8377
8378        expression.set(k, new_child_nodes if is_list_arg else seq_get(new_child_nodes, 0))
8379
8380
8381def replace_tree(
8382    expression: Expression,
8383    fun: t.Callable,
8384    prune: t.Optional[t.Callable[[Expression], bool]] = None,
8385) -> Expression:
8386    """
8387    Replace an entire tree with the result of function calls on each node.
8388
8389    This will be traversed in reverse dfs, so leaves first.
8390    If new nodes are created as a result of function calls, they will also be traversed.
8391    """
8392    stack = list(expression.dfs(prune=prune))
8393
8394    while stack:
8395        node = stack.pop()
8396        new_node = fun(node)
8397
8398        if new_node is not node:
8399            node.replace(new_node)
8400
8401            if isinstance(new_node, Expression):
8402                stack.append(new_node)
8403
8404    return new_node
8405
8406
8407def column_table_names(expression: Expression, exclude: str = "") -> t.Set[str]:
8408    """
8409    Return all table names referenced through columns in an expression.
8410
8411    Example:
8412        >>> import sqlglot
8413        >>> sorted(column_table_names(sqlglot.parse_one("a.b AND c.d AND c.e")))
8414        ['a', 'c']
8415
8416    Args:
8417        expression: expression to find table names.
8418        exclude: a table name to exclude
8419
8420    Returns:
8421        A list of unique names.
8422    """
8423    return {
8424        table
8425        for table in (column.table for column in expression.find_all(Column))
8426        if table and table != exclude
8427    }
8428
8429
8430def table_name(table: Table | str, dialect: DialectType = None, identify: bool = False) -> str:
8431    """Get the full name of a table as a string.
8432
8433    Args:
8434        table: Table expression node or string.
8435        dialect: The dialect to generate the table name for.
8436        identify: Determines when an identifier should be quoted. Possible values are:
8437            False (default): Never quote, except in cases where it's mandatory by the dialect.
8438            True: Always quote.
8439
8440    Examples:
8441        >>> from sqlglot import exp, parse_one
8442        >>> table_name(parse_one("select * from a.b.c").find(exp.Table))
8443        'a.b.c'
8444
8445    Returns:
8446        The table name.
8447    """
8448
8449    table = maybe_parse(table, into=Table, dialect=dialect)
8450
8451    if not table:
8452        raise ValueError(f"Cannot parse {table}")
8453
8454    return ".".join(
8455        (
8456            part.sql(dialect=dialect, identify=True, copy=False, comments=False)
8457            if identify or not SAFE_IDENTIFIER_RE.match(part.name)
8458            else part.name
8459        )
8460        for part in table.parts
8461    )
8462
8463
8464def normalize_table_name(table: str | Table, dialect: DialectType = None, copy: bool = True) -> str:
8465    """Returns a case normalized table name without quotes.
8466
8467    Args:
8468        table: the table to normalize
8469        dialect: the dialect to use for normalization rules
8470        copy: whether to copy the expression.
8471
8472    Examples:
8473        >>> normalize_table_name("`A-B`.c", dialect="bigquery")
8474        'A-B.c'
8475    """
8476    from sqlglot.optimizer.normalize_identifiers import normalize_identifiers
8477
8478    return ".".join(
8479        p.name
8480        for p in normalize_identifiers(
8481            to_table(table, dialect=dialect, copy=copy), dialect=dialect
8482        ).parts
8483    )
8484
8485
8486def replace_tables(
8487    expression: E, mapping: t.Dict[str, str], dialect: DialectType = None, copy: bool = True
8488) -> E:
8489    """Replace all tables in expression according to the mapping.
8490
8491    Args:
8492        expression: expression node to be transformed and replaced.
8493        mapping: mapping of table names.
8494        dialect: the dialect of the mapping table
8495        copy: whether to copy the expression.
8496
8497    Examples:
8498        >>> from sqlglot import exp, parse_one
8499        >>> replace_tables(parse_one("select * from a.b"), {"a.b": "c"}).sql()
8500        'SELECT * FROM c /* a.b */'
8501
8502    Returns:
8503        The mapped expression.
8504    """
8505
8506    mapping = {normalize_table_name(k, dialect=dialect): v for k, v in mapping.items()}
8507
8508    def _replace_tables(node: Expression) -> Expression:
8509        if isinstance(node, Table) and node.meta.get("replace") is not False:
8510            original = normalize_table_name(node, dialect=dialect)
8511            new_name = mapping.get(original)
8512
8513            if new_name:
8514                table = to_table(
8515                    new_name,
8516                    **{k: v for k, v in node.args.items() if k not in TABLE_PARTS},
8517                    dialect=dialect,
8518                )
8519                table.add_comments([original])
8520                return table
8521        return node
8522
8523    return expression.transform(_replace_tables, copy=copy)  # type: ignore
8524
8525
8526def replace_placeholders(expression: Expression, *args, **kwargs) -> Expression:
8527    """Replace placeholders in an expression.
8528
8529    Args:
8530        expression: expression node to be transformed and replaced.
8531        args: positional names that will substitute unnamed placeholders in the given order.
8532        kwargs: keyword arguments that will substitute named placeholders.
8533
8534    Examples:
8535        >>> from sqlglot import exp, parse_one
8536        >>> replace_placeholders(
8537        ...     parse_one("select * from :tbl where ? = ?"),
8538        ...     exp.to_identifier("str_col"), "b", tbl=exp.to_identifier("foo")
8539        ... ).sql()
8540        "SELECT * FROM foo WHERE str_col = 'b'"
8541
8542    Returns:
8543        The mapped expression.
8544    """
8545
8546    def _replace_placeholders(node: Expression, args, **kwargs) -> Expression:
8547        if isinstance(node, Placeholder):
8548            if node.this:
8549                new_name = kwargs.get(node.this)
8550                if new_name is not None:
8551                    return convert(new_name)
8552            else:
8553                try:
8554                    return convert(next(args))
8555                except StopIteration:
8556                    pass
8557        return node
8558
8559    return expression.transform(_replace_placeholders, iter(args), **kwargs)
8560
8561
8562def expand(
8563    expression: Expression,
8564    sources: t.Dict[str, Query | t.Callable[[], Query]],
8565    dialect: DialectType = None,
8566    copy: bool = True,
8567) -> Expression:
8568    """Transforms an expression by expanding all referenced sources into subqueries.
8569
8570    Examples:
8571        >>> from sqlglot import parse_one
8572        >>> expand(parse_one("select * from x AS z"), {"x": parse_one("select * from y")}).sql()
8573        'SELECT * FROM (SELECT * FROM y) AS z /* source: x */'
8574
8575        >>> expand(parse_one("select * from x AS z"), {"x": parse_one("select * from y"), "y": parse_one("select * from z")}).sql()
8576        'SELECT * FROM (SELECT * FROM (SELECT * FROM z) AS y /* source: y */) AS z /* source: x */'
8577
8578    Args:
8579        expression: The expression to expand.
8580        sources: A dict of name to query or a callable that provides a query on demand.
8581        dialect: The dialect of the sources dict or the callable.
8582        copy: Whether to copy the expression during transformation. Defaults to True.
8583
8584    Returns:
8585        The transformed expression.
8586    """
8587    normalized_sources = {normalize_table_name(k, dialect=dialect): v for k, v in sources.items()}
8588
8589    def _expand(node: Expression):
8590        if isinstance(node, Table):
8591            name = normalize_table_name(node, dialect=dialect)
8592            source = normalized_sources.get(name)
8593
8594            if source:
8595                # Create a subquery with the same alias (or table name if no alias)
8596                parsed_source = source() if callable(source) else source
8597                subquery = parsed_source.subquery(node.alias or name)
8598                subquery.comments = [f"source: {name}"]
8599
8600                # Continue expanding within the subquery
8601                return subquery.transform(_expand, copy=False)
8602
8603        return node
8604
8605    return expression.transform(_expand, copy=copy)
8606
8607
8608def func(name: str, *args, copy: bool = True, dialect: DialectType = None, **kwargs) -> Func:
8609    """
8610    Returns a Func expression.
8611
8612    Examples:
8613        >>> func("abs", 5).sql()
8614        'ABS(5)'
8615
8616        >>> func("cast", this=5, to=DataType.build("DOUBLE")).sql()
8617        'CAST(5 AS DOUBLE)'
8618
8619    Args:
8620        name: the name of the function to build.
8621        args: the args used to instantiate the function of interest.
8622        copy: whether to copy the argument expressions.
8623        dialect: the source dialect.
8624        kwargs: the kwargs used to instantiate the function of interest.
8625
8626    Note:
8627        The arguments `args` and `kwargs` are mutually exclusive.
8628
8629    Returns:
8630        An instance of the function of interest, or an anonymous function, if `name` doesn't
8631        correspond to an existing `sqlglot.expressions.Func` class.
8632    """
8633    if args and kwargs:
8634        raise ValueError("Can't use both args and kwargs to instantiate a function.")
8635
8636    from sqlglot.dialects.dialect import Dialect
8637
8638    dialect = Dialect.get_or_raise(dialect)
8639
8640    converted: t.List[Expression] = [maybe_parse(arg, dialect=dialect, copy=copy) for arg in args]
8641    kwargs = {key: maybe_parse(value, dialect=dialect, copy=copy) for key, value in kwargs.items()}
8642
8643    constructor = dialect.parser_class.FUNCTIONS.get(name.upper())
8644    if constructor:
8645        if converted:
8646            if "dialect" in constructor.__code__.co_varnames:
8647                function = constructor(converted, dialect=dialect)
8648            else:
8649                function = constructor(converted)
8650        elif constructor.__name__ == "from_arg_list":
8651            function = constructor.__self__(**kwargs)  # type: ignore
8652        else:
8653            constructor = FUNCTION_BY_NAME.get(name.upper())
8654            if constructor:
8655                function = constructor(**kwargs)
8656            else:
8657                raise ValueError(
8658                    f"Unable to convert '{name}' into a Func. Either manually construct "
8659                    "the Func expression of interest or parse the function call."
8660                )
8661    else:
8662        kwargs = kwargs or {"expressions": converted}
8663        function = Anonymous(this=name, **kwargs)
8664
8665    for error_message in function.error_messages(converted):
8666        raise ValueError(error_message)
8667
8668    return function
8669
8670
8671def case(
8672    expression: t.Optional[ExpOrStr] = None,
8673    **opts,
8674) -> Case:
8675    """
8676    Initialize a CASE statement.
8677
8678    Example:
8679        case().when("a = 1", "foo").else_("bar")
8680
8681    Args:
8682        expression: Optionally, the input expression (not all dialects support this)
8683        **opts: Extra keyword arguments for parsing `expression`
8684    """
8685    if expression is not None:
8686        this = maybe_parse(expression, **opts)
8687    else:
8688        this = None
8689    return Case(this=this, ifs=[])
8690
8691
8692def array(
8693    *expressions: ExpOrStr, copy: bool = True, dialect: DialectType = None, **kwargs
8694) -> Array:
8695    """
8696    Returns an array.
8697
8698    Examples:
8699        >>> array(1, 'x').sql()
8700        'ARRAY(1, x)'
8701
8702    Args:
8703        expressions: the expressions to add to the array.
8704        copy: whether to copy the argument expressions.
8705        dialect: the source dialect.
8706        kwargs: the kwargs used to instantiate the function of interest.
8707
8708    Returns:
8709        An array expression.
8710    """
8711    return Array(
8712        expressions=[
8713            maybe_parse(expression, copy=copy, dialect=dialect, **kwargs)
8714            for expression in expressions
8715        ]
8716    )
8717
8718
8719def tuple_(
8720    *expressions: ExpOrStr, copy: bool = True, dialect: DialectType = None, **kwargs
8721) -> Tuple:
8722    """
8723    Returns an tuple.
8724
8725    Examples:
8726        >>> tuple_(1, 'x').sql()
8727        '(1, x)'
8728
8729    Args:
8730        expressions: the expressions to add to the tuple.
8731        copy: whether to copy the argument expressions.
8732        dialect: the source dialect.
8733        kwargs: the kwargs used to instantiate the function of interest.
8734
8735    Returns:
8736        A tuple expression.
8737    """
8738    return Tuple(
8739        expressions=[
8740            maybe_parse(expression, copy=copy, dialect=dialect, **kwargs)
8741            for expression in expressions
8742        ]
8743    )
8744
8745
8746def true() -> Boolean:
8747    """
8748    Returns a true Boolean expression.
8749    """
8750    return Boolean(this=True)
8751
8752
8753def false() -> Boolean:
8754    """
8755    Returns a false Boolean expression.
8756    """
8757    return Boolean(this=False)
8758
8759
8760def null() -> Null:
8761    """
8762    Returns a Null expression.
8763    """
8764    return Null()
8765
8766
8767NONNULL_CONSTANTS = (
8768    Literal,
8769    Boolean,
8770)
8771
8772CONSTANTS = (
8773    Literal,
8774    Boolean,
8775    Null,
8776)