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