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 typing as t
  20from collections import deque
  21from copy import deepcopy
  22from enum import auto
  23
  24from sqlglot.errors import ParseError
  25from sqlglot.helper import (
  26    AutoName,
  27    camel_to_snake_case,
  28    ensure_collection,
  29    ensure_list,
  30    seq_get,
  31    split_num_words,
  32    subclasses,
  33)
  34from sqlglot.tokens import Token
  35
  36if t.TYPE_CHECKING:
  37    from sqlglot.dialects.dialect import DialectType
  38
  39E = t.TypeVar("E", bound="Expression")
  40
  41
  42class _Expression(type):
  43    def __new__(cls, clsname, bases, attrs):
  44        klass = super().__new__(cls, clsname, bases, attrs)
  45
  46        # When an Expression class is created, its key is automatically set to be
  47        # the lowercase version of the class' name.
  48        klass.key = clsname.lower()
  49
  50        # This is so that docstrings are not inherited in pdoc
  51        klass.__doc__ = klass.__doc__ or ""
  52
  53        return klass
  54
  55
  56class Expression(metaclass=_Expression):
  57    """
  58    The base class for all expressions in a syntax tree. Each Expression encapsulates any necessary
  59    context, such as its child expressions, their names (arg keys), and whether a given child expression
  60    is optional or not.
  61
  62    Attributes:
  63        key: a unique key for each class in the Expression hierarchy. This is useful for hashing
  64            and representing expressions as strings.
  65        arg_types: determines what arguments (child nodes) are supported by an expression. It
  66            maps arg keys to booleans that indicate whether the corresponding args are optional.
  67        parent: a reference to the parent expression (or None, in case of root expressions).
  68        arg_key: the arg key an expression is associated with, i.e. the name its parent expression
  69            uses to refer to it.
  70        comments: a list of comments that are associated with a given expression. This is used in
  71            order to preserve comments when transpiling SQL code.
  72        _type: the `sqlglot.expressions.DataType` type of an expression. This is inferred by the
  73            optimizer, in order to enable some transformations that require type information.
  74
  75    Example:
  76        >>> class Foo(Expression):
  77        ...     arg_types = {"this": True, "expression": False}
  78
  79        The above definition informs us that Foo is an Expression that requires an argument called
  80        "this" and may also optionally receive an argument called "expression".
  81
  82    Args:
  83        args: a mapping used for retrieving the arguments of an expression, given their arg keys.
  84    """
  85
  86    key = "expression"
  87    arg_types = {"this": True}
  88    __slots__ = ("args", "parent", "arg_key", "comments", "_type", "_meta", "_hash")
  89
  90    def __init__(self, **args: t.Any):
  91        self.args: t.Dict[str, t.Any] = args
  92        self.parent: t.Optional[Expression] = None
  93        self.arg_key: t.Optional[str] = None
  94        self.comments: t.Optional[t.List[str]] = None
  95        self._type: t.Optional[DataType] = None
  96        self._meta: t.Optional[t.Dict[str, t.Any]] = None
  97        self._hash: t.Optional[int] = None
  98
  99        for arg_key, value in self.args.items():
 100            self._set_parent(arg_key, value)
 101
 102    def __eq__(self, other) -> bool:
 103        return type(self) is type(other) and hash(self) == hash(other)
 104
 105    @property
 106    def hashable_args(self) -> t.Any:
 107        args = (self.args.get(k) for k in self.arg_types)
 108
 109        return tuple(
 110            (tuple(_norm_arg(a) for a in arg) if arg else None)
 111            if type(arg) is list
 112            else (_norm_arg(arg) if arg is not None and arg is not False else None)
 113            for arg in args
 114        )
 115
 116    def __hash__(self) -> int:
 117        if self._hash is not None:
 118            return self._hash
 119
 120        return hash((self.__class__, self.hashable_args))
 121
 122    @property
 123    def this(self):
 124        """
 125        Retrieves the argument with key "this".
 126        """
 127        return self.args.get("this")
 128
 129    @property
 130    def expression(self):
 131        """
 132        Retrieves the argument with key "expression".
 133        """
 134        return self.args.get("expression")
 135
 136    @property
 137    def expressions(self):
 138        """
 139        Retrieves the argument with key "expressions".
 140        """
 141        return self.args.get("expressions") or []
 142
 143    def text(self, key) -> str:
 144        """
 145        Returns a textual representation of the argument corresponding to "key". This can only be used
 146        for args that are strings or leaf Expression instances, such as identifiers and literals.
 147        """
 148        field = self.args.get(key)
 149        if isinstance(field, str):
 150            return field
 151        if isinstance(field, (Identifier, Literal, Var)):
 152            return field.this
 153        if isinstance(field, (Star, Null)):
 154            return field.name
 155        return ""
 156
 157    @property
 158    def is_string(self) -> bool:
 159        """
 160        Checks whether a Literal expression is a string.
 161        """
 162        return isinstance(self, Literal) and self.args["is_string"]
 163
 164    @property
 165    def is_number(self) -> bool:
 166        """
 167        Checks whether a Literal expression is a number.
 168        """
 169        return isinstance(self, Literal) and not self.args["is_string"]
 170
 171    @property
 172    def is_int(self) -> bool:
 173        """
 174        Checks whether a Literal expression is an integer.
 175        """
 176        if self.is_number:
 177            try:
 178                int(self.name)
 179                return True
 180            except ValueError:
 181                pass
 182        return False
 183
 184    @property
 185    def is_star(self) -> bool:
 186        """Checks whether an expression is a star."""
 187        return isinstance(self, Star) or (isinstance(self, Column) and isinstance(self.this, Star))
 188
 189    @property
 190    def alias(self) -> str:
 191        """
 192        Returns the alias of the expression, or an empty string if it's not aliased.
 193        """
 194        if isinstance(self.args.get("alias"), TableAlias):
 195            return self.args["alias"].name
 196        return self.text("alias")
 197
 198    @property
 199    def name(self) -> str:
 200        return self.text("this")
 201
 202    @property
 203    def alias_or_name(self):
 204        return self.alias or self.name
 205
 206    @property
 207    def output_name(self):
 208        """
 209        Name of the output column if this expression is a selection.
 210
 211        If the Expression has no output name, an empty string is returned.
 212
 213        Example:
 214            >>> from sqlglot import parse_one
 215            >>> parse_one("SELECT a").expressions[0].output_name
 216            'a'
 217            >>> parse_one("SELECT b AS c").expressions[0].output_name
 218            'c'
 219            >>> parse_one("SELECT 1 + 2").expressions[0].output_name
 220            ''
 221        """
 222        return ""
 223
 224    @property
 225    def type(self) -> t.Optional[DataType]:
 226        return self._type
 227
 228    @type.setter
 229    def type(self, dtype: t.Optional[DataType | DataType.Type | str]) -> None:
 230        if dtype and not isinstance(dtype, DataType):
 231            dtype = DataType.build(dtype)
 232        self._type = dtype  # type: ignore
 233
 234    @property
 235    def meta(self) -> t.Dict[str, t.Any]:
 236        if self._meta is None:
 237            self._meta = {}
 238        return self._meta
 239
 240    def __deepcopy__(self, memo):
 241        copy = self.__class__(**deepcopy(self.args))
 242        if self.comments is not None:
 243            copy.comments = deepcopy(self.comments)
 244
 245        if self._type is not None:
 246            copy._type = self._type.copy()
 247
 248        if self._meta is not None:
 249            copy._meta = deepcopy(self._meta)
 250
 251        return copy
 252
 253    def copy(self):
 254        """
 255        Returns a deep copy of the expression.
 256        """
 257        new = deepcopy(self)
 258        new.parent = self.parent
 259        return new
 260
 261    def add_comments(self, comments: t.Optional[t.List[str]]) -> None:
 262        if self.comments is None:
 263            self.comments = []
 264        if comments:
 265            self.comments.extend(comments)
 266
 267    def append(self, arg_key, value):
 268        """
 269        Appends value to arg_key if it's a list or sets it as a new list.
 270
 271        Args:
 272            arg_key (str): name of the list expression arg
 273            value (Any): value to append to the list
 274        """
 275        if not isinstance(self.args.get(arg_key), list):
 276            self.args[arg_key] = []
 277        self.args[arg_key].append(value)
 278        self._set_parent(arg_key, value)
 279
 280    def set(self, arg_key, value):
 281        """
 282        Sets `arg_key` to `value`.
 283
 284        Args:
 285            arg_key (str): name of the expression arg.
 286            value: value to set the arg to.
 287        """
 288        self.args[arg_key] = value
 289        self._set_parent(arg_key, value)
 290
 291    def _set_parent(self, arg_key, value):
 292        if hasattr(value, "parent"):
 293            value.parent = self
 294            value.arg_key = arg_key
 295        elif type(value) is list:
 296            for v in value:
 297                if hasattr(v, "parent"):
 298                    v.parent = self
 299                    v.arg_key = arg_key
 300
 301    @property
 302    def depth(self):
 303        """
 304        Returns the depth of this tree.
 305        """
 306        if self.parent:
 307            return self.parent.depth + 1
 308        return 0
 309
 310    def iter_expressions(self) -> t.Iterator[t.Tuple[str, Expression]]:
 311        """Yields the key and expression for all arguments, exploding list args."""
 312        for k, vs in self.args.items():
 313            if type(vs) is list:
 314                for v in vs:
 315                    if hasattr(v, "parent"):
 316                        yield k, v
 317            else:
 318                if hasattr(vs, "parent"):
 319                    yield k, vs
 320
 321    def find(self, *expression_types: t.Type[E], bfs=True) -> E | None:
 322        """
 323        Returns the first node in this tree which matches at least one of
 324        the specified types.
 325
 326        Args:
 327            expression_types: the expression type(s) to match.
 328
 329        Returns:
 330            The node which matches the criteria or None if no such node was found.
 331        """
 332        return next(self.find_all(*expression_types, bfs=bfs), None)
 333
 334    def find_all(self, *expression_types: t.Type[E], bfs=True) -> t.Iterator[E]:
 335        """
 336        Returns a generator object which visits all nodes in this tree and only
 337        yields those that match at least one of the specified expression types.
 338
 339        Args:
 340            expression_types: the expression type(s) to match.
 341
 342        Returns:
 343            The generator object.
 344        """
 345        for expression, *_ in self.walk(bfs=bfs):
 346            if isinstance(expression, expression_types):
 347                yield expression
 348
 349    def find_ancestor(self, *expression_types: t.Type[E]) -> E | None:
 350        """
 351        Returns a nearest parent matching expression_types.
 352
 353        Args:
 354            expression_types: the expression type(s) to match.
 355
 356        Returns:
 357            The parent node.
 358        """
 359        ancestor = self.parent
 360        while ancestor and not isinstance(ancestor, expression_types):
 361            ancestor = ancestor.parent
 362        return t.cast(E, ancestor)
 363
 364    @property
 365    def parent_select(self):
 366        """
 367        Returns the parent select statement.
 368        """
 369        return self.find_ancestor(Select)
 370
 371    @property
 372    def same_parent(self):
 373        """Returns if the parent is the same class as itself."""
 374        return type(self.parent) is self.__class__
 375
 376    def root(self) -> Expression:
 377        """
 378        Returns the root expression of this tree.
 379        """
 380        expression = self
 381        while expression.parent:
 382            expression = expression.parent
 383        return expression
 384
 385    def walk(self, bfs=True, prune=None):
 386        """
 387        Returns a generator object which visits all nodes in this tree.
 388
 389        Args:
 390            bfs (bool): if set to True the BFS traversal order will be applied,
 391                otherwise the DFS traversal will be used instead.
 392            prune ((node, parent, arg_key) -> bool): callable that returns True if
 393                the generator should stop traversing this branch of the tree.
 394
 395        Returns:
 396            the generator object.
 397        """
 398        if bfs:
 399            yield from self.bfs(prune=prune)
 400        else:
 401            yield from self.dfs(prune=prune)
 402
 403    def dfs(self, parent=None, key=None, prune=None):
 404        """
 405        Returns a generator object which visits all nodes in this tree in
 406        the DFS (Depth-first) order.
 407
 408        Returns:
 409            The generator object.
 410        """
 411        parent = parent or self.parent
 412        yield self, parent, key
 413        if prune and prune(self, parent, key):
 414            return
 415
 416        for k, v in self.iter_expressions():
 417            yield from v.dfs(self, k, prune)
 418
 419    def bfs(self, prune=None):
 420        """
 421        Returns a generator object which visits all nodes in this tree in
 422        the BFS (Breadth-first) order.
 423
 424        Returns:
 425            The generator object.
 426        """
 427        queue = deque([(self, self.parent, None)])
 428
 429        while queue:
 430            item, parent, key = queue.popleft()
 431
 432            yield item, parent, key
 433            if prune and prune(item, parent, key):
 434                continue
 435
 436            for k, v in item.iter_expressions():
 437                queue.append((v, item, k))
 438
 439    def unnest(self):
 440        """
 441        Returns the first non parenthesis child or self.
 442        """
 443        expression = self
 444        while type(expression) is Paren:
 445            expression = expression.this
 446        return expression
 447
 448    def unalias(self):
 449        """
 450        Returns the inner expression if this is an Alias.
 451        """
 452        if isinstance(self, Alias):
 453            return self.this
 454        return self
 455
 456    def unnest_operands(self):
 457        """
 458        Returns unnested operands as a tuple.
 459        """
 460        return tuple(arg.unnest() for _, arg in self.iter_expressions())
 461
 462    def flatten(self, unnest=True):
 463        """
 464        Returns a generator which yields child nodes who's parents are the same class.
 465
 466        A AND B AND C -> [A, B, C]
 467        """
 468        for node, _, _ in self.dfs(prune=lambda n, p, *_: p and not type(n) is self.__class__):
 469            if not type(node) is self.__class__:
 470                yield node.unnest() if unnest else node
 471
 472    def __str__(self):
 473        return self.sql()
 474
 475    def __repr__(self):
 476        return self._to_s()
 477
 478    def sql(self, dialect: DialectType = None, **opts) -> str:
 479        """
 480        Returns SQL string representation of this tree.
 481
 482        Args:
 483            dialect: the dialect of the output SQL string (eg. "spark", "hive", "presto", "mysql").
 484            opts: other `sqlglot.generator.Generator` options.
 485
 486        Returns:
 487            The SQL string.
 488        """
 489        from sqlglot.dialects import Dialect
 490
 491        return Dialect.get_or_raise(dialect)().generate(self, **opts)
 492
 493    def _to_s(self, hide_missing: bool = True, level: int = 0) -> str:
 494        indent = "" if not level else "\n"
 495        indent += "".join(["  "] * level)
 496        left = f"({self.key.upper()} "
 497
 498        args: t.Dict[str, t.Any] = {
 499            k: ", ".join(
 500                v._to_s(hide_missing=hide_missing, level=level + 1)
 501                if hasattr(v, "_to_s")
 502                else str(v)
 503                for v in ensure_list(vs)
 504                if v is not None
 505            )
 506            for k, vs in self.args.items()
 507        }
 508        args["comments"] = self.comments
 509        args["type"] = self.type
 510        args = {k: v for k, v in args.items() if v or not hide_missing}
 511
 512        right = ", ".join(f"{k}: {v}" for k, v in args.items())
 513        right += ")"
 514
 515        return indent + left + right
 516
 517    def transform(self, fun, *args, copy=True, **kwargs):
 518        """
 519        Recursively visits all tree nodes (excluding already transformed ones)
 520        and applies the given transformation function to each node.
 521
 522        Args:
 523            fun (function): a function which takes a node as an argument and returns a
 524                new transformed node or the same node without modifications. If the function
 525                returns None, then the corresponding node will be removed from the syntax tree.
 526            copy (bool): if set to True a new tree instance is constructed, otherwise the tree is
 527                modified in place.
 528
 529        Returns:
 530            The transformed tree.
 531        """
 532        node = self.copy() if copy else self
 533        new_node = fun(node, *args, **kwargs)
 534
 535        if new_node is None or not isinstance(new_node, Expression):
 536            return new_node
 537        if new_node is not node:
 538            new_node.parent = node.parent
 539            return new_node
 540
 541        replace_children(new_node, lambda child: child.transform(fun, *args, copy=False, **kwargs))
 542        return new_node
 543
 544    def replace(self, expression):
 545        """
 546        Swap out this expression with a new expression.
 547
 548        For example::
 549
 550            >>> tree = Select().select("x").from_("tbl")
 551            >>> tree.find(Column).replace(Column(this="y"))
 552            (COLUMN this: y)
 553            >>> tree.sql()
 554            'SELECT y FROM tbl'
 555
 556        Args:
 557            expression (Expression|None): new node
 558
 559        Returns:
 560            The new expression or expressions.
 561        """
 562        if not self.parent:
 563            return expression
 564
 565        parent = self.parent
 566        self.parent = None
 567
 568        replace_children(parent, lambda child: expression if child is self else child)
 569        return expression
 570
 571    def pop(self):
 572        """
 573        Remove this expression from its AST.
 574
 575        Returns:
 576            The popped expression.
 577        """
 578        self.replace(None)
 579        return self
 580
 581    def assert_is(self, type_):
 582        """
 583        Assert that this `Expression` is an instance of `type_`.
 584
 585        If it is NOT an instance of `type_`, this raises an assertion error.
 586        Otherwise, this returns this expression.
 587
 588        Examples:
 589            This is useful for type security in chained expressions:
 590
 591            >>> import sqlglot
 592            >>> sqlglot.parse_one("SELECT x from y").assert_is(Select).select("z").sql()
 593            'SELECT x, z FROM y'
 594        """
 595        assert isinstance(self, type_)
 596        return self
 597
 598    def error_messages(self, args: t.Optional[t.Sequence] = None) -> t.List[str]:
 599        """
 600        Checks if this expression is valid (e.g. all mandatory args are set).
 601
 602        Args:
 603            args: a sequence of values that were used to instantiate a Func expression. This is used
 604                to check that the provided arguments don't exceed the function argument limit.
 605
 606        Returns:
 607            A list of error messages for all possible errors that were found.
 608        """
 609        errors: t.List[str] = []
 610
 611        for k in self.args:
 612            if k not in self.arg_types:
 613                errors.append(f"Unexpected keyword: '{k}' for {self.__class__}")
 614        for k, mandatory in self.arg_types.items():
 615            v = self.args.get(k)
 616            if mandatory and (v is None or (isinstance(v, list) and not v)):
 617                errors.append(f"Required keyword: '{k}' missing for {self.__class__}")
 618
 619        if (
 620            args
 621            and isinstance(self, Func)
 622            and len(args) > len(self.arg_types)
 623            and not self.is_var_len_args
 624        ):
 625            errors.append(
 626                f"The number of provided arguments ({len(args)}) is greater than "
 627                f"the maximum number of supported arguments ({len(self.arg_types)})"
 628            )
 629
 630        return errors
 631
 632    def dump(self):
 633        """
 634        Dump this Expression to a JSON-serializable dict.
 635        """
 636        from sqlglot.serde import dump
 637
 638        return dump(self)
 639
 640    @classmethod
 641    def load(cls, obj):
 642        """
 643        Load a dict (as returned by `Expression.dump`) into an Expression instance.
 644        """
 645        from sqlglot.serde import load
 646
 647        return load(obj)
 648
 649
 650IntoType = t.Union[
 651    str,
 652    t.Type[Expression],
 653    t.Collection[t.Union[str, t.Type[Expression]]],
 654]
 655ExpOrStr = t.Union[str, Expression]
 656
 657
 658class Condition(Expression):
 659    def and_(self, *expressions, dialect=None, copy=True, **opts):
 660        """
 661        AND this condition with one or multiple expressions.
 662
 663        Example:
 664            >>> condition("x=1").and_("y=1").sql()
 665            'x = 1 AND y = 1'
 666
 667        Args:
 668            *expressions (str | Expression): the SQL code strings to parse.
 669                If an `Expression` instance is passed, it will be used as-is.
 670            dialect (str): the dialect used to parse the input expression.
 671            copy (bool): whether or not to copy the involved expressions (only applies to Expressions).
 672            opts (kwargs): other options to use to parse the input expressions.
 673
 674        Returns:
 675            And: the new condition.
 676        """
 677        return and_(self, *expressions, dialect=dialect, copy=copy, **opts)
 678
 679    def or_(self, *expressions, dialect=None, copy=True, **opts):
 680        """
 681        OR this condition with one or multiple expressions.
 682
 683        Example:
 684            >>> condition("x=1").or_("y=1").sql()
 685            'x = 1 OR y = 1'
 686
 687        Args:
 688            *expressions (str | Expression): the SQL code strings to parse.
 689                If an `Expression` instance is passed, it will be used as-is.
 690            dialect (str): the dialect used to parse the input expression.
 691            copy (bool): whether or not to copy the involved expressions (only applies to Expressions).
 692            opts (kwargs): other options to use to parse the input expressions.
 693
 694        Returns:
 695            Or: the new condition.
 696        """
 697        return or_(self, *expressions, dialect=dialect, copy=copy, **opts)
 698
 699    def not_(self, copy=True):
 700        """
 701        Wrap this condition with NOT.
 702
 703        Example:
 704            >>> condition("x=1").not_().sql()
 705            'NOT x = 1'
 706
 707        Args:
 708            copy (bool): whether or not to copy this object.
 709
 710        Returns:
 711            Not: the new condition.
 712        """
 713        return not_(self, copy=copy)
 714
 715    def as_(
 716        self,
 717        alias: str | Identifier,
 718        quoted: t.Optional[bool] = None,
 719        dialect: DialectType = None,
 720        copy: bool = True,
 721        **opts,
 722    ) -> Alias:
 723        return alias_(self, alias, quoted=quoted, dialect=dialect, copy=copy, **opts)
 724
 725    def _binop(self, klass: t.Type[E], other: t.Any, reverse: bool = False) -> E:
 726        this = self.copy()
 727        other = convert(other, copy=True)
 728        if not isinstance(this, klass) and not isinstance(other, klass):
 729            this = _wrap(this, Binary)
 730            other = _wrap(other, Binary)
 731        if reverse:
 732            return klass(this=other, expression=this)
 733        return klass(this=this, expression=other)
 734
 735    def __getitem__(self, other: ExpOrStr | t.Tuple[ExpOrStr]):
 736        return Bracket(
 737            this=self.copy(), expressions=[convert(e, copy=True) for e in ensure_list(other)]
 738        )
 739
 740    def isin(
 741        self, *expressions: t.Any, query: t.Optional[ExpOrStr] = None, copy=True, **opts
 742    ) -> In:
 743        return In(
 744            this=_maybe_copy(self, copy),
 745            expressions=[convert(e, copy=copy) for e in expressions],
 746            query=maybe_parse(query, copy=copy, **opts) if query else None,
 747        )
 748
 749    def between(self, low: t.Any, high: t.Any, copy=True, **opts) -> Between:
 750        return Between(
 751            this=_maybe_copy(self, copy),
 752            low=convert(low, copy=copy, **opts),
 753            high=convert(high, copy=copy, **opts),
 754        )
 755
 756    def is_(self, other: ExpOrStr) -> Is:
 757        return self._binop(Is, other)
 758
 759    def like(self, other: ExpOrStr) -> Like:
 760        return self._binop(Like, other)
 761
 762    def ilike(self, other: ExpOrStr) -> ILike:
 763        return self._binop(ILike, other)
 764
 765    def eq(self, other: t.Any) -> EQ:
 766        return self._binop(EQ, other)
 767
 768    def neq(self, other: t.Any) -> NEQ:
 769        return self._binop(NEQ, other)
 770
 771    def rlike(self, other: ExpOrStr) -> RegexpLike:
 772        return self._binop(RegexpLike, other)
 773
 774    def __lt__(self, other: t.Any) -> LT:
 775        return self._binop(LT, other)
 776
 777    def __le__(self, other: t.Any) -> LTE:
 778        return self._binop(LTE, other)
 779
 780    def __gt__(self, other: t.Any) -> GT:
 781        return self._binop(GT, other)
 782
 783    def __ge__(self, other: t.Any) -> GTE:
 784        return self._binop(GTE, other)
 785
 786    def __add__(self, other: t.Any) -> Add:
 787        return self._binop(Add, other)
 788
 789    def __radd__(self, other: t.Any) -> Add:
 790        return self._binop(Add, other, reverse=True)
 791
 792    def __sub__(self, other: t.Any) -> Sub:
 793        return self._binop(Sub, other)
 794
 795    def __rsub__(self, other: t.Any) -> Sub:
 796        return self._binop(Sub, other, reverse=True)
 797
 798    def __mul__(self, other: t.Any) -> Mul:
 799        return self._binop(Mul, other)
 800
 801    def __rmul__(self, other: t.Any) -> Mul:
 802        return self._binop(Mul, other, reverse=True)
 803
 804    def __truediv__(self, other: t.Any) -> Div:
 805        return self._binop(Div, other)
 806
 807    def __rtruediv__(self, other: t.Any) -> Div:
 808        return self._binop(Div, other, reverse=True)
 809
 810    def __floordiv__(self, other: t.Any) -> IntDiv:
 811        return self._binop(IntDiv, other)
 812
 813    def __rfloordiv__(self, other: t.Any) -> IntDiv:
 814        return self._binop(IntDiv, other, reverse=True)
 815
 816    def __mod__(self, other: t.Any) -> Mod:
 817        return self._binop(Mod, other)
 818
 819    def __rmod__(self, other: t.Any) -> Mod:
 820        return self._binop(Mod, other, reverse=True)
 821
 822    def __pow__(self, other: t.Any) -> Pow:
 823        return self._binop(Pow, other)
 824
 825    def __rpow__(self, other: t.Any) -> Pow:
 826        return self._binop(Pow, other, reverse=True)
 827
 828    def __and__(self, other: t.Any) -> And:
 829        return self._binop(And, other)
 830
 831    def __rand__(self, other: t.Any) -> And:
 832        return self._binop(And, other, reverse=True)
 833
 834    def __or__(self, other: t.Any) -> Or:
 835        return self._binop(Or, other)
 836
 837    def __ror__(self, other: t.Any) -> Or:
 838        return self._binop(Or, other, reverse=True)
 839
 840    def __neg__(self) -> Neg:
 841        return Neg(this=_wrap(self.copy(), Binary))
 842
 843    def __invert__(self) -> Not:
 844        return not_(self.copy())
 845
 846
 847class Predicate(Condition):
 848    """Relationships like x = y, x > 1, x >= y."""
 849
 850
 851class DerivedTable(Expression):
 852    @property
 853    def alias_column_names(self):
 854        table_alias = self.args.get("alias")
 855        if not table_alias:
 856            return []
 857        column_list = table_alias.assert_is(TableAlias).args.get("columns") or []
 858        return [c.name for c in column_list]
 859
 860    @property
 861    def selects(self):
 862        return self.this.selects if isinstance(self.this, Subqueryable) else []
 863
 864    @property
 865    def named_selects(self):
 866        return [select.output_name for select in self.selects]
 867
 868
 869class Unionable(Expression):
 870    def union(self, expression, distinct=True, dialect=None, **opts):
 871        """
 872        Builds a UNION expression.
 873
 874        Example:
 875            >>> import sqlglot
 876            >>> sqlglot.parse_one("SELECT * FROM foo").union("SELECT * FROM bla").sql()
 877            'SELECT * FROM foo UNION SELECT * FROM bla'
 878
 879        Args:
 880            expression (str | Expression): the SQL code string.
 881                If an `Expression` instance is passed, it will be used as-is.
 882            distinct (bool): set the DISTINCT flag if and only if this is true.
 883            dialect (str): the dialect used to parse the input expression.
 884            opts (kwargs): other options to use to parse the input expressions.
 885        Returns:
 886            Union: the Union expression.
 887        """
 888        return union(left=self, right=expression, distinct=distinct, dialect=dialect, **opts)
 889
 890    def intersect(self, expression, distinct=True, dialect=None, **opts):
 891        """
 892        Builds an INTERSECT expression.
 893
 894        Example:
 895            >>> import sqlglot
 896            >>> sqlglot.parse_one("SELECT * FROM foo").intersect("SELECT * FROM bla").sql()
 897            'SELECT * FROM foo INTERSECT SELECT * FROM bla'
 898
 899        Args:
 900            expression (str | Expression): the SQL code string.
 901                If an `Expression` instance is passed, it will be used as-is.
 902            distinct (bool): set the DISTINCT flag if and only if this is true.
 903            dialect (str): the dialect used to parse the input expression.
 904            opts (kwargs): other options to use to parse the input expressions.
 905        Returns:
 906            Intersect: the Intersect expression
 907        """
 908        return intersect(left=self, right=expression, distinct=distinct, dialect=dialect, **opts)
 909
 910    def except_(self, expression, distinct=True, dialect=None, **opts):
 911        """
 912        Builds an EXCEPT expression.
 913
 914        Example:
 915            >>> import sqlglot
 916            >>> sqlglot.parse_one("SELECT * FROM foo").except_("SELECT * FROM bla").sql()
 917            'SELECT * FROM foo EXCEPT SELECT * FROM bla'
 918
 919        Args:
 920            expression (str | Expression): the SQL code string.
 921                If an `Expression` instance is passed, it will be used as-is.
 922            distinct (bool): set the DISTINCT flag if and only if this is true.
 923            dialect (str): the dialect used to parse the input expression.
 924            opts (kwargs): other options to use to parse the input expressions.
 925        Returns:
 926            Except: the Except expression
 927        """
 928        return except_(left=self, right=expression, distinct=distinct, dialect=dialect, **opts)
 929
 930
 931class UDTF(DerivedTable, Unionable):
 932    @property
 933    def selects(self):
 934        alias = self.args.get("alias")
 935        return alias.columns if alias else []
 936
 937
 938class Cache(Expression):
 939    arg_types = {
 940        "with": False,
 941        "this": True,
 942        "lazy": False,
 943        "options": False,
 944        "expression": False,
 945    }
 946
 947
 948class Uncache(Expression):
 949    arg_types = {"this": True, "exists": False}
 950
 951
 952class Create(Expression):
 953    arg_types = {
 954        "with": False,
 955        "this": True,
 956        "kind": True,
 957        "expression": False,
 958        "exists": False,
 959        "properties": False,
 960        "replace": False,
 961        "unique": False,
 962        "indexes": False,
 963        "no_schema_binding": False,
 964        "begin": False,
 965        "clone": False,
 966    }
 967
 968
 969# https://docs.snowflake.com/en/sql-reference/sql/create-clone
 970class Clone(Expression):
 971    arg_types = {
 972        "this": True,
 973        "when": False,
 974        "kind": False,
 975        "expression": False,
 976    }
 977
 978
 979class Describe(Expression):
 980    arg_types = {"this": True, "kind": False}
 981
 982
 983class Pragma(Expression):
 984    pass
 985
 986
 987class Set(Expression):
 988    arg_types = {"expressions": False}
 989
 990
 991class SetItem(Expression):
 992    arg_types = {
 993        "this": False,
 994        "expressions": False,
 995        "kind": False,
 996        "collate": False,  # MySQL SET NAMES statement
 997        "global": False,
 998    }
 999
1000
1001class Show(Expression):
1002    arg_types = {
1003        "this": True,
1004        "target": False,
1005        "offset": False,
1006        "limit": False,
1007        "like": False,
1008        "where": False,
1009        "db": False,
1010        "full": False,
1011        "mutex": False,
1012        "query": False,
1013        "channel": False,
1014        "global": False,
1015        "log": False,
1016        "position": False,
1017        "types": False,
1018    }
1019
1020
1021class UserDefinedFunction(Expression):
1022    arg_types = {"this": True, "expressions": False, "wrapped": False}
1023
1024
1025class CharacterSet(Expression):
1026    arg_types = {"this": True, "default": False}
1027
1028
1029class With(Expression):
1030    arg_types = {"expressions": True, "recursive": False}
1031
1032    @property
1033    def recursive(self) -> bool:
1034        return bool(self.args.get("recursive"))
1035
1036
1037class WithinGroup(Expression):
1038    arg_types = {"this": True, "expression": False}
1039
1040
1041class CTE(DerivedTable):
1042    arg_types = {"this": True, "alias": True}
1043
1044
1045class TableAlias(Expression):
1046    arg_types = {"this": False, "columns": False}
1047
1048    @property
1049    def columns(self):
1050        return self.args.get("columns") or []
1051
1052
1053class BitString(Condition):
1054    pass
1055
1056
1057class HexString(Condition):
1058    pass
1059
1060
1061class ByteString(Condition):
1062    pass
1063
1064
1065class Column(Condition):
1066    arg_types = {"this": True, "table": False, "db": False, "catalog": False, "join_mark": False}
1067
1068    @property
1069    def table(self) -> str:
1070        return self.text("table")
1071
1072    @property
1073    def db(self) -> str:
1074        return self.text("db")
1075
1076    @property
1077    def catalog(self) -> str:
1078        return self.text("catalog")
1079
1080    @property
1081    def output_name(self) -> str:
1082        return self.name
1083
1084    @property
1085    def parts(self) -> t.List[Identifier]:
1086        """Return the parts of a column in order catalog, db, table, name."""
1087        return [
1088            t.cast(Identifier, self.args[part])
1089            for part in ("catalog", "db", "table", "this")
1090            if self.args.get(part)
1091        ]
1092
1093    def to_dot(self) -> Dot:
1094        """Converts the column into a dot expression."""
1095        parts = self.parts
1096        parent = self.parent
1097
1098        while parent:
1099            if isinstance(parent, Dot):
1100                parts.append(parent.expression)
1101            parent = parent.parent
1102
1103        return Dot.build(parts)
1104
1105
1106class ColumnPosition(Expression):
1107    arg_types = {"this": False, "position": True}
1108
1109
1110class ColumnDef(Expression):
1111    arg_types = {
1112        "this": True,
1113        "kind": False,
1114        "constraints": False,
1115        "exists": False,
1116        "position": False,
1117    }
1118
1119    @property
1120    def constraints(self) -> t.List[ColumnConstraint]:
1121        return self.args.get("constraints") or []
1122
1123
1124class AlterColumn(Expression):
1125    arg_types = {
1126        "this": True,
1127        "dtype": False,
1128        "collate": False,
1129        "using": False,
1130        "default": False,
1131        "drop": False,
1132    }
1133
1134
1135class RenameTable(Expression):
1136    pass
1137
1138
1139class SetTag(Expression):
1140    arg_types = {"expressions": True, "unset": False}
1141
1142
1143class Comment(Expression):
1144    arg_types = {"this": True, "kind": True, "expression": True, "exists": False}
1145
1146
1147# https://clickhouse.com/docs/en/engines/table-engines/mergetree-family/mergetree#mergetree-table-ttl
1148class MergeTreeTTLAction(Expression):
1149    arg_types = {
1150        "this": True,
1151        "delete": False,
1152        "recompress": False,
1153        "to_disk": False,
1154        "to_volume": False,
1155    }
1156
1157
1158# https://clickhouse.com/docs/en/engines/table-engines/mergetree-family/mergetree#mergetree-table-ttl
1159class MergeTreeTTL(Expression):
1160    arg_types = {
1161        "expressions": True,
1162        "where": False,
1163        "group": False,
1164        "aggregates": False,
1165    }
1166
1167
1168class ColumnConstraint(Expression):
1169    arg_types = {"this": False, "kind": True}
1170
1171    @property
1172    def kind(self) -> ColumnConstraintKind:
1173        return self.args["kind"]
1174
1175
1176class ColumnConstraintKind(Expression):
1177    pass
1178
1179
1180class AutoIncrementColumnConstraint(ColumnConstraintKind):
1181    pass
1182
1183
1184class CaseSpecificColumnConstraint(ColumnConstraintKind):
1185    arg_types = {"not_": True}
1186
1187
1188class CharacterSetColumnConstraint(ColumnConstraintKind):
1189    arg_types = {"this": True}
1190
1191
1192class CheckColumnConstraint(ColumnConstraintKind):
1193    pass
1194
1195
1196class CollateColumnConstraint(ColumnConstraintKind):
1197    pass
1198
1199
1200class CommentColumnConstraint(ColumnConstraintKind):
1201    pass
1202
1203
1204class CompressColumnConstraint(ColumnConstraintKind):
1205    pass
1206
1207
1208class DateFormatColumnConstraint(ColumnConstraintKind):
1209    arg_types = {"this": True}
1210
1211
1212class DefaultColumnConstraint(ColumnConstraintKind):
1213    pass
1214
1215
1216class EncodeColumnConstraint(ColumnConstraintKind):
1217    pass
1218
1219
1220class GeneratedAsIdentityColumnConstraint(ColumnConstraintKind):
1221    # this: True -> ALWAYS, this: False -> BY DEFAULT
1222    arg_types = {
1223        "this": False,
1224        "on_null": False,
1225        "start": False,
1226        "increment": False,
1227        "minvalue": False,
1228        "maxvalue": False,
1229        "cycle": False,
1230    }
1231
1232
1233class InlineLengthColumnConstraint(ColumnConstraintKind):
1234    pass
1235
1236
1237class NotNullColumnConstraint(ColumnConstraintKind):
1238    arg_types = {"allow_null": False}
1239
1240
1241# https://dev.mysql.com/doc/refman/5.7/en/timestamp-initialization.html
1242class OnUpdateColumnConstraint(ColumnConstraintKind):
1243    pass
1244
1245
1246class PrimaryKeyColumnConstraint(ColumnConstraintKind):
1247    arg_types = {"desc": False}
1248
1249
1250class TitleColumnConstraint(ColumnConstraintKind):
1251    pass
1252
1253
1254class UniqueColumnConstraint(ColumnConstraintKind):
1255    arg_types: t.Dict[str, t.Any] = {}
1256
1257
1258class UppercaseColumnConstraint(ColumnConstraintKind):
1259    arg_types: t.Dict[str, t.Any] = {}
1260
1261
1262class PathColumnConstraint(ColumnConstraintKind):
1263    pass
1264
1265
1266class Constraint(Expression):
1267    arg_types = {"this": True, "expressions": True}
1268
1269
1270class Delete(Expression):
1271    arg_types = {"with": False, "this": False, "using": False, "where": False, "returning": False}
1272
1273    def delete(
1274        self,
1275        table: ExpOrStr,
1276        dialect: DialectType = None,
1277        copy: bool = True,
1278        **opts,
1279    ) -> Delete:
1280        """
1281        Create a DELETE expression or replace the table on an existing DELETE expression.
1282
1283        Example:
1284            >>> delete("tbl").sql()
1285            'DELETE FROM tbl'
1286
1287        Args:
1288            table: the table from which to delete.
1289            dialect: the dialect used to parse the input expression.
1290            copy: if `False`, modify this expression instance in-place.
1291            opts: other options to use to parse the input expressions.
1292
1293        Returns:
1294            Delete: the modified expression.
1295        """
1296        return _apply_builder(
1297            expression=table,
1298            instance=self,
1299            arg="this",
1300            dialect=dialect,
1301            into=Table,
1302            copy=copy,
1303            **opts,
1304        )
1305
1306    def where(
1307        self,
1308        *expressions: ExpOrStr,
1309        append: bool = True,
1310        dialect: DialectType = None,
1311        copy: bool = True,
1312        **opts,
1313    ) -> Delete:
1314        """
1315        Append to or set the WHERE expressions.
1316
1317        Example:
1318            >>> delete("tbl").where("x = 'a' OR x < 'b'").sql()
1319            "DELETE FROM tbl WHERE x = 'a' OR x < 'b'"
1320
1321        Args:
1322            *expressions: the SQL code strings to parse.
1323                If an `Expression` instance is passed, it will be used as-is.
1324                Multiple expressions are combined with an AND operator.
1325            append: if `True`, AND the new expressions to any existing expression.
1326                Otherwise, this resets the expression.
1327            dialect: the dialect used to parse the input expressions.
1328            copy: if `False`, modify this expression instance in-place.
1329            opts: other options to use to parse the input expressions.
1330
1331        Returns:
1332            Delete: the modified expression.
1333        """
1334        return _apply_conjunction_builder(
1335            *expressions,
1336            instance=self,
1337            arg="where",
1338            append=append,
1339            into=Where,
1340            dialect=dialect,
1341            copy=copy,
1342            **opts,
1343        )
1344
1345    def returning(
1346        self,
1347        expression: ExpOrStr,
1348        dialect: DialectType = None,
1349        copy: bool = True,
1350        **opts,
1351    ) -> Delete:
1352        """
1353        Set the RETURNING expression. Not supported by all dialects.
1354
1355        Example:
1356            >>> delete("tbl").returning("*", dialect="postgres").sql()
1357            'DELETE FROM tbl RETURNING *'
1358
1359        Args:
1360            expression: the SQL code strings to parse.
1361                If an `Expression` instance is passed, it will be used as-is.
1362            dialect: the dialect used to parse the input expressions.
1363            copy: if `False`, modify this expression instance in-place.
1364            opts: other options to use to parse the input expressions.
1365
1366        Returns:
1367            Delete: the modified expression.
1368        """
1369        return _apply_builder(
1370            expression=expression,
1371            instance=self,
1372            arg="returning",
1373            prefix="RETURNING",
1374            dialect=dialect,
1375            copy=copy,
1376            into=Returning,
1377            **opts,
1378        )
1379
1380
1381class Drop(Expression):
1382    arg_types = {
1383        "this": False,
1384        "kind": False,
1385        "exists": False,
1386        "temporary": False,
1387        "materialized": False,
1388        "cascade": False,
1389        "constraints": False,
1390        "purge": False,
1391    }
1392
1393
1394class Filter(Expression):
1395    arg_types = {"this": True, "expression": True}
1396
1397
1398class Check(Expression):
1399    pass
1400
1401
1402class Directory(Expression):
1403    # https://spark.apache.org/docs/3.0.0-preview/sql-ref-syntax-dml-insert-overwrite-directory-hive.html
1404    arg_types = {"this": True, "local": False, "row_format": False}
1405
1406
1407class ForeignKey(Expression):
1408    arg_types = {
1409        "expressions": True,
1410        "reference": False,
1411        "delete": False,
1412        "update": False,
1413    }
1414
1415
1416class PrimaryKey(Expression):
1417    arg_types = {"expressions": True, "options": False}
1418
1419
1420class Unique(Expression):
1421    arg_types = {"expressions": True}
1422
1423
1424# https://www.postgresql.org/docs/9.1/sql-selectinto.html
1425# https://docs.aws.amazon.com/redshift/latest/dg/r_SELECT_INTO.html#r_SELECT_INTO-examples
1426class Into(Expression):
1427    arg_types = {"this": True, "temporary": False, "unlogged": False}
1428
1429
1430class From(Expression):
1431    @property
1432    def name(self) -> str:
1433        return self.this.name
1434
1435    @property
1436    def alias_or_name(self) -> str:
1437        return self.this.alias_or_name
1438
1439
1440class Having(Expression):
1441    pass
1442
1443
1444class Hint(Expression):
1445    arg_types = {"expressions": True}
1446
1447
1448class JoinHint(Expression):
1449    arg_types = {"this": True, "expressions": True}
1450
1451
1452class Identifier(Expression):
1453    arg_types = {"this": True, "quoted": False}
1454
1455    @property
1456    def quoted(self):
1457        return bool(self.args.get("quoted"))
1458
1459    @property
1460    def hashable_args(self) -> t.Any:
1461        if self.quoted and any(char.isupper() for char in self.this):
1462            return (self.this, self.quoted)
1463        return self.this.lower()
1464
1465    @property
1466    def output_name(self):
1467        return self.name
1468
1469
1470class Index(Expression):
1471    arg_types = {
1472        "this": False,
1473        "table": False,
1474        "where": False,
1475        "columns": False,
1476        "unique": False,
1477        "primary": False,
1478        "amp": False,  # teradata
1479    }
1480
1481
1482class Insert(Expression):
1483    arg_types = {
1484        "with": False,
1485        "this": True,
1486        "expression": False,
1487        "conflict": False,
1488        "returning": False,
1489        "overwrite": False,
1490        "exists": False,
1491        "partition": False,
1492        "alternative": False,
1493    }
1494
1495    def with_(
1496        self,
1497        alias: ExpOrStr,
1498        as_: ExpOrStr,
1499        recursive: t.Optional[bool] = None,
1500        append: bool = True,
1501        dialect: DialectType = None,
1502        copy: bool = True,
1503        **opts,
1504    ) -> Insert:
1505        """
1506        Append to or set the common table expressions.
1507
1508        Example:
1509            >>> insert("SELECT x FROM cte", "t").with_("cte", as_="SELECT * FROM tbl").sql()
1510            'WITH cte AS (SELECT * FROM tbl) INSERT INTO t SELECT x FROM cte'
1511
1512        Args:
1513            alias: the SQL code string to parse as the table name.
1514                If an `Expression` instance is passed, this is used as-is.
1515            as_: the SQL code string to parse as the table expression.
1516                If an `Expression` instance is passed, it will be used as-is.
1517            recursive: set the RECURSIVE part of the expression. Defaults to `False`.
1518            append: if `True`, add to any existing expressions.
1519                Otherwise, this resets the expressions.
1520            dialect: the dialect used to parse the input expression.
1521            copy: if `False`, modify this expression instance in-place.
1522            opts: other options to use to parse the input expressions.
1523
1524        Returns:
1525            The modified expression.
1526        """
1527        return _apply_cte_builder(
1528            self, alias, as_, recursive=recursive, append=append, dialect=dialect, copy=copy, **opts
1529        )
1530
1531
1532class OnConflict(Expression):
1533    arg_types = {
1534        "duplicate": False,
1535        "expressions": False,
1536        "nothing": False,
1537        "key": False,
1538        "constraint": False,
1539    }
1540
1541
1542class Returning(Expression):
1543    arg_types = {"expressions": True}
1544
1545
1546# https://dev.mysql.com/doc/refman/8.0/en/charset-introducer.html
1547class Introducer(Expression):
1548    arg_types = {"this": True, "expression": True}
1549
1550
1551# national char, like n'utf8'
1552class National(Expression):
1553    pass
1554
1555
1556class LoadData(Expression):
1557    arg_types = {
1558        "this": True,
1559        "local": False,
1560        "overwrite": False,
1561        "inpath": True,
1562        "partition": False,
1563        "input_format": False,
1564        "serde": False,
1565    }
1566
1567
1568class Partition(Expression):
1569    arg_types = {"expressions": True}
1570
1571
1572class Fetch(Expression):
1573    arg_types = {
1574        "direction": False,
1575        "count": False,
1576        "percent": False,
1577        "with_ties": False,
1578    }
1579
1580
1581class Group(Expression):
1582    arg_types = {
1583        "expressions": False,
1584        "grouping_sets": False,
1585        "cube": False,
1586        "rollup": False,
1587        "totals": False,
1588    }
1589
1590
1591class Lambda(Expression):
1592    arg_types = {"this": True, "expressions": True}
1593
1594
1595class Limit(Expression):
1596    arg_types = {"this": False, "expression": True}
1597
1598
1599class Literal(Condition):
1600    arg_types = {"this": True, "is_string": True}
1601
1602    @property
1603    def hashable_args(self) -> t.Any:
1604        return (self.this, self.args.get("is_string"))
1605
1606    @classmethod
1607    def number(cls, number) -> Literal:
1608        return cls(this=str(number), is_string=False)
1609
1610    @classmethod
1611    def string(cls, string) -> Literal:
1612        return cls(this=str(string), is_string=True)
1613
1614    @property
1615    def output_name(self):
1616        return self.name
1617
1618
1619class Join(Expression):
1620    arg_types = {
1621        "this": True,
1622        "on": False,
1623        "side": False,
1624        "kind": False,
1625        "using": False,
1626        "natural": False,
1627        "global": False,
1628        "hint": False,
1629    }
1630
1631    @property
1632    def kind(self):
1633        return self.text("kind").upper()
1634
1635    @property
1636    def side(self):
1637        return self.text("side").upper()
1638
1639    @property
1640    def hint(self):
1641        return self.text("hint").upper()
1642
1643    @property
1644    def alias_or_name(self):
1645        return self.this.alias_or_name
1646
1647    def on(self, *expressions, append=True, dialect=None, copy=True, **opts):
1648        """
1649        Append to or set the ON expressions.
1650
1651        Example:
1652            >>> import sqlglot
1653            >>> sqlglot.parse_one("JOIN x", into=Join).on("y = 1").sql()
1654            'JOIN x ON y = 1'
1655
1656        Args:
1657            *expressions (str | Expression): the SQL code strings to parse.
1658                If an `Expression` instance is passed, it will be used as-is.
1659                Multiple expressions are combined with an AND operator.
1660            append (bool): if `True`, AND the new expressions to any existing expression.
1661                Otherwise, this resets the expression.
1662            dialect (str): the dialect used to parse the input expressions.
1663            copy (bool): if `False`, modify this expression instance in-place.
1664            opts (kwargs): other options to use to parse the input expressions.
1665
1666        Returns:
1667            Join: the modified join expression.
1668        """
1669        join = _apply_conjunction_builder(
1670            *expressions,
1671            instance=self,
1672            arg="on",
1673            append=append,
1674            dialect=dialect,
1675            copy=copy,
1676            **opts,
1677        )
1678
1679        if join.kind == "CROSS":
1680            join.set("kind", None)
1681
1682        return join
1683
1684    def using(self, *expressions, append=True, dialect=None, copy=True, **opts):
1685        """
1686        Append to or set the USING expressions.
1687
1688        Example:
1689            >>> import sqlglot
1690            >>> sqlglot.parse_one("JOIN x", into=Join).using("foo", "bla").sql()
1691            'JOIN x USING (foo, bla)'
1692
1693        Args:
1694            *expressions (str | Expression): the SQL code strings to parse.
1695                If an `Expression` instance is passed, it will be used as-is.
1696            append (bool): if `True`, concatenate the new expressions to the existing "using" list.
1697                Otherwise, this resets the expression.
1698            dialect (str): the dialect used to parse the input expressions.
1699            copy (bool): if `False`, modify this expression instance in-place.
1700            opts (kwargs): other options to use to parse the input expressions.
1701
1702        Returns:
1703            Join: the modified join expression.
1704        """
1705        join = _apply_list_builder(
1706            *expressions,
1707            instance=self,
1708            arg="using",
1709            append=append,
1710            dialect=dialect,
1711            copy=copy,
1712            **opts,
1713        )
1714
1715        if join.kind == "CROSS":
1716            join.set("kind", None)
1717
1718        return join
1719
1720
1721class Lateral(UDTF):
1722    arg_types = {"this": True, "view": False, "outer": False, "alias": False}
1723
1724
1725class MatchRecognize(Expression):
1726    arg_types = {
1727        "partition_by": False,
1728        "order": False,
1729        "measures": False,
1730        "rows": False,
1731        "after": False,
1732        "pattern": False,
1733        "define": False,
1734        "alias": False,
1735    }
1736
1737
1738# Clickhouse FROM FINAL modifier
1739# https://clickhouse.com/docs/en/sql-reference/statements/select/from/#final-modifier
1740class Final(Expression):
1741    pass
1742
1743
1744class Offset(Expression):
1745    arg_types = {"this": False, "expression": True}
1746
1747
1748class Order(Expression):
1749    arg_types = {"this": False, "expressions": True}
1750
1751
1752# hive specific sorts
1753# https://cwiki.apache.org/confluence/display/Hive/LanguageManual+SortBy
1754class Cluster(Order):
1755    pass
1756
1757
1758class Distribute(Order):
1759    pass
1760
1761
1762class Sort(Order):
1763    pass
1764
1765
1766class Ordered(Expression):
1767    arg_types = {"this": True, "desc": True, "nulls_first": True}
1768
1769
1770class Property(Expression):
1771    arg_types = {"this": True, "value": True}
1772
1773
1774class AfterJournalProperty(Property):
1775    arg_types = {"no": True, "dual": False, "local": False}
1776
1777
1778class AlgorithmProperty(Property):
1779    arg_types = {"this": True}
1780
1781
1782class AutoIncrementProperty(Property):
1783    arg_types = {"this": True}
1784
1785
1786class BlockCompressionProperty(Property):
1787    arg_types = {"autotemp": False, "always": False, "default": True, "manual": True, "never": True}
1788
1789
1790class CharacterSetProperty(Property):
1791    arg_types = {"this": True, "default": True}
1792
1793
1794class ChecksumProperty(Property):
1795    arg_types = {"on": False, "default": False}
1796
1797
1798class CollateProperty(Property):
1799    arg_types = {"this": True}
1800
1801
1802class DataBlocksizeProperty(Property):
1803    arg_types = {"size": False, "units": False, "min": False, "default": False}
1804
1805
1806class DefinerProperty(Property):
1807    arg_types = {"this": True}
1808
1809
1810class DistKeyProperty(Property):
1811    arg_types = {"this": True}
1812
1813
1814class DistStyleProperty(Property):
1815    arg_types = {"this": True}
1816
1817
1818class EngineProperty(Property):
1819    arg_types = {"this": True}
1820
1821
1822class ExecuteAsProperty(Property):
1823    arg_types = {"this": True}
1824
1825
1826class ExternalProperty(Property):
1827    arg_types = {"this": False}
1828
1829
1830class FallbackProperty(Property):
1831    arg_types = {"no": True, "protection": False}
1832
1833
1834class FileFormatProperty(Property):
1835    arg_types = {"this": True}
1836
1837
1838class FreespaceProperty(Property):
1839    arg_types = {"this": True, "percent": False}
1840
1841
1842class InputOutputFormat(Expression):
1843    arg_types = {"input_format": False, "output_format": False}
1844
1845
1846class IsolatedLoadingProperty(Property):
1847    arg_types = {
1848        "no": True,
1849        "concurrent": True,
1850        "for_all": True,
1851        "for_insert": True,
1852        "for_none": True,
1853    }
1854
1855
1856class JournalProperty(Property):
1857    arg_types = {"no": True, "dual": False, "before": False}
1858
1859
1860class LanguageProperty(Property):
1861    arg_types = {"this": True}
1862
1863
1864class LikeProperty(Property):
1865    arg_types = {"this": True, "expressions": False}
1866
1867
1868class LocationProperty(Property):
1869    arg_types = {"this": True}
1870
1871
1872class LockingProperty(Property):
1873    arg_types = {
1874        "this": False,
1875        "kind": True,
1876        "for_or_in": True,
1877        "lock_type": True,
1878        "override": False,
1879    }
1880
1881
1882class LogProperty(Property):
1883    arg_types = {"no": True}
1884
1885
1886class MaterializedProperty(Property):
1887    arg_types = {"this": False}
1888
1889
1890class MergeBlockRatioProperty(Property):
1891    arg_types = {"this": False, "no": False, "default": False, "percent": False}
1892
1893
1894class NoPrimaryIndexProperty(Property):
1895    arg_types = {"this": False}
1896
1897
1898class OnCommitProperty(Property):
1899    arg_type = {"this": False}
1900
1901
1902class PartitionedByProperty(Property):
1903    arg_types = {"this": True}
1904
1905
1906class ReturnsProperty(Property):
1907    arg_types = {"this": True, "is_table": False, "table": False}
1908
1909
1910class RowFormatProperty(Property):
1911    arg_types = {"this": True}
1912
1913
1914class RowFormatDelimitedProperty(Property):
1915    # https://cwiki.apache.org/confluence/display/hive/languagemanual+dml
1916    arg_types = {
1917        "fields": False,
1918        "escaped": False,
1919        "collection_items": False,
1920        "map_keys": False,
1921        "lines": False,
1922        "null": False,
1923        "serde": False,
1924    }
1925
1926
1927class RowFormatSerdeProperty(Property):
1928    arg_types = {"this": True}
1929
1930
1931class SchemaCommentProperty(Property):
1932    arg_types = {"this": True}
1933
1934
1935class SerdeProperties(Property):
1936    arg_types = {"expressions": True}
1937
1938
1939class SetProperty(Property):
1940    arg_types = {"multi": True}
1941
1942
1943class SettingsProperty(Property):
1944    arg_types = {"expressions": True}
1945
1946
1947class SortKeyProperty(Property):
1948    arg_types = {"this": True, "compound": False}
1949
1950
1951class SqlSecurityProperty(Property):
1952    arg_types = {"definer": True}
1953
1954
1955class StabilityProperty(Property):
1956    arg_types = {"this": True}
1957
1958
1959class TableFormatProperty(Property):
1960    arg_types = {"this": True}
1961
1962
1963class TemporaryProperty(Property):
1964    arg_types = {"global_": True}
1965
1966
1967class TransientProperty(Property):
1968    arg_types = {"this": False}
1969
1970
1971class VolatileProperty(Property):
1972    arg_types = {"this": False}
1973
1974
1975class WithDataProperty(Property):
1976    arg_types = {"no": True, "statistics": False}
1977
1978
1979class WithJournalTableProperty(Property):
1980    arg_types = {"this": True}
1981
1982
1983class Properties(Expression):
1984    arg_types = {"expressions": True}
1985
1986    NAME_TO_PROPERTY = {
1987        "ALGORITHM": AlgorithmProperty,
1988        "AUTO_INCREMENT": AutoIncrementProperty,
1989        "CHARACTER SET": CharacterSetProperty,
1990        "COLLATE": CollateProperty,
1991        "COMMENT": SchemaCommentProperty,
1992        "DEFINER": DefinerProperty,
1993        "DISTKEY": DistKeyProperty,
1994        "DISTSTYLE": DistStyleProperty,
1995        "ENGINE": EngineProperty,
1996        "EXECUTE AS": ExecuteAsProperty,
1997        "FORMAT": FileFormatProperty,
1998        "LANGUAGE": LanguageProperty,
1999        "LOCATION": LocationProperty,
2000        "PARTITIONED_BY": PartitionedByProperty,
2001        "RETURNS": ReturnsProperty,
2002        "ROW_FORMAT": RowFormatProperty,
2003        "SORTKEY": SortKeyProperty,
2004        "TABLE_FORMAT": TableFormatProperty,
2005    }
2006
2007    PROPERTY_TO_NAME = {v: k for k, v in NAME_TO_PROPERTY.items()}
2008
2009    # CREATE property locations
2010    # Form: schema specified
2011    #   create [POST_CREATE]
2012    #     table a [POST_NAME]
2013    #     (b int) [POST_SCHEMA]
2014    #     with ([POST_WITH])
2015    #     index (b) [POST_INDEX]
2016    #
2017    # Form: alias selection
2018    #   create [POST_CREATE]
2019    #     table a [POST_NAME]
2020    #     as [POST_ALIAS] (select * from b) [POST_EXPRESSION]
2021    #     index (c) [POST_INDEX]
2022    class Location(AutoName):
2023        POST_CREATE = auto()
2024        POST_NAME = auto()
2025        POST_SCHEMA = auto()
2026        POST_WITH = auto()
2027        POST_ALIAS = auto()
2028        POST_EXPRESSION = auto()
2029        POST_INDEX = auto()
2030        UNSUPPORTED = auto()
2031
2032    @classmethod
2033    def from_dict(cls, properties_dict) -> Properties:
2034        expressions = []
2035        for key, value in properties_dict.items():
2036            property_cls = cls.NAME_TO_PROPERTY.get(key.upper())
2037            if property_cls:
2038                expressions.append(property_cls(this=convert(value)))
2039            else:
2040                expressions.append(Property(this=Literal.string(key), value=convert(value)))
2041
2042        return cls(expressions=expressions)
2043
2044
2045class Qualify(Expression):
2046    pass
2047
2048
2049# https://www.ibm.com/docs/en/ias?topic=procedures-return-statement-in-sql
2050class Return(Expression):
2051    pass
2052
2053
2054class Reference(Expression):
2055    arg_types = {"this": True, "expressions": False, "options": False}
2056
2057
2058class Tuple(Expression):
2059    arg_types = {"expressions": False}
2060
2061    def isin(
2062        self, *expressions: t.Any, query: t.Optional[ExpOrStr] = None, copy=True, **opts
2063    ) -> In:
2064        return In(
2065            this=_maybe_copy(self, copy),
2066            expressions=[convert(e, copy=copy) for e in expressions],
2067            query=maybe_parse(query, copy=copy, **opts) if query else None,
2068        )
2069
2070
2071class Subqueryable(Unionable):
2072    def subquery(self, alias=None, copy=True) -> Subquery:
2073        """
2074        Convert this expression to an aliased expression that can be used as a Subquery.
2075
2076        Example:
2077            >>> subquery = Select().select("x").from_("tbl").subquery()
2078            >>> Select().select("x").from_(subquery).sql()
2079            'SELECT x FROM (SELECT x FROM tbl)'
2080
2081        Args:
2082            alias (str | Identifier): an optional alias for the subquery
2083            copy (bool): if `False`, modify this expression instance in-place.
2084
2085        Returns:
2086            Alias: the subquery
2087        """
2088        instance = _maybe_copy(self, copy)
2089        if not isinstance(alias, Expression):
2090            alias = TableAlias(this=to_identifier(alias)) if alias else None
2091
2092        return Subquery(this=instance, alias=alias)
2093
2094    def limit(self, expression, dialect=None, copy=True, **opts) -> Select:
2095        raise NotImplementedError
2096
2097    @property
2098    def ctes(self):
2099        with_ = self.args.get("with")
2100        if not with_:
2101            return []
2102        return with_.expressions
2103
2104    @property
2105    def selects(self):
2106        raise NotImplementedError("Subqueryable objects must implement `selects`")
2107
2108    @property
2109    def named_selects(self):
2110        raise NotImplementedError("Subqueryable objects must implement `named_selects`")
2111
2112    def with_(
2113        self,
2114        alias: ExpOrStr,
2115        as_: ExpOrStr,
2116        recursive: t.Optional[bool] = None,
2117        append: bool = True,
2118        dialect: DialectType = None,
2119        copy: bool = True,
2120        **opts,
2121    ) -> Subqueryable:
2122        """
2123        Append to or set the common table expressions.
2124
2125        Example:
2126            >>> Select().with_("tbl2", as_="SELECT * FROM tbl").select("x").from_("tbl2").sql()
2127            'WITH tbl2 AS (SELECT * FROM tbl) SELECT x FROM tbl2'
2128
2129        Args:
2130            alias: the SQL code string to parse as the table name.
2131                If an `Expression` instance is passed, this is used as-is.
2132            as_: the SQL code string to parse as the table expression.
2133                If an `Expression` instance is passed, it will be used as-is.
2134            recursive: set the RECURSIVE part of the expression. Defaults to `False`.
2135            append: if `True`, add to any existing expressions.
2136                Otherwise, this resets the expressions.
2137            dialect: the dialect used to parse the input expression.
2138            copy: if `False`, modify this expression instance in-place.
2139            opts: other options to use to parse the input expressions.
2140
2141        Returns:
2142            The modified expression.
2143        """
2144        return _apply_cte_builder(
2145            self, alias, as_, recursive=recursive, append=append, dialect=dialect, copy=copy, **opts
2146        )
2147
2148
2149QUERY_MODIFIERS = {
2150    "match": False,
2151    "laterals": False,
2152    "joins": False,
2153    "pivots": False,
2154    "where": False,
2155    "group": False,
2156    "having": False,
2157    "qualify": False,
2158    "windows": False,
2159    "distribute": False,
2160    "sort": False,
2161    "cluster": False,
2162    "order": False,
2163    "limit": False,
2164    "offset": False,
2165    "locks": False,
2166    "sample": False,
2167    "settings": False,
2168    "format": False,
2169}
2170
2171
2172class Table(Expression):
2173    arg_types = {
2174        "this": True,
2175        "alias": False,
2176        "db": False,
2177        "catalog": False,
2178        "laterals": False,
2179        "joins": False,
2180        "pivots": False,
2181        "hints": False,
2182        "system_time": False,
2183    }
2184
2185    @property
2186    def db(self) -> str:
2187        return self.text("db")
2188
2189    @property
2190    def catalog(self) -> str:
2191        return self.text("catalog")
2192
2193    @property
2194    def parts(self) -> t.List[Identifier]:
2195        """Return the parts of a column in order catalog, db, table."""
2196        return [
2197            t.cast(Identifier, self.args[part])
2198            for part in ("catalog", "db", "this")
2199            if self.args.get(part)
2200        ]
2201
2202
2203# See the TSQL "Querying data in a system-versioned temporal table" page
2204class SystemTime(Expression):
2205    arg_types = {
2206        "this": False,
2207        "expression": False,
2208        "kind": True,
2209    }
2210
2211
2212class Union(Subqueryable):
2213    arg_types = {
2214        "with": False,
2215        "this": True,
2216        "expression": True,
2217        "distinct": False,
2218        **QUERY_MODIFIERS,
2219    }
2220
2221    def limit(self, expression, dialect=None, copy=True, **opts) -> Select:
2222        """
2223        Set the LIMIT expression.
2224
2225        Example:
2226            >>> select("1").union(select("1")).limit(1).sql()
2227            'SELECT * FROM (SELECT 1 UNION SELECT 1) AS _l_0 LIMIT 1'
2228
2229        Args:
2230            expression (str | int | Expression): the SQL code string to parse.
2231                This can also be an integer.
2232                If a `Limit` instance is passed, this is used as-is.
2233                If another `Expression` instance is passed, it will be wrapped in a `Limit`.
2234            dialect (str): the dialect used to parse the input expression.
2235            copy (bool): if `False`, modify this expression instance in-place.
2236            opts (kwargs): other options to use to parse the input expressions.
2237
2238        Returns:
2239            Select: The limited subqueryable.
2240        """
2241        return (
2242            select("*")
2243            .from_(self.subquery(alias="_l_0", copy=copy))
2244            .limit(expression, dialect=dialect, copy=False, **opts)
2245        )
2246
2247    def select(
2248        self,
2249        *expressions: ExpOrStr,
2250        append: bool = True,
2251        dialect: DialectType = None,
2252        copy: bool = True,
2253        **opts,
2254    ) -> Union:
2255        """Append to or set the SELECT of the union recursively.
2256
2257        Example:
2258            >>> from sqlglot import parse_one
2259            >>> parse_one("select a from x union select a from y union select a from z").select("b").sql()
2260            'SELECT a, b FROM x UNION SELECT a, b FROM y UNION SELECT a, b FROM z'
2261
2262        Args:
2263            *expressions: the SQL code strings to parse.
2264                If an `Expression` instance is passed, it will be used as-is.
2265            append: if `True`, add to any existing expressions.
2266                Otherwise, this resets the expressions.
2267            dialect: the dialect used to parse the input expressions.
2268            copy: if `False`, modify this expression instance in-place.
2269            opts: other options to use to parse the input expressions.
2270
2271        Returns:
2272            Union: the modified expression.
2273        """
2274        this = self.copy() if copy else self
2275        this.this.unnest().select(*expressions, append=append, dialect=dialect, copy=False, **opts)
2276        this.expression.unnest().select(
2277            *expressions, append=append, dialect=dialect, copy=False, **opts
2278        )
2279        return this
2280
2281    @property
2282    def named_selects(self):
2283        return self.this.unnest().named_selects
2284
2285    @property
2286    def is_star(self) -> bool:
2287        return self.this.is_star or self.expression.is_star
2288
2289    @property
2290    def selects(self):
2291        return self.this.unnest().selects
2292
2293    @property
2294    def left(self):
2295        return self.this
2296
2297    @property
2298    def right(self):
2299        return self.expression
2300
2301
2302class Except(Union):
2303    pass
2304
2305
2306class Intersect(Union):
2307    pass
2308
2309
2310class Unnest(UDTF):
2311    arg_types = {
2312        "expressions": True,
2313        "ordinality": False,
2314        "alias": False,
2315        "offset": False,
2316    }
2317
2318
2319class Update(Expression):
2320    arg_types = {
2321        "with": False,
2322        "this": False,
2323        "expressions": True,
2324        "from": False,
2325        "where": False,
2326        "returning": False,
2327    }
2328
2329
2330class Values(UDTF):
2331    arg_types = {
2332        "expressions": True,
2333        "ordinality": False,
2334        "alias": False,
2335    }
2336
2337
2338class Var(Expression):
2339    pass
2340
2341
2342class Schema(Expression):
2343    arg_types = {"this": False, "expressions": False}
2344
2345
2346# https://dev.mysql.com/doc/refman/8.0/en/select.html
2347# https://docs.oracle.com/en/database/oracle/oracle-database/19/sqlrf/SELECT.html
2348class Lock(Expression):
2349    arg_types = {"update": True, "expressions": False, "wait": False}
2350
2351
2352class Select(Subqueryable):
2353    arg_types = {
2354        "with": False,
2355        "kind": False,
2356        "expressions": False,
2357        "hint": False,
2358        "distinct": False,
2359        "struct": False,  # https://cloud.google.com/bigquery/docs/reference/standard-sql/query-syntax#return_query_results_as_a_value_table
2360        "value": False,
2361        "into": False,
2362        "from": False,
2363        **QUERY_MODIFIERS,
2364    }
2365
2366    def from_(
2367        self, expression: ExpOrStr, dialect: DialectType = None, copy: bool = True, **opts
2368    ) -> Select:
2369        """
2370        Set the FROM expression.
2371
2372        Example:
2373            >>> Select().from_("tbl").select("x").sql()
2374            'SELECT x FROM tbl'
2375
2376        Args:
2377            expression : the SQL code strings to parse.
2378                If a `From` instance is passed, this is used as-is.
2379                If another `Expression` instance is passed, it will be wrapped in a `From`.
2380            dialect: the dialect used to parse the input expression.
2381            copy: if `False`, modify this expression instance in-place.
2382            opts: other options to use to parse the input expressions.
2383
2384        Returns:
2385            Select: the modified expression.
2386        """
2387        return _apply_builder(
2388            expression=expression,
2389            instance=self,
2390            arg="from",
2391            into=From,
2392            prefix="FROM",
2393            dialect=dialect,
2394            copy=copy,
2395            **opts,
2396        )
2397
2398    def group_by(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
2399        """
2400        Set the GROUP BY expression.
2401
2402        Example:
2403            >>> Select().from_("tbl").select("x", "COUNT(1)").group_by("x").sql()
2404            'SELECT x, COUNT(1) FROM tbl GROUP BY x'
2405
2406        Args:
2407            *expressions (str | Expression): the SQL code strings to parse.
2408                If a `Group` instance is passed, this is used as-is.
2409                If another `Expression` instance is passed, it will be wrapped in a `Group`.
2410                If nothing is passed in then a group by is not applied to the expression
2411            append (bool): if `True`, add to any existing expressions.
2412                Otherwise, this flattens all the `Group` expression into a single expression.
2413            dialect (str): the dialect used to parse the input expression.
2414            copy (bool): if `False`, modify this expression instance in-place.
2415            opts (kwargs): other options to use to parse the input expressions.
2416
2417        Returns:
2418            Select: the modified expression.
2419        """
2420        if not expressions:
2421            return self if not copy else self.copy()
2422        return _apply_child_list_builder(
2423            *expressions,
2424            instance=self,
2425            arg="group",
2426            append=append,
2427            copy=copy,
2428            prefix="GROUP BY",
2429            into=Group,
2430            dialect=dialect,
2431            **opts,
2432        )
2433
2434    def order_by(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
2435        """
2436        Set the ORDER BY expression.
2437
2438        Example:
2439            >>> Select().from_("tbl").select("x").order_by("x DESC").sql()
2440            'SELECT x FROM tbl ORDER BY x DESC'
2441
2442        Args:
2443            *expressions (str | Expression): the SQL code strings to parse.
2444                If a `Group` instance is passed, this is used as-is.
2445                If another `Expression` instance is passed, it will be wrapped in a `Order`.
2446            append (bool): if `True`, add to any existing expressions.
2447                Otherwise, this flattens all the `Order` expression into a single expression.
2448            dialect (str): the dialect used to parse the input expression.
2449            copy (bool): if `False`, modify this expression instance in-place.
2450            opts (kwargs): other options to use to parse the input expressions.
2451
2452        Returns:
2453            Select: the modified expression.
2454        """
2455        return _apply_child_list_builder(
2456            *expressions,
2457            instance=self,
2458            arg="order",
2459            append=append,
2460            copy=copy,
2461            prefix="ORDER BY",
2462            into=Order,
2463            dialect=dialect,
2464            **opts,
2465        )
2466
2467    def sort_by(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
2468        """
2469        Set the SORT BY expression.
2470
2471        Example:
2472            >>> Select().from_("tbl").select("x").sort_by("x DESC").sql(dialect="hive")
2473            'SELECT x FROM tbl SORT BY x DESC'
2474
2475        Args:
2476            *expressions (str | Expression): the SQL code strings to parse.
2477                If a `Group` instance is passed, this is used as-is.
2478                If another `Expression` instance is passed, it will be wrapped in a `SORT`.
2479            append (bool): if `True`, add to any existing expressions.
2480                Otherwise, this flattens all the `Order` expression into a single expression.
2481            dialect (str): the dialect used to parse the input expression.
2482            copy (bool): if `False`, modify this expression instance in-place.
2483            opts (kwargs): other options to use to parse the input expressions.
2484
2485        Returns:
2486            Select: the modified expression.
2487        """
2488        return _apply_child_list_builder(
2489            *expressions,
2490            instance=self,
2491            arg="sort",
2492            append=append,
2493            copy=copy,
2494            prefix="SORT BY",
2495            into=Sort,
2496            dialect=dialect,
2497            **opts,
2498        )
2499
2500    def cluster_by(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
2501        """
2502        Set the CLUSTER BY expression.
2503
2504        Example:
2505            >>> Select().from_("tbl").select("x").cluster_by("x DESC").sql(dialect="hive")
2506            'SELECT x FROM tbl CLUSTER BY x DESC'
2507
2508        Args:
2509            *expressions (str | Expression): the SQL code strings to parse.
2510                If a `Group` instance is passed, this is used as-is.
2511                If another `Expression` instance is passed, it will be wrapped in a `Cluster`.
2512            append (bool): if `True`, add to any existing expressions.
2513                Otherwise, this flattens all the `Order` expression into a single expression.
2514            dialect (str): the dialect used to parse the input expression.
2515            copy (bool): if `False`, modify this expression instance in-place.
2516            opts (kwargs): other options to use to parse the input expressions.
2517
2518        Returns:
2519            Select: the modified expression.
2520        """
2521        return _apply_child_list_builder(
2522            *expressions,
2523            instance=self,
2524            arg="cluster",
2525            append=append,
2526            copy=copy,
2527            prefix="CLUSTER BY",
2528            into=Cluster,
2529            dialect=dialect,
2530            **opts,
2531        )
2532
2533    def limit(self, expression, dialect=None, copy=True, **opts) -> Select:
2534        """
2535        Set the LIMIT expression.
2536
2537        Example:
2538            >>> Select().from_("tbl").select("x").limit(10).sql()
2539            'SELECT x FROM tbl LIMIT 10'
2540
2541        Args:
2542            expression (str | int | Expression): the SQL code string to parse.
2543                This can also be an integer.
2544                If a `Limit` instance is passed, this is used as-is.
2545                If another `Expression` instance is passed, it will be wrapped in a `Limit`.
2546            dialect (str): the dialect used to parse the input expression.
2547            copy (bool): if `False`, modify this expression instance in-place.
2548            opts (kwargs): other options to use to parse the input expressions.
2549
2550        Returns:
2551            Select: the modified expression.
2552        """
2553        return _apply_builder(
2554            expression=expression,
2555            instance=self,
2556            arg="limit",
2557            into=Limit,
2558            prefix="LIMIT",
2559            dialect=dialect,
2560            copy=copy,
2561            **opts,
2562        )
2563
2564    def offset(self, expression, dialect=None, copy=True, **opts) -> Select:
2565        """
2566        Set the OFFSET expression.
2567
2568        Example:
2569            >>> Select().from_("tbl").select("x").offset(10).sql()
2570            'SELECT x FROM tbl OFFSET 10'
2571
2572        Args:
2573            expression (str | int | Expression): the SQL code string to parse.
2574                This can also be an integer.
2575                If a `Offset` instance is passed, this is used as-is.
2576                If another `Expression` instance is passed, it will be wrapped in a `Offset`.
2577            dialect (str): the dialect used to parse the input expression.
2578            copy (bool): if `False`, modify this expression instance in-place.
2579            opts (kwargs): other options to use to parse the input expressions.
2580
2581        Returns:
2582            Select: the modified expression.
2583        """
2584        return _apply_builder(
2585            expression=expression,
2586            instance=self,
2587            arg="offset",
2588            into=Offset,
2589            prefix="OFFSET",
2590            dialect=dialect,
2591            copy=copy,
2592            **opts,
2593        )
2594
2595    def select(
2596        self,
2597        *expressions: ExpOrStr,
2598        append: bool = True,
2599        dialect: DialectType = None,
2600        copy: bool = True,
2601        **opts,
2602    ) -> Select:
2603        """
2604        Append to or set the SELECT expressions.
2605
2606        Example:
2607            >>> Select().select("x", "y").sql()
2608            'SELECT x, y'
2609
2610        Args:
2611            *expressions: the SQL code strings to parse.
2612                If an `Expression` instance is passed, it will be used as-is.
2613            append: if `True`, add to any existing expressions.
2614                Otherwise, this resets the expressions.
2615            dialect: the dialect used to parse the input expressions.
2616            copy: if `False`, modify this expression instance in-place.
2617            opts: other options to use to parse the input expressions.
2618
2619        Returns:
2620            Select: the modified expression.
2621        """
2622        return _apply_list_builder(
2623            *expressions,
2624            instance=self,
2625            arg="expressions",
2626            append=append,
2627            dialect=dialect,
2628            copy=copy,
2629            **opts,
2630        )
2631
2632    def lateral(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
2633        """
2634        Append to or set the LATERAL expressions.
2635
2636        Example:
2637            >>> Select().select("x").lateral("OUTER explode(y) tbl2 AS z").from_("tbl").sql()
2638            'SELECT x FROM tbl LATERAL VIEW OUTER EXPLODE(y) tbl2 AS z'
2639
2640        Args:
2641            *expressions (str | Expression): the SQL code strings to parse.
2642                If an `Expression` instance is passed, it will be used as-is.
2643            append (bool): if `True`, add to any existing expressions.
2644                Otherwise, this resets the expressions.
2645            dialect (str): the dialect used to parse the input expressions.
2646            copy (bool): if `False`, modify this expression instance in-place.
2647            opts (kwargs): other options to use to parse the input expressions.
2648
2649        Returns:
2650            Select: the modified expression.
2651        """
2652        return _apply_list_builder(
2653            *expressions,
2654            instance=self,
2655            arg="laterals",
2656            append=append,
2657            into=Lateral,
2658            prefix="LATERAL VIEW",
2659            dialect=dialect,
2660            copy=copy,
2661            **opts,
2662        )
2663
2664    def join(
2665        self,
2666        expression,
2667        on=None,
2668        using=None,
2669        append=True,
2670        join_type=None,
2671        join_alias=None,
2672        dialect=None,
2673        copy=True,
2674        **opts,
2675    ) -> Select:
2676        """
2677        Append to or set the JOIN expressions.
2678
2679        Example:
2680            >>> Select().select("*").from_("tbl").join("tbl2", on="tbl1.y = tbl2.y").sql()
2681            'SELECT * FROM tbl JOIN tbl2 ON tbl1.y = tbl2.y'
2682
2683            >>> Select().select("1").from_("a").join("b", using=["x", "y", "z"]).sql()
2684            'SELECT 1 FROM a JOIN b USING (x, y, z)'
2685
2686            Use `join_type` to change the type of join:
2687
2688            >>> Select().select("*").from_("tbl").join("tbl2", on="tbl1.y = tbl2.y", join_type="left outer").sql()
2689            'SELECT * FROM tbl LEFT OUTER JOIN tbl2 ON tbl1.y = tbl2.y'
2690
2691        Args:
2692            expression (str | Expression): the SQL code string to parse.
2693                If an `Expression` instance is passed, it will be used as-is.
2694            on (str | Expression): optionally specify the join "on" criteria as a SQL string.
2695                If an `Expression` instance is passed, it will be used as-is.
2696            using (str | Expression): optionally specify the join "using" criteria as a SQL string.
2697                If an `Expression` instance is passed, it will be used as-is.
2698            append (bool): if `True`, add to any existing expressions.
2699                Otherwise, this resets the expressions.
2700            join_type (str): If set, alter the parsed join type
2701            dialect (str): the dialect used to parse the input expressions.
2702            copy (bool): if `False`, modify this expression instance in-place.
2703            opts (kwargs): other options to use to parse the input expressions.
2704
2705        Returns:
2706            Select: the modified expression.
2707        """
2708        parse_args = {"dialect": dialect, **opts}
2709
2710        try:
2711            expression = maybe_parse(expression, into=Join, prefix="JOIN", **parse_args)
2712        except ParseError:
2713            expression = maybe_parse(expression, into=(Join, Expression), **parse_args)
2714
2715        join = expression if isinstance(expression, Join) else Join(this=expression)
2716
2717        if isinstance(join.this, Select):
2718            join.this.replace(join.this.subquery())
2719
2720        if join_type:
2721            natural: t.Optional[Token]
2722            side: t.Optional[Token]
2723            kind: t.Optional[Token]
2724
2725            natural, side, kind = maybe_parse(join_type, into="JOIN_TYPE", **parse_args)  # type: ignore
2726
2727            if natural:
2728                join.set("natural", True)
2729            if side:
2730                join.set("side", side.text)
2731            if kind:
2732                join.set("kind", kind.text)
2733
2734        if on:
2735            on = and_(*ensure_collection(on), dialect=dialect, copy=copy, **opts)
2736            join.set("on", on)
2737
2738        if using:
2739            join = _apply_list_builder(
2740                *ensure_collection(using),
2741                instance=join,
2742                arg="using",
2743                append=append,
2744                copy=copy,
2745                **opts,
2746            )
2747
2748        if join_alias:
2749            join.set("this", alias_(join.this, join_alias, table=True))
2750        return _apply_list_builder(
2751            join,
2752            instance=self,
2753            arg="joins",
2754            append=append,
2755            copy=copy,
2756            **opts,
2757        )
2758
2759    def where(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
2760        """
2761        Append to or set the WHERE expressions.
2762
2763        Example:
2764            >>> Select().select("x").from_("tbl").where("x = 'a' OR x < 'b'").sql()
2765            "SELECT x FROM tbl WHERE x = 'a' OR x < 'b'"
2766
2767        Args:
2768            *expressions (str | Expression): the SQL code strings to parse.
2769                If an `Expression` instance is passed, it will be used as-is.
2770                Multiple expressions are combined with an AND operator.
2771            append (bool): if `True`, AND the new expressions to any existing expression.
2772                Otherwise, this resets the expression.
2773            dialect (str): the dialect used to parse the input expressions.
2774            copy (bool): if `False`, modify this expression instance in-place.
2775            opts (kwargs): other options to use to parse the input expressions.
2776
2777        Returns:
2778            Select: the modified expression.
2779        """
2780        return _apply_conjunction_builder(
2781            *expressions,
2782            instance=self,
2783            arg="where",
2784            append=append,
2785            into=Where,
2786            dialect=dialect,
2787            copy=copy,
2788            **opts,
2789        )
2790
2791    def having(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
2792        """
2793        Append to or set the HAVING expressions.
2794
2795        Example:
2796            >>> Select().select("x", "COUNT(y)").from_("tbl").group_by("x").having("COUNT(y) > 3").sql()
2797            'SELECT x, COUNT(y) FROM tbl GROUP BY x HAVING COUNT(y) > 3'
2798
2799        Args:
2800            *expressions (str | Expression): the SQL code strings to parse.
2801                If an `Expression` instance is passed, it will be used as-is.
2802                Multiple expressions are combined with an AND operator.
2803            append (bool): if `True`, AND the new expressions to any existing expression.
2804                Otherwise, this resets the expression.
2805            dialect (str): the dialect used to parse the input expressions.
2806            copy (bool): if `False`, modify this expression instance in-place.
2807            opts (kwargs): other options to use to parse the input expressions.
2808
2809        Returns:
2810            Select: the modified expression.
2811        """
2812        return _apply_conjunction_builder(
2813            *expressions,
2814            instance=self,
2815            arg="having",
2816            append=append,
2817            into=Having,
2818            dialect=dialect,
2819            copy=copy,
2820            **opts,
2821        )
2822
2823    def window(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
2824        return _apply_list_builder(
2825            *expressions,
2826            instance=self,
2827            arg="windows",
2828            append=append,
2829            into=Window,
2830            dialect=dialect,
2831            copy=copy,
2832            **opts,
2833        )
2834
2835    def qualify(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
2836        return _apply_conjunction_builder(
2837            *expressions,
2838            instance=self,
2839            arg="qualify",
2840            append=append,
2841            into=Qualify,
2842            dialect=dialect,
2843            copy=copy,
2844            **opts,
2845        )
2846
2847    def distinct(self, *ons: ExpOrStr, distinct: bool = True, copy: bool = True) -> Select:
2848        """
2849        Set the OFFSET expression.
2850
2851        Example:
2852            >>> Select().from_("tbl").select("x").distinct().sql()
2853            'SELECT DISTINCT x FROM tbl'
2854
2855        Args:
2856            ons: the expressions to distinct on
2857            distinct: whether the Select should be distinct
2858            copy: if `False`, modify this expression instance in-place.
2859
2860        Returns:
2861            Select: the modified expression.
2862        """
2863        instance = _maybe_copy(self, copy)
2864        on = Tuple(expressions=[maybe_parse(on, copy=copy) for on in ons]) if ons else None
2865        instance.set("distinct", Distinct(on=on) if distinct else None)
2866        return instance
2867
2868    def ctas(self, table, properties=None, dialect=None, copy=True, **opts) -> Create:
2869        """
2870        Convert this expression to a CREATE TABLE AS statement.
2871
2872        Example:
2873            >>> Select().select("*").from_("tbl").ctas("x").sql()
2874            'CREATE TABLE x AS SELECT * FROM tbl'
2875
2876        Args:
2877            table (str | Expression): the SQL code string to parse as the table name.
2878                If another `Expression` instance is passed, it will be used as-is.
2879            properties (dict): an optional mapping of table properties
2880            dialect (str): the dialect used to parse the input table.
2881            copy (bool): if `False`, modify this expression instance in-place.
2882            opts (kwargs): other options to use to parse the input table.
2883
2884        Returns:
2885            Create: the CREATE TABLE AS expression
2886        """
2887        instance = _maybe_copy(self, copy)
2888        table_expression = maybe_parse(
2889            table,
2890            into=Table,
2891            dialect=dialect,
2892            **opts,
2893        )
2894        properties_expression = None
2895        if properties:
2896            properties_expression = Properties.from_dict(properties)
2897
2898        return Create(
2899            this=table_expression,
2900            kind="table",
2901            expression=instance,
2902            properties=properties_expression,
2903        )
2904
2905    def lock(self, update: bool = True, copy: bool = True) -> Select:
2906        """
2907        Set the locking read mode for this expression.
2908
2909        Examples:
2910            >>> Select().select("x").from_("tbl").where("x = 'a'").lock().sql("mysql")
2911            "SELECT x FROM tbl WHERE x = 'a' FOR UPDATE"
2912
2913            >>> Select().select("x").from_("tbl").where("x = 'a'").lock(update=False).sql("mysql")
2914            "SELECT x FROM tbl WHERE x = 'a' FOR SHARE"
2915
2916        Args:
2917            update: if `True`, the locking type will be `FOR UPDATE`, else it will be `FOR SHARE`.
2918            copy: if `False`, modify this expression instance in-place.
2919
2920        Returns:
2921            The modified expression.
2922        """
2923
2924        inst = _maybe_copy(self, copy)
2925        inst.set("locks", [Lock(update=update)])
2926
2927        return inst
2928
2929    @property
2930    def named_selects(self) -> t.List[str]:
2931        return [e.output_name for e in self.expressions if e.alias_or_name]
2932
2933    @property
2934    def is_star(self) -> bool:
2935        return any(expression.is_star for expression in self.expressions)
2936
2937    @property
2938    def selects(self) -> t.List[Expression]:
2939        return self.expressions
2940
2941
2942class Subquery(DerivedTable, Unionable):
2943    arg_types = {
2944        "this": True,
2945        "alias": False,
2946        "with": False,
2947        **QUERY_MODIFIERS,
2948    }
2949
2950    def unnest(self):
2951        """
2952        Returns the first non subquery.
2953        """
2954        expression = self
2955        while isinstance(expression, Subquery):
2956            expression = expression.this
2957        return expression
2958
2959    @property
2960    def is_star(self) -> bool:
2961        return self.this.is_star
2962
2963    @property
2964    def output_name(self):
2965        return self.alias
2966
2967
2968class TableSample(Expression):
2969    arg_types = {
2970        "this": False,
2971        "method": False,
2972        "bucket_numerator": False,
2973        "bucket_denominator": False,
2974        "bucket_field": False,
2975        "percent": False,
2976        "rows": False,
2977        "size": False,
2978        "seed": False,
2979        "kind": False,
2980    }
2981
2982
2983class Tag(Expression):
2984    """Tags are used for generating arbitrary sql like SELECT <span>x</span>."""
2985
2986    arg_types = {
2987        "this": False,
2988        "prefix": False,
2989        "postfix": False,
2990    }
2991
2992
2993class Pivot(Expression):
2994    arg_types = {
2995        "alias": False,
2996        "expressions": True,
2997        "field": True,
2998        "unpivot": True,
2999        "columns": False,
3000    }
3001
3002
3003class Window(Expression):
3004    arg_types = {
3005        "this": True,
3006        "partition_by": False,
3007        "order": False,
3008        "spec": False,
3009        "alias": False,
3010        "over": False,
3011        "first": False,
3012    }
3013
3014
3015class WindowSpec(Expression):
3016    arg_types = {
3017        "kind": False,
3018        "start": False,
3019        "start_side": False,
3020        "end": False,
3021        "end_side": False,
3022    }
3023
3024
3025class Where(Expression):
3026    pass
3027
3028
3029class Star(Expression):
3030    arg_types = {"except": False, "replace": False}
3031
3032    @property
3033    def name(self) -> str:
3034        return "*"
3035
3036    @property
3037    def output_name(self):
3038        return self.name
3039
3040
3041class Parameter(Expression):
3042    arg_types = {"this": True, "wrapped": False}
3043
3044
3045class SessionParameter(Expression):
3046    arg_types = {"this": True, "kind": False}
3047
3048
3049class Placeholder(Expression):
3050    arg_types = {"this": False, "kind": False}
3051
3052
3053class Null(Condition):
3054    arg_types: t.Dict[str, t.Any] = {}
3055
3056    @property
3057    def name(self) -> str:
3058        return "NULL"
3059
3060
3061class Boolean(Condition):
3062    pass
3063
3064
3065class DataTypeSize(Expression):
3066    arg_types = {"this": True, "expression": False}
3067
3068
3069class DataType(Expression):
3070    arg_types = {
3071        "this": True,
3072        "expressions": False,
3073        "nested": False,
3074        "values": False,
3075        "prefix": False,
3076    }
3077
3078    class Type(AutoName):
3079        ARRAY = auto()
3080        BIGDECIMAL = auto()
3081        BIGINT = auto()
3082        BIGSERIAL = auto()
3083        BINARY = auto()
3084        BIT = auto()
3085        BOOLEAN = auto()
3086        CHAR = auto()
3087        DATE = auto()
3088        DATETIME = auto()
3089        DATETIME64 = auto()
3090        DECIMAL = auto()
3091        DOUBLE = auto()
3092        FLOAT = auto()
3093        GEOGRAPHY = auto()
3094        GEOMETRY = auto()
3095        HLLSKETCH = auto()
3096        HSTORE = auto()
3097        IMAGE = auto()
3098        INET = auto()
3099        INT = auto()
3100        INT128 = auto()
3101        INT256 = auto()
3102        INTERVAL = auto()
3103        JSON = auto()
3104        JSONB = auto()
3105        LONGBLOB = auto()
3106        LONGTEXT = auto()
3107        MAP = auto()
3108        MEDIUMBLOB = auto()
3109        MEDIUMTEXT = auto()
3110        MONEY = auto()
3111        NCHAR = auto()
3112        NULL = auto()
3113        NULLABLE = auto()
3114        NVARCHAR = auto()
3115        OBJECT = auto()
3116        ROWVERSION = auto()
3117        SERIAL = auto()
3118        SMALLINT = auto()
3119        SMALLMONEY = auto()
3120        SMALLSERIAL = auto()
3121        STRUCT = auto()
3122        SUPER = auto()
3123        TEXT = auto()
3124        TIME = auto()
3125        TIMESTAMP = auto()
3126        TIMESTAMPTZ = auto()
3127        TIMESTAMPLTZ = auto()
3128        TINYINT = auto()
3129        UBIGINT = auto()
3130        UINT = auto()
3131        USMALLINT = auto()
3132        UTINYINT = auto()
3133        UNKNOWN = auto()  # Sentinel value, useful for type annotation
3134        UINT128 = auto()
3135        UINT256 = auto()
3136        UNIQUEIDENTIFIER = auto()
3137        UUID = auto()
3138        VARBINARY = auto()
3139        VARCHAR = auto()
3140        VARIANT = auto()
3141        XML = auto()
3142
3143    TEXT_TYPES = {
3144        Type.CHAR,
3145        Type.NCHAR,
3146        Type.VARCHAR,
3147        Type.NVARCHAR,
3148        Type.TEXT,
3149    }
3150
3151    INTEGER_TYPES = {
3152        Type.INT,
3153        Type.TINYINT,
3154        Type.SMALLINT,
3155        Type.BIGINT,
3156        Type.INT128,
3157        Type.INT256,
3158    }
3159
3160    FLOAT_TYPES = {
3161        Type.FLOAT,
3162        Type.DOUBLE,
3163    }
3164
3165    NUMERIC_TYPES = {*INTEGER_TYPES, *FLOAT_TYPES}
3166
3167    TEMPORAL_TYPES = {
3168        Type.TIMESTAMP,
3169        Type.TIMESTAMPTZ,
3170        Type.TIMESTAMPLTZ,
3171        Type.DATE,
3172        Type.DATETIME,
3173        Type.DATETIME64,
3174    }
3175
3176    @classmethod
3177    def build(
3178        cls, dtype: str | DataType | DataType.Type, dialect: DialectType = None, **kwargs
3179    ) -> DataType:
3180        from sqlglot import parse_one
3181
3182        if isinstance(dtype, str):
3183            if dtype.upper() in cls.Type.__members__:
3184                data_type_exp: t.Optional[Expression] = DataType(this=DataType.Type[dtype.upper()])
3185            else:
3186                data_type_exp = parse_one(dtype, read=dialect, into=DataType)
3187            if data_type_exp is None:
3188                raise ValueError(f"Unparsable data type value: {dtype}")
3189        elif isinstance(dtype, DataType.Type):
3190            data_type_exp = DataType(this=dtype)
3191        elif isinstance(dtype, DataType):
3192            return dtype
3193        else:
3194            raise ValueError(f"Invalid data type: {type(dtype)}. Expected str or DataType.Type")
3195        return DataType(**{**data_type_exp.args, **kwargs})
3196
3197    def is_type(self, dtype: DataType.Type) -> bool:
3198        return self.this == dtype
3199
3200
3201# https://www.postgresql.org/docs/15/datatype-pseudo.html
3202class PseudoType(Expression):
3203    pass
3204
3205
3206# WHERE x <OP> EXISTS|ALL|ANY|SOME(SELECT ...)
3207class SubqueryPredicate(Predicate):
3208    pass
3209
3210
3211class All(SubqueryPredicate):
3212    pass
3213
3214
3215class Any(SubqueryPredicate):
3216    pass
3217
3218
3219class Exists(SubqueryPredicate):
3220    pass
3221
3222
3223# Commands to interact with the databases or engines. For most of the command
3224# expressions we parse whatever comes after the command's name as a string.
3225class Command(Expression):
3226    arg_types = {"this": True, "expression": False}
3227
3228
3229class Transaction(Expression):
3230    arg_types = {"this": False, "modes": False}
3231
3232
3233class Commit(Expression):
3234    arg_types = {"chain": False}
3235
3236
3237class Rollback(Expression):
3238    arg_types = {"savepoint": False}
3239
3240
3241class AlterTable(Expression):
3242    arg_types = {"this": True, "actions": True, "exists": False}
3243
3244
3245class AddConstraint(Expression):
3246    arg_types = {"this": False, "expression": False, "enforced": False}
3247
3248
3249class DropPartition(Expression):
3250    arg_types = {"expressions": True, "exists": False}
3251
3252
3253# Binary expressions like (ADD a b)
3254class Binary(Condition):
3255    arg_types = {"this": True, "expression": True}
3256
3257    @property
3258    def left(self):
3259        return self.this
3260
3261    @property
3262    def right(self):
3263        return self.expression
3264
3265
3266class Add(Binary):
3267    pass
3268
3269
3270class Connector(Binary):
3271    pass
3272
3273
3274class And(Connector):
3275    pass
3276
3277
3278class Or(Connector):
3279    pass
3280
3281
3282class BitwiseAnd(Binary):
3283    pass
3284
3285
3286class BitwiseLeftShift(Binary):
3287    pass
3288
3289
3290class BitwiseOr(Binary):
3291    pass
3292
3293
3294class BitwiseRightShift(Binary):
3295    pass
3296
3297
3298class BitwiseXor(Binary):
3299    pass
3300
3301
3302class Div(Binary):
3303    pass
3304
3305
3306class Overlaps(Binary):
3307    pass
3308
3309
3310class Dot(Binary):
3311    @property
3312    def name(self) -> str:
3313        return self.expression.name
3314
3315    @classmethod
3316    def build(self, expressions: t.Sequence[Expression]) -> Dot:
3317        """Build a Dot object with a sequence of expressions."""
3318        if len(expressions) < 2:
3319            raise ValueError(f"Dot requires >= 2 expressions.")
3320
3321        a, b, *expressions = expressions
3322        dot = Dot(this=a, expression=b)
3323
3324        for expression in expressions:
3325            dot = Dot(this=dot, expression=expression)
3326
3327        return dot
3328
3329
3330class DPipe(Binary):
3331    pass
3332
3333
3334class EQ(Binary, Predicate):
3335    pass
3336
3337
3338class NullSafeEQ(Binary, Predicate):
3339    pass
3340
3341
3342class NullSafeNEQ(Binary, Predicate):
3343    pass
3344
3345
3346class Distance(Binary):
3347    pass
3348
3349
3350class Escape(Binary):
3351    pass
3352
3353
3354class Glob(Binary, Predicate):
3355    pass
3356
3357
3358class GT(Binary, Predicate):
3359    pass
3360
3361
3362class GTE(Binary, Predicate):
3363    pass
3364
3365
3366class ILike(Binary, Predicate):
3367    pass
3368
3369
3370class ILikeAny(Binary, Predicate):
3371    pass
3372
3373
3374class IntDiv(Binary):
3375    pass
3376
3377
3378class Is(Binary, Predicate):
3379    pass
3380
3381
3382class Kwarg(Binary):
3383    """Kwarg in special functions like func(kwarg => y)."""
3384
3385
3386class Like(Binary, Predicate):
3387    pass
3388
3389
3390class LikeAny(Binary, Predicate):
3391    pass
3392
3393
3394class LT(Binary, Predicate):
3395    pass
3396
3397
3398class LTE(Binary, Predicate):
3399    pass
3400
3401
3402class Mod(Binary):
3403    pass
3404
3405
3406class Mul(Binary):
3407    pass
3408
3409
3410class NEQ(Binary, Predicate):
3411    pass
3412
3413
3414class SimilarTo(Binary, Predicate):
3415    pass
3416
3417
3418class Slice(Binary):
3419    arg_types = {"this": False, "expression": False}
3420
3421
3422class Sub(Binary):
3423    pass
3424
3425
3426class ArrayOverlaps(Binary):
3427    pass
3428
3429
3430# Unary Expressions
3431# (NOT a)
3432class Unary(Condition):
3433    pass
3434
3435
3436class BitwiseNot(Unary):
3437    pass
3438
3439
3440class Not(Unary):
3441    pass
3442
3443
3444class Paren(Unary):
3445    arg_types = {"this": True, "with": False}
3446
3447
3448class Neg(Unary):
3449    pass
3450
3451
3452class Alias(Expression):
3453    arg_types = {"this": True, "alias": False}
3454
3455    @property
3456    def output_name(self):
3457        return self.alias
3458
3459
3460class Aliases(Expression):
3461    arg_types = {"this": True, "expressions": True}
3462
3463    @property
3464    def aliases(self):
3465        return self.expressions
3466
3467
3468class AtTimeZone(Expression):
3469    arg_types = {"this": True, "zone": True}
3470
3471
3472class Between(Predicate):
3473    arg_types = {"this": True, "low": True, "high": True}
3474
3475
3476class Bracket(Condition):
3477    arg_types = {"this": True, "expressions": True}
3478
3479
3480class Distinct(Expression):
3481    arg_types = {"expressions": False, "on": False}
3482
3483
3484class In(Predicate):
3485    arg_types = {
3486        "this": True,
3487        "expressions": False,
3488        "query": False,
3489        "unnest": False,
3490        "field": False,
3491        "is_global": False,
3492    }
3493
3494
3495class TimeUnit(Expression):
3496    """Automatically converts unit arg into a var."""
3497
3498    arg_types = {"unit": False}
3499
3500    def __init__(self, **args):
3501        unit = args.get("unit")
3502        if isinstance(unit, (Column, Literal)):
3503            args["unit"] = Var(this=unit.name)
3504        elif isinstance(unit, Week):
3505            unit.set("this", Var(this=unit.this.name))
3506        super().__init__(**args)
3507
3508
3509class Interval(TimeUnit):
3510    arg_types = {"this": False, "unit": False}
3511
3512    @property
3513    def unit(self) -> t.Optional[Var]:
3514        return self.args.get("unit")
3515
3516
3517class IgnoreNulls(Expression):
3518    pass
3519
3520
3521class RespectNulls(Expression):
3522    pass
3523
3524
3525# Functions
3526class Func(Condition):
3527    """
3528    The base class for all function expressions.
3529
3530    Attributes:
3531        is_var_len_args (bool): if set to True the last argument defined in arg_types will be
3532            treated as a variable length argument and the argument's value will be stored as a list.
3533        _sql_names (list): determines the SQL name (1st item in the list) and aliases (subsequent items)
3534            for this function expression. These values are used to map this node to a name during parsing
3535            as well as to provide the function's name during SQL string generation. By default the SQL
3536            name is set to the expression's class name transformed to snake case.
3537    """
3538
3539    is_var_len_args = False
3540
3541    @classmethod
3542    def from_arg_list(cls, args):
3543        if cls.is_var_len_args:
3544            all_arg_keys = list(cls.arg_types)
3545            # If this function supports variable length argument treat the last argument as such.
3546            non_var_len_arg_keys = all_arg_keys[:-1] if cls.is_var_len_args else all_arg_keys
3547            num_non_var = len(non_var_len_arg_keys)
3548
3549            args_dict = {arg_key: arg for arg, arg_key in zip(args, non_var_len_arg_keys)}
3550            args_dict[all_arg_keys[-1]] = args[num_non_var:]
3551        else:
3552            args_dict = {arg_key: arg for arg, arg_key in zip(args, cls.arg_types)}
3553
3554        return cls(**args_dict)
3555
3556    @classmethod
3557    def sql_names(cls):
3558        if cls is Func:
3559            raise NotImplementedError(
3560                "SQL name is only supported by concrete function implementations"
3561            )
3562        if "_sql_names" not in cls.__dict__:
3563            cls._sql_names = [camel_to_snake_case(cls.__name__)]
3564        return cls._sql_names
3565
3566    @classmethod
3567    def sql_name(cls):
3568        return cls.sql_names()[0]
3569
3570    @classmethod
3571    def default_parser_mappings(cls):
3572        return {name: cls.from_arg_list for name in cls.sql_names()}
3573
3574
3575class AggFunc(Func):
3576    pass
3577
3578
3579class ParameterizedAgg(AggFunc):
3580    arg_types = {"this": True, "expressions": True, "params": True}
3581
3582
3583class Abs(Func):
3584    pass
3585
3586
3587class Anonymous(Func):
3588    arg_types = {"this": True, "expressions": False}
3589    is_var_len_args = True
3590
3591
3592# https://docs.snowflake.com/en/sql-reference/functions/hll
3593# https://docs.aws.amazon.com/redshift/latest/dg/r_HLL_function.html
3594class Hll(AggFunc):
3595    arg_types = {"this": True, "expressions": False}
3596    is_var_len_args = True
3597
3598
3599class ApproxDistinct(AggFunc):
3600    arg_types = {"this": True, "accuracy": False}
3601    _sql_names = ["APPROX_DISTINCT", "APPROX_COUNT_DISTINCT"]
3602
3603
3604class Array(Func):
3605    arg_types = {"expressions": False}
3606    is_var_len_args = True
3607
3608
3609# https://docs.snowflake.com/en/sql-reference/functions/to_char
3610class ToChar(Func):
3611    arg_types = {"this": True, "format": False}
3612
3613
3614class GenerateSeries(Func):
3615    arg_types = {"start": True, "end": True, "step": False}
3616
3617
3618class ArrayAgg(AggFunc):
3619    pass
3620
3621
3622class ArrayAll(Func):
3623    arg_types = {"this": True, "expression": True}
3624
3625
3626class ArrayAny(Func):
3627    arg_types = {"this": True, "expression": True}
3628
3629
3630class ArrayConcat(Func):
3631    arg_types = {"this": True, "expressions": False}
3632    is_var_len_args = True
3633
3634
3635class ArrayContains(Binary, Func):
3636    pass
3637
3638
3639class ArrayContained(Binary):
3640    pass
3641
3642
3643class ArrayFilter(Func):
3644    arg_types = {"this": True, "expression": True}
3645    _sql_names = ["FILTER", "ARRAY_FILTER"]
3646
3647
3648class ArrayJoin(Func):
3649    arg_types = {"this": True, "expression": True, "null": False}
3650
3651
3652class ArraySize(Func):
3653    arg_types = {"this": True, "expression": False}
3654
3655
3656class ArraySort(Func):
3657    arg_types = {"this": True, "expression": False}
3658
3659
3660class ArraySum(Func):
3661    pass
3662
3663
3664class ArrayUnionAgg(AggFunc):
3665    pass
3666
3667
3668class Avg(AggFunc):
3669    pass
3670
3671
3672class AnyValue(AggFunc):
3673    pass
3674
3675
3676class Case(Func):
3677    arg_types = {"this": False, "ifs": True, "default": False}
3678
3679    def when(self, condition: ExpOrStr, then: ExpOrStr, copy: bool = True, **opts) -> Case:
3680        instance = _maybe_copy(self, copy)
3681        instance.append(
3682            "ifs",
3683            If(
3684                this=maybe_parse(condition, copy=copy, **opts),
3685                true=maybe_parse(then, copy=copy, **opts),
3686            ),
3687        )
3688        return instance
3689
3690    def else_(self, condition: ExpOrStr, copy: bool = True, **opts) -> Case:
3691        instance = _maybe_copy(self, copy)
3692        instance.set("default", maybe_parse(condition, copy=copy, **opts))
3693        return instance
3694
3695
3696class Cast(Func):
3697    arg_types = {"this": True, "to": True}
3698
3699    @property
3700    def name(self) -> str:
3701        return self.this.name
3702
3703    @property
3704    def to(self):
3705        return self.args["to"]
3706
3707    @property
3708    def output_name(self):
3709        return self.name
3710
3711    def is_type(self, dtype: DataType.Type) -> bool:
3712        return self.to.is_type(dtype)
3713
3714
3715class CastToStrType(Func):
3716    arg_types = {"this": True, "expression": True}
3717
3718
3719class Collate(Binary):
3720    pass
3721
3722
3723class TryCast(Cast):
3724    pass
3725
3726
3727class Ceil(Func):
3728    arg_types = {"this": True, "decimals": False}
3729    _sql_names = ["CEIL", "CEILING"]
3730
3731
3732class Coalesce(Func):
3733    arg_types = {"this": True, "expressions": False}
3734    is_var_len_args = True
3735
3736
3737class Concat(Func):
3738    arg_types = {"expressions": True}
3739    is_var_len_args = True
3740
3741
3742class ConcatWs(Concat):
3743    _sql_names = ["CONCAT_WS"]
3744
3745
3746class Count(AggFunc):
3747    arg_types = {"this": False}
3748
3749
3750class CountIf(AggFunc):
3751    pass
3752
3753
3754class CurrentDate(Func):
3755    arg_types = {"this": False}
3756
3757
3758class CurrentDatetime(Func):
3759    arg_types = {"this": False}
3760
3761
3762class CurrentTime(Func):
3763    arg_types = {"this": False}
3764
3765
3766class CurrentTimestamp(Func):
3767    arg_types = {"this": False}
3768
3769
3770class CurrentUser(Func):
3771    arg_types = {"this": False}
3772
3773
3774class DateAdd(Func, TimeUnit):
3775    arg_types = {"this": True, "expression": True, "unit": False}
3776
3777
3778class DateSub(Func, TimeUnit):
3779    arg_types = {"this": True, "expression": True, "unit": False}
3780
3781
3782class DateDiff(Func, TimeUnit):
3783    _sql_names = ["DATEDIFF", "DATE_DIFF"]
3784    arg_types = {"this": True, "expression": True, "unit": False}
3785
3786
3787class DateTrunc(Func):
3788    arg_types = {"unit": True, "this": True, "zone": False}
3789
3790
3791class DatetimeAdd(Func, TimeUnit):
3792    arg_types = {"this": True, "expression": True, "unit": False}
3793
3794
3795class DatetimeSub(Func, TimeUnit):
3796    arg_types = {"this": True, "expression": True, "unit": False}
3797
3798
3799class DatetimeDiff(Func, TimeUnit):
3800    arg_types = {"this": True, "expression": True, "unit": False}
3801
3802
3803class DatetimeTrunc(Func, TimeUnit):
3804    arg_types = {"this": True, "unit": True, "zone": False}
3805
3806
3807class DayOfWeek(Func):
3808    _sql_names = ["DAY_OF_WEEK", "DAYOFWEEK"]
3809
3810
3811class DayOfMonth(Func):
3812    _sql_names = ["DAY_OF_MONTH", "DAYOFMONTH"]
3813
3814
3815class DayOfYear(Func):
3816    _sql_names = ["DAY_OF_YEAR", "DAYOFYEAR"]
3817
3818
3819class WeekOfYear(Func):
3820    _sql_names = ["WEEK_OF_YEAR", "WEEKOFYEAR"]
3821
3822
3823class LastDateOfMonth(Func):
3824    pass
3825
3826
3827class Extract(Func):
3828    arg_types = {"this": True, "expression": True}
3829
3830
3831class TimestampAdd(Func, TimeUnit):
3832    arg_types = {"this": True, "expression": True, "unit": False}
3833
3834
3835class TimestampSub(Func, TimeUnit):
3836    arg_types = {"this": True, "expression": True, "unit": False}
3837
3838
3839class TimestampDiff(Func, TimeUnit):
3840    arg_types = {"this": True, "expression": True, "unit": False}
3841
3842
3843class TimestampTrunc(Func, TimeUnit):
3844    arg_types = {"this": True, "unit": True, "zone": False}
3845
3846
3847class TimeAdd(Func, TimeUnit):
3848    arg_types = {"this": True, "expression": True, "unit": False}
3849
3850
3851class TimeSub(Func, TimeUnit):
3852    arg_types = {"this": True, "expression": True, "unit": False}
3853
3854
3855class TimeDiff(Func, TimeUnit):
3856    arg_types = {"this": True, "expression": True, "unit": False}
3857
3858
3859class TimeTrunc(Func, TimeUnit):
3860    arg_types = {"this": True, "unit": True, "zone": False}
3861
3862
3863class DateFromParts(Func):
3864    _sql_names = ["DATEFROMPARTS"]
3865    arg_types = {"year": True, "month": True, "day": True}
3866
3867
3868class DateStrToDate(Func):
3869    pass
3870
3871
3872class DateToDateStr(Func):
3873    pass
3874
3875
3876class DateToDi(Func):
3877    pass
3878
3879
3880class Day(Func):
3881    pass
3882
3883
3884class Decode(Func):
3885    arg_types = {"this": True, "charset": True, "replace": False}
3886
3887
3888class DiToDate(Func):
3889    pass
3890
3891
3892class Encode(Func):
3893    arg_types = {"this": True, "charset": True}
3894
3895
3896class Exp(Func):
3897    pass
3898
3899
3900class Explode(Func):
3901    pass
3902
3903
3904class Floor(Func):
3905    arg_types = {"this": True, "decimals": False}
3906
3907
3908class FromBase64(Func):
3909    pass
3910
3911
3912class ToBase64(Func):
3913    pass
3914
3915
3916class Greatest(Func):
3917    arg_types = {"this": True, "expressions": False}
3918    is_var_len_args = True
3919
3920
3921class GroupConcat(Func):
3922    arg_types = {"this": True, "separator": False}
3923
3924
3925class Hex(Func):
3926    pass
3927
3928
3929class If(Func):
3930    arg_types = {"this": True, "true": True, "false": False}
3931
3932
3933class IfNull(Func):
3934    arg_types = {"this": True, "expression": False}
3935    _sql_names = ["IFNULL", "NVL"]
3936
3937
3938class Initcap(Func):
3939    pass
3940
3941
3942class JSONKeyValue(Expression):
3943    arg_types = {"this": True, "expression": True}
3944
3945
3946class JSONObject(Func):
3947    arg_types = {
3948        "expressions": False,
3949        "null_handling": False,
3950        "unique_keys": False,
3951        "return_type": False,
3952        "format_json": False,
3953        "encoding": False,
3954    }
3955
3956
3957class OpenJSONColumnDef(Expression):
3958    arg_types = {"this": True, "kind": True, "path": False, "as_json": False}
3959
3960
3961class OpenJSON(Func):
3962    arg_types = {"this": True, "path": False, "expressions": False}
3963
3964
3965class JSONBContains(Binary):
3966    _sql_names = ["JSONB_CONTAINS"]
3967
3968
3969class JSONExtract(Binary, Func):
3970    _sql_names = ["JSON_EXTRACT"]
3971
3972
3973class JSONExtractScalar(JSONExtract):
3974    _sql_names = ["JSON_EXTRACT_SCALAR"]
3975
3976
3977class JSONBExtract(JSONExtract):
3978    _sql_names = ["JSONB_EXTRACT"]
3979
3980
3981class JSONBExtractScalar(JSONExtract):
3982    _sql_names = ["JSONB_EXTRACT_SCALAR"]
3983
3984
3985class JSONFormat(Func):
3986    arg_types = {"this": False, "options": False}
3987    _sql_names = ["JSON_FORMAT"]
3988
3989
3990class Least(Func):
3991    arg_types = {"expressions": False}
3992    is_var_len_args = True
3993
3994
3995class Length(Func):
3996    pass
3997
3998
3999class Levenshtein(Func):
4000    arg_types = {
4001        "this": True,
4002        "expression": False,
4003        "ins_cost": False,
4004        "del_cost": False,
4005        "sub_cost": False,
4006    }
4007
4008
4009class Ln(Func):
4010    pass
4011
4012
4013class Log(Func):
4014    arg_types = {"this": True, "expression": False}
4015
4016
4017class Log2(Func):
4018    pass
4019
4020
4021class Log10(Func):
4022    pass
4023
4024
4025class LogicalOr(AggFunc):
4026    _sql_names = ["LOGICAL_OR", "BOOL_OR", "BOOLOR_AGG"]
4027
4028
4029class LogicalAnd(AggFunc):
4030    _sql_names = ["LOGICAL_AND", "BOOL_AND", "BOOLAND_AGG"]
4031
4032
4033class Lower(Func):
4034    _sql_names = ["LOWER", "LCASE"]
4035
4036
4037class Map(Func):
4038    arg_types = {"keys": False, "values": False}
4039
4040
4041class StarMap(Func):
4042    pass
4043
4044
4045class VarMap(Func):
4046    arg_types = {"keys": True, "values": True}
4047    is_var_len_args = True
4048
4049
4050# https://dev.mysql.com/doc/refman/8.0/en/fulltext-search.html
4051class MatchAgainst(Func):
4052    arg_types = {"this": True, "expressions": True, "modifier": False}
4053
4054
4055class Max(AggFunc):
4056    arg_types = {"this": True, "expressions": False}
4057    is_var_len_args = True
4058
4059
4060class MD5(Func):
4061    _sql_names = ["MD5"]
4062
4063
4064class Min(AggFunc):
4065    arg_types = {"this": True, "expressions": False}
4066    is_var_len_args = True
4067
4068
4069class Month(Func):
4070    pass
4071
4072
4073class Nvl2(Func):
4074    arg_types = {"this": True, "true": True, "false": False}
4075
4076
4077class Posexplode(Func):
4078    pass
4079
4080
4081class Pow(Binary, Func):
4082    _sql_names = ["POWER", "POW"]
4083
4084
4085class PercentileCont(AggFunc):
4086    arg_types = {"this": True, "expression": False}
4087
4088
4089class PercentileDisc(AggFunc):
4090    arg_types = {"this": True, "expression": False}
4091
4092
4093class Quantile(AggFunc):
4094    arg_types = {"this": True, "quantile": True}
4095
4096
4097class ApproxQuantile(Quantile):
4098    arg_types = {"this": True, "quantile": True, "accuracy": False, "weight": False}
4099
4100
4101class RangeN(Func):
4102    arg_types = {"this": True, "expressions": True, "each": False}
4103
4104
4105class ReadCSV(Func):
4106    _sql_names = ["READ_CSV"]
4107    is_var_len_args = True
4108    arg_types = {"this": True, "expressions": False}
4109
4110
4111class Reduce(Func):
4112    arg_types = {"this": True, "initial": True, "merge": True, "finish": False}
4113
4114
4115class RegexpExtract(Func):
4116    arg_types = {
4117        "this": True,
4118        "expression": True,
4119        "position": False,
4120        "occurrence": False,
4121        "group": False,
4122    }
4123
4124
4125class RegexpLike(Func):
4126    arg_types = {"this": True, "expression": True, "flag": False}
4127
4128
4129class RegexpILike(Func):
4130    arg_types = {"this": True, "expression": True, "flag": False}
4131
4132
4133# https://spark.apache.org/docs/latest/api/python/reference/pyspark.sql/api/pyspark.sql.functions.split.html
4134# limit is the number of times a pattern is applied
4135class RegexpSplit(Func):
4136    arg_types = {"this": True, "expression": True, "limit": False}
4137
4138
4139class Repeat(Func):
4140    arg_types = {"this": True, "times": True}
4141
4142
4143class Round(Func):
4144    arg_types = {"this": True, "decimals": False}
4145
4146
4147class RowNumber(Func):
4148    arg_types: t.Dict[str, t.Any] = {}
4149
4150
4151class SafeDivide(Func):
4152    arg_types = {"this": True, "expression": True}
4153
4154
4155class SetAgg(AggFunc):
4156    pass
4157
4158
4159class SHA(Func):
4160    _sql_names = ["SHA", "SHA1"]
4161
4162
4163class SHA2(Func):
4164    _sql_names = ["SHA2"]
4165    arg_types = {"this": True, "length": False}
4166
4167
4168class SortArray(Func):
4169    arg_types = {"this": True, "asc": False}
4170
4171
4172class Split(Func):
4173    arg_types = {"this": True, "expression": True, "limit": False}
4174
4175
4176# Start may be omitted in the case of postgres
4177# https://www.postgresql.org/docs/9.1/functions-string.html @ Table 9-6
4178class Substring(Func):
4179    arg_types = {"this": True, "start": False, "length": False}
4180
4181
4182class StandardHash(Func):
4183    arg_types = {"this": True, "expression": False}
4184
4185
4186class StrPosition(Func):
4187    arg_types = {
4188        "this": True,
4189        "substr": True,
4190        "position": False,
4191        "instance": False,
4192    }
4193
4194
4195class StrToDate(Func):
4196    arg_types = {"this": True, "format": True}
4197
4198
4199class StrToTime(Func):
4200    arg_types = {"this": True, "format": True}
4201
4202
4203# Spark allows unix_timestamp()
4204# https://spark.apache.org/docs/3.1.3/api/python/reference/api/pyspark.sql.functions.unix_timestamp.html
4205class StrToUnix(Func):
4206    arg_types = {"this": False, "format": False}
4207
4208
4209class NumberToStr(Func):
4210    arg_types = {"this": True, "format": True}
4211
4212
4213class Struct(Func):
4214    arg_types = {"expressions": True}
4215    is_var_len_args = True
4216
4217
4218class StructExtract(Func):
4219    arg_types = {"this": True, "expression": True}
4220
4221
4222class Sum(AggFunc):
4223    pass
4224
4225
4226class Sqrt(Func):
4227    pass
4228
4229
4230class Stddev(AggFunc):
4231    pass
4232
4233
4234class StddevPop(AggFunc):
4235    pass
4236
4237
4238class StddevSamp(AggFunc):
4239    pass
4240
4241
4242class TimeToStr(Func):
4243    arg_types = {"this": True, "format": True}
4244
4245
4246class TimeToTimeStr(Func):
4247    pass
4248
4249
4250class TimeToUnix(Func):
4251    pass
4252
4253
4254class TimeStrToDate(Func):
4255    pass
4256
4257
4258class TimeStrToTime(Func):
4259    pass
4260
4261
4262class TimeStrToUnix(Func):
4263    pass
4264
4265
4266class Trim(Func):
4267    arg_types = {
4268        "this": True,
4269        "expression": False,
4270        "position": False,
4271        "collation": False,
4272    }
4273
4274
4275class TsOrDsAdd(Func, TimeUnit):
4276    arg_types = {"this": True, "expression": True, "unit": False}
4277
4278
4279class TsOrDsToDateStr(Func):
4280    pass
4281
4282
4283class TsOrDsToDate(Func):
4284    arg_types = {"this": True, "format": False}
4285
4286
4287class TsOrDiToDi(Func):
4288    pass
4289
4290
4291class Unhex(Func):
4292    pass
4293
4294
4295class UnixToStr(Func):
4296    arg_types = {"this": True, "format": False}
4297
4298
4299# https://prestodb.io/docs/current/functions/datetime.html
4300# presto has weird zone/hours/minutes
4301class UnixToTime(Func):
4302    arg_types = {"this": True, "scale": False, "zone": False, "hours": False, "minutes": False}
4303
4304    SECONDS = Literal.string("seconds")
4305    MILLIS = Literal.string("millis")
4306    MICROS = Literal.string("micros")
4307
4308
4309class UnixToTimeStr(Func):
4310    pass
4311
4312
4313class Upper(Func):
4314    _sql_names = ["UPPER", "UCASE"]
4315
4316
4317class Variance(AggFunc):
4318    _sql_names = ["VARIANCE", "VARIANCE_SAMP", "VAR_SAMP"]
4319
4320
4321class VariancePop(AggFunc):
4322    _sql_names = ["VARIANCE_POP", "VAR_POP"]
4323
4324
4325class Week(Func):
4326    arg_types = {"this": True, "mode": False}
4327
4328
4329class XMLTable(Func):
4330    arg_types = {"this": True, "passing": False, "columns": False, "by_ref": False}
4331
4332
4333class Year(Func):
4334    pass
4335
4336
4337class Use(Expression):
4338    arg_types = {"this": True, "kind": False}
4339
4340
4341class Merge(Expression):
4342    arg_types = {"this": True, "using": True, "on": True, "expressions": True}
4343
4344
4345class When(Func):
4346    arg_types = {"matched": True, "source": False, "condition": False, "then": True}
4347
4348
4349# https://docs.oracle.com/javadb/10.8.3.0/ref/rrefsqljnextvaluefor.html
4350# https://learn.microsoft.com/en-us/sql/t-sql/functions/next-value-for-transact-sql?view=sql-server-ver16
4351class NextValueFor(Func):
4352    arg_types = {"this": True, "order": False}
4353
4354
4355def _norm_arg(arg):
4356    return arg.lower() if type(arg) is str else arg
4357
4358
4359ALL_FUNCTIONS = subclasses(__name__, Func, (AggFunc, Anonymous, Func))
4360
4361
4362# Helpers
4363@t.overload
4364def maybe_parse(
4365    sql_or_expression: ExpOrStr,
4366    *,
4367    into: t.Type[E],
4368    dialect: DialectType = None,
4369    prefix: t.Optional[str] = None,
4370    copy: bool = False,
4371    **opts,
4372) -> E:
4373    ...
4374
4375
4376@t.overload
4377def maybe_parse(
4378    sql_or_expression: str | E,
4379    *,
4380    into: t.Optional[IntoType] = None,
4381    dialect: DialectType = None,
4382    prefix: t.Optional[str] = None,
4383    copy: bool = False,
4384    **opts,
4385) -> E:
4386    ...
4387
4388
4389def maybe_parse(
4390    sql_or_expression: ExpOrStr,
4391    *,
4392    into: t.Optional[IntoType] = None,
4393    dialect: DialectType = None,
4394    prefix: t.Optional[str] = None,
4395    copy: bool = False,
4396    **opts,
4397) -> Expression:
4398    """Gracefully handle a possible string or expression.
4399
4400    Example:
4401        >>> maybe_parse("1")
4402        (LITERAL this: 1, is_string: False)
4403        >>> maybe_parse(to_identifier("x"))
4404        (IDENTIFIER this: x, quoted: False)
4405
4406    Args:
4407        sql_or_expression: the SQL code string or an expression
4408        into: the SQLGlot Expression to parse into
4409        dialect: the dialect used to parse the input expressions (in the case that an
4410            input expression is a SQL string).
4411        prefix: a string to prefix the sql with before it gets parsed
4412            (automatically includes a space)
4413        copy: whether or not to copy the expression.
4414        **opts: other options to use to parse the input expressions (again, in the case
4415            that an input expression is a SQL string).
4416
4417    Returns:
4418        Expression: the parsed or given expression.
4419    """
4420    if isinstance(sql_or_expression, Expression):
4421        if copy:
4422            return sql_or_expression.copy()
4423        return sql_or_expression
4424
4425    import sqlglot
4426
4427    sql = str(sql_or_expression)
4428    if prefix:
4429        sql = f"{prefix} {sql}"
4430    return sqlglot.parse_one(sql, read=dialect, into=into, **opts)
4431
4432
4433def _maybe_copy(instance, copy=True):
4434    return instance.copy() if copy else instance
4435
4436
4437def _is_wrong_expression(expression, into):
4438    return isinstance(expression, Expression) and not isinstance(expression, into)
4439
4440
4441def _apply_builder(
4442    expression,
4443    instance,
4444    arg,
4445    copy=True,
4446    prefix=None,
4447    into=None,
4448    dialect=None,
4449    **opts,
4450):
4451    if _is_wrong_expression(expression, into):
4452        expression = into(this=expression)
4453    instance = _maybe_copy(instance, copy)
4454    expression = maybe_parse(
4455        sql_or_expression=expression,
4456        prefix=prefix,
4457        into=into,
4458        dialect=dialect,
4459        **opts,
4460    )
4461    instance.set(arg, expression)
4462    return instance
4463
4464
4465def _apply_child_list_builder(
4466    *expressions,
4467    instance,
4468    arg,
4469    append=True,
4470    copy=True,
4471    prefix=None,
4472    into=None,
4473    dialect=None,
4474    properties=None,
4475    **opts,
4476):
4477    instance = _maybe_copy(instance, copy)
4478    parsed = []
4479    for expression in expressions:
4480        if _is_wrong_expression(expression, into):
4481            expression = into(expressions=[expression])
4482        expression = maybe_parse(
4483            expression,
4484            into=into,
4485            dialect=dialect,
4486            prefix=prefix,
4487            **opts,
4488        )
4489        parsed.extend(expression.expressions)
4490
4491    existing = instance.args.get(arg)
4492    if append and existing:
4493        parsed = existing.expressions + parsed
4494
4495    child = into(expressions=parsed)
4496    for k, v in (properties or {}).items():
4497        child.set(k, v)
4498    instance.set(arg, child)
4499    return instance
4500
4501
4502def _apply_list_builder(
4503    *expressions,
4504    instance,
4505    arg,
4506    append=True,
4507    copy=True,
4508    prefix=None,
4509    into=None,
4510    dialect=None,
4511    **opts,
4512):
4513    inst = _maybe_copy(instance, copy)
4514
4515    expressions = [
4516        maybe_parse(
4517            sql_or_expression=expression,
4518            into=into,
4519            prefix=prefix,
4520            dialect=dialect,
4521            **opts,
4522        )
4523        for expression in expressions
4524    ]
4525
4526    existing_expressions = inst.args.get(arg)
4527    if append and existing_expressions:
4528        expressions = existing_expressions + expressions
4529
4530    inst.set(arg, expressions)
4531    return inst
4532
4533
4534def _apply_conjunction_builder(
4535    *expressions,
4536    instance,
4537    arg,
4538    into=None,
4539    append=True,
4540    copy=True,
4541    dialect=None,
4542    **opts,
4543):
4544    expressions = [exp for exp in expressions if exp is not None and exp != ""]
4545    if not expressions:
4546        return instance
4547
4548    inst = _maybe_copy(instance, copy)
4549
4550    existing = inst.args.get(arg)
4551    if append and existing is not None:
4552        expressions = [existing.this if into else existing] + list(expressions)
4553
4554    node = and_(*expressions, dialect=dialect, copy=copy, **opts)
4555
4556    inst.set(arg, into(this=node) if into else node)
4557    return inst
4558
4559
4560def _apply_cte_builder(
4561    instance: E,
4562    alias: ExpOrStr,
4563    as_: ExpOrStr,
4564    recursive: t.Optional[bool] = None,
4565    append: bool = True,
4566    dialect: DialectType = None,
4567    copy: bool = True,
4568    **opts,
4569) -> E:
4570    alias_expression = maybe_parse(alias, dialect=dialect, into=TableAlias, **opts)
4571    as_expression = maybe_parse(as_, dialect=dialect, **opts)
4572    cte = CTE(this=as_expression, alias=alias_expression)
4573    return _apply_child_list_builder(
4574        cte,
4575        instance=instance,
4576        arg="with",
4577        append=append,
4578        copy=copy,
4579        into=With,
4580        properties={"recursive": recursive or False},
4581    )
4582
4583
4584def _combine(expressions, operator, dialect=None, copy=True, **opts):
4585    expressions = [
4586        condition(expression, dialect=dialect, copy=copy, **opts) for expression in expressions
4587    ]
4588    this = expressions[0]
4589    if expressions[1:]:
4590        this = _wrap(this, Connector)
4591    for expression in expressions[1:]:
4592        this = operator(this=this, expression=_wrap(expression, Connector))
4593    return this
4594
4595
4596def _wrap(expression: E, kind: t.Type[Expression]) -> E | Paren:
4597    if isinstance(expression, kind):
4598        return Paren(this=expression)
4599    return expression
4600
4601
4602def union(left, right, distinct=True, dialect=None, **opts):
4603    """
4604    Initializes a syntax tree from one UNION expression.
4605
4606    Example:
4607        >>> union("SELECT * FROM foo", "SELECT * FROM bla").sql()
4608        'SELECT * FROM foo UNION SELECT * FROM bla'
4609
4610    Args:
4611        left (str | Expression): the SQL code string corresponding to the left-hand side.
4612            If an `Expression` instance is passed, it will be used as-is.
4613        right (str | Expression): the SQL code string corresponding to the right-hand side.
4614            If an `Expression` instance is passed, it will be used as-is.
4615        distinct (bool): set the DISTINCT flag if and only if this is true.
4616        dialect (str): the dialect used to parse the input expression.
4617        opts (kwargs): other options to use to parse the input expressions.
4618    Returns:
4619        Union: the syntax tree for the UNION expression.
4620    """
4621    left = maybe_parse(sql_or_expression=left, dialect=dialect, **opts)
4622    right = maybe_parse(sql_or_expression=right, dialect=dialect, **opts)
4623
4624    return Union(this=left, expression=right, distinct=distinct)
4625
4626
4627def intersect(left, right, distinct=True, dialect=None, **opts):
4628    """
4629    Initializes a syntax tree from one INTERSECT expression.
4630
4631    Example:
4632        >>> intersect("SELECT * FROM foo", "SELECT * FROM bla").sql()
4633        'SELECT * FROM foo INTERSECT SELECT * FROM bla'
4634
4635    Args:
4636        left (str | Expression): the SQL code string corresponding to the left-hand side.
4637            If an `Expression` instance is passed, it will be used as-is.
4638        right (str | Expression): the SQL code string corresponding to the right-hand side.
4639            If an `Expression` instance is passed, it will be used as-is.
4640        distinct (bool): set the DISTINCT flag if and only if this is true.
4641        dialect (str): the dialect used to parse the input expression.
4642        opts (kwargs): other options to use to parse the input expressions.
4643    Returns:
4644        Intersect: the syntax tree for the INTERSECT expression.
4645    """
4646    left = maybe_parse(sql_or_expression=left, dialect=dialect, **opts)
4647    right = maybe_parse(sql_or_expression=right, dialect=dialect, **opts)
4648
4649    return Intersect(this=left, expression=right, distinct=distinct)
4650
4651
4652def except_(left, right, distinct=True, dialect=None, **opts):
4653    """
4654    Initializes a syntax tree from one EXCEPT expression.
4655
4656    Example:
4657        >>> except_("SELECT * FROM foo", "SELECT * FROM bla").sql()
4658        'SELECT * FROM foo EXCEPT SELECT * FROM bla'
4659
4660    Args:
4661        left (str | Expression): the SQL code string corresponding to the left-hand side.
4662            If an `Expression` instance is passed, it will be used as-is.
4663        right (str | Expression): the SQL code string corresponding to the right-hand side.
4664            If an `Expression` instance is passed, it will be used as-is.
4665        distinct (bool): set the DISTINCT flag if and only if this is true.
4666        dialect (str): the dialect used to parse the input expression.
4667        opts (kwargs): other options to use to parse the input expressions.
4668    Returns:
4669        Except: the syntax tree for the EXCEPT statement.
4670    """
4671    left = maybe_parse(sql_or_expression=left, dialect=dialect, **opts)
4672    right = maybe_parse(sql_or_expression=right, dialect=dialect, **opts)
4673
4674    return Except(this=left, expression=right, distinct=distinct)
4675
4676
4677def select(*expressions: ExpOrStr, dialect: DialectType = None, **opts) -> Select:
4678    """
4679    Initializes a syntax tree from one or multiple SELECT expressions.
4680
4681    Example:
4682        >>> select("col1", "col2").from_("tbl").sql()
4683        'SELECT col1, col2 FROM tbl'
4684
4685    Args:
4686        *expressions: the SQL code string to parse as the expressions of a
4687            SELECT statement. If an Expression instance is passed, this is used as-is.
4688        dialect: the dialect used to parse the input expressions (in the case that an
4689            input expression is a SQL string).
4690        **opts: other options to use to parse the input expressions (again, in the case
4691            that an input expression is a SQL string).
4692
4693    Returns:
4694        Select: the syntax tree for the SELECT statement.
4695    """
4696    return Select().select(*expressions, dialect=dialect, **opts)
4697
4698
4699def from_(expression: ExpOrStr, dialect: DialectType = None, **opts) -> Select:
4700    """
4701    Initializes a syntax tree from a FROM expression.
4702
4703    Example:
4704        >>> from_("tbl").select("col1", "col2").sql()
4705        'SELECT col1, col2 FROM tbl'
4706
4707    Args:
4708        *expression: the SQL code string to parse as the FROM expressions of a
4709            SELECT statement. If an Expression instance is passed, this is used as-is.
4710        dialect: the dialect used to parse the input expression (in the case that the
4711            input expression is a SQL string).
4712        **opts: other options to use to parse the input expressions (again, in the case
4713            that the input expression is a SQL string).
4714
4715    Returns:
4716        Select: the syntax tree for the SELECT statement.
4717    """
4718    return Select().from_(expression, dialect=dialect, **opts)
4719
4720
4721def update(
4722    table: str | Table,
4723    properties: dict,
4724    where: t.Optional[ExpOrStr] = None,
4725    from_: t.Optional[ExpOrStr] = None,
4726    dialect: DialectType = None,
4727    **opts,
4728) -> Update:
4729    """
4730    Creates an update statement.
4731
4732    Example:
4733        >>> update("my_table", {"x": 1, "y": "2", "z": None}, from_="baz", where="id > 1").sql()
4734        "UPDATE my_table SET x = 1, y = '2', z = NULL FROM baz WHERE id > 1"
4735
4736    Args:
4737        *properties: dictionary of properties to set which are
4738            auto converted to sql objects eg None -> NULL
4739        where: sql conditional parsed into a WHERE statement
4740        from_: sql statement parsed into a FROM statement
4741        dialect: the dialect used to parse the input expressions.
4742        **opts: other options to use to parse the input expressions.
4743
4744    Returns:
4745        Update: the syntax tree for the UPDATE statement.
4746    """
4747    update_expr = Update(this=maybe_parse(table, into=Table, dialect=dialect))
4748    update_expr.set(
4749        "expressions",
4750        [
4751            EQ(this=maybe_parse(k, dialect=dialect, **opts), expression=convert(v))
4752            for k, v in properties.items()
4753        ],
4754    )
4755    if from_:
4756        update_expr.set(
4757            "from",
4758            maybe_parse(from_, into=From, dialect=dialect, prefix="FROM", **opts),
4759        )
4760    if isinstance(where, Condition):
4761        where = Where(this=where)
4762    if where:
4763        update_expr.set(
4764            "where",
4765            maybe_parse(where, into=Where, dialect=dialect, prefix="WHERE", **opts),
4766        )
4767    return update_expr
4768
4769
4770def delete(
4771    table: ExpOrStr,
4772    where: t.Optional[ExpOrStr] = None,
4773    returning: t.Optional[ExpOrStr] = None,
4774    dialect: DialectType = None,
4775    **opts,
4776) -> Delete:
4777    """
4778    Builds a delete statement.
4779
4780    Example:
4781        >>> delete("my_table", where="id > 1").sql()
4782        'DELETE FROM my_table WHERE id > 1'
4783
4784    Args:
4785        where: sql conditional parsed into a WHERE statement
4786        returning: sql conditional parsed into a RETURNING statement
4787        dialect: the dialect used to parse the input expressions.
4788        **opts: other options to use to parse the input expressions.
4789
4790    Returns:
4791        Delete: the syntax tree for the DELETE statement.
4792    """
4793    delete_expr = Delete().delete(table, dialect=dialect, copy=False, **opts)
4794    if where:
4795        delete_expr = delete_expr.where(where, dialect=dialect, copy=False, **opts)
4796    if returning:
4797        delete_expr = delete_expr.returning(returning, dialect=dialect, copy=False, **opts)
4798    return delete_expr
4799
4800
4801def insert(
4802    expression: ExpOrStr,
4803    into: ExpOrStr,
4804    columns: t.Optional[t.Sequence[ExpOrStr]] = None,
4805    overwrite: t.Optional[bool] = None,
4806    dialect: DialectType = None,
4807    copy: bool = True,
4808    **opts,
4809) -> Insert:
4810    """
4811    Builds an INSERT statement.
4812
4813    Example:
4814        >>> insert("VALUES (1, 2, 3)", "tbl").sql()
4815        'INSERT INTO tbl VALUES (1, 2, 3)'
4816
4817    Args:
4818        expression: the sql string or expression of the INSERT statement
4819        into: the tbl to insert data to.
4820        columns: optionally the table's column names.
4821        overwrite: whether to INSERT OVERWRITE or not.
4822        dialect: the dialect used to parse the input expressions.
4823        copy: whether or not to copy the expression.
4824        **opts: other options to use to parse the input expressions.
4825
4826    Returns:
4827        Insert: the syntax tree for the INSERT statement.
4828    """
4829    expr = maybe_parse(expression, dialect=dialect, copy=copy, **opts)
4830    this: Table | Schema = maybe_parse(into, into=Table, dialect=dialect, copy=copy, **opts)
4831
4832    if columns:
4833        this = _apply_list_builder(
4834            *columns,
4835            instance=Schema(this=this),
4836            arg="expressions",
4837            into=Identifier,
4838            copy=False,
4839            dialect=dialect,
4840            **opts,
4841        )
4842
4843    return Insert(this=this, expression=expr, overwrite=overwrite)
4844
4845
4846def condition(expression, dialect=None, copy=True, **opts) -> Condition:
4847    """
4848    Initialize a logical condition expression.
4849
4850    Example:
4851        >>> condition("x=1").sql()
4852        'x = 1'
4853
4854        This is helpful for composing larger logical syntax trees:
4855        >>> where = condition("x=1")
4856        >>> where = where.and_("y=1")
4857        >>> Select().from_("tbl").select("*").where(where).sql()
4858        'SELECT * FROM tbl WHERE x = 1 AND y = 1'
4859
4860    Args:
4861        *expression (str | Expression): the SQL code string to parse.
4862            If an Expression instance is passed, this is used as-is.
4863        dialect (str): the dialect used to parse the input expression (in the case that the
4864            input expression is a SQL string).
4865        copy (bool): Whether or not to copy `expression` (only applies to expressions).
4866        **opts: other options to use to parse the input expressions (again, in the case
4867            that the input expression is a SQL string).
4868
4869    Returns:
4870        Condition: the expression
4871    """
4872    return maybe_parse(  # type: ignore
4873        expression,
4874        into=Condition,
4875        dialect=dialect,
4876        copy=copy,
4877        **opts,
4878    )
4879
4880
4881def and_(*expressions, dialect=None, copy=True, **opts) -> And:
4882    """
4883    Combine multiple conditions with an AND logical operator.
4884
4885    Example:
4886        >>> and_("x=1", and_("y=1", "z=1")).sql()
4887        'x = 1 AND (y = 1 AND z = 1)'
4888
4889    Args:
4890        *expressions (str | Expression): the SQL code strings to parse.
4891            If an Expression instance is passed, this is used as-is.
4892        dialect (str): the dialect used to parse the input expression.
4893        copy (bool): whether or not to copy `expressions` (only applies to Expressions).
4894        **opts: other options to use to parse the input expressions.
4895
4896    Returns:
4897        And: the new condition
4898    """
4899    return _combine(expressions, And, dialect, copy=copy, **opts)
4900
4901
4902def or_(*expressions, dialect=None, copy=True, **opts) -> Or:
4903    """
4904    Combine multiple conditions with an OR logical operator.
4905
4906    Example:
4907        >>> or_("x=1", or_("y=1", "z=1")).sql()
4908        'x = 1 OR (y = 1 OR z = 1)'
4909
4910    Args:
4911        *expressions (str | Expression): the SQL code strings to parse.
4912            If an Expression instance is passed, this is used as-is.
4913        dialect (str): the dialect used to parse the input expression.
4914        copy (bool): whether or not to copy `expressions` (only applies to Expressions).
4915        **opts: other options to use to parse the input expressions.
4916
4917    Returns:
4918        Or: the new condition
4919    """
4920    return _combine(expressions, Or, dialect, copy=copy, **opts)
4921
4922
4923def not_(expression, dialect=None, copy=True, **opts) -> Not:
4924    """
4925    Wrap a condition with a NOT operator.
4926
4927    Example:
4928        >>> not_("this_suit='black'").sql()
4929        "NOT this_suit = 'black'"
4930
4931    Args:
4932        expression (str | Expression): the SQL code strings to parse.
4933            If an Expression instance is passed, this is used as-is.
4934        dialect (str): the dialect used to parse the input expression.
4935        **opts: other options to use to parse the input expressions.
4936
4937    Returns:
4938        Not: the new condition
4939    """
4940    this = condition(
4941        expression,
4942        dialect=dialect,
4943        copy=copy,
4944        **opts,
4945    )
4946    return Not(this=_wrap(this, Connector))
4947
4948
4949def paren(expression, copy=True) -> Paren:
4950    return Paren(this=_maybe_copy(expression, copy))
4951
4952
4953SAFE_IDENTIFIER_RE = re.compile(r"^[_a-zA-Z][\w]*$")
4954
4955
4956@t.overload
4957def to_identifier(name: None, quoted: t.Optional[bool] = None, copy: bool = True) -> None:
4958    ...
4959
4960
4961@t.overload
4962def to_identifier(
4963    name: str | Identifier, quoted: t.Optional[bool] = None, copy: bool = True
4964) -> Identifier:
4965    ...
4966
4967
4968def to_identifier(name, quoted=None, copy=True):
4969    """Builds an identifier.
4970
4971    Args:
4972        name: The name to turn into an identifier.
4973        quoted: Whether or not force quote the identifier.
4974        copy: Whether or not to copy a passed in Identefier node.
4975
4976    Returns:
4977        The identifier ast node.
4978    """
4979
4980    if name is None:
4981        return None
4982
4983    if isinstance(name, Identifier):
4984        identifier = _maybe_copy(name, copy)
4985    elif isinstance(name, str):
4986        identifier = Identifier(
4987            this=name,
4988            quoted=not SAFE_IDENTIFIER_RE.match(name) if quoted is None else quoted,
4989        )
4990    else:
4991        raise ValueError(f"Name needs to be a string or an Identifier, got: {name.__class__}")
4992    return identifier
4993
4994
4995INTERVAL_STRING_RE = re.compile(r"\s*([0-9]+)\s*([a-zA-Z]+)\s*")
4996
4997
4998def to_interval(interval: str | Literal) -> Interval:
4999    """Builds an interval expression from a string like '1 day' or '5 months'."""
5000    if isinstance(interval, Literal):
5001        if not interval.is_string:
5002            raise ValueError("Invalid interval string.")
5003
5004        interval = interval.this
5005
5006    interval_parts = INTERVAL_STRING_RE.match(interval)  # type: ignore
5007
5008    if not interval_parts:
5009        raise ValueError("Invalid interval string.")
5010
5011    return Interval(
5012        this=Literal.string(interval_parts.group(1)),
5013        unit=Var(this=interval_parts.group(2)),
5014    )
5015
5016
5017@t.overload
5018def to_table(sql_path: str | Table, **kwargs) -> Table:
5019    ...
5020
5021
5022@t.overload
5023def to_table(sql_path: None, **kwargs) -> None:
5024    ...
5025
5026
5027def to_table(sql_path: t.Optional[str | Table], **kwargs) -> t.Optional[Table]:
5028    """
5029    Create a table expression from a `[catalog].[schema].[table]` sql path. Catalog and schema are optional.
5030    If a table is passed in then that table is returned.
5031
5032    Args:
5033        sql_path: a `[catalog].[schema].[table]` string.
5034
5035    Returns:
5036        A table expression.
5037    """
5038    if sql_path is None or isinstance(sql_path, Table):
5039        return sql_path
5040    if not isinstance(sql_path, str):
5041        raise ValueError(f"Invalid type provided for a table: {type(sql_path)}")
5042
5043    catalog, db, table_name = (to_identifier(x) for x in split_num_words(sql_path, ".", 3))
5044    return Table(this=table_name, db=db, catalog=catalog, **kwargs)
5045
5046
5047def to_column(sql_path: str | Column, **kwargs) -> Column:
5048    """
5049    Create a column from a `[table].[column]` sql path. Schema is optional.
5050
5051    If a column is passed in then that column is returned.
5052
5053    Args:
5054        sql_path: `[table].[column]` string
5055    Returns:
5056        Table: A column expression
5057    """
5058    if sql_path is None or isinstance(sql_path, Column):
5059        return sql_path
5060    if not isinstance(sql_path, str):
5061        raise ValueError(f"Invalid type provided for column: {type(sql_path)}")
5062    return column(*reversed(sql_path.split(".")), **kwargs)  # type: ignore
5063
5064
5065def alias_(
5066    expression: ExpOrStr,
5067    alias: str | Identifier,
5068    table: bool | t.Sequence[str | Identifier] = False,
5069    quoted: t.Optional[bool] = None,
5070    dialect: DialectType = None,
5071    copy: bool = True,
5072    **opts,
5073):
5074    """Create an Alias expression.
5075
5076    Example:
5077        >>> alias_('foo', 'bar').sql()
5078        'foo AS bar'
5079
5080        >>> alias_('(select 1, 2)', 'bar', table=['a', 'b']).sql()
5081        '(SELECT 1, 2) AS bar(a, b)'
5082
5083    Args:
5084        expression: the SQL code strings to parse.
5085            If an Expression instance is passed, this is used as-is.
5086        alias: the alias name to use. If the name has
5087            special characters it is quoted.
5088        table: Whether or not to create a table alias, can also be a list of columns.
5089        quoted: whether or not to quote the alias
5090        dialect: the dialect used to parse the input expression.
5091        copy: Whether or not to copy the expression.
5092        **opts: other options to use to parse the input expressions.
5093
5094    Returns:
5095        Alias: the aliased expression
5096    """
5097    exp = maybe_parse(expression, dialect=dialect, copy=copy, **opts)
5098    alias = to_identifier(alias, quoted=quoted)
5099
5100    if table:
5101        table_alias = TableAlias(this=alias)
5102        exp.set("alias", table_alias)
5103
5104        if not isinstance(table, bool):
5105            for column in table:
5106                table_alias.append("columns", to_identifier(column, quoted=quoted))
5107
5108        return exp
5109
5110    # We don't set the "alias" arg for Window expressions, because that would add an IDENTIFIER node in
5111    # the AST, representing a "named_window" [1] construct (eg. bigquery). What we want is an ALIAS node
5112    # for the complete Window expression.
5113    #
5114    # [1]: https://cloud.google.com/bigquery/docs/reference/standard-sql/window-function-calls
5115
5116    if "alias" in exp.arg_types and not isinstance(exp, Window):
5117        exp.set("alias", alias)
5118        return exp
5119    return Alias(this=exp, alias=alias)
5120
5121
5122def subquery(expression, alias=None, dialect=None, **opts):
5123    """
5124    Build a subquery expression.
5125
5126    Example:
5127        >>> subquery('select x from tbl', 'bar').select('x').sql()
5128        'SELECT x FROM (SELECT x FROM tbl) AS bar'
5129
5130    Args:
5131        expression (str | Expression): the SQL code strings to parse.
5132            If an Expression instance is passed, this is used as-is.
5133        alias (str | Expression): the alias name to use.
5134        dialect (str): the dialect used to parse the input expression.
5135        **opts: other options to use to parse the input expressions.
5136
5137    Returns:
5138        Select: a new select with the subquery expression included
5139    """
5140
5141    expression = maybe_parse(expression, dialect=dialect, **opts).subquery(alias)
5142    return Select().from_(expression, dialect=dialect, **opts)
5143
5144
5145def column(
5146    col: str | Identifier,
5147    table: t.Optional[str | Identifier] = None,
5148    db: t.Optional[str | Identifier] = None,
5149    catalog: t.Optional[str | Identifier] = None,
5150    quoted: t.Optional[bool] = None,
5151) -> Column:
5152    """
5153    Build a Column.
5154
5155    Args:
5156        col: column name
5157        table: table name
5158        db: db name
5159        catalog: catalog name
5160        quoted: whether or not to force quote each part
5161    Returns:
5162        Column: column instance
5163    """
5164    return Column(
5165        this=to_identifier(col, quoted=quoted),
5166        table=to_identifier(table, quoted=quoted),
5167        db=to_identifier(db, quoted=quoted),
5168        catalog=to_identifier(catalog, quoted=quoted),
5169    )
5170
5171
5172def cast(expression: ExpOrStr, to: str | DataType | DataType.Type, **opts) -> Cast:
5173    """Cast an expression to a data type.
5174
5175    Example:
5176        >>> cast('x + 1', 'int').sql()
5177        'CAST(x + 1 AS INT)'
5178
5179    Args:
5180        expression: The expression to cast.
5181        to: The datatype to cast to.
5182
5183    Returns:
5184        A cast node.
5185    """
5186    expression = maybe_parse(expression, **opts)
5187    return Cast(this=expression, to=DataType.build(to, **opts))
5188
5189
5190def table_(table, db=None, catalog=None, quoted=None, alias=None) -> Table:
5191    """Build a Table.
5192
5193    Args:
5194        table (str | Expression): column name
5195        db (str | Expression): db name
5196        catalog (str | Expression): catalog name
5197
5198    Returns:
5199        Table: table instance
5200    """
5201    return Table(
5202        this=to_identifier(table, quoted=quoted),
5203        db=to_identifier(db, quoted=quoted),
5204        catalog=to_identifier(catalog, quoted=quoted),
5205        alias=TableAlias(this=to_identifier(alias)) if alias else None,
5206    )
5207
5208
5209def values(
5210    values: t.Iterable[t.Tuple[t.Any, ...]],
5211    alias: t.Optional[str] = None,
5212    columns: t.Optional[t.Iterable[str] | t.Dict[str, DataType]] = None,
5213) -> Values:
5214    """Build VALUES statement.
5215
5216    Example:
5217        >>> values([(1, '2')]).sql()
5218        "VALUES (1, '2')"
5219
5220    Args:
5221        values: values statements that will be converted to SQL
5222        alias: optional alias
5223        columns: Optional list of ordered column names or ordered dictionary of column names to types.
5224         If either are provided then an alias is also required.
5225
5226    Returns:
5227        Values: the Values expression object
5228    """
5229    if columns and not alias:
5230        raise ValueError("Alias is required when providing columns")
5231
5232    return Values(
5233        expressions=[convert(tup) for tup in values],
5234        alias=(
5235            TableAlias(this=to_identifier(alias), columns=[to_identifier(x) for x in columns])
5236            if columns
5237            else (TableAlias(this=to_identifier(alias)) if alias else None)
5238        ),
5239    )
5240
5241
5242def var(name: t.Optional[ExpOrStr]) -> Var:
5243    """Build a SQL variable.
5244
5245    Example:
5246        >>> repr(var('x'))
5247        '(VAR this: x)'
5248
5249        >>> repr(var(column('x', table='y')))
5250        '(VAR this: x)'
5251
5252    Args:
5253        name: The name of the var or an expression who's name will become the var.
5254
5255    Returns:
5256        The new variable node.
5257    """
5258    if not name:
5259        raise ValueError("Cannot convert empty name into var.")
5260
5261    if isinstance(name, Expression):
5262        name = name.name
5263    return Var(this=name)
5264
5265
5266def rename_table(old_name: str | Table, new_name: str | Table) -> AlterTable:
5267    """Build ALTER TABLE... RENAME... expression
5268
5269    Args:
5270        old_name: The old name of the table
5271        new_name: The new name of the table
5272
5273    Returns:
5274        Alter table expression
5275    """
5276    old_table = to_table(old_name)
5277    new_table = to_table(new_name)
5278    return AlterTable(
5279        this=old_table,
5280        actions=[
5281            RenameTable(this=new_table),
5282        ],
5283    )
5284
5285
5286def convert(value: t.Any, copy: bool = False) -> Expression:
5287    """Convert a python value into an expression object.
5288
5289    Raises an error if a conversion is not possible.
5290
5291    Args:
5292        value: A python object.
5293        copy: Whether or not to copy `value` (only applies to Expressions and collections).
5294
5295    Returns:
5296        Expression: the equivalent expression object.
5297    """
5298    if isinstance(value, Expression):
5299        return _maybe_copy(value, copy)
5300    if isinstance(value, str):
5301        return Literal.string(value)
5302    if isinstance(value, bool):
5303        return Boolean(this=value)
5304    if value is None or (isinstance(value, float) and math.isnan(value)):
5305        return NULL
5306    if isinstance(value, numbers.Number):
5307        return Literal.number(value)
5308    if isinstance(value, datetime.datetime):
5309        datetime_literal = Literal.string(
5310            (value if value.tzinfo else value.replace(tzinfo=datetime.timezone.utc)).isoformat()
5311        )
5312        return TimeStrToTime(this=datetime_literal)
5313    if isinstance(value, datetime.date):
5314        date_literal = Literal.string(value.strftime("%Y-%m-%d"))
5315        return DateStrToDate(this=date_literal)
5316    if isinstance(value, tuple):
5317        return Tuple(expressions=[convert(v, copy=copy) for v in value])
5318    if isinstance(value, list):
5319        return Array(expressions=[convert(v, copy=copy) for v in value])
5320    if isinstance(value, dict):
5321        return Map(
5322            keys=[convert(k, copy=copy) for k in value],
5323            values=[convert(v, copy=copy) for v in value.values()],
5324        )
5325    raise ValueError(f"Cannot convert {value}")
5326
5327
5328def replace_children(expression, fun, *args, **kwargs):
5329    """
5330    Replace children of an expression with the result of a lambda fun(child) -> exp.
5331    """
5332    for k, v in expression.args.items():
5333        is_list_arg = type(v) is list
5334
5335        child_nodes = v if is_list_arg else [v]
5336        new_child_nodes = []
5337
5338        for cn in child_nodes:
5339            if isinstance(cn, Expression):
5340                for child_node in ensure_collection(fun(cn, *args, **kwargs)):
5341                    new_child_nodes.append(child_node)
5342                    child_node.parent = expression
5343                    child_node.arg_key = k
5344            else:
5345                new_child_nodes.append(cn)
5346
5347        expression.args[k] = new_child_nodes if is_list_arg else seq_get(new_child_nodes, 0)
5348
5349
5350def column_table_names(expression):
5351    """
5352    Return all table names referenced through columns in an expression.
5353
5354    Example:
5355        >>> import sqlglot
5356        >>> column_table_names(sqlglot.parse_one("a.b AND c.d AND c.e"))
5357        ['c', 'a']
5358
5359    Args:
5360        expression (sqlglot.Expression): expression to find table names
5361
5362    Returns:
5363        list: A list of unique names
5364    """
5365    return list(dict.fromkeys(column.table for column in expression.find_all(Column)))
5366
5367
5368def table_name(table) -> str:
5369    """Get the full name of a table as a string.
5370
5371    Args:
5372        table (exp.Table | str): table expression node or string.
5373
5374    Examples:
5375        >>> from sqlglot import exp, parse_one
5376        >>> table_name(parse_one("select * from a.b.c").find(exp.Table))
5377        'a.b.c'
5378
5379    Returns:
5380        The table name.
5381    """
5382
5383    table = maybe_parse(table, into=Table)
5384
5385    if not table:
5386        raise ValueError(f"Cannot parse {table}")
5387
5388    return ".".join(
5389        part
5390        for part in (
5391            table.text("catalog"),
5392            table.text("db"),
5393            table.name,
5394        )
5395        if part
5396    )
5397
5398
5399def replace_tables(expression, mapping):
5400    """Replace all tables in expression according to the mapping.
5401
5402    Args:
5403        expression (sqlglot.Expression): expression node to be transformed and replaced.
5404        mapping (Dict[str, str]): mapping of table names.
5405
5406    Examples:
5407        >>> from sqlglot import exp, parse_one
5408        >>> replace_tables(parse_one("select * from a.b"), {"a.b": "c"}).sql()
5409        'SELECT * FROM c'
5410
5411    Returns:
5412        The mapped expression.
5413    """
5414
5415    def _replace_tables(node):
5416        if isinstance(node, Table):
5417            new_name = mapping.get(table_name(node))
5418            if new_name:
5419                return to_table(
5420                    new_name,
5421                    **{k: v for k, v in node.args.items() if k not in ("this", "db", "catalog")},
5422                )
5423        return node
5424
5425    return expression.transform(_replace_tables)
5426
5427
5428def replace_placeholders(expression, *args, **kwargs):
5429    """Replace placeholders in an expression.
5430
5431    Args:
5432        expression (sqlglot.Expression): expression node to be transformed and replaced.
5433        args: positional names that will substitute unnamed placeholders in the given order.
5434        kwargs: keyword arguments that will substitute named placeholders.
5435
5436    Examples:
5437        >>> from sqlglot import exp, parse_one
5438        >>> replace_placeholders(
5439        ...     parse_one("select * from :tbl where ? = ?"),
5440        ...     exp.to_identifier("str_col"), "b", tbl=exp.to_identifier("foo")
5441        ... ).sql()
5442        "SELECT * FROM foo WHERE str_col = 'b'"
5443
5444    Returns:
5445        The mapped expression.
5446    """
5447
5448    def _replace_placeholders(node, args, **kwargs):
5449        if isinstance(node, Placeholder):
5450            if node.name:
5451                new_name = kwargs.get(node.name)
5452                if new_name:
5453                    return convert(new_name)
5454            else:
5455                try:
5456                    return convert(next(args))
5457                except StopIteration:
5458                    pass
5459        return node
5460
5461    return expression.transform(_replace_placeholders, iter(args), **kwargs)
5462
5463
5464def expand(
5465    expression: Expression, sources: t.Dict[str, Subqueryable], copy: bool = True
5466) -> Expression:
5467    """Transforms an expression by expanding all referenced sources into subqueries.
5468
5469    Examples:
5470        >>> from sqlglot import parse_one
5471        >>> expand(parse_one("select * from x AS z"), {"x": parse_one("select * from y")}).sql()
5472        'SELECT * FROM (SELECT * FROM y) AS z /* source: x */'
5473
5474        >>> expand(parse_one("select * from x AS z"), {"x": parse_one("select * from y"), "y": parse_one("select * from z")}).sql()
5475        'SELECT * FROM (SELECT * FROM (SELECT * FROM z) AS y /* source: y */) AS z /* source: x */'
5476
5477    Args:
5478        expression: The expression to expand.
5479        sources: A dictionary of name to Subqueryables.
5480        copy: Whether or not to copy the expression during transformation. Defaults to True.
5481
5482    Returns:
5483        The transformed expression.
5484    """
5485
5486    def _expand(node: Expression):
5487        if isinstance(node, Table):
5488            name = table_name(node)
5489            source = sources.get(name)
5490            if source:
5491                subquery = source.subquery(node.alias or name)
5492                subquery.comments = [f"source: {name}"]
5493                return subquery.transform(_expand, copy=False)
5494        return node
5495
5496    return expression.transform(_expand, copy=copy)
5497
5498
5499def func(name: str, *args, dialect: DialectType = None, **kwargs) -> Func:
5500    """
5501    Returns a Func expression.
5502
5503    Examples:
5504        >>> func("abs", 5).sql()
5505        'ABS(5)'
5506
5507        >>> func("cast", this=5, to=DataType.build("DOUBLE")).sql()
5508        'CAST(5 AS DOUBLE)'
5509
5510    Args:
5511        name: the name of the function to build.
5512        args: the args used to instantiate the function of interest.
5513        dialect: the source dialect.
5514        kwargs: the kwargs used to instantiate the function of interest.
5515
5516    Note:
5517        The arguments `args` and `kwargs` are mutually exclusive.
5518
5519    Returns:
5520        An instance of the function of interest, or an anonymous function, if `name` doesn't
5521        correspond to an existing `sqlglot.expressions.Func` class.
5522    """
5523    if args and kwargs:
5524        raise ValueError("Can't use both args and kwargs to instantiate a function.")
5525
5526    from sqlglot.dialects.dialect import Dialect
5527
5528    converted: t.List[Expression] = [maybe_parse(arg, dialect=dialect) for arg in args]
5529    kwargs = {key: maybe_parse(value, dialect=dialect) for key, value in kwargs.items()}
5530
5531    parser = Dialect.get_or_raise(dialect)().parser()
5532    from_args_list = parser.FUNCTIONS.get(name.upper())
5533
5534    if from_args_list:
5535        function = from_args_list(converted) if converted else from_args_list.__self__(**kwargs)  # type: ignore
5536    else:
5537        kwargs = kwargs or {"expressions": converted}
5538        function = Anonymous(this=name, **kwargs)
5539
5540    for error_message in function.error_messages(converted):
5541        raise ValueError(error_message)
5542
5543    return function
5544
5545
5546def true():
5547    """
5548    Returns a true Boolean expression.
5549    """
5550    return Boolean(this=True)
5551
5552
5553def false():
5554    """
5555    Returns a false Boolean expression.
5556    """
5557    return Boolean(this=False)
5558
5559
5560def null():
5561    """
5562    Returns a Null expression.
5563    """
5564    return Null()
5565
5566
5567# TODO: deprecate this
5568TRUE = Boolean(this=True)
5569FALSE = Boolean(this=False)
5570NULL = Null()