Edit on GitHub

Expressions

Every AST node in SQLGlot is represented by a subclass of Expression.

This module contains the implementation of all supported Expression types. Additionally, it exposes a number of helper functions, which are mainly used to programmatically build SQL expressions, such as select.


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

The base class for all expressions in a syntax tree. Each Expression encapsulates any necessary context, such as its child expressions, their names (arg keys), and whether a given child expression is optional or not.

Attributes:
  • key: a unique key for each class in the Expression hierarchy. This is useful for hashing and representing expressions as strings.
  • arg_types: determines what arguments (child nodes) are supported by an expression. It maps arg keys to booleans that indicate whether the corresponding args are optional.
  • parent: a reference to the parent expression (or None, in case of root expressions).
  • arg_key: the arg key an expression is associated with, i.e. the name its parent expression uses to refer to it.
  • comments: a list of comments that are associated with a given expression. This is used in order to preserve comments when transpiling SQL code.
  • type: the DataType type of an expression. This is inferred by the optimizer, in order to enable some transformations that require type information.
  • meta: a dictionary that can be used to store useful metadata for a given expression.
Example:
>>> class Foo(Expression):
...     arg_types = {"this": True, "expression": False}

The above definition informs us that Foo is an Expression that requires an argument called "this" and may also optionally receive an argument called "expression".

Arguments:
  • args: a mapping used for retrieving the arguments of an expression, given their arg keys.
Expression(**args: Any)
 94    def __init__(self, **args: t.Any):
 95        self.args: t.Dict[str, t.Any] = args
 96        self.parent: t.Optional[Expression] = None
 97        self.arg_key: t.Optional[str] = None
 98        self.comments: t.Optional[t.List[str]] = None
 99        self._type: t.Optional[DataType] = None
100        self._meta: t.Optional[t.Dict[str, t.Any]] = None
101        self._hash: t.Optional[int] = None
102
103        for arg_key, value in self.args.items():
104            self._set_parent(arg_key, value)
key = 'expression'
arg_types = {'this': True}
args: Dict[str, Any]
parent: Optional[Expression]
arg_key: Optional[str]
comments: Optional[List[str]]
hashable_args: Any
this: Any

Retrieves the argument with key "this".

expression: Any

Retrieves the argument with key "expression".

expressions

Retrieves the argument with key "expressions".

def text(self, key) -> str:
144    def text(self, key) -> str:
145        """
146        Returns a textual representation of the argument corresponding to "key". This can only be used
147        for args that are strings or leaf Expression instances, such as identifiers and literals.
148        """
149        field = self.args.get(key)
150        if isinstance(field, str):
151            return field
152        if isinstance(field, (Identifier, Literal, Var)):
153            return field.this
154        if isinstance(field, (Star, Null)):
155            return field.name
156        return ""

Returns a textual representation of the argument corresponding to "key". This can only be used for args that are strings or leaf Expression instances, such as identifiers and literals.

is_string: bool

Checks whether a Literal expression is a string.

is_number: bool

Checks whether a Literal expression is a number.

is_int: bool

Checks whether a Literal expression is an integer.

is_star: bool

Checks whether an expression is a star.

alias: str

Returns the alias of the expression, or an empty string if it's not aliased.

alias_column_names: List[str]
name: str
alias_or_name: str
output_name: str

Name of the output column if this expression is a selection.

If the Expression has no output name, an empty string is returned.

Example:
>>> from sqlglot import parse_one
>>> parse_one("SELECT a")sqlglot.expressions[0].output_name
'a'
>>> parse_one("SELECT b AS c")sqlglot.expressions[0].output_name
'c'
>>> parse_one("SELECT 1 + 2")sqlglot.expressions[0].output_name
''
type: Optional[DataType]
meta: Dict[str, Any]
def copy(self):
261    def copy(self):
262        """
263        Returns a deep copy of the expression.
264        """
265        new = deepcopy(self)
266        new.parent = self.parent
267        return new

Returns a deep copy of the expression.

def add_comments(self, comments: Optional[List[str]]) -> None:
269    def add_comments(self, comments: t.Optional[t.List[str]]) -> None:
270        if self.comments is None:
271            self.comments = []
272        if comments:
273            for comment in comments:
274                _, *meta = comment.split(SQLGLOT_META)
275                if meta:
276                    for kv in "".join(meta).split(","):
277                        k, *v = kv.split("=")
278                        value = v[0].strip() if v else True
279                        self.meta[k.strip()] = value
280                self.comments.append(comment)
def append(self, arg_key: str, value: Any) -> None:
282    def append(self, arg_key: str, value: t.Any) -> None:
283        """
284        Appends value to arg_key if it's a list or sets it as a new list.
285
286        Args:
287            arg_key (str): name of the list expression arg
288            value (Any): value to append to the list
289        """
290        if not isinstance(self.args.get(arg_key), list):
291            self.args[arg_key] = []
292        self.args[arg_key].append(value)
293        self._set_parent(arg_key, value)

Appends value to arg_key if it's a list or sets it as a new list.

Arguments:
  • arg_key (str): name of the list expression arg
  • value (Any): value to append to the list
def set(self, arg_key: str, value: Any) -> None:
295    def set(self, arg_key: str, value: t.Any) -> None:
296        """
297        Sets arg_key to value.
298
299        Args:
300            arg_key: name of the expression arg.
301            value: value to set the arg to.
302        """
303        if value is None:
304            self.args.pop(arg_key, None)
305            return
306
307        self.args[arg_key] = value
308        self._set_parent(arg_key, value)

Sets arg_key to value.

Arguments:
  • arg_key: name of the expression arg.
  • value: value to set the arg to.
depth: int

Returns the depth of this tree.

def iter_expressions(self) -> Iterator[Tuple[str, Expression]]:
329    def iter_expressions(self) -> t.Iterator[t.Tuple[str, Expression]]:
330        """Yields the key and expression for all arguments, exploding list args."""
331        for k, vs in self.args.items():
332            if type(vs) is list:
333                for v in vs:
334                    if hasattr(v, "parent"):
335                        yield k, v
336            else:
337                if hasattr(vs, "parent"):
338                    yield k, vs

Yields the key and expression for all arguments, exploding list args.

def find(self, *expression_types: Type[~E], bfs: bool = True) -> Optional[~E]:
340    def find(self, *expression_types: t.Type[E], bfs: bool = True) -> t.Optional[E]:
341        """
342        Returns the first node in this tree which matches at least one of
343        the specified types.
344
345        Args:
346            expression_types: the expression type(s) to match.
347            bfs: whether to search the AST using the BFS algorithm (DFS is used if false).
348
349        Returns:
350            The node which matches the criteria or None if no such node was found.
351        """
352        return next(self.find_all(*expression_types, bfs=bfs), None)

Returns the first node in this tree which matches at least one of the specified types.

Arguments:
  • expression_types: the expression type(s) to match.
  • bfs: whether to search the AST using the BFS algorithm (DFS is used if false).
Returns:

The node which matches the criteria or None if no such node was found.

def find_all(self, *expression_types: Type[~E], bfs: bool = True) -> Iterator[~E]:
354    def find_all(self, *expression_types: t.Type[E], bfs: bool = True) -> t.Iterator[E]:
355        """
356        Returns a generator object which visits all nodes in this tree and only
357        yields those that match at least one of the specified expression types.
358
359        Args:
360            expression_types: the expression type(s) to match.
361            bfs: whether to search the AST using the BFS algorithm (DFS is used if false).
362
363        Returns:
364            The generator object.
365        """
366        for expression, *_ in self.walk(bfs=bfs):
367            if isinstance(expression, expression_types):
368                yield expression

Returns a generator object which visits all nodes in this tree and only yields those that match at least one of the specified expression types.

Arguments:
  • expression_types: the expression type(s) to match.
  • bfs: whether to search the AST using the BFS algorithm (DFS is used if false).
Returns:

The generator object.

def find_ancestor(self, *expression_types: Type[~E]) -> Optional[~E]:
370    def find_ancestor(self, *expression_types: t.Type[E]) -> t.Optional[E]:
371        """
372        Returns a nearest parent matching expression_types.
373
374        Args:
375            expression_types: the expression type(s) to match.
376
377        Returns:
378            The parent node.
379        """
380        ancestor = self.parent
381        while ancestor and not isinstance(ancestor, expression_types):
382            ancestor = ancestor.parent
383        return t.cast(E, ancestor)

Returns a nearest parent matching expression_types.

Arguments:
  • expression_types: the expression type(s) to match.
Returns:

The parent node.

parent_select: Optional[Select]

Returns the parent select statement.

same_parent: bool

Returns if the parent is the same class as itself.

def root(self) -> Expression:
397    def root(self) -> Expression:
398        """
399        Returns the root expression of this tree.
400        """
401        expression = self
402        while expression.parent:
403            expression = expression.parent
404        return expression

Returns the root expression of this tree.

def walk(self, bfs=True, prune=None):
406    def walk(self, bfs=True, prune=None):
407        """
408        Returns a generator object which visits all nodes in this tree.
409
410        Args:
411            bfs (bool): if set to True the BFS traversal order will be applied,
412                otherwise the DFS traversal will be used instead.
413            prune ((node, parent, arg_key) -> bool): callable that returns True if
414                the generator should stop traversing this branch of the tree.
415
416        Returns:
417            the generator object.
418        """
419        if bfs:
420            yield from self.bfs(prune=prune)
421        else:
422            yield from self.dfs(prune=prune)

Returns a generator object which visits all nodes in this tree.

Arguments:
  • bfs (bool): if set to True the BFS traversal order will be applied, otherwise the DFS traversal will be used instead.
  • prune ((node, parent, arg_key) -> bool): callable that returns True if the generator should stop traversing this branch of the tree.
Returns:

the generator object.

def dfs(self, parent=None, key=None, prune=None):
424    def dfs(self, parent=None, key=None, prune=None):
425        """
426        Returns a generator object which visits all nodes in this tree in
427        the DFS (Depth-first) order.
428
429        Returns:
430            The generator object.
431        """
432        parent = parent or self.parent
433        yield self, parent, key
434        if prune and prune(self, parent, key):
435            return
436
437        for k, v in self.iter_expressions():
438            yield from v.dfs(self, k, prune)

Returns a generator object which visits all nodes in this tree in the DFS (Depth-first) order.

Returns:

The generator object.

def bfs(self, prune=None):
440    def bfs(self, prune=None):
441        """
442        Returns a generator object which visits all nodes in this tree in
443        the BFS (Breadth-first) order.
444
445        Returns:
446            The generator object.
447        """
448        queue = deque([(self, self.parent, None)])
449
450        while queue:
451            item, parent, key = queue.popleft()
452
453            yield item, parent, key
454            if prune and prune(item, parent, key):
455                continue
456
457            for k, v in item.iter_expressions():
458                queue.append((v, item, k))

Returns a generator object which visits all nodes in this tree in the BFS (Breadth-first) order.

Returns:

The generator object.

def unnest(self):
460    def unnest(self):
461        """
462        Returns the first non parenthesis child or self.
463        """
464        expression = self
465        while type(expression) is Paren:
466            expression = expression.this
467        return expression

Returns the first non parenthesis child or self.

def unalias(self):
469    def unalias(self):
470        """
471        Returns the inner expression if this is an Alias.
472        """
473        if isinstance(self, Alias):
474            return self.this
475        return self

Returns the inner expression if this is an Alias.

def unnest_operands(self):
477    def unnest_operands(self):
478        """
479        Returns unnested operands as a tuple.
480        """
481        return tuple(arg.unnest() for _, arg in self.iter_expressions())

Returns unnested operands as a tuple.

def flatten(self, unnest=True):
483    def flatten(self, unnest=True):
484        """
485        Returns a generator which yields child nodes who's parents are the same class.
486
487        A AND B AND C -> [A, B, C]
488        """
489        for node, _, _ in self.dfs(prune=lambda n, p, *_: p and not type(n) is self.__class__):
490            if not type(node) is self.__class__:
491                yield node.unnest() if unnest and not isinstance(node, Subquery) else node

Returns a generator which yields child nodes who's parents are the same class.

A AND B AND C -> [A, B, C]

def sql( self, dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, **opts) -> str:
499    def sql(self, dialect: DialectType = None, **opts) -> str:
500        """
501        Returns SQL string representation of this tree.
502
503        Args:
504            dialect: the dialect of the output SQL string (eg. "spark", "hive", "presto", "mysql").
505            opts: other `sqlglot.generator.Generator` options.
506
507        Returns:
508            The SQL string.
509        """
510        from sqlglot.dialects import Dialect
511
512        return Dialect.get_or_raise(dialect)().generate(self, **opts)

Returns SQL string representation of this tree.

Arguments:
  • dialect: the dialect of the output SQL string (eg. "spark", "hive", "presto", "mysql").
  • opts: other sqlglot.generator.Generator options.
Returns:

The SQL string.

def transform(self, fun, *args, copy=True, **kwargs):
538    def transform(self, fun, *args, copy=True, **kwargs):
539        """
540        Recursively visits all tree nodes (excluding already transformed ones)
541        and applies the given transformation function to each node.
542
543        Args:
544            fun (function): a function which takes a node as an argument and returns a
545                new transformed node or the same node without modifications. If the function
546                returns None, then the corresponding node will be removed from the syntax tree.
547            copy (bool): if set to True a new tree instance is constructed, otherwise the tree is
548                modified in place.
549
550        Returns:
551            The transformed tree.
552        """
553        node = self.copy() if copy else self
554        new_node = fun(node, *args, **kwargs)
555
556        if new_node is None or not isinstance(new_node, Expression):
557            return new_node
558        if new_node is not node:
559            new_node.parent = node.parent
560            return new_node
561
562        replace_children(new_node, lambda child: child.transform(fun, *args, copy=False, **kwargs))
563        return new_node

Recursively visits all tree nodes (excluding already transformed ones) and applies the given transformation function to each node.

Arguments:
  • fun (function): a function which takes a node as an argument and returns a new transformed node or the same node without modifications. If the function returns None, then the corresponding node will be removed from the syntax tree.
  • copy (bool): if set to True a new tree instance is constructed, otherwise the tree is modified in place.
Returns:

The transformed tree.

def replace(self, expression):
573    def replace(self, expression):
574        """
575        Swap out this expression with a new expression.
576
577        For example::
578
579            >>> tree = Select().select("x").from_("tbl")
580            >>> tree.find(Column).replace(Column(this="y"))
581            (COLUMN this: y)
582            >>> tree.sql()
583            'SELECT y FROM tbl'
584
585        Args:
586            expression: new node
587
588        Returns:
589            The new expression or expressions.
590        """
591        if not self.parent:
592            return expression
593
594        parent = self.parent
595        self.parent = None
596
597        replace_children(parent, lambda child: expression if child is self else child)
598        return expression

Swap out this expression with a new expression.

For example::

>>> tree = Select().select("x").from_("tbl")
>>> tree.find(Column).replace(Column(this="y"))
(COLUMN this: y)
>>> tree.sql()
'SELECT y FROM tbl'
Arguments:
  • expression: new node
Returns:

The new expression or expressions.

def pop(self: ~E) -> ~E:
600    def pop(self: E) -> E:
601        """
602        Remove this expression from its AST.
603
604        Returns:
605            The popped expression.
606        """
607        self.replace(None)
608        return self

Remove this expression from its AST.

Returns:

The popped expression.

def assert_is(self, type_: Type[~E]) -> ~E:
610    def assert_is(self, type_: t.Type[E]) -> E:
611        """
612        Assert that this `Expression` is an instance of `type_`.
613
614        If it is NOT an instance of `type_`, this raises an assertion error.
615        Otherwise, this returns this expression.
616
617        Examples:
618            This is useful for type security in chained expressions:
619
620            >>> import sqlglot
621            >>> sqlglot.parse_one("SELECT x from y").assert_is(Select).select("z").sql()
622            'SELECT x, z FROM y'
623        """
624        assert isinstance(self, type_)
625        return self

Assert that this Expression is an instance of type_.

If it is NOT an instance of type_, this raises an assertion error. Otherwise, this returns this expression.

Examples:

This is useful for type security in chained expressions:

>>> import sqlglot
>>> sqlglot.parse_one("SELECT x from y").assert_is(Select).select("z").sql()
'SELECT x, z FROM y'
def error_messages(self, args: Optional[Sequence] = None) -> List[str]:
627    def error_messages(self, args: t.Optional[t.Sequence] = None) -> t.List[str]:
628        """
629        Checks if this expression is valid (e.g. all mandatory args are set).
630
631        Args:
632            args: a sequence of values that were used to instantiate a Func expression. This is used
633                to check that the provided arguments don't exceed the function argument limit.
634
635        Returns:
636            A list of error messages for all possible errors that were found.
637        """
638        errors: t.List[str] = []
639
640        for k in self.args:
641            if k not in self.arg_types:
642                errors.append(f"Unexpected keyword: '{k}' for {self.__class__}")
643        for k, mandatory in self.arg_types.items():
644            v = self.args.get(k)
645            if mandatory and (v is None or (isinstance(v, list) and not v)):
646                errors.append(f"Required keyword: '{k}' missing for {self.__class__}")
647
648        if (
649            args
650            and isinstance(self, Func)
651            and len(args) > len(self.arg_types)
652            and not self.is_var_len_args
653        ):
654            errors.append(
655                f"The number of provided arguments ({len(args)}) is greater than "
656                f"the maximum number of supported arguments ({len(self.arg_types)})"
657            )
658
659        return errors

Checks if this expression is valid (e.g. all mandatory args are set).

Arguments:
  • args: a sequence of values that were used to instantiate a Func expression. This is used to check that the provided arguments don't exceed the function argument limit.
Returns:

A list of error messages for all possible errors that were found.

def dump(self):
661    def dump(self):
662        """
663        Dump this Expression to a JSON-serializable dict.
664        """
665        from sqlglot.serde import dump
666
667        return dump(self)

Dump this Expression to a JSON-serializable dict.

@classmethod
def load(cls, obj):
669    @classmethod
670    def load(cls, obj):
671        """
672        Load a dict (as returned by `Expression.dump`) into an Expression instance.
673        """
674        from sqlglot.serde import load
675
676        return load(obj)

Load a dict (as returned by Expression.dump) into an Expression instance.

def and_( self, *expressions: Union[str, Expression, NoneType], dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, copy: bool = True, **opts) -> Condition:
678    def and_(
679        self,
680        *expressions: t.Optional[ExpOrStr],
681        dialect: DialectType = None,
682        copy: bool = True,
683        **opts,
684    ) -> Condition:
685        """
686        AND this condition with one or multiple expressions.
687
688        Example:
689            >>> condition("x=1").and_("y=1").sql()
690            'x = 1 AND y = 1'
691
692        Args:
693            *expressions: the SQL code strings to parse.
694                If an `Expression` instance is passed, it will be used as-is.
695            dialect: the dialect used to parse the input expression.
696            copy: whether or not to copy the involved expressions (only applies to Expressions).
697            opts: other options to use to parse the input expressions.
698
699        Returns:
700            The new And condition.
701        """
702        return and_(self, *expressions, dialect=dialect, copy=copy, **opts)

AND this condition with one or multiple expressions.

Example:
>>> condition("x=1").and_("y=1").sql()
'x = 1 AND y = 1'
Arguments:
  • *expressions: the SQL code strings to parse. If an Expression instance is passed, it will be used as-is.
  • dialect: the dialect used to parse the input expression.
  • copy: whether or not to copy the involved expressions (only applies to Expressions).
  • opts: other options to use to parse the input expressions.
Returns:

The new And condition.

def or_( self, *expressions: Union[str, Expression, NoneType], dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, copy: bool = True, **opts) -> Condition:
704    def or_(
705        self,
706        *expressions: t.Optional[ExpOrStr],
707        dialect: DialectType = None,
708        copy: bool = True,
709        **opts,
710    ) -> Condition:
711        """
712        OR this condition with one or multiple expressions.
713
714        Example:
715            >>> condition("x=1").or_("y=1").sql()
716            'x = 1 OR y = 1'
717
718        Args:
719            *expressions: the SQL code strings to parse.
720                If an `Expression` instance is passed, it will be used as-is.
721            dialect: the dialect used to parse the input expression.
722            copy: whether or not to copy the involved expressions (only applies to Expressions).
723            opts: other options to use to parse the input expressions.
724
725        Returns:
726            The new Or condition.
727        """
728        return or_(self, *expressions, dialect=dialect, copy=copy, **opts)

OR this condition with one or multiple expressions.

Example:
>>> condition("x=1").or_("y=1").sql()
'x = 1 OR y = 1'
Arguments:
  • *expressions: the SQL code strings to parse. If an Expression instance is passed, it will be used as-is.
  • dialect: the dialect used to parse the input expression.
  • copy: whether or not to copy the involved expressions (only applies to Expressions).
  • opts: other options to use to parse the input expressions.
Returns:

The new Or condition.

def not_(self, copy: bool = True):
730    def not_(self, copy: bool = True):
731        """
732        Wrap this condition with NOT.
733
734        Example:
735            >>> condition("x=1").not_().sql()
736            'NOT x = 1'
737
738        Args:
739            copy: whether or not to copy this object.
740
741        Returns:
742            The new Not instance.
743        """
744        return not_(self, copy=copy)

Wrap this condition with NOT.

Example:
>>> condition("x=1").not_().sql()
'NOT x = 1'
Arguments:
  • copy: whether or not to copy this object.
Returns:

The new Not instance.

def as_( self, alias: str | Identifier, quoted: Optional[bool] = None, dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, copy: bool = True, **opts) -> Alias:
746    def as_(
747        self,
748        alias: str | Identifier,
749        quoted: t.Optional[bool] = None,
750        dialect: DialectType = None,
751        copy: bool = True,
752        **opts,
753    ) -> Alias:
754        return alias_(self, alias, quoted=quoted, dialect=dialect, copy=copy, **opts)
def isin( self, *expressions: Any, query: Union[str, Expression, NoneType] = None, unnest: Union[str, Expression, NoneType, Collection[Union[str, Expression]]] = None, copy: bool = True, **opts) -> In:
779    def isin(
780        self,
781        *expressions: t.Any,
782        query: t.Optional[ExpOrStr] = None,
783        unnest: t.Optional[ExpOrStr] | t.Collection[ExpOrStr] = None,
784        copy: bool = True,
785        **opts,
786    ) -> In:
787        return In(
788            this=maybe_copy(self, copy),
789            expressions=[convert(e, copy=copy) for e in expressions],
790            query=maybe_parse(query, copy=copy, **opts) if query else None,
791            unnest=Unnest(
792                expressions=[
793                    maybe_parse(t.cast(ExpOrStr, e), copy=copy, **opts) for e in ensure_list(unnest)
794                ]
795            )
796            if unnest
797            else None,
798        )
def between( self, low: Any, high: Any, copy: bool = True, **opts) -> Between:
800    def between(self, low: t.Any, high: t.Any, copy: bool = True, **opts) -> Between:
801        return Between(
802            this=maybe_copy(self, copy),
803            low=convert(low, copy=copy, **opts),
804            high=convert(high, copy=copy, **opts),
805        )
def is_( self, other: Union[str, Expression]) -> Is:
807    def is_(self, other: ExpOrStr) -> Is:
808        return self._binop(Is, other)
def like( self, other: Union[str, Expression]) -> Like:
810    def like(self, other: ExpOrStr) -> Like:
811        return self._binop(Like, other)
def ilike( self, other: Union[str, Expression]) -> ILike:
813    def ilike(self, other: ExpOrStr) -> ILike:
814        return self._binop(ILike, other)
def eq(self, other: Any) -> EQ:
816    def eq(self, other: t.Any) -> EQ:
817        return self._binop(EQ, other)
def neq(self, other: Any) -> NEQ:
819    def neq(self, other: t.Any) -> NEQ:
820        return self._binop(NEQ, other)
def rlike( self, other: Union[str, Expression]) -> RegexpLike:
822    def rlike(self, other: ExpOrStr) -> RegexpLike:
823        return self._binop(RegexpLike, other)
IntoType = typing.Union[str, typing.Type[Expression], typing.Collection[typing.Union[str, typing.Type[Expression]]]]
ExpOrStr = typing.Union[str, Expression]
class Condition(Expression):
906class Condition(Expression):
907    """Logical conditions like x AND y, or simply x"""

Logical conditions like x AND y, or simply x

key = 'condition'
class Predicate(Condition):
910class Predicate(Condition):
911    """Relationships like x = y, x > 1, x >= y."""

Relationships like x = y, x > 1, x >= y.

key = 'predicate'
class DerivedTable(Expression):
914class DerivedTable(Expression):
915    @property
916    def selects(self) -> t.List[Expression]:
917        return self.this.selects if isinstance(self.this, Subqueryable) else []
918
919    @property
920    def named_selects(self) -> t.List[str]:
921        return [select.output_name for select in self.selects]
selects: List[Expression]
named_selects: List[str]
key = 'derivedtable'
class Unionable(Expression):
924class Unionable(Expression):
925    def union(
926        self, expression: ExpOrStr, distinct: bool = True, dialect: DialectType = None, **opts
927    ) -> Unionable:
928        """
929        Builds a UNION expression.
930
931        Example:
932            >>> import sqlglot
933            >>> sqlglot.parse_one("SELECT * FROM foo").union("SELECT * FROM bla").sql()
934            'SELECT * FROM foo UNION SELECT * FROM bla'
935
936        Args:
937            expression: the SQL code string.
938                If an `Expression` instance is passed, it will be used as-is.
939            distinct: set the DISTINCT flag if and only if this is true.
940            dialect: the dialect used to parse the input expression.
941            opts: other options to use to parse the input expressions.
942
943        Returns:
944            The new Union expression.
945        """
946        return union(left=self, right=expression, distinct=distinct, dialect=dialect, **opts)
947
948    def intersect(
949        self, expression: ExpOrStr, distinct: bool = True, dialect: DialectType = None, **opts
950    ) -> Unionable:
951        """
952        Builds an INTERSECT expression.
953
954        Example:
955            >>> import sqlglot
956            >>> sqlglot.parse_one("SELECT * FROM foo").intersect("SELECT * FROM bla").sql()
957            'SELECT * FROM foo INTERSECT SELECT * FROM bla'
958
959        Args:
960            expression: the SQL code string.
961                If an `Expression` instance is passed, it will be used as-is.
962            distinct: set the DISTINCT flag if and only if this is true.
963            dialect: the dialect used to parse the input expression.
964            opts: other options to use to parse the input expressions.
965
966        Returns:
967            The new Intersect expression.
968        """
969        return intersect(left=self, right=expression, distinct=distinct, dialect=dialect, **opts)
970
971    def except_(
972        self, expression: ExpOrStr, distinct: bool = True, dialect: DialectType = None, **opts
973    ) -> Unionable:
974        """
975        Builds an EXCEPT expression.
976
977        Example:
978            >>> import sqlglot
979            >>> sqlglot.parse_one("SELECT * FROM foo").except_("SELECT * FROM bla").sql()
980            'SELECT * FROM foo EXCEPT SELECT * FROM bla'
981
982        Args:
983            expression: the SQL code string.
984                If an `Expression` instance is passed, it will be used as-is.
985            distinct: set the DISTINCT flag if and only if this is true.
986            dialect: the dialect used to parse the input expression.
987            opts: other options to use to parse the input expressions.
988
989        Returns:
990            The new Except expression.
991        """
992        return except_(left=self, right=expression, distinct=distinct, dialect=dialect, **opts)
def union( self, expression: Union[str, Expression], distinct: bool = True, dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, **opts) -> Unionable:
925    def union(
926        self, expression: ExpOrStr, distinct: bool = True, dialect: DialectType = None, **opts
927    ) -> Unionable:
928        """
929        Builds a UNION expression.
930
931        Example:
932            >>> import sqlglot
933            >>> sqlglot.parse_one("SELECT * FROM foo").union("SELECT * FROM bla").sql()
934            'SELECT * FROM foo UNION SELECT * FROM bla'
935
936        Args:
937            expression: the SQL code string.
938                If an `Expression` instance is passed, it will be used as-is.
939            distinct: set the DISTINCT flag if and only if this is true.
940            dialect: the dialect used to parse the input expression.
941            opts: other options to use to parse the input expressions.
942
943        Returns:
944            The new Union expression.
945        """
946        return union(left=self, right=expression, distinct=distinct, dialect=dialect, **opts)

Builds a UNION expression.

Example:
>>> import sqlglot
>>> sqlglot.parse_one("SELECT * FROM foo").union("SELECT * FROM bla").sql()
'SELECT * FROM foo UNION SELECT * FROM bla'
Arguments:
  • expression: the SQL code string. If an Expression instance is passed, it will be used as-is.
  • distinct: set the DISTINCT flag if and only if this is true.
  • dialect: the dialect used to parse the input expression.
  • opts: other options to use to parse the input expressions.
Returns:

The new Union expression.

def intersect( self, expression: Union[str, Expression], distinct: bool = True, dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, **opts) -> Unionable:
948    def intersect(
949        self, expression: ExpOrStr, distinct: bool = True, dialect: DialectType = None, **opts
950    ) -> Unionable:
951        """
952        Builds an INTERSECT expression.
953
954        Example:
955            >>> import sqlglot
956            >>> sqlglot.parse_one("SELECT * FROM foo").intersect("SELECT * FROM bla").sql()
957            'SELECT * FROM foo INTERSECT SELECT * FROM bla'
958
959        Args:
960            expression: the SQL code string.
961                If an `Expression` instance is passed, it will be used as-is.
962            distinct: set the DISTINCT flag if and only if this is true.
963            dialect: the dialect used to parse the input expression.
964            opts: other options to use to parse the input expressions.
965
966        Returns:
967            The new Intersect expression.
968        """
969        return intersect(left=self, right=expression, distinct=distinct, dialect=dialect, **opts)

Builds an INTERSECT expression.

Example:
>>> import sqlglot
>>> sqlglot.parse_one("SELECT * FROM foo").intersect("SELECT * FROM bla").sql()
'SELECT * FROM foo INTERSECT SELECT * FROM bla'
Arguments:
  • expression: the SQL code string. If an Expression instance is passed, it will be used as-is.
  • distinct: set the DISTINCT flag if and only if this is true.
  • dialect: the dialect used to parse the input expression.
  • opts: other options to use to parse the input expressions.
Returns:

The new Intersect expression.

def except_( self, expression: Union[str, Expression], distinct: bool = True, dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, **opts) -> Unionable:
971    def except_(
972        self, expression: ExpOrStr, distinct: bool = True, dialect: DialectType = None, **opts
973    ) -> Unionable:
974        """
975        Builds an EXCEPT expression.
976
977        Example:
978            >>> import sqlglot
979            >>> sqlglot.parse_one("SELECT * FROM foo").except_("SELECT * FROM bla").sql()
980            'SELECT * FROM foo EXCEPT SELECT * FROM bla'
981
982        Args:
983            expression: the SQL code string.
984                If an `Expression` instance is passed, it will be used as-is.
985            distinct: set the DISTINCT flag if and only if this is true.
986            dialect: the dialect used to parse the input expression.
987            opts: other options to use to parse the input expressions.
988
989        Returns:
990            The new Except expression.
991        """
992        return except_(left=self, right=expression, distinct=distinct, dialect=dialect, **opts)

Builds an EXCEPT expression.

Example:
>>> import sqlglot
>>> sqlglot.parse_one("SELECT * FROM foo").except_("SELECT * FROM bla").sql()
'SELECT * FROM foo EXCEPT SELECT * FROM bla'
Arguments:
  • expression: the SQL code string. If an Expression instance is passed, it will be used as-is.
  • distinct: set the DISTINCT flag if and only if this is true.
  • dialect: the dialect used to parse the input expression.
  • opts: other options to use to parse the input expressions.
Returns:

The new Except expression.

key = 'unionable'
class UDTF(DerivedTable, Unionable):
995class UDTF(DerivedTable, Unionable):
996    @property
997    def selects(self) -> t.List[Expression]:
998        alias = self.args.get("alias")
999        return alias.columns if alias else []
selects: List[Expression]
key = 'udtf'
class Cache(Expression):
1002class Cache(Expression):
1003    arg_types = {
1004        "with": False,
1005        "this": True,
1006        "lazy": False,
1007        "options": False,
1008        "expression": False,
1009    }
arg_types = {'with': False, 'this': True, 'lazy': False, 'options': False, 'expression': False}
key = 'cache'
class Uncache(Expression):
1012class Uncache(Expression):
1013    arg_types = {"this": True, "exists": False}
arg_types = {'this': True, 'exists': False}
key = 'uncache'
class DDL(Expression):
1016class DDL(Expression):
1017    @property
1018    def ctes(self):
1019        with_ = self.args.get("with")
1020        if not with_:
1021            return []
1022        return with_.expressions
1023
1024    @property
1025    def named_selects(self) -> t.List[str]:
1026        if isinstance(self.expression, Subqueryable):
1027            return self.expression.named_selects
1028        return []
1029
1030    @property
1031    def selects(self) -> t.List[Expression]:
1032        if isinstance(self.expression, Subqueryable):
1033            return self.expression.selects
1034        return []
ctes
named_selects: List[str]
selects: List[Expression]
key = 'ddl'
class Create(DDL):
1037class Create(DDL):
1038    arg_types = {
1039        "with": False,
1040        "this": True,
1041        "kind": True,
1042        "expression": False,
1043        "exists": False,
1044        "properties": False,
1045        "replace": False,
1046        "unique": False,
1047        "indexes": False,
1048        "no_schema_binding": False,
1049        "begin": False,
1050        "end": False,
1051        "clone": False,
1052    }
arg_types = {'with': False, 'this': True, 'kind': True, 'expression': False, 'exists': False, 'properties': False, 'replace': False, 'unique': False, 'indexes': False, 'no_schema_binding': False, 'begin': False, 'end': False, 'clone': False}
key = 'create'
class Clone(Expression):
1058class Clone(Expression):
1059    arg_types = {
1060        "this": True,
1061        "when": False,
1062        "kind": False,
1063        "shallow": False,
1064        "expression": False,
1065        "copy": False,
1066    }
arg_types = {'this': True, 'when': False, 'kind': False, 'shallow': False, 'expression': False, 'copy': False}
key = 'clone'
class Describe(Expression):
1069class Describe(Expression):
1070    arg_types = {"this": True, "kind": False, "expressions": False}
arg_types = {'this': True, 'kind': False, 'expressions': False}
key = 'describe'
class Kill(Expression):
1073class Kill(Expression):
1074    arg_types = {"this": True, "kind": False}
arg_types = {'this': True, 'kind': False}
key = 'kill'
class Pragma(Expression):
1077class Pragma(Expression):
1078    pass
key = 'pragma'
class Set(Expression):
1081class Set(Expression):
1082    arg_types = {"expressions": False, "unset": False, "tag": False}
arg_types = {'expressions': False, 'unset': False, 'tag': False}
key = 'set'
class SetItem(Expression):
1085class SetItem(Expression):
1086    arg_types = {
1087        "this": False,
1088        "expressions": False,
1089        "kind": False,
1090        "collate": False,  # MySQL SET NAMES statement
1091        "global": False,
1092    }
arg_types = {'this': False, 'expressions': False, 'kind': False, 'collate': False, 'global': False}
key = 'setitem'
class Show(Expression):
1095class Show(Expression):
1096    arg_types = {
1097        "this": True,
1098        "target": False,
1099        "offset": False,
1100        "limit": False,
1101        "like": False,
1102        "where": False,
1103        "db": False,
1104        "scope": False,
1105        "scope_kind": False,
1106        "full": False,
1107        "mutex": False,
1108        "query": False,
1109        "channel": False,
1110        "global": False,
1111        "log": False,
1112        "position": False,
1113        "types": False,
1114    }
arg_types = {'this': True, 'target': False, 'offset': False, 'limit': False, 'like': False, 'where': False, 'db': False, 'scope': False, 'scope_kind': False, 'full': False, 'mutex': False, 'query': False, 'channel': False, 'global': False, 'log': False, 'position': False, 'types': False}
key = 'show'
class UserDefinedFunction(Expression):
1117class UserDefinedFunction(Expression):
1118    arg_types = {"this": True, "expressions": False, "wrapped": False}
arg_types = {'this': True, 'expressions': False, 'wrapped': False}
key = 'userdefinedfunction'
class CharacterSet(Expression):
1121class CharacterSet(Expression):
1122    arg_types = {"this": True, "default": False}
arg_types = {'this': True, 'default': False}
key = 'characterset'
class With(Expression):
1125class With(Expression):
1126    arg_types = {"expressions": True, "recursive": False}
1127
1128    @property
1129    def recursive(self) -> bool:
1130        return bool(self.args.get("recursive"))
arg_types = {'expressions': True, 'recursive': False}
recursive: bool
key = 'with'
class WithinGroup(Expression):
1133class WithinGroup(Expression):
1134    arg_types = {"this": True, "expression": False}
arg_types = {'this': True, 'expression': False}
key = 'withingroup'
class CTE(DerivedTable):
1137class CTE(DerivedTable):
1138    arg_types = {"this": True, "alias": True}
arg_types = {'this': True, 'alias': True}
key = 'cte'
class TableAlias(Expression):
1141class TableAlias(Expression):
1142    arg_types = {"this": False, "columns": False}
1143
1144    @property
1145    def columns(self):
1146        return self.args.get("columns") or []
arg_types = {'this': False, 'columns': False}
columns
key = 'tablealias'
class BitString(Condition):
1149class BitString(Condition):
1150    pass
key = 'bitstring'
class HexString(Condition):
1153class HexString(Condition):
1154    pass
key = 'hexstring'
class ByteString(Condition):
1157class ByteString(Condition):
1158    pass
key = 'bytestring'
class RawString(Condition):
1161class RawString(Condition):
1162    pass
key = 'rawstring'
class Column(Condition):
1165class Column(Condition):
1166    arg_types = {"this": True, "table": False, "db": False, "catalog": False, "join_mark": False}
1167
1168    @property
1169    def table(self) -> str:
1170        return self.text("table")
1171
1172    @property
1173    def db(self) -> str:
1174        return self.text("db")
1175
1176    @property
1177    def catalog(self) -> str:
1178        return self.text("catalog")
1179
1180    @property
1181    def output_name(self) -> str:
1182        return self.name
1183
1184    @property
1185    def parts(self) -> t.List[Identifier]:
1186        """Return the parts of a column in order catalog, db, table, name."""
1187        return [
1188            t.cast(Identifier, self.args[part])
1189            for part in ("catalog", "db", "table", "this")
1190            if self.args.get(part)
1191        ]
1192
1193    def to_dot(self) -> Dot | Identifier:
1194        """Converts the column into a dot expression."""
1195        parts = self.parts
1196        parent = self.parent
1197
1198        while parent:
1199            if isinstance(parent, Dot):
1200                parts.append(parent.expression)
1201            parent = parent.parent
1202
1203        return Dot.build(deepcopy(parts)) if len(parts) > 1 else parts[0]
arg_types = {'this': True, 'table': False, 'db': False, 'catalog': False, 'join_mark': False}
table: str
db: str
catalog: str
output_name: str

Name of the output column if this expression is a selection.

If the Expression has no output name, an empty string is returned.

Example:
>>> from sqlglot import parse_one
>>> parse_one("SELECT a")sqlglot.expressions[0].output_name
'a'
>>> parse_one("SELECT b AS c")sqlglot.expressions[0].output_name
'c'
>>> parse_one("SELECT 1 + 2")sqlglot.expressions[0].output_name
''
parts: List[Identifier]

Return the parts of a column in order catalog, db, table, name.

def to_dot(self) -> Dot | Identifier:
1193    def to_dot(self) -> Dot | Identifier:
1194        """Converts the column into a dot expression."""
1195        parts = self.parts
1196        parent = self.parent
1197
1198        while parent:
1199            if isinstance(parent, Dot):
1200                parts.append(parent.expression)
1201            parent = parent.parent
1202
1203        return Dot.build(deepcopy(parts)) if len(parts) > 1 else parts[0]

Converts the column into a dot expression.

key = 'column'
class ColumnPosition(Expression):
1206class ColumnPosition(Expression):
1207    arg_types = {"this": False, "position": True}
arg_types = {'this': False, 'position': True}
key = 'columnposition'
class ColumnDef(Expression):
1210class ColumnDef(Expression):
1211    arg_types = {
1212        "this": True,
1213        "kind": False,
1214        "constraints": False,
1215        "exists": False,
1216        "position": False,
1217    }
1218
1219    @property
1220    def constraints(self) -> t.List[ColumnConstraint]:
1221        return self.args.get("constraints") or []
arg_types = {'this': True, 'kind': False, 'constraints': False, 'exists': False, 'position': False}
constraints: List[ColumnConstraint]
key = 'columndef'
class AlterColumn(Expression):
1224class AlterColumn(Expression):
1225    arg_types = {
1226        "this": True,
1227        "dtype": False,
1228        "collate": False,
1229        "using": False,
1230        "default": False,
1231        "drop": False,
1232    }
arg_types = {'this': True, 'dtype': False, 'collate': False, 'using': False, 'default': False, 'drop': False}
key = 'altercolumn'
class RenameTable(Expression):
1235class RenameTable(Expression):
1236    pass
key = 'renametable'
class Comment(Expression):
1239class Comment(Expression):
1240    arg_types = {"this": True, "kind": True, "expression": True, "exists": False}
arg_types = {'this': True, 'kind': True, 'expression': True, 'exists': False}
key = 'comment'
class Comprehension(Expression):
1243class Comprehension(Expression):
1244    arg_types = {"this": True, "expression": True, "iterator": True, "condition": False}
arg_types = {'this': True, 'expression': True, 'iterator': True, 'condition': False}
key = 'comprehension'
class MergeTreeTTLAction(Expression):
1248class MergeTreeTTLAction(Expression):
1249    arg_types = {
1250        "this": True,
1251        "delete": False,
1252        "recompress": False,
1253        "to_disk": False,
1254        "to_volume": False,
1255    }
arg_types = {'this': True, 'delete': False, 'recompress': False, 'to_disk': False, 'to_volume': False}
key = 'mergetreettlaction'
class MergeTreeTTL(Expression):
1259class MergeTreeTTL(Expression):
1260    arg_types = {
1261        "expressions": True,
1262        "where": False,
1263        "group": False,
1264        "aggregates": False,
1265    }
arg_types = {'expressions': True, 'where': False, 'group': False, 'aggregates': False}
key = 'mergetreettl'
class IndexConstraintOption(Expression):
1269class IndexConstraintOption(Expression):
1270    arg_types = {
1271        "key_block_size": False,
1272        "using": False,
1273        "parser": False,
1274        "comment": False,
1275        "visible": False,
1276        "engine_attr": False,
1277        "secondary_engine_attr": False,
1278    }
arg_types = {'key_block_size': False, 'using': False, 'parser': False, 'comment': False, 'visible': False, 'engine_attr': False, 'secondary_engine_attr': False}
key = 'indexconstraintoption'
class ColumnConstraint(Expression):
1281class ColumnConstraint(Expression):
1282    arg_types = {"this": False, "kind": True}
1283
1284    @property
1285    def kind(self) -> ColumnConstraintKind:
1286        return self.args["kind"]
arg_types = {'this': False, 'kind': True}
key = 'columnconstraint'
class ColumnConstraintKind(Expression):
1289class ColumnConstraintKind(Expression):
1290    pass
key = 'columnconstraintkind'
class AutoIncrementColumnConstraint(ColumnConstraintKind):
1293class AutoIncrementColumnConstraint(ColumnConstraintKind):
1294    pass
key = 'autoincrementcolumnconstraint'
class CaseSpecificColumnConstraint(ColumnConstraintKind):
1297class CaseSpecificColumnConstraint(ColumnConstraintKind):
1298    arg_types = {"not_": True}
arg_types = {'not_': True}
key = 'casespecificcolumnconstraint'
class CharacterSetColumnConstraint(ColumnConstraintKind):
1301class CharacterSetColumnConstraint(ColumnConstraintKind):
1302    arg_types = {"this": True}
arg_types = {'this': True}
key = 'charactersetcolumnconstraint'
class CheckColumnConstraint(ColumnConstraintKind):
1305class CheckColumnConstraint(ColumnConstraintKind):
1306    pass
key = 'checkcolumnconstraint'
class ClusteredColumnConstraint(ColumnConstraintKind):
1309class ClusteredColumnConstraint(ColumnConstraintKind):
1310    pass
key = 'clusteredcolumnconstraint'
class CollateColumnConstraint(ColumnConstraintKind):
1313class CollateColumnConstraint(ColumnConstraintKind):
1314    pass
key = 'collatecolumnconstraint'
class CommentColumnConstraint(ColumnConstraintKind):
1317class CommentColumnConstraint(ColumnConstraintKind):
1318    pass
key = 'commentcolumnconstraint'
class CompressColumnConstraint(ColumnConstraintKind):
1321class CompressColumnConstraint(ColumnConstraintKind):
1322    pass
key = 'compresscolumnconstraint'
class DateFormatColumnConstraint(ColumnConstraintKind):
1325class DateFormatColumnConstraint(ColumnConstraintKind):
1326    arg_types = {"this": True}
arg_types = {'this': True}
key = 'dateformatcolumnconstraint'
class DefaultColumnConstraint(ColumnConstraintKind):
1329class DefaultColumnConstraint(ColumnConstraintKind):
1330    pass
key = 'defaultcolumnconstraint'
class EncodeColumnConstraint(ColumnConstraintKind):
1333class EncodeColumnConstraint(ColumnConstraintKind):
1334    pass
key = 'encodecolumnconstraint'
class GeneratedAsIdentityColumnConstraint(ColumnConstraintKind):
1337class GeneratedAsIdentityColumnConstraint(ColumnConstraintKind):
1338    # this: True -> ALWAYS, this: False -> BY DEFAULT
1339    arg_types = {
1340        "this": False,
1341        "expression": False,
1342        "on_null": False,
1343        "start": False,
1344        "increment": False,
1345        "minvalue": False,
1346        "maxvalue": False,
1347        "cycle": False,
1348    }
arg_types = {'this': False, 'expression': False, 'on_null': False, 'start': False, 'increment': False, 'minvalue': False, 'maxvalue': False, 'cycle': False}
key = 'generatedasidentitycolumnconstraint'
class IndexColumnConstraint(ColumnConstraintKind):
1352class IndexColumnConstraint(ColumnConstraintKind):
1353    arg_types = {
1354        "this": False,
1355        "schema": True,
1356        "kind": False,
1357        "index_type": False,
1358        "options": False,
1359    }
arg_types = {'this': False, 'schema': True, 'kind': False, 'index_type': False, 'options': False}
key = 'indexcolumnconstraint'
class InlineLengthColumnConstraint(ColumnConstraintKind):
1362class InlineLengthColumnConstraint(ColumnConstraintKind):
1363    pass
key = 'inlinelengthcolumnconstraint'
class NonClusteredColumnConstraint(ColumnConstraintKind):
1366class NonClusteredColumnConstraint(ColumnConstraintKind):
1367    pass
key = 'nonclusteredcolumnconstraint'
class NotForReplicationColumnConstraint(ColumnConstraintKind):
1370class NotForReplicationColumnConstraint(ColumnConstraintKind):
1371    arg_types = {}
arg_types = {}
key = 'notforreplicationcolumnconstraint'
class NotNullColumnConstraint(ColumnConstraintKind):
1374class NotNullColumnConstraint(ColumnConstraintKind):
1375    arg_types = {"allow_null": False}
arg_types = {'allow_null': False}
key = 'notnullcolumnconstraint'
class OnUpdateColumnConstraint(ColumnConstraintKind):
1379class OnUpdateColumnConstraint(ColumnConstraintKind):
1380    pass
key = 'onupdatecolumnconstraint'
class PrimaryKeyColumnConstraint(ColumnConstraintKind):
1383class PrimaryKeyColumnConstraint(ColumnConstraintKind):
1384    arg_types = {"desc": False}
arg_types = {'desc': False}
key = 'primarykeycolumnconstraint'
class TitleColumnConstraint(ColumnConstraintKind):
1387class TitleColumnConstraint(ColumnConstraintKind):
1388    pass
key = 'titlecolumnconstraint'
class UniqueColumnConstraint(ColumnConstraintKind):
1391class UniqueColumnConstraint(ColumnConstraintKind):
1392    arg_types = {"this": False, "index_type": False}
arg_types = {'this': False, 'index_type': False}
key = 'uniquecolumnconstraint'
class UppercaseColumnConstraint(ColumnConstraintKind):
1395class UppercaseColumnConstraint(ColumnConstraintKind):
1396    arg_types: t.Dict[str, t.Any] = {}
arg_types: Dict[str, Any] = {}
key = 'uppercasecolumnconstraint'
class PathColumnConstraint(ColumnConstraintKind):
1399class PathColumnConstraint(ColumnConstraintKind):
1400    pass
key = 'pathcolumnconstraint'
class ComputedColumnConstraint(ColumnConstraintKind):
1405class ComputedColumnConstraint(ColumnConstraintKind):
1406    arg_types = {"this": True, "persisted": False, "not_null": False}
arg_types = {'this': True, 'persisted': False, 'not_null': False}
key = 'computedcolumnconstraint'
class Constraint(Expression):
1409class Constraint(Expression):
1410    arg_types = {"this": True, "expressions": True}
arg_types = {'this': True, 'expressions': True}
key = 'constraint'
class Delete(Expression):
1413class Delete(Expression):
1414    arg_types = {
1415        "with": False,
1416        "this": False,
1417        "using": False,
1418        "where": False,
1419        "returning": False,
1420        "limit": False,
1421        "tables": False,  # Multiple-Table Syntax (MySQL)
1422    }
1423
1424    def delete(
1425        self,
1426        table: ExpOrStr,
1427        dialect: DialectType = None,
1428        copy: bool = True,
1429        **opts,
1430    ) -> Delete:
1431        """
1432        Create a DELETE expression or replace the table on an existing DELETE expression.
1433
1434        Example:
1435            >>> delete("tbl").sql()
1436            'DELETE FROM tbl'
1437
1438        Args:
1439            table: the table from which to delete.
1440            dialect: the dialect used to parse the input expression.
1441            copy: if `False`, modify this expression instance in-place.
1442            opts: other options to use to parse the input expressions.
1443
1444        Returns:
1445            Delete: the modified expression.
1446        """
1447        return _apply_builder(
1448            expression=table,
1449            instance=self,
1450            arg="this",
1451            dialect=dialect,
1452            into=Table,
1453            copy=copy,
1454            **opts,
1455        )
1456
1457    def where(
1458        self,
1459        *expressions: t.Optional[ExpOrStr],
1460        append: bool = True,
1461        dialect: DialectType = None,
1462        copy: bool = True,
1463        **opts,
1464    ) -> Delete:
1465        """
1466        Append to or set the WHERE expressions.
1467
1468        Example:
1469            >>> delete("tbl").where("x = 'a' OR x < 'b'").sql()
1470            "DELETE FROM tbl WHERE x = 'a' OR x < 'b'"
1471
1472        Args:
1473            *expressions: the SQL code strings to parse.
1474                If an `Expression` instance is passed, it will be used as-is.
1475                Multiple expressions are combined with an AND operator.
1476            append: if `True`, AND the new expressions to any existing expression.
1477                Otherwise, this resets the expression.
1478            dialect: the dialect used to parse the input expressions.
1479            copy: if `False`, modify this expression instance in-place.
1480            opts: other options to use to parse the input expressions.
1481
1482        Returns:
1483            Delete: the modified expression.
1484        """
1485        return _apply_conjunction_builder(
1486            *expressions,
1487            instance=self,
1488            arg="where",
1489            append=append,
1490            into=Where,
1491            dialect=dialect,
1492            copy=copy,
1493            **opts,
1494        )
1495
1496    def returning(
1497        self,
1498        expression: ExpOrStr,
1499        dialect: DialectType = None,
1500        copy: bool = True,
1501        **opts,
1502    ) -> Delete:
1503        """
1504        Set the RETURNING expression. Not supported by all dialects.
1505
1506        Example:
1507            >>> delete("tbl").returning("*", dialect="postgres").sql()
1508            'DELETE FROM tbl RETURNING *'
1509
1510        Args:
1511            expression: the SQL code strings to parse.
1512                If an `Expression` instance is passed, it will be used as-is.
1513            dialect: the dialect used to parse the input expressions.
1514            copy: if `False`, modify this expression instance in-place.
1515            opts: other options to use to parse the input expressions.
1516
1517        Returns:
1518            Delete: the modified expression.
1519        """
1520        return _apply_builder(
1521            expression=expression,
1522            instance=self,
1523            arg="returning",
1524            prefix="RETURNING",
1525            dialect=dialect,
1526            copy=copy,
1527            into=Returning,
1528            **opts,
1529        )
arg_types = {'with': False, 'this': False, 'using': False, 'where': False, 'returning': False, 'limit': False, 'tables': False}
def delete( self, table: Union[str, Expression], dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, copy: bool = True, **opts) -> Delete:
1424    def delete(
1425        self,
1426        table: ExpOrStr,
1427        dialect: DialectType = None,
1428        copy: bool = True,
1429        **opts,
1430    ) -> Delete:
1431        """
1432        Create a DELETE expression or replace the table on an existing DELETE expression.
1433
1434        Example:
1435            >>> delete("tbl").sql()
1436            'DELETE FROM tbl'
1437
1438        Args:
1439            table: the table from which to delete.
1440            dialect: the dialect used to parse the input expression.
1441            copy: if `False`, modify this expression instance in-place.
1442            opts: other options to use to parse the input expressions.
1443
1444        Returns:
1445            Delete: the modified expression.
1446        """
1447        return _apply_builder(
1448            expression=table,
1449            instance=self,
1450            arg="this",
1451            dialect=dialect,
1452            into=Table,
1453            copy=copy,
1454            **opts,
1455        )

Create a DELETE expression or replace the table on an existing DELETE expression.

Example:
>>> delete("tbl").sql()
'DELETE FROM tbl'
Arguments:
  • table: the table from which to delete.
  • dialect: the dialect used to parse the input expression.
  • copy: if False, modify this expression instance in-place.
  • opts: other options to use to parse the input expressions.
Returns:

Delete: the modified expression.

def where( self, *expressions: Union[str, Expression, NoneType], append: bool = True, dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, copy: bool = True, **opts) -> Delete:
1457    def where(
1458        self,
1459        *expressions: t.Optional[ExpOrStr],
1460        append: bool = True,
1461        dialect: DialectType = None,
1462        copy: bool = True,
1463        **opts,
1464    ) -> Delete:
1465        """
1466        Append to or set the WHERE expressions.
1467
1468        Example:
1469            >>> delete("tbl").where("x = 'a' OR x < 'b'").sql()
1470            "DELETE FROM tbl WHERE x = 'a' OR x < 'b'"
1471
1472        Args:
1473            *expressions: the SQL code strings to parse.
1474                If an `Expression` instance is passed, it will be used as-is.
1475                Multiple expressions are combined with an AND operator.
1476            append: if `True`, AND the new expressions to any existing expression.
1477                Otherwise, this resets the expression.
1478            dialect: the dialect used to parse the input expressions.
1479            copy: if `False`, modify this expression instance in-place.
1480            opts: other options to use to parse the input expressions.
1481
1482        Returns:
1483            Delete: the modified expression.
1484        """
1485        return _apply_conjunction_builder(
1486            *expressions,
1487            instance=self,
1488            arg="where",
1489            append=append,
1490            into=Where,
1491            dialect=dialect,
1492            copy=copy,
1493            **opts,
1494        )

Append to or set the WHERE expressions.

Example:
>>> delete("tbl").where("x = 'a' OR x < 'b'").sql()
"DELETE FROM tbl WHERE x = 'a' OR x < 'b'"
Arguments:
  • *expressions: the SQL code strings to parse. If an Expression instance is passed, it will be used as-is. Multiple expressions are combined with an AND operator.
  • append: if True, AND the new expressions to any existing expression. Otherwise, this resets the expression.
  • dialect: the dialect used to parse the input expressions.
  • copy: if False, modify this expression instance in-place.
  • opts: other options to use to parse the input expressions.
Returns:

Delete: the modified expression.

def returning( self, expression: Union[str, Expression], dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, copy: bool = True, **opts) -> Delete:
1496    def returning(
1497        self,
1498        expression: ExpOrStr,
1499        dialect: DialectType = None,
1500        copy: bool = True,
1501        **opts,
1502    ) -> Delete:
1503        """
1504        Set the RETURNING expression. Not supported by all dialects.
1505
1506        Example:
1507            >>> delete("tbl").returning("*", dialect="postgres").sql()
1508            'DELETE FROM tbl RETURNING *'
1509
1510        Args:
1511            expression: the SQL code strings to parse.
1512                If an `Expression` instance is passed, it will be used as-is.
1513            dialect: the dialect used to parse the input expressions.
1514            copy: if `False`, modify this expression instance in-place.
1515            opts: other options to use to parse the input expressions.
1516
1517        Returns:
1518            Delete: the modified expression.
1519        """
1520        return _apply_builder(
1521            expression=expression,
1522            instance=self,
1523            arg="returning",
1524            prefix="RETURNING",
1525            dialect=dialect,
1526            copy=copy,
1527            into=Returning,
1528            **opts,
1529        )

Set the RETURNING expression. Not supported by all dialects.

Example:
>>> delete("tbl").returning("*", dialect="postgres").sql()
'DELETE FROM tbl RETURNING *'
Arguments:
  • expression: the SQL code strings to parse. If an Expression instance is passed, it will be used as-is.
  • dialect: the dialect used to parse the input expressions.
  • copy: if False, modify this expression instance in-place.
  • opts: other options to use to parse the input expressions.
Returns:

Delete: the modified expression.

key = 'delete'
class Drop(Expression):
1532class Drop(Expression):
1533    arg_types = {
1534        "this": False,
1535        "kind": False,
1536        "exists": False,
1537        "temporary": False,
1538        "materialized": False,
1539        "cascade": False,
1540        "constraints": False,
1541        "purge": False,
1542    }
arg_types = {'this': False, 'kind': False, 'exists': False, 'temporary': False, 'materialized': False, 'cascade': False, 'constraints': False, 'purge': False}
key = 'drop'
class Filter(Expression):
1545class Filter(Expression):
1546    arg_types = {"this": True, "expression": True}
arg_types = {'this': True, 'expression': True}
key = 'filter'
class Check(Expression):
1549class Check(Expression):
1550    pass
key = 'check'
class Connect(Expression):
1554class Connect(Expression):
1555    arg_types = {"start": False, "connect": True}
arg_types = {'start': False, 'connect': True}
key = 'connect'
class Prior(Expression):
1558class Prior(Expression):
1559    pass
key = 'prior'
class Directory(Expression):
1562class Directory(Expression):
1563    # https://spark.apache.org/docs/3.0.0-preview/sql-ref-syntax-dml-insert-overwrite-directory-hive.html
1564    arg_types = {"this": True, "local": False, "row_format": False}
arg_types = {'this': True, 'local': False, 'row_format': False}
key = 'directory'
class ForeignKey(Expression):
1567class ForeignKey(Expression):
1568    arg_types = {
1569        "expressions": True,
1570        "reference": False,
1571        "delete": False,
1572        "update": False,
1573    }
arg_types = {'expressions': True, 'reference': False, 'delete': False, 'update': False}
key = 'foreignkey'
class ColumnPrefix(Expression):
1576class ColumnPrefix(Expression):
1577    arg_types = {"this": True, "expression": True}
arg_types = {'this': True, 'expression': True}
key = 'columnprefix'
class PrimaryKey(Expression):
1580class PrimaryKey(Expression):
1581    arg_types = {"expressions": True, "options": False}
arg_types = {'expressions': True, 'options': False}
key = 'primarykey'
class Into(Expression):
1586class Into(Expression):
1587    arg_types = {"this": True, "temporary": False, "unlogged": False}
arg_types = {'this': True, 'temporary': False, 'unlogged': False}
key = 'into'
class From(Expression):
1590class From(Expression):
1591    @property
1592    def name(self) -> str:
1593        return self.this.name
1594
1595    @property
1596    def alias_or_name(self) -> str:
1597        return self.this.alias_or_name
name: str
alias_or_name: str
key = 'from'
class Having(Expression):
1600class Having(Expression):
1601    pass
key = 'having'
class Hint(Expression):
1604class Hint(Expression):
1605    arg_types = {"expressions": True}
arg_types = {'expressions': True}
key = 'hint'
class JoinHint(Expression):
1608class JoinHint(Expression):
1609    arg_types = {"this": True, "expressions": True}
arg_types = {'this': True, 'expressions': True}
key = 'joinhint'
class Identifier(Expression):
1612class Identifier(Expression):
1613    arg_types = {"this": True, "quoted": False, "global": False, "temporary": False}
1614
1615    @property
1616    def quoted(self) -> bool:
1617        return bool(self.args.get("quoted"))
1618
1619    @property
1620    def hashable_args(self) -> t.Any:
1621        return (self.this, self.quoted)
1622
1623    @property
1624    def output_name(self) -> str:
1625        return self.name
arg_types = {'this': True, 'quoted': False, 'global': False, 'temporary': False}
quoted: bool
hashable_args: Any
output_name: str

Name of the output column if this expression is a selection.

If the Expression has no output name, an empty string is returned.

Example:
>>> from sqlglot import parse_one
>>> parse_one("SELECT a")sqlglot.expressions[0].output_name
'a'
>>> parse_one("SELECT b AS c")sqlglot.expressions[0].output_name
'c'
>>> parse_one("SELECT 1 + 2")sqlglot.expressions[0].output_name
''
key = 'identifier'
class Opclass(Expression):
1629class Opclass(Expression):
1630    arg_types = {"this": True, "expression": True}
arg_types = {'this': True, 'expression': True}
key = 'opclass'
class Index(Expression):
1633class Index(Expression):
1634    arg_types = {
1635        "this": False,
1636        "table": False,
1637        "using": False,
1638        "where": False,
1639        "columns": False,
1640        "unique": False,
1641        "primary": False,
1642        "amp": False,  # teradata
1643        "partition_by": False,  # teradata
1644        "where": False,  # postgres partial indexes
1645    }
arg_types = {'this': False, 'table': False, 'using': False, 'where': False, 'columns': False, 'unique': False, 'primary': False, 'amp': False, 'partition_by': False}
key = 'index'
class Insert(DDL):
1648class Insert(DDL):
1649    arg_types = {
1650        "with": False,
1651        "this": True,
1652        "expression": False,
1653        "conflict": False,
1654        "returning": False,
1655        "overwrite": False,
1656        "exists": False,
1657        "partition": False,
1658        "alternative": False,
1659        "where": False,
1660        "ignore": False,
1661        "by_name": False,
1662    }
1663
1664    def with_(
1665        self,
1666        alias: ExpOrStr,
1667        as_: ExpOrStr,
1668        recursive: t.Optional[bool] = None,
1669        append: bool = True,
1670        dialect: DialectType = None,
1671        copy: bool = True,
1672        **opts,
1673    ) -> Insert:
1674        """
1675        Append to or set the common table expressions.
1676
1677        Example:
1678            >>> insert("SELECT x FROM cte", "t").with_("cte", as_="SELECT * FROM tbl").sql()
1679            'WITH cte AS (SELECT * FROM tbl) INSERT INTO t SELECT x FROM cte'
1680
1681        Args:
1682            alias: the SQL code string to parse as the table name.
1683                If an `Expression` instance is passed, this is used as-is.
1684            as_: the SQL code string to parse as the table expression.
1685                If an `Expression` instance is passed, it will be used as-is.
1686            recursive: set the RECURSIVE part of the expression. Defaults to `False`.
1687            append: if `True`, add to any existing expressions.
1688                Otherwise, this resets the expressions.
1689            dialect: the dialect used to parse the input expression.
1690            copy: if `False`, modify this expression instance in-place.
1691            opts: other options to use to parse the input expressions.
1692
1693        Returns:
1694            The modified expression.
1695        """
1696        return _apply_cte_builder(
1697            self, alias, as_, recursive=recursive, append=append, dialect=dialect, copy=copy, **opts
1698        )
arg_types = {'with': False, 'this': True, 'expression': False, 'conflict': False, 'returning': False, 'overwrite': False, 'exists': False, 'partition': False, 'alternative': False, 'where': False, 'ignore': False, 'by_name': False}
def with_( self, alias: Union[str, Expression], as_: Union[str, Expression], recursive: Optional[bool] = None, append: bool = True, dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, copy: bool = True, **opts) -> Insert:
1664    def with_(
1665        self,
1666        alias: ExpOrStr,
1667        as_: ExpOrStr,
1668        recursive: t.Optional[bool] = None,
1669        append: bool = True,
1670        dialect: DialectType = None,
1671        copy: bool = True,
1672        **opts,
1673    ) -> Insert:
1674        """
1675        Append to or set the common table expressions.
1676
1677        Example:
1678            >>> insert("SELECT x FROM cte", "t").with_("cte", as_="SELECT * FROM tbl").sql()
1679            'WITH cte AS (SELECT * FROM tbl) INSERT INTO t SELECT x FROM cte'
1680
1681        Args:
1682            alias: the SQL code string to parse as the table name.
1683                If an `Expression` instance is passed, this is used as-is.
1684            as_: the SQL code string to parse as the table expression.
1685                If an `Expression` instance is passed, it will be used as-is.
1686            recursive: set the RECURSIVE part of the expression. Defaults to `False`.
1687            append: if `True`, add to any existing expressions.
1688                Otherwise, this resets the expressions.
1689            dialect: the dialect used to parse the input expression.
1690            copy: if `False`, modify this expression instance in-place.
1691            opts: other options to use to parse the input expressions.
1692
1693        Returns:
1694            The modified expression.
1695        """
1696        return _apply_cte_builder(
1697            self, alias, as_, recursive=recursive, append=append, dialect=dialect, copy=copy, **opts
1698        )

Append to or set the common table expressions.

Example:
>>> insert("SELECT x FROM cte", "t").with_("cte", as_="SELECT * FROM tbl").sql()
'WITH cte AS (SELECT * FROM tbl) INSERT INTO t SELECT x FROM cte'
Arguments:
  • alias: the SQL code string to parse as the table name. If an Expression instance is passed, this is used as-is.
  • as_: the SQL code string to parse as the table expression. If an Expression instance is passed, it will be used as-is.
  • recursive: set the RECURSIVE part of the expression. Defaults to False.
  • append: if True, add to any existing expressions. Otherwise, this resets the expressions.
  • dialect: the dialect used to parse the input expression.
  • copy: if False, modify this expression instance in-place.
  • opts: other options to use to parse the input expressions.
Returns:

The modified expression.

key = 'insert'
class OnConflict(Expression):
1701class OnConflict(Expression):
1702    arg_types = {
1703        "duplicate": False,
1704        "expressions": False,
1705        "nothing": False,
1706        "key": False,
1707        "constraint": False,
1708    }
arg_types = {'duplicate': False, 'expressions': False, 'nothing': False, 'key': False, 'constraint': False}
key = 'onconflict'
class Returning(Expression):
1711class Returning(Expression):
1712    arg_types = {"expressions": True, "into": False}
arg_types = {'expressions': True, 'into': False}
key = 'returning'
class Introducer(Expression):
1716class Introducer(Expression):
1717    arg_types = {"this": True, "expression": True}
arg_types = {'this': True, 'expression': True}
key = 'introducer'
class National(Expression):
1721class National(Expression):
1722    pass
key = 'national'
class LoadData(Expression):
1725class LoadData(Expression):
1726    arg_types = {
1727        "this": True,
1728        "local": False,
1729        "overwrite": False,
1730        "inpath": True,
1731        "partition": False,
1732        "input_format": False,
1733        "serde": False,
1734    }
arg_types = {'this': True, 'local': False, 'overwrite': False, 'inpath': True, 'partition': False, 'input_format': False, 'serde': False}
key = 'loaddata'
class Partition(Expression):
1737class Partition(Expression):
1738    arg_types = {"expressions": True}
arg_types = {'expressions': True}
key = 'partition'
class Fetch(Expression):
1741class Fetch(Expression):
1742    arg_types = {
1743        "direction": False,
1744        "count": False,
1745        "percent": False,
1746        "with_ties": False,
1747    }
arg_types = {'direction': False, 'count': False, 'percent': False, 'with_ties': False}
key = 'fetch'
class Group(Expression):
1750class Group(Expression):
1751    arg_types = {
1752        "expressions": False,
1753        "grouping_sets": False,
1754        "cube": False,
1755        "rollup": False,
1756        "totals": False,
1757        "all": False,
1758    }
arg_types = {'expressions': False, 'grouping_sets': False, 'cube': False, 'rollup': False, 'totals': False, 'all': False}
key = 'group'
class Lambda(Expression):
1761class Lambda(Expression):
1762    arg_types = {"this": True, "expressions": True}
arg_types = {'this': True, 'expressions': True}
key = 'lambda'
class Limit(Expression):
1765class Limit(Expression):
1766    arg_types = {"this": False, "expression": True, "offset": False}
arg_types = {'this': False, 'expression': True, 'offset': False}
key = 'limit'
class Literal(Condition):
1769class Literal(Condition):
1770    arg_types = {"this": True, "is_string": True}
1771
1772    @property
1773    def hashable_args(self) -> t.Any:
1774        return (self.this, self.args.get("is_string"))
1775
1776    @classmethod
1777    def number(cls, number) -> Literal:
1778        return cls(this=str(number), is_string=False)
1779
1780    @classmethod
1781    def string(cls, string) -> Literal:
1782        return cls(this=str(string), is_string=True)
1783
1784    @property
1785    def output_name(self) -> str:
1786        return self.name
arg_types = {'this': True, 'is_string': True}
hashable_args: Any
@classmethod
def number(cls, number) -> Literal:
1776    @classmethod
1777    def number(cls, number) -> Literal:
1778        return cls(this=str(number), is_string=False)
@classmethod
def string(cls, string) -> Literal:
1780    @classmethod
1781    def string(cls, string) -> Literal:
1782        return cls(this=str(string), is_string=True)
output_name: str

Name of the output column if this expression is a selection.

If the Expression has no output name, an empty string is returned.

Example:
>>> from sqlglot import parse_one
>>> parse_one("SELECT a")sqlglot.expressions[0].output_name
'a'
>>> parse_one("SELECT b AS c")sqlglot.expressions[0].output_name
'c'
>>> parse_one("SELECT 1 + 2")sqlglot.expressions[0].output_name
''
key = 'literal'
class Join(Expression):
1789class Join(Expression):
1790    arg_types = {
1791        "this": True,
1792        "on": False,
1793        "side": False,
1794        "kind": False,
1795        "using": False,
1796        "method": False,
1797        "global": False,
1798        "hint": False,
1799    }
1800
1801    @property
1802    def method(self) -> str:
1803        return self.text("method").upper()
1804
1805    @property
1806    def kind(self) -> str:
1807        return self.text("kind").upper()
1808
1809    @property
1810    def side(self) -> str:
1811        return self.text("side").upper()
1812
1813    @property
1814    def hint(self) -> str:
1815        return self.text("hint").upper()
1816
1817    @property
1818    def alias_or_name(self) -> str:
1819        return self.this.alias_or_name
1820
1821    def on(
1822        self,
1823        *expressions: t.Optional[ExpOrStr],
1824        append: bool = True,
1825        dialect: DialectType = None,
1826        copy: bool = True,
1827        **opts,
1828    ) -> Join:
1829        """
1830        Append to or set the ON expressions.
1831
1832        Example:
1833            >>> import sqlglot
1834            >>> sqlglot.parse_one("JOIN x", into=Join).on("y = 1").sql()
1835            'JOIN x ON y = 1'
1836
1837        Args:
1838            *expressions: the SQL code strings to parse.
1839                If an `Expression` instance is passed, it will be used as-is.
1840                Multiple expressions are combined with an AND operator.
1841            append: if `True`, AND the new expressions to any existing expression.
1842                Otherwise, this resets the expression.
1843            dialect: the dialect used to parse the input expressions.
1844            copy: if `False`, modify this expression instance in-place.
1845            opts: other options to use to parse the input expressions.
1846
1847        Returns:
1848            The modified Join expression.
1849        """
1850        join = _apply_conjunction_builder(
1851            *expressions,
1852            instance=self,
1853            arg="on",
1854            append=append,
1855            dialect=dialect,
1856            copy=copy,
1857            **opts,
1858        )
1859
1860        if join.kind == "CROSS":
1861            join.set("kind", None)
1862
1863        return join
1864
1865    def using(
1866        self,
1867        *expressions: t.Optional[ExpOrStr],
1868        append: bool = True,
1869        dialect: DialectType = None,
1870        copy: bool = True,
1871        **opts,
1872    ) -> Join:
1873        """
1874        Append to or set the USING expressions.
1875
1876        Example:
1877            >>> import sqlglot
1878            >>> sqlglot.parse_one("JOIN x", into=Join).using("foo", "bla").sql()
1879            'JOIN x USING (foo, bla)'
1880
1881        Args:
1882            *expressions: the SQL code strings to parse.
1883                If an `Expression` instance is passed, it will be used as-is.
1884            append: if `True`, concatenate the new expressions to the existing "using" list.
1885                Otherwise, this resets the expression.
1886            dialect: the dialect used to parse the input expressions.
1887            copy: if `False`, modify this expression instance in-place.
1888            opts: other options to use to parse the input expressions.
1889
1890        Returns:
1891            The modified Join expression.
1892        """
1893        join = _apply_list_builder(
1894            *expressions,
1895            instance=self,
1896            arg="using",
1897            append=append,
1898            dialect=dialect,
1899            copy=copy,
1900            **opts,
1901        )
1902
1903        if join.kind == "CROSS":
1904            join.set("kind", None)
1905
1906        return join
arg_types = {'this': True, 'on': False, 'side': False, 'kind': False, 'using': False, 'method': False, 'global': False, 'hint': False}
method: str
kind: str
side: str
hint: str
alias_or_name: str
def on( self, *expressions: Union[str, Expression, NoneType], append: bool = True, dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, copy: bool = True, **opts) -> Join:
1821    def on(
1822        self,
1823        *expressions: t.Optional[ExpOrStr],
1824        append: bool = True,
1825        dialect: DialectType = None,
1826        copy: bool = True,
1827        **opts,
1828    ) -> Join:
1829        """
1830        Append to or set the ON expressions.
1831
1832        Example:
1833            >>> import sqlglot
1834            >>> sqlglot.parse_one("JOIN x", into=Join).on("y = 1").sql()
1835            'JOIN x ON y = 1'
1836
1837        Args:
1838            *expressions: the SQL code strings to parse.
1839                If an `Expression` instance is passed, it will be used as-is.
1840                Multiple expressions are combined with an AND operator.
1841            append: if `True`, AND the new expressions to any existing expression.
1842                Otherwise, this resets the expression.
1843            dialect: the dialect used to parse the input expressions.
1844            copy: if `False`, modify this expression instance in-place.
1845            opts: other options to use to parse the input expressions.
1846
1847        Returns:
1848            The modified Join expression.
1849        """
1850        join = _apply_conjunction_builder(
1851            *expressions,
1852            instance=self,
1853            arg="on",
1854            append=append,
1855            dialect=dialect,
1856            copy=copy,
1857            **opts,
1858        )
1859
1860        if join.kind == "CROSS":
1861            join.set("kind", None)
1862
1863        return join

Append to or set the ON expressions.

Example:
>>> import sqlglot
>>> sqlglot.parse_one("JOIN x", into=Join).on("y = 1").sql()
'JOIN x ON y = 1'
Arguments:
  • *expressions: the SQL code strings to parse. If an Expression instance is passed, it will be used as-is. Multiple expressions are combined with an AND operator.
  • append: if True, AND the new expressions to any existing expression. Otherwise, this resets the expression.
  • dialect: the dialect used to parse the input expressions.
  • copy: if False, modify this expression instance in-place.
  • opts: other options to use to parse the input expressions.
Returns:

The modified Join expression.

def using( self, *expressions: Union[str, Expression, NoneType], append: bool = True, dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, copy: bool = True, **opts) -> Join:
1865    def using(
1866        self,
1867        *expressions: t.Optional[ExpOrStr],
1868        append: bool = True,
1869        dialect: DialectType = None,
1870        copy: bool = True,
1871        **opts,
1872    ) -> Join:
1873        """
1874        Append to or set the USING expressions.
1875
1876        Example:
1877            >>> import sqlglot
1878            >>> sqlglot.parse_one("JOIN x", into=Join).using("foo", "bla").sql()
1879            'JOIN x USING (foo, bla)'
1880
1881        Args:
1882            *expressions: the SQL code strings to parse.
1883                If an `Expression` instance is passed, it will be used as-is.
1884            append: if `True`, concatenate the new expressions to the existing "using" list.
1885                Otherwise, this resets the expression.
1886            dialect: the dialect used to parse the input expressions.
1887            copy: if `False`, modify this expression instance in-place.
1888            opts: other options to use to parse the input expressions.
1889
1890        Returns:
1891            The modified Join expression.
1892        """
1893        join = _apply_list_builder(
1894            *expressions,
1895            instance=self,
1896            arg="using",
1897            append=append,
1898            dialect=dialect,
1899            copy=copy,
1900            **opts,
1901        )
1902
1903        if join.kind == "CROSS":
1904            join.set("kind", None)
1905
1906        return join

Append to or set the USING expressions.

Example:
>>> import sqlglot
>>> sqlglot.parse_one("JOIN x", into=Join).using("foo", "bla").sql()
'JOIN x USING (foo, bla)'
Arguments:
  • *expressions: the SQL code strings to parse. If an Expression instance is passed, it will be used as-is.
  • append: if True, concatenate the new expressions to the existing "using" list. Otherwise, this resets the expression.
  • dialect: the dialect used to parse the input expressions.
  • copy: if False, modify this expression instance in-place.
  • opts: other options to use to parse the input expressions.
Returns:

The modified Join expression.

key = 'join'
class Lateral(UDTF):
1909class Lateral(UDTF):
1910    arg_types = {"this": True, "view": False, "outer": False, "alias": False}
arg_types = {'this': True, 'view': False, 'outer': False, 'alias': False}
key = 'lateral'
class MatchRecognize(Expression):
1913class MatchRecognize(Expression):
1914    arg_types = {
1915        "partition_by": False,
1916        "order": False,
1917        "measures": False,
1918        "rows": False,
1919        "after": False,
1920        "pattern": False,
1921        "define": False,
1922        "alias": False,
1923    }
arg_types = {'partition_by': False, 'order': False, 'measures': False, 'rows': False, 'after': False, 'pattern': False, 'define': False, 'alias': False}
key = 'matchrecognize'
class Final(Expression):
1928class Final(Expression):
1929    pass
key = 'final'
class Offset(Expression):
1932class Offset(Expression):
1933    arg_types = {"this": False, "expression": True}
arg_types = {'this': False, 'expression': True}
key = 'offset'
class Order(Expression):
1936class Order(Expression):
1937    arg_types = {"this": False, "expressions": True}
arg_types = {'this': False, 'expressions': True}
key = 'order'
class Cluster(Order):
1942class Cluster(Order):
1943    pass
key = 'cluster'
class Distribute(Order):
1946class Distribute(Order):
1947    pass
key = 'distribute'
class Sort(Order):
1950class Sort(Order):
1951    pass
key = 'sort'
class Ordered(Expression):
1954class Ordered(Expression):
1955    arg_types = {"this": True, "desc": False, "nulls_first": True}
arg_types = {'this': True, 'desc': False, 'nulls_first': True}
key = 'ordered'
class Property(Expression):
1958class Property(Expression):
1959    arg_types = {"this": True, "value": True}
arg_types = {'this': True, 'value': True}
key = 'property'
class AlgorithmProperty(Property):
1962class AlgorithmProperty(Property):
1963    arg_types = {"this": True}
arg_types = {'this': True}
key = 'algorithmproperty'
class AutoIncrementProperty(Property):
1966class AutoIncrementProperty(Property):
1967    arg_types = {"this": True}
arg_types = {'this': True}
key = 'autoincrementproperty'
class BlockCompressionProperty(Property):
1970class BlockCompressionProperty(Property):
1971    arg_types = {"autotemp": False, "always": False, "default": True, "manual": True, "never": True}
arg_types = {'autotemp': False, 'always': False, 'default': True, 'manual': True, 'never': True}
key = 'blockcompressionproperty'
class CharacterSetProperty(Property):
1974class CharacterSetProperty(Property):
1975    arg_types = {"this": True, "default": True}
arg_types = {'this': True, 'default': True}
key = 'charactersetproperty'
class ChecksumProperty(Property):
1978class ChecksumProperty(Property):
1979    arg_types = {"on": False, "default": False}
arg_types = {'on': False, 'default': False}
key = 'checksumproperty'
class CollateProperty(Property):
1982class CollateProperty(Property):
1983    arg_types = {"this": True}
arg_types = {'this': True}
key = 'collateproperty'
class CopyGrantsProperty(Property):
1986class CopyGrantsProperty(Property):
1987    arg_types = {}
arg_types = {}
key = 'copygrantsproperty'
class DataBlocksizeProperty(Property):
1990class DataBlocksizeProperty(Property):
1991    arg_types = {
1992        "size": False,
1993        "units": False,
1994        "minimum": False,
1995        "maximum": False,
1996        "default": False,
1997    }
arg_types = {'size': False, 'units': False, 'minimum': False, 'maximum': False, 'default': False}
key = 'datablocksizeproperty'
class DefinerProperty(Property):
2000class DefinerProperty(Property):
2001    arg_types = {"this": True}
arg_types = {'this': True}
key = 'definerproperty'
class DistKeyProperty(Property):
2004class DistKeyProperty(Property):
2005    arg_types = {"this": True}
arg_types = {'this': True}
key = 'distkeyproperty'
class DistStyleProperty(Property):
2008class DistStyleProperty(Property):
2009    arg_types = {"this": True}
arg_types = {'this': True}
key = 'diststyleproperty'
class EngineProperty(Property):
2012class EngineProperty(Property):
2013    arg_types = {"this": True}
arg_types = {'this': True}
key = 'engineproperty'
class HeapProperty(Property):
2016class HeapProperty(Property):
2017    arg_types = {}
arg_types = {}
key = 'heapproperty'
class ToTableProperty(Property):
2020class ToTableProperty(Property):
2021    arg_types = {"this": True}
arg_types = {'this': True}
key = 'totableproperty'
class ExecuteAsProperty(Property):
2024class ExecuteAsProperty(Property):
2025    arg_types = {"this": True}
arg_types = {'this': True}
key = 'executeasproperty'
class ExternalProperty(Property):
2028class ExternalProperty(Property):
2029    arg_types = {"this": False}
arg_types = {'this': False}
key = 'externalproperty'
class FallbackProperty(Property):
2032class FallbackProperty(Property):
2033    arg_types = {"no": True, "protection": False}
arg_types = {'no': True, 'protection': False}
key = 'fallbackproperty'
class FileFormatProperty(Property):
2036class FileFormatProperty(Property):
2037    arg_types = {"this": True}
arg_types = {'this': True}
key = 'fileformatproperty'
class FreespaceProperty(Property):
2040class FreespaceProperty(Property):
2041    arg_types = {"this": True, "percent": False}
arg_types = {'this': True, 'percent': False}
key = 'freespaceproperty'
class InputModelProperty(Property):
2044class InputModelProperty(Property):
2045    arg_types = {"this": True}
arg_types = {'this': True}
key = 'inputmodelproperty'
class OutputModelProperty(Property):
2048class OutputModelProperty(Property):
2049    arg_types = {"this": True}
arg_types = {'this': True}
key = 'outputmodelproperty'
class IsolatedLoadingProperty(Property):
2052class IsolatedLoadingProperty(Property):
2053    arg_types = {
2054        "no": True,
2055        "concurrent": True,
2056        "for_all": True,
2057        "for_insert": True,
2058        "for_none": True,
2059    }
arg_types = {'no': True, 'concurrent': True, 'for_all': True, 'for_insert': True, 'for_none': True}
key = 'isolatedloadingproperty'
class JournalProperty(Property):
2062class JournalProperty(Property):
2063    arg_types = {
2064        "no": False,
2065        "dual": False,
2066        "before": False,
2067        "local": False,
2068        "after": False,
2069    }
arg_types = {'no': False, 'dual': False, 'before': False, 'local': False, 'after': False}
key = 'journalproperty'
class LanguageProperty(Property):
2072class LanguageProperty(Property):
2073    arg_types = {"this": True}
arg_types = {'this': True}
key = 'languageproperty'
class ClusteredByProperty(Property):
2077class ClusteredByProperty(Property):
2078    arg_types = {"expressions": True, "sorted_by": False, "buckets": True}
arg_types = {'expressions': True, 'sorted_by': False, 'buckets': True}
key = 'clusteredbyproperty'
class DictProperty(Property):
2081class DictProperty(Property):
2082    arg_types = {"this": True, "kind": True, "settings": False}
arg_types = {'this': True, 'kind': True, 'settings': False}
key = 'dictproperty'
class DictSubProperty(Property):
2085class DictSubProperty(Property):
2086    pass
key = 'dictsubproperty'
class DictRange(Property):
2089class DictRange(Property):
2090    arg_types = {"this": True, "min": True, "max": True}
arg_types = {'this': True, 'min': True, 'max': True}
key = 'dictrange'
class OnCluster(Property):
2095class OnCluster(Property):
2096    arg_types = {"this": True}
arg_types = {'this': True}
key = 'oncluster'
class LikeProperty(Property):
2099class LikeProperty(Property):
2100    arg_types = {"this": True, "expressions": False}
arg_types = {'this': True, 'expressions': False}
key = 'likeproperty'
class LocationProperty(Property):
2103class LocationProperty(Property):
2104    arg_types = {"this": True}
arg_types = {'this': True}
key = 'locationproperty'
class LockingProperty(Property):
2107class LockingProperty(Property):
2108    arg_types = {
2109        "this": False,
2110        "kind": True,
2111        "for_or_in": False,
2112        "lock_type": True,
2113        "override": False,
2114    }
arg_types = {'this': False, 'kind': True, 'for_or_in': False, 'lock_type': True, 'override': False}
key = 'lockingproperty'
class LogProperty(Property):
2117class LogProperty(Property):
2118    arg_types = {"no": True}
arg_types = {'no': True}
key = 'logproperty'
class MaterializedProperty(Property):
2121class MaterializedProperty(Property):
2122    arg_types = {"this": False}
arg_types = {'this': False}
key = 'materializedproperty'
class MergeBlockRatioProperty(Property):
2125class MergeBlockRatioProperty(Property):
2126    arg_types = {"this": False, "no": False, "default": False, "percent": False}
arg_types = {'this': False, 'no': False, 'default': False, 'percent': False}
key = 'mergeblockratioproperty'
class NoPrimaryIndexProperty(Property):
2129class NoPrimaryIndexProperty(Property):
2130    arg_types = {}
arg_types = {}
key = 'noprimaryindexproperty'
class OnProperty(Property):
2133class OnProperty(Property):
2134    arg_types = {"this": True}
arg_types = {'this': True}
key = 'onproperty'
class OnCommitProperty(Property):
2137class OnCommitProperty(Property):
2138    arg_types = {"delete": False}
arg_types = {'delete': False}
key = 'oncommitproperty'
class PartitionedByProperty(Property):
2141class PartitionedByProperty(Property):
2142    arg_types = {"this": True}
arg_types = {'this': True}
key = 'partitionedbyproperty'
class RemoteWithConnectionModelProperty(Property):
2145class RemoteWithConnectionModelProperty(Property):
2146    arg_types = {"this": True}
arg_types = {'this': True}
key = 'remotewithconnectionmodelproperty'
class ReturnsProperty(Property):
2149class ReturnsProperty(Property):
2150    arg_types = {"this": True, "is_table": False, "table": False}
arg_types = {'this': True, 'is_table': False, 'table': False}
key = 'returnsproperty'
class RowFormatProperty(Property):
2153class RowFormatProperty(Property):
2154    arg_types = {"this": True}
arg_types = {'this': True}
key = 'rowformatproperty'
class RowFormatDelimitedProperty(Property):
2157class RowFormatDelimitedProperty(Property):
2158    # https://cwiki.apache.org/confluence/display/hive/languagemanual+dml
2159    arg_types = {
2160        "fields": False,
2161        "escaped": False,
2162        "collection_items": False,
2163        "map_keys": False,
2164        "lines": False,
2165        "null": False,
2166        "serde": False,
2167    }
arg_types = {'fields': False, 'escaped': False, 'collection_items': False, 'map_keys': False, 'lines': False, 'null': False, 'serde': False}
key = 'rowformatdelimitedproperty'
class RowFormatSerdeProperty(Property):
2170class RowFormatSerdeProperty(Property):
2171    arg_types = {"this": True, "serde_properties": False}
arg_types = {'this': True, 'serde_properties': False}
key = 'rowformatserdeproperty'
class QueryTransform(Expression):
2175class QueryTransform(Expression):
2176    arg_types = {
2177        "expressions": True,
2178        "command_script": True,
2179        "schema": False,
2180        "row_format_before": False,
2181        "record_writer": False,
2182        "row_format_after": False,
2183        "record_reader": False,
2184    }
arg_types = {'expressions': True, 'command_script': True, 'schema': False, 'row_format_before': False, 'record_writer': False, 'row_format_after': False, 'record_reader': False}
key = 'querytransform'
class SampleProperty(Property):
2187class SampleProperty(Property):
2188    arg_types = {"this": True}
arg_types = {'this': True}
key = 'sampleproperty'
class SchemaCommentProperty(Property):
2191class SchemaCommentProperty(Property):
2192    arg_types = {"this": True}
arg_types = {'this': True}
key = 'schemacommentproperty'
class SerdeProperties(Property):
2195class SerdeProperties(Property):
2196    arg_types = {"expressions": True}
arg_types = {'expressions': True}
key = 'serdeproperties'
class SetProperty(Property):
2199class SetProperty(Property):
2200    arg_types = {"multi": True}
arg_types = {'multi': True}
key = 'setproperty'
class SettingsProperty(Property):
2203class SettingsProperty(Property):
2204    arg_types = {"expressions": True}
arg_types = {'expressions': True}
key = 'settingsproperty'
class SortKeyProperty(Property):
2207class SortKeyProperty(Property):
2208    arg_types = {"this": True, "compound": False}
arg_types = {'this': True, 'compound': False}
key = 'sortkeyproperty'
class SqlSecurityProperty(Property):
2211class SqlSecurityProperty(Property):
2212    arg_types = {"definer": True}
arg_types = {'definer': True}
key = 'sqlsecurityproperty'
class StabilityProperty(Property):
2215class StabilityProperty(Property):
2216    arg_types = {"this": True}
arg_types = {'this': True}
key = 'stabilityproperty'
class TemporaryProperty(Property):
2219class TemporaryProperty(Property):
2220    arg_types = {}
arg_types = {}
key = 'temporaryproperty'
class TransformModelProperty(Property):
2223class TransformModelProperty(Property):
2224    arg_types = {"expressions": True}
arg_types = {'expressions': True}
key = 'transformmodelproperty'
class TransientProperty(Property):
2227class TransientProperty(Property):
2228    arg_types = {"this": False}
arg_types = {'this': False}
key = 'transientproperty'
class VolatileProperty(Property):
2231class VolatileProperty(Property):
2232    arg_types = {"this": False}
arg_types = {'this': False}
key = 'volatileproperty'
class WithDataProperty(Property):
2235class WithDataProperty(Property):
2236    arg_types = {"no": True, "statistics": False}
arg_types = {'no': True, 'statistics': False}
key = 'withdataproperty'
class WithJournalTableProperty(Property):
2239class WithJournalTableProperty(Property):
2240    arg_types = {"this": True}
arg_types = {'this': True}
key = 'withjournaltableproperty'
class Properties(Expression):
2243class Properties(Expression):
2244    arg_types = {"expressions": True}
2245
2246    NAME_TO_PROPERTY = {
2247        "ALGORITHM": AlgorithmProperty,
2248        "AUTO_INCREMENT": AutoIncrementProperty,
2249        "CHARACTER SET": CharacterSetProperty,
2250        "CLUSTERED_BY": ClusteredByProperty,
2251        "COLLATE": CollateProperty,
2252        "COMMENT": SchemaCommentProperty,
2253        "DEFINER": DefinerProperty,
2254        "DISTKEY": DistKeyProperty,
2255        "DISTSTYLE": DistStyleProperty,
2256        "ENGINE": EngineProperty,
2257        "EXECUTE AS": ExecuteAsProperty,
2258        "FORMAT": FileFormatProperty,
2259        "LANGUAGE": LanguageProperty,
2260        "LOCATION": LocationProperty,
2261        "PARTITIONED_BY": PartitionedByProperty,
2262        "RETURNS": ReturnsProperty,
2263        "ROW_FORMAT": RowFormatProperty,
2264        "SORTKEY": SortKeyProperty,
2265    }
2266
2267    PROPERTY_TO_NAME = {v: k for k, v in NAME_TO_PROPERTY.items()}
2268
2269    # CREATE property locations
2270    # Form: schema specified
2271    #   create [POST_CREATE]
2272    #     table a [POST_NAME]
2273    #     (b int) [POST_SCHEMA]
2274    #     with ([POST_WITH])
2275    #     index (b) [POST_INDEX]
2276    #
2277    # Form: alias selection
2278    #   create [POST_CREATE]
2279    #     table a [POST_NAME]
2280    #     as [POST_ALIAS] (select * from b) [POST_EXPRESSION]
2281    #     index (c) [POST_INDEX]
2282    class Location(AutoName):
2283        POST_CREATE = auto()
2284        POST_NAME = auto()
2285        POST_SCHEMA = auto()
2286        POST_WITH = auto()
2287        POST_ALIAS = auto()
2288        POST_EXPRESSION = auto()
2289        POST_INDEX = auto()
2290        UNSUPPORTED = auto()
2291
2292    @classmethod
2293    def from_dict(cls, properties_dict: t.Dict) -> Properties:
2294        expressions = []
2295        for key, value in properties_dict.items():
2296            property_cls = cls.NAME_TO_PROPERTY.get(key.upper())
2297            if property_cls:
2298                expressions.append(property_cls(this=convert(value)))
2299            else:
2300                expressions.append(Property(this=Literal.string(key), value=convert(value)))
2301
2302        return cls(expressions=expressions)
arg_types = {'expressions': True}
NAME_TO_PROPERTY = {'ALGORITHM': <class 'AlgorithmProperty'>, 'AUTO_INCREMENT': <class 'AutoIncrementProperty'>, 'CHARACTER SET': <class 'CharacterSetProperty'>, 'CLUSTERED_BY': <class 'ClusteredByProperty'>, 'COLLATE': <class 'CollateProperty'>, 'COMMENT': <class 'SchemaCommentProperty'>, 'DEFINER': <class 'DefinerProperty'>, 'DISTKEY': <class 'DistKeyProperty'>, 'DISTSTYLE': <class 'DistStyleProperty'>, 'ENGINE': <class 'EngineProperty'>, 'EXECUTE AS': <class 'ExecuteAsProperty'>, 'FORMAT': <class 'FileFormatProperty'>, 'LANGUAGE': <class 'LanguageProperty'>, 'LOCATION': <class 'LocationProperty'>, 'PARTITIONED_BY': <class 'PartitionedByProperty'>, 'RETURNS': <class 'ReturnsProperty'>, 'ROW_FORMAT': <class 'RowFormatProperty'>, 'SORTKEY': <class 'SortKeyProperty'>}
PROPERTY_TO_NAME = {<class 'AlgorithmProperty'>: 'ALGORITHM', <class 'AutoIncrementProperty'>: 'AUTO_INCREMENT', <class 'CharacterSetProperty'>: 'CHARACTER SET', <class 'ClusteredByProperty'>: 'CLUSTERED_BY', <class 'CollateProperty'>: 'COLLATE', <class 'SchemaCommentProperty'>: 'COMMENT', <class 'DefinerProperty'>: 'DEFINER', <class 'DistKeyProperty'>: 'DISTKEY', <class 'DistStyleProperty'>: 'DISTSTYLE', <class 'EngineProperty'>: 'ENGINE', <class 'ExecuteAsProperty'>: 'EXECUTE AS', <class 'FileFormatProperty'>: 'FORMAT', <class 'LanguageProperty'>: 'LANGUAGE', <class 'LocationProperty'>: 'LOCATION', <class 'PartitionedByProperty'>: 'PARTITIONED_BY', <class 'ReturnsProperty'>: 'RETURNS', <class 'RowFormatProperty'>: 'ROW_FORMAT', <class 'SortKeyProperty'>: 'SORTKEY'}
@classmethod
def from_dict(cls, properties_dict: Dict) -> Properties:
2292    @classmethod
2293    def from_dict(cls, properties_dict: t.Dict) -> Properties:
2294        expressions = []
2295        for key, value in properties_dict.items():
2296            property_cls = cls.NAME_TO_PROPERTY.get(key.upper())
2297            if property_cls:
2298                expressions.append(property_cls(this=convert(value)))
2299            else:
2300                expressions.append(Property(this=Literal.string(key), value=convert(value)))
2301
2302        return cls(expressions=expressions)
key = 'properties'
class Properties.Location(sqlglot.helper.AutoName):
2282    class Location(AutoName):
2283        POST_CREATE = auto()
2284        POST_NAME = auto()
2285        POST_SCHEMA = auto()
2286        POST_WITH = auto()
2287        POST_ALIAS = auto()
2288        POST_EXPRESSION = auto()
2289        POST_INDEX = auto()
2290        UNSUPPORTED = auto()

An enumeration.

POST_CREATE = <Location.POST_CREATE: 'POST_CREATE'>
POST_NAME = <Location.POST_NAME: 'POST_NAME'>
POST_SCHEMA = <Location.POST_SCHEMA: 'POST_SCHEMA'>
POST_WITH = <Location.POST_WITH: 'POST_WITH'>
POST_ALIAS = <Location.POST_ALIAS: 'POST_ALIAS'>
POST_EXPRESSION = <Location.POST_EXPRESSION: 'POST_EXPRESSION'>
POST_INDEX = <Location.POST_INDEX: 'POST_INDEX'>
UNSUPPORTED = <Location.UNSUPPORTED: 'UNSUPPORTED'>
Inherited Members
enum.Enum
name
value
class Qualify(Expression):
2305class Qualify(Expression):
2306    pass
key = 'qualify'
class InputOutputFormat(Expression):
2309class InputOutputFormat(Expression):
2310    arg_types = {"input_format": False, "output_format": False}
arg_types = {'input_format': False, 'output_format': False}
key = 'inputoutputformat'
class Return(Expression):
2314class Return(Expression):
2315    pass
key = 'return'
class Reference(Expression):
2318class Reference(Expression):
2319    arg_types = {"this": True, "expressions": False, "options": False}
arg_types = {'this': True, 'expressions': False, 'options': False}
key = 'reference'
class Tuple(Expression):
2322class Tuple(Expression):
2323    arg_types = {"expressions": False}
2324
2325    def isin(
2326        self,
2327        *expressions: t.Any,
2328        query: t.Optional[ExpOrStr] = None,
2329        unnest: t.Optional[ExpOrStr] | t.Collection[ExpOrStr] = None,
2330        copy: bool = True,
2331        **opts,
2332    ) -> In:
2333        return In(
2334            this=maybe_copy(self, copy),
2335            expressions=[convert(e, copy=copy) for e in expressions],
2336            query=maybe_parse(query, copy=copy, **opts) if query else None,
2337            unnest=Unnest(
2338                expressions=[
2339                    maybe_parse(t.cast(ExpOrStr, e), copy=copy, **opts) for e in ensure_list(unnest)
2340                ]
2341            )
2342            if unnest
2343            else None,
2344        )
arg_types = {'expressions': False}
def isin( self, *expressions: Any, query: Union[str, Expression, NoneType] = None, unnest: Union[str, Expression, NoneType, Collection[Union[str, Expression]]] = None, copy: bool = True, **opts) -> In:
2325    def isin(
2326        self,
2327        *expressions: t.Any,
2328        query: t.Optional[ExpOrStr] = None,
2329        unnest: t.Optional[ExpOrStr] | t.Collection[ExpOrStr] = None,
2330        copy: bool = True,
2331        **opts,
2332    ) -> In:
2333        return In(
2334            this=maybe_copy(self, copy),
2335            expressions=[convert(e, copy=copy) for e in expressions],
2336            query=maybe_parse(query, copy=copy, **opts) if query else None,
2337            unnest=Unnest(
2338                expressions=[
2339                    maybe_parse(t.cast(ExpOrStr, e), copy=copy, **opts) for e in ensure_list(unnest)
2340                ]
2341            )
2342            if unnest
2343            else None,
2344        )
key = 'tuple'
class Subqueryable(Unionable):
2347class Subqueryable(Unionable):
2348    def subquery(self, alias: t.Optional[ExpOrStr] = None, copy: bool = True) -> Subquery:
2349        """
2350        Convert this expression to an aliased expression that can be used as a Subquery.
2351
2352        Example:
2353            >>> subquery = Select().select("x").from_("tbl").subquery()
2354            >>> Select().select("x").from_(subquery).sql()
2355            'SELECT x FROM (SELECT x FROM tbl)'
2356
2357        Args:
2358            alias (str | Identifier): an optional alias for the subquery
2359            copy (bool): if `False`, modify this expression instance in-place.
2360
2361        Returns:
2362            Alias: the subquery
2363        """
2364        instance = maybe_copy(self, copy)
2365        if not isinstance(alias, Expression):
2366            alias = TableAlias(this=to_identifier(alias)) if alias else None
2367
2368        return Subquery(this=instance, alias=alias)
2369
2370    def limit(
2371        self, expression: ExpOrStr | int, dialect: DialectType = None, copy: bool = True, **opts
2372    ) -> Select:
2373        raise NotImplementedError
2374
2375    @property
2376    def ctes(self):
2377        with_ = self.args.get("with")
2378        if not with_:
2379            return []
2380        return with_.expressions
2381
2382    @property
2383    def selects(self) -> t.List[Expression]:
2384        raise NotImplementedError("Subqueryable objects must implement `selects`")
2385
2386    @property
2387    def named_selects(self) -> t.List[str]:
2388        raise NotImplementedError("Subqueryable objects must implement `named_selects`")
2389
2390    def select(
2391        self,
2392        *expressions: t.Optional[ExpOrStr],
2393        append: bool = True,
2394        dialect: DialectType = None,
2395        copy: bool = True,
2396        **opts,
2397    ) -> Subqueryable:
2398        raise NotImplementedError("Subqueryable objects must implement `select`")
2399
2400    def with_(
2401        self,
2402        alias: ExpOrStr,
2403        as_: ExpOrStr,
2404        recursive: t.Optional[bool] = None,
2405        append: bool = True,
2406        dialect: DialectType = None,
2407        copy: bool = True,
2408        **opts,
2409    ) -> Subqueryable:
2410        """
2411        Append to or set the common table expressions.
2412
2413        Example:
2414            >>> Select().with_("tbl2", as_="SELECT * FROM tbl").select("x").from_("tbl2").sql()
2415            'WITH tbl2 AS (SELECT * FROM tbl) SELECT x FROM tbl2'
2416
2417        Args:
2418            alias: the SQL code string to parse as the table name.
2419                If an `Expression` instance is passed, this is used as-is.
2420            as_: the SQL code string to parse as the table expression.
2421                If an `Expression` instance is passed, it will be used as-is.
2422            recursive: set the RECURSIVE part of the expression. Defaults to `False`.
2423            append: if `True`, add to any existing expressions.
2424                Otherwise, this resets the expressions.
2425            dialect: the dialect used to parse the input expression.
2426            copy: if `False`, modify this expression instance in-place.
2427            opts: other options to use to parse the input expressions.
2428
2429        Returns:
2430            The modified expression.
2431        """
2432        return _apply_cte_builder(
2433            self, alias, as_, recursive=recursive, append=append, dialect=dialect, copy=copy, **opts
2434        )
def subquery( self, alias: Union[str, Expression, NoneType] = None, copy: bool = True) -> Subquery:
2348    def subquery(self, alias: t.Optional[ExpOrStr] = None, copy: bool = True) -> Subquery:
2349        """
2350        Convert this expression to an aliased expression that can be used as a Subquery.
2351
2352        Example:
2353            >>> subquery = Select().select("x").from_("tbl").subquery()
2354            >>> Select().select("x").from_(subquery).sql()
2355            'SELECT x FROM (SELECT x FROM tbl)'
2356
2357        Args:
2358            alias (str | Identifier): an optional alias for the subquery
2359            copy (bool): if `False`, modify this expression instance in-place.
2360
2361        Returns:
2362            Alias: the subquery
2363        """
2364        instance = maybe_copy(self, copy)
2365        if not isinstance(alias, Expression):
2366            alias = TableAlias(this=to_identifier(alias)) if alias else None
2367
2368        return Subquery(this=instance, alias=alias)

Convert this expression to an aliased expression that can be used as a Subquery.

Example:
>>> subquery = Select().select("x").from_("tbl").subquery()
>>> Select().select("x").from_(subquery).sql()
'SELECT x FROM (SELECT x FROM tbl)'
Arguments:
  • alias (str | Identifier): an optional alias for the subquery
  • copy (bool): if False, modify this expression instance in-place.
Returns:

Alias: the subquery

def limit( self, expression: Union[str, Expression, int], dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, copy: bool = True, **opts) -> Select:
2370    def limit(
2371        self, expression: ExpOrStr | int, dialect: DialectType = None, copy: bool = True, **opts
2372    ) -> Select:
2373        raise NotImplementedError
ctes
selects: List[Expression]
named_selects: List[str]
def select( self, *expressions: Union[str, Expression, NoneType], append: bool = True, dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, copy: bool = True, **opts) -> Subqueryable:
2390    def select(
2391        self,
2392        *expressions: t.Optional[ExpOrStr],
2393        append: bool = True,
2394        dialect: DialectType = None,
2395        copy: bool = True,
2396        **opts,
2397    ) -> Subqueryable:
2398        raise NotImplementedError("Subqueryable objects must implement `select`")
def with_( self, alias: Union[str, Expression], as_: Union[str, Expression], recursive: Optional[bool] = None, append: bool = True, dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, copy: bool = True, **opts) -> Subqueryable:
2400    def with_(
2401        self,
2402        alias: ExpOrStr,
2403        as_: ExpOrStr,
2404        recursive: t.Optional[bool] = None,
2405        append: bool = True,
2406        dialect: DialectType = None,
2407        copy: bool = True,
2408        **opts,
2409    ) -> Subqueryable:
2410        """
2411        Append to or set the common table expressions.
2412
2413        Example:
2414            >>> Select().with_("tbl2", as_="SELECT * FROM tbl").select("x").from_("tbl2").sql()
2415            'WITH tbl2 AS (SELECT * FROM tbl) SELECT x FROM tbl2'
2416
2417        Args:
2418            alias: the SQL code string to parse as the table name.
2419                If an `Expression` instance is passed, this is used as-is.
2420            as_: the SQL code string to parse as the table expression.
2421                If an `Expression` instance is passed, it will be used as-is.
2422            recursive: set the RECURSIVE part of the expression. Defaults to `False`.
2423            append: if `True`, add to any existing expressions.
2424                Otherwise, this resets the expressions.
2425            dialect: the dialect used to parse the input expression.
2426            copy: if `False`, modify this expression instance in-place.
2427            opts: other options to use to parse the input expressions.
2428
2429        Returns:
2430            The modified expression.
2431        """
2432        return _apply_cte_builder(
2433            self, alias, as_, recursive=recursive, append=append, dialect=dialect, copy=copy, **opts
2434        )

Append to or set the common table expressions.

Example:
>>> Select().with_("tbl2", as_="SELECT * FROM tbl").select("x").from_("tbl2").sql()
'WITH tbl2 AS (SELECT * FROM tbl) SELECT x FROM tbl2'
Arguments:
  • alias: the SQL code string to parse as the table name. If an Expression instance is passed, this is used as-is.
  • as_: the SQL code string to parse as the table expression. If an Expression instance is passed, it will be used as-is.
  • recursive: set the RECURSIVE part of the expression. Defaults to False.
  • append: if True, add to any existing expressions. Otherwise, this resets the expressions.
  • dialect: the dialect used to parse the input expression.
  • copy: if False, modify this expression instance in-place.
  • opts: other options to use to parse the input expressions.
Returns:

The modified expression.

key = 'subqueryable'
QUERY_MODIFIERS = {'match': False, 'laterals': False, 'joins': False, 'connect': False, 'pivots': False, 'where': False, 'group': False, 'having': False, 'qualify': False, 'windows': False, 'distribute': False, 'sort': False, 'cluster': False, 'order': False, 'limit': False, 'offset': False, 'locks': False, 'sample': False, 'settings': False, 'format': False}
class WithTableHint(Expression):
2462class WithTableHint(Expression):
2463    arg_types = {"expressions": True}
arg_types = {'expressions': True}
key = 'withtablehint'
class IndexTableHint(Expression):
2467class IndexTableHint(Expression):
2468    arg_types = {"this": True, "expressions": False, "target": False}
arg_types = {'this': True, 'expressions': False, 'target': False}
key = 'indextablehint'
class Table(Expression):
2471class Table(Expression):
2472    arg_types = {
2473        "this": True,
2474        "alias": False,
2475        "db": False,
2476        "catalog": False,
2477        "laterals": False,
2478        "joins": False,
2479        "pivots": False,
2480        "hints": False,
2481        "system_time": False,
2482        "version": False,
2483        "format": False,
2484        "pattern": False,
2485        "index": False,
2486    }
2487
2488    @property
2489    def name(self) -> str:
2490        if isinstance(self.this, Func):
2491            return ""
2492        return self.this.name
2493
2494    @property
2495    def db(self) -> str:
2496        return self.text("db")
2497
2498    @property
2499    def catalog(self) -> str:
2500        return self.text("catalog")
2501
2502    @property
2503    def selects(self) -> t.List[Expression]:
2504        return []
2505
2506    @property
2507    def named_selects(self) -> t.List[str]:
2508        return []
2509
2510    @property
2511    def parts(self) -> t.List[Expression]:
2512        """Return the parts of a table in order catalog, db, table."""
2513        parts: t.List[Expression] = []
2514
2515        for arg in ("catalog", "db", "this"):
2516            part = self.args.get(arg)
2517
2518            if isinstance(part, Dot):
2519                parts.extend(part.flatten())
2520            elif isinstance(part, Expression):
2521                parts.append(part)
2522
2523        return parts
arg_types = {'this': True, 'alias': False, 'db': False, 'catalog': False, 'laterals': False, 'joins': False, 'pivots': False, 'hints': False, 'system_time': False, 'version': False, 'format': False, 'pattern': False, 'index': False}
name: str
db: str
catalog: str
selects: List[Expression]
named_selects: List[str]
parts: List[Expression]

Return the parts of a table in order catalog, db, table.

key = 'table'
class Union(Subqueryable):
2526class Union(Subqueryable):
2527    arg_types = {
2528        "with": False,
2529        "this": True,
2530        "expression": True,
2531        "distinct": False,
2532        "by_name": False,
2533        **QUERY_MODIFIERS,
2534    }
2535
2536    def limit(
2537        self, expression: ExpOrStr | int, dialect: DialectType = None, copy: bool = True, **opts
2538    ) -> Select:
2539        """
2540        Set the LIMIT expression.
2541
2542        Example:
2543            >>> select("1").union(select("1")).limit(1).sql()
2544            'SELECT * FROM (SELECT 1 UNION SELECT 1) AS _l_0 LIMIT 1'
2545
2546        Args:
2547            expression: the SQL code string to parse.
2548                This can also be an integer.
2549                If a `Limit` instance is passed, this is used as-is.
2550                If another `Expression` instance is passed, it will be wrapped in a `Limit`.
2551            dialect: the dialect used to parse the input expression.
2552            copy: if `False`, modify this expression instance in-place.
2553            opts: other options to use to parse the input expressions.
2554
2555        Returns:
2556            The limited subqueryable.
2557        """
2558        return (
2559            select("*")
2560            .from_(self.subquery(alias="_l_0", copy=copy))
2561            .limit(expression, dialect=dialect, copy=False, **opts)
2562        )
2563
2564    def select(
2565        self,
2566        *expressions: t.Optional[ExpOrStr],
2567        append: bool = True,
2568        dialect: DialectType = None,
2569        copy: bool = True,
2570        **opts,
2571    ) -> Union:
2572        """Append to or set the SELECT of the union recursively.
2573
2574        Example:
2575            >>> from sqlglot import parse_one
2576            >>> parse_one("select a from x union select a from y union select a from z").select("b").sql()
2577            'SELECT a, b FROM x UNION SELECT a, b FROM y UNION SELECT a, b FROM z'
2578
2579        Args:
2580            *expressions: the SQL code strings to parse.
2581                If an `Expression` instance is passed, it will be used as-is.
2582            append: if `True`, add to any existing expressions.
2583                Otherwise, this resets the expressions.
2584            dialect: the dialect used to parse the input expressions.
2585            copy: if `False`, modify this expression instance in-place.
2586            opts: other options to use to parse the input expressions.
2587
2588        Returns:
2589            Union: the modified expression.
2590        """
2591        this = self.copy() if copy else self
2592        this.this.unnest().select(*expressions, append=append, dialect=dialect, copy=False, **opts)
2593        this.expression.unnest().select(
2594            *expressions, append=append, dialect=dialect, copy=False, **opts
2595        )
2596        return this
2597
2598    @property
2599    def named_selects(self) -> t.List[str]:
2600        return self.this.unnest().named_selects
2601
2602    @property
2603    def is_star(self) -> bool:
2604        return self.this.is_star or self.expression.is_star
2605
2606    @property
2607    def selects(self) -> t.List[Expression]:
2608        return self.this.unnest().selects
2609
2610    @property
2611    def left(self) -> Expression:
2612        return self.this
2613
2614    @property
2615    def right(self) -> Expression:
2616        return self.expression
arg_types = {'with': False, 'this': True, 'expression': True, 'distinct': False, 'by_name': False, 'match': False, 'laterals': False, 'joins': False, 'connect': False, 'pivots': False, 'where': False, 'group': False, 'having': False, 'qualify': False, 'windows': False, 'distribute': False, 'sort': False, 'cluster': False, 'order': False, 'limit': False, 'offset': False, 'locks': False, 'sample': False, 'settings': False, 'format': False}
def limit( self, expression: Union[str, Expression, int], dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, copy: bool = True, **opts) -> Select:
2536    def limit(
2537        self, expression: ExpOrStr | int, dialect: DialectType = None, copy: bool = True, **opts
2538    ) -> Select:
2539        """
2540        Set the LIMIT expression.
2541
2542        Example:
2543            >>> select("1").union(select("1")).limit(1).sql()
2544            'SELECT * FROM (SELECT 1 UNION SELECT 1) AS _l_0 LIMIT 1'
2545
2546        Args:
2547            expression: the SQL code string to parse.
2548                This can also be an integer.
2549                If a `Limit` instance is passed, this is used as-is.
2550                If another `Expression` instance is passed, it will be wrapped in a `Limit`.
2551            dialect: the dialect used to parse the input expression.
2552            copy: if `False`, modify this expression instance in-place.
2553            opts: other options to use to parse the input expressions.
2554
2555        Returns:
2556            The limited subqueryable.
2557        """
2558        return (
2559            select("*")
2560            .from_(self.subquery(alias="_l_0", copy=copy))
2561            .limit(expression, dialect=dialect, copy=False, **opts)
2562        )

Set the LIMIT expression.

Example:
>>> select("1").union(select("1")).limit(1).sql()
'SELECT * FROM (SELECT 1 UNION SELECT 1) AS _l_0 LIMIT 1'
Arguments:
  • expression: the SQL code string to parse. This can also be an integer. If a Limit instance is passed, this is used as-is. If another Expression instance is passed, it will be wrapped in a Limit.
  • dialect: the dialect used to parse the input expression.
  • copy: if False, modify this expression instance in-place.
  • opts: other options to use to parse the input expressions.
Returns:

The limited subqueryable.

def select( self, *expressions: Union[str, Expression, NoneType], append: bool = True, dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, copy: bool = True, **opts) -> Union:
2564    def select(
2565        self,
2566        *expressions: t.Optional[ExpOrStr],
2567        append: bool = True,
2568        dialect: DialectType = None,
2569        copy: bool = True,
2570        **opts,
2571    ) -> Union:
2572        """Append to or set the SELECT of the union recursively.
2573
2574        Example:
2575            >>> from sqlglot import parse_one
2576            >>> parse_one("select a from x union select a from y union select a from z").select("b").sql()
2577            'SELECT a, b FROM x UNION SELECT a, b FROM y UNION SELECT a, b FROM z'
2578
2579        Args:
2580            *expressions: the SQL code strings to parse.
2581                If an `Expression` instance is passed, it will be used as-is.
2582            append: if `True`, add to any existing expressions.
2583                Otherwise, this resets the expressions.
2584            dialect: the dialect used to parse the input expressions.
2585            copy: if `False`, modify this expression instance in-place.
2586            opts: other options to use to parse the input expressions.
2587
2588        Returns:
2589            Union: the modified expression.
2590        """
2591        this = self.copy() if copy else self
2592        this.this.unnest().select(*expressions, append=append, dialect=dialect, copy=False, **opts)
2593        this.expression.unnest().select(
2594            *expressions, append=append, dialect=dialect, copy=False, **opts
2595        )
2596        return this

Append to or set the SELECT of the union recursively.

Example:
>>> from sqlglot import parse_one
>>> parse_one("select a from x union select a from y union select a from z").select("b").sql()
'SELECT a, b FROM x UNION SELECT a, b FROM y UNION SELECT a, b FROM z'
Arguments:
  • *expressions: the SQL code strings to parse. If an Expression instance is passed, it will be used as-is.
  • append: if True, add to any existing expressions. Otherwise, this resets the expressions.
  • dialect: the dialect used to parse the input expressions.
  • copy: if False, modify this expression instance in-place.
  • opts: other options to use to parse the input expressions.
Returns:

Union: the modified expression.

named_selects: List[str]
is_star: bool

Checks whether an expression is a star.

selects: List[Expression]
left: Expression
right: Expression
key = 'union'
class Except(Union):
2619class Except(Union):
2620    pass
key = 'except'
class Intersect(Union):
2623class Intersect(Union):
2624    pass
key = 'intersect'
class Unnest(UDTF):
2627class Unnest(UDTF):
2628    arg_types = {
2629        "expressions": True,
2630        "alias": False,
2631        "offset": False,
2632    }
arg_types = {'expressions': True, 'alias': False, 'offset': False}
key = 'unnest'
class Update(Expression):
2635class Update(Expression):
2636    arg_types = {
2637        "with": False,
2638        "this": False,
2639        "expressions": True,
2640        "from": False,
2641        "where": False,
2642        "returning": False,
2643        "order": False,
2644        "limit": False,
2645    }
arg_types = {'with': False, 'this': False, 'expressions': True, 'from': False, 'where': False, 'returning': False, 'order': False, 'limit': False}
key = 'update'
class Values(UDTF):
2648class Values(UDTF):
2649    arg_types = {
2650        "expressions": True,
2651        "ordinality": False,
2652        "alias": False,
2653    }
arg_types = {'expressions': True, 'ordinality': False, 'alias': False}
key = 'values'
class Var(Expression):
2656class Var(Expression):
2657    pass
key = 'var'
class Version(Expression):
2660class Version(Expression):
2661    """
2662    Time travel, iceberg, bigquery etc
2663    https://trino.io/docs/current/connector/iceberg.html?highlight=snapshot#using-snapshots
2664    https://www.databricks.com/blog/2019/02/04/introducing-delta-time-travel-for-large-scale-data-lakes.html
2665    https://cloud.google.com/bigquery/docs/reference/standard-sql/query-syntax#for_system_time_as_of
2666    https://learn.microsoft.com/en-us/sql/relational-databases/tables/querying-data-in-a-system-versioned-temporal-table?view=sql-server-ver16
2667    this is either TIMESTAMP or VERSION
2668    kind is ("AS OF", "BETWEEN")
2669    """
2670
2671    arg_types = {"this": True, "kind": True, "expression": False}
arg_types = {'this': True, 'kind': True, 'expression': False}
key = 'version'
class Schema(Expression):
2674class Schema(Expression):
2675    arg_types = {"this": False, "expressions": False}
arg_types = {'this': False, 'expressions': False}
key = 'schema'
class Lock(Expression):
2680class Lock(Expression):
2681    arg_types = {"update": True, "expressions": False, "wait": False}
arg_types = {'update': True, 'expressions': False, 'wait': False}
key = 'lock'
class Select(Subqueryable):
2684class Select(Subqueryable):
2685    arg_types = {
2686        "with": False,
2687        "kind": False,
2688        "expressions": False,
2689        "hint": False,
2690        "distinct": False,
2691        "into": False,
2692        "from": False,
2693        **QUERY_MODIFIERS,
2694    }
2695
2696    def from_(
2697        self, expression: ExpOrStr, dialect: DialectType = None, copy: bool = True, **opts
2698    ) -> Select:
2699        """
2700        Set the FROM expression.
2701
2702        Example:
2703            >>> Select().from_("tbl").select("x").sql()
2704            'SELECT x FROM tbl'
2705
2706        Args:
2707            expression : the SQL code strings to parse.
2708                If a `From` instance is passed, this is used as-is.
2709                If another `Expression` instance is passed, it will be wrapped in a `From`.
2710            dialect: the dialect used to parse the input expression.
2711            copy: if `False`, modify this expression instance in-place.
2712            opts: other options to use to parse the input expressions.
2713
2714        Returns:
2715            The modified Select expression.
2716        """
2717        return _apply_builder(
2718            expression=expression,
2719            instance=self,
2720            arg="from",
2721            into=From,
2722            prefix="FROM",
2723            dialect=dialect,
2724            copy=copy,
2725            **opts,
2726        )
2727
2728    def group_by(
2729        self,
2730        *expressions: t.Optional[ExpOrStr],
2731        append: bool = True,
2732        dialect: DialectType = None,
2733        copy: bool = True,
2734        **opts,
2735    ) -> Select:
2736        """
2737        Set the GROUP BY expression.
2738
2739        Example:
2740            >>> Select().from_("tbl").select("x", "COUNT(1)").group_by("x").sql()
2741            'SELECT x, COUNT(1) FROM tbl GROUP BY x'
2742
2743        Args:
2744            *expressions: the SQL code strings to parse.
2745                If a `Group` instance is passed, this is used as-is.
2746                If another `Expression` instance is passed, it will be wrapped in a `Group`.
2747                If nothing is passed in then a group by is not applied to the expression
2748            append: if `True`, add to any existing expressions.
2749                Otherwise, this flattens all the `Group` expression into a single expression.
2750            dialect: the dialect used to parse the input expression.
2751            copy: if `False`, modify this expression instance in-place.
2752            opts: other options to use to parse the input expressions.
2753
2754        Returns:
2755            The modified Select expression.
2756        """
2757        if not expressions:
2758            return self if not copy else self.copy()
2759
2760        return _apply_child_list_builder(
2761            *expressions,
2762            instance=self,
2763            arg="group",
2764            append=append,
2765            copy=copy,
2766            prefix="GROUP BY",
2767            into=Group,
2768            dialect=dialect,
2769            **opts,
2770        )
2771
2772    def order_by(
2773        self,
2774        *expressions: t.Optional[ExpOrStr],
2775        append: bool = True,
2776        dialect: DialectType = None,
2777        copy: bool = True,
2778        **opts,
2779    ) -> Select:
2780        """
2781        Set the ORDER BY expression.
2782
2783        Example:
2784            >>> Select().from_("tbl").select("x").order_by("x DESC").sql()
2785            'SELECT x FROM tbl ORDER BY x DESC'
2786
2787        Args:
2788            *expressions: the SQL code strings to parse.
2789                If a `Group` instance is passed, this is used as-is.
2790                If another `Expression` instance is passed, it will be wrapped in a `Order`.
2791            append: if `True`, add to any existing expressions.
2792                Otherwise, this flattens all the `Order` expression into a single expression.
2793            dialect: the dialect used to parse the input expression.
2794            copy: if `False`, modify this expression instance in-place.
2795            opts: other options to use to parse the input expressions.
2796
2797        Returns:
2798            The modified Select expression.
2799        """
2800        return _apply_child_list_builder(
2801            *expressions,
2802            instance=self,
2803            arg="order",
2804            append=append,
2805            copy=copy,
2806            prefix="ORDER BY",
2807            into=Order,
2808            dialect=dialect,
2809            **opts,
2810        )
2811
2812    def sort_by(
2813        self,
2814        *expressions: t.Optional[ExpOrStr],
2815        append: bool = True,
2816        dialect: DialectType = None,
2817        copy: bool = True,
2818        **opts,
2819    ) -> Select:
2820        """
2821        Set the SORT BY expression.
2822
2823        Example:
2824            >>> Select().from_("tbl").select("x").sort_by("x DESC").sql(dialect="hive")
2825            'SELECT x FROM tbl SORT BY x DESC'
2826
2827        Args:
2828            *expressions: the SQL code strings to parse.
2829                If a `Group` instance is passed, this is used as-is.
2830                If another `Expression` instance is passed, it will be wrapped in a `SORT`.
2831            append: if `True`, add to any existing expressions.
2832                Otherwise, this flattens all the `Order` expression into a single expression.
2833            dialect: the dialect used to parse the input expression.
2834            copy: if `False`, modify this expression instance in-place.
2835            opts: other options to use to parse the input expressions.
2836
2837        Returns:
2838            The modified Select expression.
2839        """
2840        return _apply_child_list_builder(
2841            *expressions,
2842            instance=self,
2843            arg="sort",
2844            append=append,
2845            copy=copy,
2846            prefix="SORT BY",
2847            into=Sort,
2848            dialect=dialect,
2849            **opts,
2850        )
2851
2852    def cluster_by(
2853        self,
2854        *expressions: t.Optional[ExpOrStr],
2855        append: bool = True,
2856        dialect: DialectType = None,
2857        copy: bool = True,
2858        **opts,
2859    ) -> Select:
2860        """
2861        Set the CLUSTER BY expression.
2862
2863        Example:
2864            >>> Select().from_("tbl").select("x").cluster_by("x DESC").sql(dialect="hive")
2865            'SELECT x FROM tbl CLUSTER BY x DESC'
2866
2867        Args:
2868            *expressions: the SQL code strings to parse.
2869                If a `Group` instance is passed, this is used as-is.
2870                If another `Expression` instance is passed, it will be wrapped in a `Cluster`.
2871            append: if `True`, add to any existing expressions.
2872                Otherwise, this flattens all the `Order` expression into a single expression.
2873            dialect: the dialect used to parse the input expression.
2874            copy: if `False`, modify this expression instance in-place.
2875            opts: other options to use to parse the input expressions.
2876
2877        Returns:
2878            The modified Select expression.
2879        """
2880        return _apply_child_list_builder(
2881            *expressions,
2882            instance=self,
2883            arg="cluster",
2884            append=append,
2885            copy=copy,
2886            prefix="CLUSTER BY",
2887            into=Cluster,
2888            dialect=dialect,
2889            **opts,
2890        )
2891
2892    def limit(
2893        self, expression: ExpOrStr | int, dialect: DialectType = None, copy: bool = True, **opts
2894    ) -> Select:
2895        """
2896        Set the LIMIT expression.
2897
2898        Example:
2899            >>> Select().from_("tbl").select("x").limit(10).sql()
2900            'SELECT x FROM tbl LIMIT 10'
2901
2902        Args:
2903            expression: the SQL code string to parse.
2904                This can also be an integer.
2905                If a `Limit` instance is passed, this is used as-is.
2906                If another `Expression` instance is passed, it will be wrapped in a `Limit`.
2907            dialect: the dialect used to parse the input expression.
2908            copy: if `False`, modify this expression instance in-place.
2909            opts: other options to use to parse the input expressions.
2910
2911        Returns:
2912            Select: the modified expression.
2913        """
2914        return _apply_builder(
2915            expression=expression,
2916            instance=self,
2917            arg="limit",
2918            into=Limit,
2919            prefix="LIMIT",
2920            dialect=dialect,
2921            copy=copy,
2922            into_arg="expression",
2923            **opts,
2924        )
2925
2926    def offset(
2927        self, expression: ExpOrStr | int, dialect: DialectType = None, copy: bool = True, **opts
2928    ) -> Select:
2929        """
2930        Set the OFFSET expression.
2931
2932        Example:
2933            >>> Select().from_("tbl").select("x").offset(10).sql()
2934            'SELECT x FROM tbl OFFSET 10'
2935
2936        Args:
2937            expression: the SQL code string to parse.
2938                This can also be an integer.
2939                If a `Offset` instance is passed, this is used as-is.
2940                If another `Expression` instance is passed, it will be wrapped in a `Offset`.
2941            dialect: the dialect used to parse the input expression.
2942            copy: if `False`, modify this expression instance in-place.
2943            opts: other options to use to parse the input expressions.
2944
2945        Returns:
2946            The modified Select expression.
2947        """
2948        return _apply_builder(
2949            expression=expression,
2950            instance=self,
2951            arg="offset",
2952            into=Offset,
2953            prefix="OFFSET",
2954            dialect=dialect,
2955            copy=copy,
2956            into_arg="expression",
2957            **opts,
2958        )
2959
2960    def select(
2961        self,
2962        *expressions: t.Optional[ExpOrStr],
2963        append: bool = True,
2964        dialect: DialectType = None,
2965        copy: bool = True,
2966        **opts,
2967    ) -> Select:
2968        """
2969        Append to or set the SELECT expressions.
2970
2971        Example:
2972            >>> Select().select("x", "y").sql()
2973            'SELECT x, y'
2974
2975        Args:
2976            *expressions: the SQL code strings to parse.
2977                If an `Expression` instance is passed, it will be used as-is.
2978            append: if `True`, add to any existing expressions.
2979                Otherwise, this resets the expressions.
2980            dialect: the dialect used to parse the input expressions.
2981            copy: if `False`, modify this expression instance in-place.
2982            opts: other options to use to parse the input expressions.
2983
2984        Returns:
2985            The modified Select expression.
2986        """
2987        return _apply_list_builder(
2988            *expressions,
2989            instance=self,
2990            arg="expressions",
2991            append=append,
2992            dialect=dialect,
2993            copy=copy,
2994            **opts,
2995        )
2996
2997    def lateral(
2998        self,
2999        *expressions: t.Optional[ExpOrStr],
3000        append: bool = True,
3001        dialect: DialectType = None,
3002        copy: bool = True,
3003        **opts,
3004    ) -> Select:
3005        """
3006        Append to or set the LATERAL expressions.
3007
3008        Example:
3009            >>> Select().select("x").lateral("OUTER explode(y) tbl2 AS z").from_("tbl").sql()
3010            'SELECT x FROM tbl LATERAL VIEW OUTER EXPLODE(y) tbl2 AS z'
3011
3012        Args:
3013            *expressions: the SQL code strings to parse.
3014                If an `Expression` instance is passed, it will be used as-is.
3015            append: if `True`, add to any existing expressions.
3016                Otherwise, this resets the expressions.
3017            dialect: the dialect used to parse the input expressions.
3018            copy: if `False`, modify this expression instance in-place.
3019            opts: other options to use to parse the input expressions.
3020
3021        Returns:
3022            The modified Select expression.
3023        """
3024        return _apply_list_builder(
3025            *expressions,
3026            instance=self,
3027            arg="laterals",
3028            append=append,
3029            into=Lateral,
3030            prefix="LATERAL VIEW",
3031            dialect=dialect,
3032            copy=copy,
3033            **opts,
3034        )
3035
3036    def join(
3037        self,
3038        expression: ExpOrStr,
3039        on: t.Optional[ExpOrStr] = None,
3040        using: t.Optional[ExpOrStr | t.Collection[ExpOrStr]] = None,
3041        append: bool = True,
3042        join_type: t.Optional[str] = None,
3043        join_alias: t.Optional[Identifier | str] = None,
3044        dialect: DialectType = None,
3045        copy: bool = True,
3046        **opts,
3047    ) -> Select:
3048        """
3049        Append to or set the JOIN expressions.
3050
3051        Example:
3052            >>> Select().select("*").from_("tbl").join("tbl2", on="tbl1.y = tbl2.y").sql()
3053            'SELECT * FROM tbl JOIN tbl2 ON tbl1.y = tbl2.y'
3054
3055            >>> Select().select("1").from_("a").join("b", using=["x", "y", "z"]).sql()
3056            'SELECT 1 FROM a JOIN b USING (x, y, z)'
3057
3058            Use `join_type` to change the type of join:
3059
3060            >>> Select().select("*").from_("tbl").join("tbl2", on="tbl1.y = tbl2.y", join_type="left outer").sql()
3061            'SELECT * FROM tbl LEFT OUTER JOIN tbl2 ON tbl1.y = tbl2.y'
3062
3063        Args:
3064            expression: the SQL code string to parse.
3065                If an `Expression` instance is passed, it will be used as-is.
3066            on: optionally specify the join "on" criteria as a SQL string.
3067                If an `Expression` instance is passed, it will be used as-is.
3068            using: optionally specify the join "using" criteria as a SQL string.
3069                If an `Expression` instance is passed, it will be used as-is.
3070            append: if `True`, add to any existing expressions.
3071                Otherwise, this resets the expressions.
3072            join_type: if set, alter the parsed join type.
3073            join_alias: an optional alias for the joined source.
3074            dialect: the dialect used to parse the input expressions.
3075            copy: if `False`, modify this expression instance in-place.
3076            opts: other options to use to parse the input expressions.
3077
3078        Returns:
3079            Select: the modified expression.
3080        """
3081        parse_args: t.Dict[str, t.Any] = {"dialect": dialect, **opts}
3082
3083        try:
3084            expression = maybe_parse(expression, into=Join, prefix="JOIN", **parse_args)
3085        except ParseError:
3086            expression = maybe_parse(expression, into=(Join, Expression), **parse_args)
3087
3088        join = expression if isinstance(expression, Join) else Join(this=expression)
3089
3090        if isinstance(join.this, Select):
3091            join.this.replace(join.this.subquery())
3092
3093        if join_type:
3094            method: t.Optional[Token]
3095            side: t.Optional[Token]
3096            kind: t.Optional[Token]
3097
3098            method, side, kind = maybe_parse(join_type, into="JOIN_TYPE", **parse_args)  # type: ignore
3099
3100            if method:
3101                join.set("method", method.text)
3102            if side:
3103                join.set("side", side.text)
3104            if kind:
3105                join.set("kind", kind.text)
3106
3107        if on:
3108            on = and_(*ensure_list(on), dialect=dialect, copy=copy, **opts)
3109            join.set("on", on)
3110
3111        if using:
3112            join = _apply_list_builder(
3113                *ensure_list(using),
3114                instance=join,
3115                arg="using",
3116                append=append,
3117                copy=copy,
3118                into=Identifier,
3119                **opts,
3120            )
3121
3122        if join_alias:
3123            join.set("this", alias_(join.this, join_alias, table=True))
3124
3125        return _apply_list_builder(
3126            join,
3127            instance=self,
3128            arg="joins",
3129            append=append,
3130            copy=copy,
3131            **opts,
3132        )
3133
3134    def where(
3135        self,
3136        *expressions: t.Optional[ExpOrStr],
3137        append: bool = True,
3138        dialect: DialectType = None,
3139        copy: bool = True,
3140        **opts,
3141    ) -> Select:
3142        """
3143        Append to or set the WHERE expressions.
3144
3145        Example:
3146            >>> Select().select("x").from_("tbl").where("x = 'a' OR x < 'b'").sql()
3147            "SELECT x FROM tbl WHERE x = 'a' OR x < 'b'"
3148
3149        Args:
3150            *expressions: the SQL code strings to parse.
3151                If an `Expression` instance is passed, it will be used as-is.
3152                Multiple expressions are combined with an AND operator.
3153            append: if `True`, AND the new expressions to any existing expression.
3154                Otherwise, this resets the expression.
3155            dialect: the dialect used to parse the input expressions.
3156            copy: if `False`, modify this expression instance in-place.
3157            opts: other options to use to parse the input expressions.
3158
3159        Returns:
3160            Select: the modified expression.
3161        """
3162        return _apply_conjunction_builder(
3163            *expressions,
3164            instance=self,
3165            arg="where",
3166            append=append,
3167            into=Where,
3168            dialect=dialect,
3169            copy=copy,
3170            **opts,
3171        )
3172
3173    def having(
3174        self,
3175        *expressions: t.Optional[ExpOrStr],
3176        append: bool = True,
3177        dialect: DialectType = None,
3178        copy: bool = True,
3179        **opts,
3180    ) -> Select:
3181        """
3182        Append to or set the HAVING expressions.
3183
3184        Example:
3185            >>> Select().select("x", "COUNT(y)").from_("tbl").group_by("x").having("COUNT(y) > 3").sql()
3186            'SELECT x, COUNT(y) FROM tbl GROUP BY x HAVING COUNT(y) > 3'
3187
3188        Args:
3189            *expressions: the SQL code strings to parse.
3190                If an `Expression` instance is passed, it will be used as-is.
3191                Multiple expressions are combined with an AND operator.
3192            append: if `True`, AND the new expressions to any existing expression.
3193                Otherwise, this resets the expression.
3194            dialect: the dialect used to parse the input expressions.
3195            copy: if `False`, modify this expression instance in-place.
3196            opts: other options to use to parse the input expressions.
3197
3198        Returns:
3199            The modified Select expression.
3200        """
3201        return _apply_conjunction_builder(
3202            *expressions,
3203            instance=self,
3204            arg="having",
3205            append=append,
3206            into=Having,
3207            dialect=dialect,
3208            copy=copy,
3209            **opts,
3210        )
3211
3212    def window(
3213        self,
3214        *expressions: t.Optional[ExpOrStr],
3215        append: bool = True,
3216        dialect: DialectType = None,
3217        copy: bool = True,
3218        **opts,
3219    ) -> Select:
3220        return _apply_list_builder(
3221            *expressions,
3222            instance=self,
3223            arg="windows",
3224            append=append,
3225            into=Window,
3226            dialect=dialect,
3227            copy=copy,
3228            **opts,
3229        )
3230
3231    def qualify(
3232        self,
3233        *expressions: t.Optional[ExpOrStr],
3234        append: bool = True,
3235        dialect: DialectType = None,
3236        copy: bool = True,
3237        **opts,
3238    ) -> Select:
3239        return _apply_conjunction_builder(
3240            *expressions,
3241            instance=self,
3242            arg="qualify",
3243            append=append,
3244            into=Qualify,
3245            dialect=dialect,
3246            copy=copy,
3247            **opts,
3248        )
3249
3250    def distinct(
3251        self, *ons: t.Optional[ExpOrStr], distinct: bool = True, copy: bool = True
3252    ) -> Select:
3253        """
3254        Set the OFFSET expression.
3255
3256        Example:
3257            >>> Select().from_("tbl").select("x").distinct().sql()
3258            'SELECT DISTINCT x FROM tbl'
3259
3260        Args:
3261            ons: the expressions to distinct on
3262            distinct: whether the Select should be distinct
3263            copy: if `False`, modify this expression instance in-place.
3264
3265        Returns:
3266            Select: the modified expression.
3267        """
3268        instance = maybe_copy(self, copy)
3269        on = Tuple(expressions=[maybe_parse(on, copy=copy) for on in ons if on]) if ons else None
3270        instance.set("distinct", Distinct(on=on) if distinct else None)
3271        return instance
3272
3273    def ctas(
3274        self,
3275        table: ExpOrStr,
3276        properties: t.Optional[t.Dict] = None,
3277        dialect: DialectType = None,
3278        copy: bool = True,
3279        **opts,
3280    ) -> Create:
3281        """
3282        Convert this expression to a CREATE TABLE AS statement.
3283
3284        Example:
3285            >>> Select().select("*").from_("tbl").ctas("x").sql()
3286            'CREATE TABLE x AS SELECT * FROM tbl'
3287
3288        Args:
3289            table: the SQL code string to parse as the table name.
3290                If another `Expression` instance is passed, it will be used as-is.
3291            properties: an optional mapping of table properties
3292            dialect: the dialect used to parse the input table.
3293            copy: if `False`, modify this expression instance in-place.
3294            opts: other options to use to parse the input table.
3295
3296        Returns:
3297            The new Create expression.
3298        """
3299        instance = maybe_copy(self, copy)
3300        table_expression = maybe_parse(
3301            table,
3302            into=Table,
3303            dialect=dialect,
3304            **opts,
3305        )
3306        properties_expression = None
3307        if properties:
3308            properties_expression = Properties.from_dict(properties)
3309
3310        return Create(
3311            this=table_expression,
3312            kind="table",
3313            expression=instance,
3314            properties=properties_expression,
3315        )
3316
3317    def lock(self, update: bool = True, copy: bool = True) -> Select:
3318        """
3319        Set the locking read mode for this expression.
3320
3321        Examples:
3322            >>> Select().select("x").from_("tbl").where("x = 'a'").lock().sql("mysql")
3323            "SELECT x FROM tbl WHERE x = 'a' FOR UPDATE"
3324
3325            >>> Select().select("x").from_("tbl").where("x = 'a'").lock(update=False).sql("mysql")
3326            "SELECT x FROM tbl WHERE x = 'a' FOR SHARE"
3327
3328        Args:
3329            update: if `True`, the locking type will be `FOR UPDATE`, else it will be `FOR SHARE`.
3330            copy: if `False`, modify this expression instance in-place.
3331
3332        Returns:
3333            The modified expression.
3334        """
3335        inst = maybe_copy(self, copy)
3336        inst.set("locks", [Lock(update=update)])
3337
3338        return inst
3339
3340    def hint(self, *hints: ExpOrStr, dialect: DialectType = None, copy: bool = True) -> Select:
3341        """
3342        Set hints for this expression.
3343
3344        Examples:
3345            >>> Select().select("x").from_("tbl").hint("BROADCAST(y)").sql(dialect="spark")
3346            'SELECT /*+ BROADCAST(y) */ x FROM tbl'
3347
3348        Args:
3349            hints: The SQL code strings to parse as the hints.
3350                If an `Expression` instance is passed, it will be used as-is.
3351            dialect: The dialect used to parse the hints.
3352            copy: If `False`, modify this expression instance in-place.
3353
3354        Returns:
3355            The modified expression.
3356        """
3357        inst = maybe_copy(self, copy)
3358        inst.set(
3359            "hint", Hint(expressions=[maybe_parse(h, copy=copy, dialect=dialect) for h in hints])
3360        )
3361
3362        return inst
3363
3364    @property
3365    def named_selects(self) -> t.List[str]:
3366        return [e.output_name for e in self.expressions if e.alias_or_name]
3367
3368    @property
3369    def is_star(self) -> bool:
3370        return any(expression.is_star for expression in self.expressions)
3371
3372    @property
3373    def selects(self) -> t.List[Expression]:
3374        return self.expressions
arg_types = {'with': False, 'kind': False, 'expressions': False, 'hint': False, 'distinct': False, 'into': False, 'from': False, 'match': False, 'laterals': False, 'joins': False, 'connect': False, 'pivots': False, 'where': False, 'group': False, 'having': False, 'qualify': False, 'windows': False, 'distribute': False, 'sort': False, 'cluster': False, 'order': False, 'limit': False, 'offset': False, 'locks': False, 'sample': False, 'settings': False, 'format': False}
def from_( self, expression: Union[str, Expression], dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, copy: bool = True, **opts) -> Select:
2696    def from_(
2697        self, expression: ExpOrStr, dialect: DialectType = None, copy: bool = True, **opts
2698    ) -> Select:
2699        """
2700        Set the FROM expression.
2701
2702        Example:
2703            >>> Select().from_("tbl").select("x").sql()
2704            'SELECT x FROM tbl'
2705
2706        Args:
2707            expression : the SQL code strings to parse.
2708                If a `From` instance is passed, this is used as-is.
2709                If another `Expression` instance is passed, it will be wrapped in a `From`.
2710            dialect: the dialect used to parse the input expression.
2711            copy: if `False`, modify this expression instance in-place.
2712            opts: other options to use to parse the input expressions.
2713
2714        Returns:
2715            The modified Select expression.
2716        """
2717        return _apply_builder(
2718            expression=expression,
2719            instance=self,
2720            arg="from",
2721            into=From,
2722            prefix="FROM",
2723            dialect=dialect,
2724            copy=copy,
2725            **opts,
2726        )

Set the FROM expression.

Example:
>>> Select().from_("tbl").select("x").sql()
'SELECT x FROM tbl'
Arguments:
  • expression : the SQL code strings to parse. If a From instance is passed, this is used as-is. If another Expression instance is passed, it will be wrapped in a From.
  • dialect: the dialect used to parse the input expression.
  • copy: if False, modify this expression instance in-place.
  • opts: other options to use to parse the input expressions.
Returns:

The modified Select expression.

def group_by( self, *expressions: Union[str, Expression, NoneType], append: bool = True, dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, copy: bool = True, **opts) -> Select:
2728    def group_by(
2729        self,
2730        *expressions: t.Optional[ExpOrStr],
2731        append: bool = True,
2732        dialect: DialectType = None,
2733        copy: bool = True,
2734        **opts,
2735    ) -> Select:
2736        """
2737        Set the GROUP BY expression.
2738
2739        Example:
2740            >>> Select().from_("tbl").select("x", "COUNT(1)").group_by("x").sql()
2741            'SELECT x, COUNT(1) FROM tbl GROUP BY x'
2742
2743        Args:
2744            *expressions: the SQL code strings to parse.
2745                If a `Group` instance is passed, this is used as-is.
2746                If another `Expression` instance is passed, it will be wrapped in a `Group`.
2747                If nothing is passed in then a group by is not applied to the expression
2748            append: if `True`, add to any existing expressions.
2749                Otherwise, this flattens all the `Group` expression into a single expression.
2750            dialect: the dialect used to parse the input expression.
2751            copy: if `False`, modify this expression instance in-place.
2752            opts: other options to use to parse the input expressions.
2753
2754        Returns:
2755            The modified Select expression.
2756        """
2757        if not expressions:
2758            return self if not copy else self.copy()
2759
2760        return _apply_child_list_builder(
2761            *expressions,
2762            instance=self,
2763            arg="group",
2764            append=append,
2765            copy=copy,
2766            prefix="GROUP BY",
2767            into=Group,
2768            dialect=dialect,
2769            **opts,
2770        )

Set the GROUP BY expression.

Example:
>>> Select().from_("tbl").select("x", "COUNT(1)").group_by("x").sql()
'SELECT x, COUNT(1) FROM tbl GROUP BY x'
Arguments:
  • *expressions: the SQL code strings to parse. If a Group instance is passed, this is used as-is. If another Expression instance is passed, it will be wrapped in a Group. If nothing is passed in then a group by is not applied to the expression
  • append: if True, add to any existing expressions. Otherwise, this flattens all the Group expression into a single expression.
  • dialect: the dialect used to parse the input expression.
  • copy: if False, modify this expression instance in-place.
  • opts: other options to use to parse the input expressions.
Returns:

The modified Select expression.

def order_by( self, *expressions: Union[str, Expression, NoneType], append: bool = True, dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, copy: bool = True, **opts) -> Select:
2772    def order_by(
2773        self,
2774        *expressions: t.Optional[ExpOrStr],
2775        append: bool = True,
2776        dialect: DialectType = None,
2777        copy: bool = True,
2778        **opts,
2779    ) -> Select:
2780        """
2781        Set the ORDER BY expression.
2782
2783        Example:
2784            >>> Select().from_("tbl").select("x").order_by("x DESC").sql()
2785            'SELECT x FROM tbl ORDER BY x DESC'
2786
2787        Args:
2788            *expressions: the SQL code strings to parse.
2789                If a `Group` instance is passed, this is used as-is.
2790                If another `Expression` instance is passed, it will be wrapped in a `Order`.
2791            append: if `True`, add to any existing expressions.
2792                Otherwise, this flattens all the `Order` expression into a single expression.
2793            dialect: the dialect used to parse the input expression.
2794            copy: if `False`, modify this expression instance in-place.
2795            opts: other options to use to parse the input expressions.
2796
2797        Returns:
2798            The modified Select expression.
2799        """
2800        return _apply_child_list_builder(
2801            *expressions,
2802            instance=self,
2803            arg="order",
2804            append=append,
2805            copy=copy,
2806            prefix="ORDER BY",
2807            into=Order,
2808            dialect=dialect,
2809            **opts,
2810        )

Set the ORDER BY expression.

Example:
>>> Select().from_("tbl").select("x").order_by("x DESC").sql()
'SELECT x FROM tbl ORDER BY x DESC'
Arguments:
  • *expressions: the SQL code strings to parse. If a Group instance is passed, this is used as-is. If another Expression instance is passed, it will be wrapped in a Order.
  • append: if True, add to any existing expressions. Otherwise, this flattens all the Order expression into a single expression.
  • dialect: the dialect used to parse the input expression.
  • copy: if False, modify this expression instance in-place.
  • opts: other options to use to parse the input expressions.
Returns:

The modified Select expression.

def sort_by( self, *expressions: Union[str, Expression, NoneType], append: bool = True, dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, copy: bool = True, **opts) -> Select:
2812    def sort_by(
2813        self,
2814        *expressions: t.Optional[ExpOrStr],
2815        append: bool = True,
2816        dialect: DialectType = None,
2817        copy: bool = True,
2818        **opts,
2819    ) -> Select:
2820        """
2821        Set the SORT BY expression.
2822
2823        Example:
2824            >>> Select().from_("tbl").select("x").sort_by("x DESC").sql(dialect="hive")
2825            'SELECT x FROM tbl SORT BY x DESC'
2826
2827        Args:
2828            *expressions: the SQL code strings to parse.
2829                If a `Group` instance is passed, this is used as-is.
2830                If another `Expression` instance is passed, it will be wrapped in a `SORT`.
2831            append: if `True`, add to any existing expressions.
2832                Otherwise, this flattens all the `Order` expression into a single expression.
2833            dialect: the dialect used to parse the input expression.
2834            copy: if `False`, modify this expression instance in-place.
2835            opts: other options to use to parse the input expressions.
2836
2837        Returns:
2838            The modified Select expression.
2839        """
2840        return _apply_child_list_builder(
2841            *expressions,
2842            instance=self,
2843            arg="sort",
2844            append=append,
2845            copy=copy,
2846            prefix="SORT BY",
2847            into=Sort,
2848            dialect=dialect,
2849            **opts,
2850        )

Set the SORT BY expression.

Example:
>>> Select().from_("tbl").select("x").sort_by("x DESC").sql(dialect="hive")
'SELECT x FROM tbl SORT BY x DESC'
Arguments:
  • *expressions: the SQL code strings to parse. If a Group instance is passed, this is used as-is. If another Expression instance is passed, it will be wrapped in a SORT.
  • append: if True, add to any existing expressions. Otherwise, this flattens all the Order expression into a single expression.
  • dialect: the dialect used to parse the input expression.
  • copy: if False, modify this expression instance in-place.
  • opts: other options to use to parse the input expressions.
Returns:

The modified Select expression.

def cluster_by( self, *expressions: Union[str, Expression, NoneType], append: bool = True, dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, copy: bool = True, **opts) -> Select:
2852    def cluster_by(
2853        self,
2854        *expressions: t.Optional[ExpOrStr],
2855        append: bool = True,
2856        dialect: DialectType = None,
2857        copy: bool = True,
2858        **opts,
2859    ) -> Select:
2860        """
2861        Set the CLUSTER BY expression.
2862
2863        Example:
2864            >>> Select().from_("tbl").select("x").cluster_by("x DESC").sql(dialect="hive")
2865            'SELECT x FROM tbl CLUSTER BY x DESC'
2866
2867        Args:
2868            *expressions: the SQL code strings to parse.
2869                If a `Group` instance is passed, this is used as-is.
2870                If another `Expression` instance is passed, it will be wrapped in a `Cluster`.
2871            append: if `True`, add to any existing expressions.
2872                Otherwise, this flattens all the `Order` expression into a single expression.
2873            dialect: the dialect used to parse the input expression.
2874            copy: if `False`, modify this expression instance in-place.
2875            opts: other options to use to parse the input expressions.
2876
2877        Returns:
2878            The modified Select expression.
2879        """
2880        return _apply_child_list_builder(
2881            *expressions,
2882            instance=self,
2883            arg="cluster",
2884            append=append,
2885            copy=copy,
2886            prefix="CLUSTER BY",
2887            into=Cluster,
2888            dialect=dialect,
2889            **opts,
2890        )

Set the CLUSTER BY expression.

Example:
>>> Select().from_("tbl").select("x").cluster_by("x DESC").sql(dialect="hive")
'SELECT x FROM tbl CLUSTER BY x DESC'
Arguments:
  • *expressions: the SQL code strings to parse. If a Group instance is passed, this is used as-is. If another Expression instance is passed, it will be wrapped in a Cluster.
  • append: if True, add to any existing expressions. Otherwise, this flattens all the Order expression into a single expression.
  • dialect: the dialect used to parse the input expression.
  • copy: if False, modify this expression instance in-place.
  • opts: other options to use to parse the input expressions.
Returns:

The modified Select expression.

def limit( self, expression: Union[str, Expression, int], dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, copy: bool = True, **opts) -> Select:
2892    def limit(
2893        self, expression: ExpOrStr | int, dialect: DialectType = None, copy: bool = True, **opts
2894    ) -> Select:
2895        """
2896        Set the LIMIT expression.
2897
2898        Example:
2899            >>> Select().from_("tbl").select("x").limit(10).sql()
2900            'SELECT x FROM tbl LIMIT 10'
2901
2902        Args:
2903            expression: the SQL code string to parse.
2904                This can also be an integer.
2905                If a `Limit` instance is passed, this is used as-is.
2906                If another `Expression` instance is passed, it will be wrapped in a `Limit`.
2907            dialect: the dialect used to parse the input expression.
2908            copy: if `False`, modify this expression instance in-place.
2909            opts: other options to use to parse the input expressions.
2910
2911        Returns:
2912            Select: the modified expression.
2913        """
2914        return _apply_builder(
2915            expression=expression,
2916            instance=self,
2917            arg="limit",
2918            into=Limit,
2919            prefix="LIMIT",
2920            dialect=dialect,
2921            copy=copy,
2922            into_arg="expression",
2923            **opts,
2924        )

Set the LIMIT expression.

Example:
>>> Select().from_("tbl").select("x").limit(10).sql()
'SELECT x FROM tbl LIMIT 10'
Arguments:
  • expression: the SQL code string to parse. This can also be an integer. If a Limit instance is passed, this is used as-is. If another Expression instance is passed, it will be wrapped in a Limit.
  • dialect: the dialect used to parse the input expression.
  • copy: if False, modify this expression instance in-place.
  • opts: other options to use to parse the input expressions.
Returns:

Select: the modified expression.

def offset( self, expression: Union[str, Expression, int], dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, copy: bool = True, **opts) -> Select:
2926    def offset(
2927        self, expression: ExpOrStr | int, dialect: DialectType = None, copy: bool = True, **opts
2928    ) -> Select:
2929        """
2930        Set the OFFSET expression.
2931
2932        Example:
2933            >>> Select().from_("tbl").select("x").offset(10).sql()
2934            'SELECT x FROM tbl OFFSET 10'
2935
2936        Args:
2937            expression: the SQL code string to parse.
2938                This can also be an integer.
2939                If a `Offset` instance is passed, this is used as-is.
2940                If another `Expression` instance is passed, it will be wrapped in a `Offset`.
2941            dialect: the dialect used to parse the input expression.
2942            copy: if `False`, modify this expression instance in-place.
2943            opts: other options to use to parse the input expressions.
2944
2945        Returns:
2946            The modified Select expression.
2947        """
2948        return _apply_builder(
2949            expression=expression,
2950            instance=self,
2951            arg="offset",
2952            into=Offset,
2953            prefix="OFFSET",
2954            dialect=dialect,
2955            copy=copy,
2956            into_arg="expression",
2957            **opts,
2958        )

Set the OFFSET expression.

Example:
>>> Select().from_("tbl").select("x").offset(10).sql()
'SELECT x FROM tbl OFFSET 10'
Arguments:
  • expression: the SQL code string to parse. This can also be an integer. If a Offset instance is passed, this is used as-is. If another Expression instance is passed, it will be wrapped in a Offset.
  • dialect: the dialect used to parse the input expression.
  • copy: if False, modify this expression instance in-place.
  • opts: other options to use to parse the input expressions.
Returns:

The modified Select expression.

def select( self, *expressions: Union[str, Expression, NoneType], append: bool = True, dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, copy: bool = True, **opts) -> Select:
2960    def select(
2961        self,
2962        *expressions: t.Optional[ExpOrStr],
2963        append: bool = True,
2964        dialect: DialectType = None,
2965        copy: bool = True,
2966        **opts,
2967    ) -> Select:
2968        """
2969        Append to or set the SELECT expressions.
2970
2971        Example:
2972            >>> Select().select("x", "y").sql()
2973            'SELECT x, y'
2974
2975        Args:
2976            *expressions: the SQL code strings to parse.
2977                If an `Expression` instance is passed, it will be used as-is.
2978            append: if `True`, add to any existing expressions.
2979                Otherwise, this resets the expressions.
2980            dialect: the dialect used to parse the input expressions.
2981            copy: if `False`, modify this expression instance in-place.
2982            opts: other options to use to parse the input expressions.
2983
2984        Returns:
2985            The modified Select expression.
2986        """
2987        return _apply_list_builder(
2988            *expressions,
2989            instance=self,
2990            arg="expressions",
2991            append=append,
2992            dialect=dialect,
2993            copy=copy,
2994            **opts,
2995        )

Append to or set the SELECT expressions.

Example:
>>> Select().select("x", "y").sql()
'SELECT x, y'
Arguments:
  • *expressions: the SQL code strings to parse. If an Expression instance is passed, it will be used as-is.
  • append: if True, add to any existing expressions. Otherwise, this resets the expressions.
  • dialect: the dialect used to parse the input expressions.
  • copy: if False, modify this expression instance in-place.
  • opts: other options to use to parse the input expressions.
Returns:

The modified Select expression.

def lateral( self, *expressions: Union[str, Expression, NoneType], append: bool = True, dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, copy: bool = True, **opts) -> Select:
2997    def lateral(
2998        self,
2999        *expressions: t.Optional[ExpOrStr],
3000        append: bool = True,
3001        dialect: DialectType = None,
3002        copy: bool = True,
3003        **opts,
3004    ) -> Select:
3005        """
3006        Append to or set the LATERAL expressions.
3007
3008        Example:
3009            >>> Select().select("x").lateral("OUTER explode(y) tbl2 AS z").from_("tbl").sql()
3010            'SELECT x FROM tbl LATERAL VIEW OUTER EXPLODE(y) tbl2 AS z'
3011
3012        Args:
3013            *expressions: the SQL code strings to parse.
3014                If an `Expression` instance is passed, it will be used as-is.
3015            append: if `True`, add to any existing expressions.
3016                Otherwise, this resets the expressions.
3017            dialect: the dialect used to parse the input expressions.
3018            copy: if `False`, modify this expression instance in-place.
3019            opts: other options to use to parse the input expressions.
3020
3021        Returns:
3022            The modified Select expression.
3023        """
3024        return _apply_list_builder(
3025            *expressions,
3026            instance=self,
3027            arg="laterals",
3028            append=append,
3029            into=Lateral,
3030            prefix="LATERAL VIEW",
3031            dialect=dialect,
3032            copy=copy,
3033            **opts,
3034        )

Append to or set the LATERAL expressions.

Example:
>>> Select().select("x").lateral("OUTER explode(y) tbl2 AS z").from_("tbl").sql()
'SELECT x FROM tbl LATERAL VIEW OUTER EXPLODE(y) tbl2 AS z'
Arguments:
  • *expressions: the SQL code strings to parse. If an Expression instance is passed, it will be used as-is.
  • append: if True, add to any existing expressions. Otherwise, this resets the expressions.
  • dialect: the dialect used to parse the input expressions.
  • copy: if False, modify this expression instance in-place.
  • opts: other options to use to parse the input expressions.
Returns:

The modified Select expression.

def join( self, expression: Union[str, Expression], on: Union[str, Expression, NoneType] = None, using: Union[str, Expression, Collection[Union[str, Expression]], NoneType] = None, append: bool = True, join_type: Optional[str] = None, join_alias: Union[Identifier, str, NoneType] = None, dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, copy: bool = True, **opts) -> Select:
3036    def join(
3037        self,
3038        expression: ExpOrStr,
3039        on: t.Optional[ExpOrStr] = None,
3040        using: t.Optional[ExpOrStr | t.Collection[ExpOrStr]] = None,
3041        append: bool = True,
3042        join_type: t.Optional[str] = None,
3043        join_alias: t.Optional[Identifier | str] = None,
3044        dialect: DialectType = None,
3045        copy: bool = True,
3046        **opts,
3047    ) -> Select:
3048        """
3049        Append to or set the JOIN expressions.
3050
3051        Example:
3052            >>> Select().select("*").from_("tbl").join("tbl2", on="tbl1.y = tbl2.y").sql()
3053            'SELECT * FROM tbl JOIN tbl2 ON tbl1.y = tbl2.y'
3054
3055            >>> Select().select("1").from_("a").join("b", using=["x", "y", "z"]).sql()
3056            'SELECT 1 FROM a JOIN b USING (x, y, z)'
3057
3058            Use `join_type` to change the type of join:
3059
3060            >>> Select().select("*").from_("tbl").join("tbl2", on="tbl1.y = tbl2.y", join_type="left outer").sql()
3061            'SELECT * FROM tbl LEFT OUTER JOIN tbl2 ON tbl1.y = tbl2.y'
3062
3063        Args:
3064            expression: the SQL code string to parse.
3065                If an `Expression` instance is passed, it will be used as-is.
3066            on: optionally specify the join "on" criteria as a SQL string.
3067                If an `Expression` instance is passed, it will be used as-is.
3068            using: optionally specify the join "using" criteria as a SQL string.
3069                If an `Expression` instance is passed, it will be used as-is.
3070            append: if `True`, add to any existing expressions.
3071                Otherwise, this resets the expressions.
3072            join_type: if set, alter the parsed join type.
3073            join_alias: an optional alias for the joined source.
3074            dialect: the dialect used to parse the input expressions.
3075            copy: if `False`, modify this expression instance in-place.
3076            opts: other options to use to parse the input expressions.
3077
3078        Returns:
3079            Select: the modified expression.
3080        """
3081        parse_args: t.Dict[str, t.Any] = {"dialect": dialect, **opts}
3082
3083        try:
3084            expression = maybe_parse(expression, into=Join, prefix="JOIN", **parse_args)
3085        except ParseError:
3086            expression = maybe_parse(expression, into=(Join, Expression), **parse_args)
3087
3088        join = expression if isinstance(expression, Join) else Join(this=expression)
3089
3090        if isinstance(join.this, Select):
3091            join.this.replace(join.this.subquery())
3092
3093        if join_type:
3094            method: t.Optional[Token]
3095            side: t.Optional[Token]
3096            kind: t.Optional[Token]
3097
3098            method, side, kind = maybe_parse(join_type, into="JOIN_TYPE", **parse_args)  # type: ignore
3099
3100            if method:
3101                join.set("method", method.text)
3102            if side:
3103                join.set("side", side.text)
3104            if kind:
3105                join.set("kind", kind.text)
3106
3107        if on:
3108            on = and_(*ensure_list(on), dialect=dialect, copy=copy, **opts)
3109            join.set("on", on)
3110
3111        if using:
3112            join = _apply_list_builder(
3113                *ensure_list(using),
3114                instance=join,
3115                arg="using",
3116                append=append,
3117                copy=copy,
3118                into=Identifier,
3119                **opts,
3120            )
3121
3122        if join_alias:
3123            join.set("this", alias_(join.this, join_alias, table=True))
3124
3125        return _apply_list_builder(
3126            join,
3127            instance=self,
3128            arg="joins",
3129            append=append,
3130            copy=copy,
3131            **opts,
3132        )

Append to or set the JOIN expressions.

Example:
>>> Select().select("*").from_("tbl").join("tbl2", on="tbl1.y = tbl2.y").sql()
'SELECT * FROM tbl JOIN tbl2 ON tbl1.y = tbl2.y'
>>> Select().select("1").from_("a").join("b", using=["x", "y", "z"]).sql()
'SELECT 1 FROM a JOIN b USING (x, y, z)'

Use join_type to change the type of join:

>>> Select().select("*").from_("tbl").join("tbl2", on="tbl1.y = tbl2.y", join_type="left outer").sql()
'SELECT * FROM tbl LEFT OUTER JOIN tbl2 ON tbl1.y = tbl2.y'
Arguments:
  • expression: the SQL code string to parse. If an Expression instance is passed, it will be used as-is.
  • on: optionally specify the join "on" criteria as a SQL string. If an Expression instance is passed, it will be used as-is.
  • using: optionally specify the join "using" criteria as a SQL string. If an Expression instance is passed, it will be used as-is.
  • append: if True, add to any existing expressions. Otherwise, this resets the expressions.
  • join_type: if set, alter the parsed join type.
  • join_alias: an optional alias for the joined source.
  • dialect: the dialect used to parse the input expressions.
  • copy: if False, modify this expression instance in-place.
  • opts: other options to use to parse the input expressions.
Returns:

Select: the modified expression.

def where( self, *expressions: Union[str, Expression, NoneType], append: bool = True, dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, copy: bool = True, **opts) -> Select:
3134    def where(
3135        self,
3136        *expressions: t.Optional[ExpOrStr],
3137        append: bool = True,
3138        dialect: DialectType = None,
3139        copy: bool = True,
3140        **opts,
3141    ) -> Select:
3142        """
3143        Append to or set the WHERE expressions.
3144
3145        Example:
3146            >>> Select().select("x").from_("tbl").where("x = 'a' OR x < 'b'").sql()
3147            "SELECT x FROM tbl WHERE x = 'a' OR x < 'b'"
3148
3149        Args:
3150            *expressions: the SQL code strings to parse.
3151                If an `Expression` instance is passed, it will be used as-is.
3152                Multiple expressions are combined with an AND operator.
3153            append: if `True`, AND the new expressions to any existing expression.
3154                Otherwise, this resets the expression.
3155            dialect: the dialect used to parse the input expressions.
3156            copy: if `False`, modify this expression instance in-place.
3157            opts: other options to use to parse the input expressions.
3158
3159        Returns:
3160            Select: the modified expression.
3161        """
3162        return _apply_conjunction_builder(
3163            *expressions,
3164            instance=self,
3165            arg="where",
3166            append=append,
3167            into=Where,
3168            dialect=dialect,
3169            copy=copy,
3170            **opts,
3171        )

Append to or set the WHERE expressions.

Example:
>>> Select().select("x").from_("tbl").where("x = 'a' OR x < 'b'").sql()
"SELECT x FROM tbl WHERE x = 'a' OR x < 'b'"
Arguments:
  • *expressions: the SQL code strings to parse. If an Expression instance is passed, it will be used as-is. Multiple expressions are combined with an AND operator.
  • append: if True, AND the new expressions to any existing expression. Otherwise, this resets the expression.
  • dialect: the dialect used to parse the input expressions.
  • copy: if False, modify this expression instance in-place.
  • opts: other options to use to parse the input expressions.
Returns:

Select: the modified expression.

def having( self, *expressions: Union[str, Expression, NoneType], append: bool = True, dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, copy: bool = True, **opts) -> Select:
3173    def having(
3174        self,
3175        *expressions: t.Optional[ExpOrStr],
3176        append: bool = True,
3177        dialect: DialectType = None,
3178        copy: bool = True,
3179        **opts,
3180    ) -> Select:
3181        """
3182        Append to or set the HAVING expressions.
3183
3184        Example:
3185            >>> Select().select("x", "COUNT(y)").from_("tbl").group_by("x").having("COUNT(y) > 3").sql()
3186            'SELECT x, COUNT(y) FROM tbl GROUP BY x HAVING COUNT(y) > 3'
3187
3188        Args:
3189            *expressions: the SQL code strings to parse.
3190                If an `Expression` instance is passed, it will be used as-is.
3191                Multiple expressions are combined with an AND operator.
3192            append: if `True`, AND the new expressions to any existing expression.
3193                Otherwise, this resets the expression.
3194            dialect: the dialect used to parse the input expressions.
3195            copy: if `False`, modify this expression instance in-place.
3196            opts: other options to use to parse the input expressions.
3197
3198        Returns:
3199            The modified Select expression.
3200        """
3201        return _apply_conjunction_builder(
3202            *expressions,
3203            instance=self,
3204            arg="having",
3205            append=append,
3206            into=Having,
3207            dialect=dialect,
3208            copy=copy,
3209            **opts,
3210        )

Append to or set the HAVING expressions.

Example:
>>> Select().select("x", "COUNT(y)").from_("tbl").group_by("x").having("COUNT(y) > 3").sql()
'SELECT x, COUNT(y) FROM tbl GROUP BY x HAVING COUNT(y) > 3'
Arguments:
  • *expressions: the SQL code strings to parse. If an Expression instance is passed, it will be used as-is. Multiple expressions are combined with an AND operator.
  • append: if True, AND the new expressions to any existing expression. Otherwise, this resets the expression.
  • dialect: the dialect used to parse the input expressions.
  • copy: if False, modify this expression instance in-place.
  • opts: other options to use to parse the input expressions.
Returns:

The modified Select expression.

def window( self, *expressions: Union[str, Expression, NoneType], append: bool = True, dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, copy: bool = True, **opts) -> Select:
3212    def window(
3213        self,
3214        *expressions: t.Optional[ExpOrStr],
3215        append: bool = True,
3216        dialect: DialectType = None,
3217        copy: bool = True,
3218        **opts,
3219    ) -> Select:
3220        return _apply_list_builder(
3221            *expressions,
3222            instance=self,
3223            arg="windows",
3224            append=append,
3225            into=Window,
3226            dialect=dialect,
3227            copy=copy,
3228            **opts,
3229        )
def qualify( self, *expressions: Union[str, Expression, NoneType], append: bool = True, dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, copy: bool = True, **opts) -> Select:
3231    def qualify(
3232        self,
3233        *expressions: t.Optional[ExpOrStr],
3234        append: bool = True,
3235        dialect: DialectType = None,
3236        copy: bool = True,
3237        **opts,
3238    ) -> Select:
3239        return _apply_conjunction_builder(
3240            *expressions,
3241            instance=self,
3242            arg="qualify",
3243            append=append,
3244            into=Qualify,
3245            dialect=dialect,
3246            copy=copy,
3247            **opts,
3248        )
def distinct( self, *ons: Union[str, Expression, NoneType], distinct: bool = True, copy: bool = True) -> Select:
3250    def distinct(
3251        self, *ons: t.Optional[ExpOrStr], distinct: bool = True, copy: bool = True
3252    ) -> Select:
3253        """
3254        Set the OFFSET expression.
3255
3256        Example:
3257            >>> Select().from_("tbl").select("x").distinct().sql()
3258            'SELECT DISTINCT x FROM tbl'
3259
3260        Args:
3261            ons: the expressions to distinct on
3262            distinct: whether the Select should be distinct
3263            copy: if `False`, modify this expression instance in-place.
3264
3265        Returns:
3266            Select: the modified expression.
3267        """
3268        instance = maybe_copy(self, copy)
3269        on = Tuple(expressions=[maybe_parse(on, copy=copy) for on in ons if on]) if ons else None
3270        instance.set("distinct", Distinct(on=on) if distinct else None)
3271        return instance

Set the OFFSET expression.

Example:
>>> Select().from_("tbl").select("x").distinct().sql()
'SELECT DISTINCT x FROM tbl'
Arguments:
  • ons: the expressions to distinct on
  • distinct: whether the Select should be distinct
  • copy: if False, modify this expression instance in-place.
Returns:

Select: the modified expression.

def ctas( self, table: Union[str, Expression], properties: Optional[Dict] = None, dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, copy: bool = True, **opts) -> Create:
3273    def ctas(
3274        self,
3275        table: ExpOrStr,
3276        properties: t.Optional[t.Dict] = None,
3277        dialect: DialectType = None,
3278        copy: bool = True,
3279        **opts,
3280    ) -> Create:
3281        """
3282        Convert this expression to a CREATE TABLE AS statement.
3283
3284        Example:
3285            >>> Select().select("*").from_("tbl").ctas("x").sql()
3286            'CREATE TABLE x AS SELECT * FROM tbl'
3287
3288        Args:
3289            table: the SQL code string to parse as the table name.
3290                If another `Expression` instance is passed, it will be used as-is.
3291            properties: an optional mapping of table properties
3292            dialect: the dialect used to parse the input table.
3293            copy: if `False`, modify this expression instance in-place.
3294            opts: other options to use to parse the input table.
3295
3296        Returns:
3297            The new Create expression.
3298        """
3299        instance = maybe_copy(self, copy)
3300        table_expression = maybe_parse(
3301            table,
3302            into=Table,
3303            dialect=dialect,
3304            **opts,
3305        )
3306        properties_expression = None
3307        if properties:
3308            properties_expression = Properties.from_dict(properties)
3309
3310        return Create(
3311            this=table_expression,
3312            kind="table",
3313            expression=instance,
3314            properties=properties_expression,
3315        )

Convert this expression to a CREATE TABLE AS statement.

Example:
>>> Select().select("*").from_("tbl").ctas("x").sql()
'CREATE TABLE x AS SELECT * FROM tbl'
Arguments:
  • table: the SQL code string to parse as the table name. If another Expression instance is passed, it will be used as-is.
  • properties: an optional mapping of table properties
  • dialect: the dialect used to parse the input table.
  • copy: if False, modify this expression instance in-place.
  • opts: other options to use to parse the input table.
Returns:

The new Create expression.

def lock( self, update: bool = True, copy: bool = True) -> Select:
3317    def lock(self, update: bool = True, copy: bool = True) -> Select:
3318        """
3319        Set the locking read mode for this expression.
3320
3321        Examples:
3322            >>> Select().select("x").from_("tbl").where("x = 'a'").lock().sql("mysql")
3323            "SELECT x FROM tbl WHERE x = 'a' FOR UPDATE"
3324
3325            >>> Select().select("x").from_("tbl").where("x = 'a'").lock(update=False).sql("mysql")
3326            "SELECT x FROM tbl WHERE x = 'a' FOR SHARE"
3327
3328        Args:
3329            update: if `True`, the locking type will be `FOR UPDATE`, else it will be `FOR SHARE`.
3330            copy: if `False`, modify this expression instance in-place.
3331
3332        Returns:
3333            The modified expression.
3334        """
3335        inst = maybe_copy(self, copy)
3336        inst.set("locks", [Lock(update=update)])
3337
3338        return inst

Set the locking read mode for this expression.

Examples:
>>> Select().select("x").from_("tbl").where("x = 'a'").lock().sql("mysql")
"SELECT x FROM tbl WHERE x = 'a' FOR UPDATE"
>>> Select().select("x").from_("tbl").where("x = 'a'").lock(update=False).sql("mysql")
"SELECT x FROM tbl WHERE x = 'a' FOR SHARE"
Arguments:
  • update: if True, the locking type will be FOR UPDATE, else it will be FOR SHARE.
  • copy: if False, modify this expression instance in-place.
Returns:

The modified expression.

def hint( self, *hints: Union[str, Expression], dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, copy: bool = True) -> Select:
3340    def hint(self, *hints: ExpOrStr, dialect: DialectType = None, copy: bool = True) -> Select:
3341        """
3342        Set hints for this expression.
3343
3344        Examples:
3345            >>> Select().select("x").from_("tbl").hint("BROADCAST(y)").sql(dialect="spark")
3346            'SELECT /*+ BROADCAST(y) */ x FROM tbl'
3347
3348        Args:
3349            hints: The SQL code strings to parse as the hints.
3350                If an `Expression` instance is passed, it will be used as-is.
3351            dialect: The dialect used to parse the hints.
3352            copy: If `False`, modify this expression instance in-place.
3353
3354        Returns:
3355            The modified expression.
3356        """
3357        inst = maybe_copy(self, copy)
3358        inst.set(
3359            "hint", Hint(expressions=[maybe_parse(h, copy=copy, dialect=dialect) for h in hints])
3360        )
3361
3362        return inst

Set hints for this expression.

Examples:
>>> Select().select("x").from_("tbl").hint("BROADCAST(y)").sql(dialect="spark")
'SELECT /*+ BROADCAST(y) */ x FROM tbl'
Arguments:
  • hints: The SQL code strings to parse as the hints. If an Expression instance is passed, it will be used as-is.
  • dialect: The dialect used to parse the hints.
  • copy: If False, modify this expression instance in-place.
Returns:

The modified expression.

named_selects: List[str]
is_star: bool

Checks whether an expression is a star.

selects: List[Expression]
key = 'select'
class Subquery(DerivedTable, Unionable):
3377class Subquery(DerivedTable, Unionable):
3378    arg_types = {
3379        "this": True,
3380        "alias": False,
3381        "with": False,
3382        **QUERY_MODIFIERS,
3383    }
3384
3385    def unnest(self):
3386        """
3387        Returns the first non subquery.
3388        """
3389        expression = self
3390        while isinstance(expression, Subquery):
3391            expression = expression.this
3392        return expression
3393
3394    def unwrap(self) -> Subquery:
3395        expression = self
3396        while expression.same_parent and expression.is_wrapper:
3397            expression = t.cast(Subquery, expression.parent)
3398        return expression
3399
3400    @property
3401    def is_wrapper(self) -> bool:
3402        """
3403        Whether this Subquery acts as a simple wrapper around another expression.
3404
3405        SELECT * FROM (((SELECT * FROM t)))
3406                      ^
3407                      This corresponds to a "wrapper" Subquery node
3408        """
3409        return all(v is None for k, v in self.args.items() if k != "this")
3410
3411    @property
3412    def is_star(self) -> bool:
3413        return self.this.is_star
3414
3415    @property
3416    def output_name(self) -> str:
3417        return self.alias
arg_types = {'this': True, 'alias': False, 'with': False, 'match': False, 'laterals': False, 'joins': False, 'connect': False, 'pivots': False, 'where': False, 'group': False, 'having': False, 'qualify': False, 'windows': False, 'distribute': False, 'sort': False, 'cluster': False, 'order': False, 'limit': False, 'offset': False, 'locks': False, 'sample': False, 'settings': False, 'format': False}
def unnest(self):
3385    def unnest(self):
3386        """
3387        Returns the first non subquery.
3388        """
3389        expression = self
3390        while isinstance(expression, Subquery):
3391            expression = expression.this
3392        return expression

Returns the first non subquery.

def unwrap(self) -> Subquery:
3394    def unwrap(self) -> Subquery:
3395        expression = self
3396        while expression.same_parent and expression.is_wrapper:
3397            expression = t.cast(Subquery, expression.parent)
3398        return expression
is_wrapper: bool

Whether this Subquery acts as a simple wrapper around another expression.

SELECT * FROM (((SELECT * FROM t))) ^ This corresponds to a "wrapper" Subquery node

is_star: bool

Checks whether an expression is a star.

output_name: str

Name of the output column if this expression is a selection.

If the Expression has no output name, an empty string is returned.

Example:
>>> from sqlglot import parse_one
>>> parse_one("SELECT a")sqlglot.expressions[0].output_name
'a'
>>> parse_one("SELECT b AS c")sqlglot.expressions[0].output_name
'c'
>>> parse_one("SELECT 1 + 2")sqlglot.expressions[0].output_name
''
key = 'subquery'
class TableSample(Expression):
3420class TableSample(Expression):
3421    arg_types = {
3422        "this": False,
3423        "expressions": False,
3424        "method": False,
3425        "bucket_numerator": False,
3426        "bucket_denominator": False,
3427        "bucket_field": False,
3428        "percent": False,
3429        "rows": False,
3430        "size": False,
3431        "seed": False,
3432        "kind": False,
3433    }
arg_types = {'this': False, 'expressions': False, 'method': False, 'bucket_numerator': False, 'bucket_denominator': False, 'bucket_field': False, 'percent': False, 'rows': False, 'size': False, 'seed': False, 'kind': False}
key = 'tablesample'
class Tag(Expression):
3436class Tag(Expression):
3437    """Tags are used for generating arbitrary sql like SELECT <span>x</span>."""
3438
3439    arg_types = {
3440        "this": False,
3441        "prefix": False,
3442        "postfix": False,
3443    }

Tags are used for generating arbitrary sql like SELECT x.

arg_types = {'this': False, 'prefix': False, 'postfix': False}
key = 'tag'
class Pivot(Expression):
3448class Pivot(Expression):
3449    arg_types = {
3450        "this": False,
3451        "alias": False,
3452        "expressions": False,
3453        "field": False,
3454        "unpivot": False,
3455        "using": False,
3456        "group": False,
3457        "columns": False,
3458        "include_nulls": False,
3459    }
arg_types = {'this': False, 'alias': False, 'expressions': False, 'field': False, 'unpivot': False, 'using': False, 'group': False, 'columns': False, 'include_nulls': False}
key = 'pivot'
class Window(Condition):
3462class Window(Condition):
3463    arg_types = {
3464        "this": True,
3465        "partition_by": False,
3466        "order": False,
3467        "spec": False,
3468        "alias": False,
3469        "over": False,
3470        "first": False,
3471    }
arg_types = {'this': True, 'partition_by': False, 'order': False, 'spec': False, 'alias': False, 'over': False, 'first': False}
key = 'window'
class WindowSpec(Expression):
3474class WindowSpec(Expression):
3475    arg_types = {
3476        "kind": False,
3477        "start": False,
3478        "start_side": False,
3479        "end": False,
3480        "end_side": False,
3481    }
arg_types = {'kind': False, 'start': False, 'start_side': False, 'end': False, 'end_side': False}
key = 'windowspec'
class Where(Expression):
3484class Where(Expression):
3485    pass
key = 'where'
class Star(Expression):
3488class Star(Expression):
3489    arg_types = {"except": False, "replace": False}
3490
3491    @property
3492    def name(self) -> str:
3493        return "*"
3494
3495    @property
3496    def output_name(self) -> str:
3497        return self.name
arg_types = {'except': False, 'replace': False}
name: str
output_name: str

Name of the output column if this expression is a selection.

If the Expression has no output name, an empty string is returned.

Example:
>>> from sqlglot import parse_one
>>> parse_one("SELECT a")sqlglot.expressions[0].output_name
'a'
>>> parse_one("SELECT b AS c")sqlglot.expressions[0].output_name
'c'
>>> parse_one("SELECT 1 + 2")sqlglot.expressions[0].output_name
''
key = 'star'
class Parameter(Condition):
3500class Parameter(Condition):
3501    arg_types = {"this": True, "wrapped": False}
arg_types = {'this': True, 'wrapped': False}
key = 'parameter'
class SessionParameter(Condition):
3504class SessionParameter(Condition):
3505    arg_types = {"this": True, "kind": False}
arg_types = {'this': True, 'kind': False}
key = 'sessionparameter'
class Placeholder(Condition):
3508class Placeholder(Condition):
3509    arg_types = {"this": False, "kind": False}
arg_types = {'this': False, 'kind': False}
key = 'placeholder'
class Null(Condition):
3512class Null(Condition):
3513    arg_types: t.Dict[str, t.Any] = {}
3514
3515    @property
3516    def name(self) -> str:
3517        return "NULL"
arg_types: Dict[str, Any] = {}
name: str
key = 'null'
class Boolean(Condition):
3520class Boolean(Condition):
3521    pass
key = 'boolean'
class DataTypeParam(Expression):
3524class DataTypeParam(Expression):
3525    arg_types = {"this": True, "expression": False}
arg_types = {'this': True, 'expression': False}
key = 'datatypeparam'
class DataType(Expression):
3528class DataType(Expression):
3529    arg_types = {
3530        "this": True,
3531        "expressions": False,
3532        "nested": False,
3533        "values": False,
3534        "prefix": False,
3535        "kind": False,
3536    }
3537
3538    class Type(AutoName):
3539        ARRAY = auto()
3540        BIGDECIMAL = auto()
3541        BIGINT = auto()
3542        BIGSERIAL = auto()
3543        BINARY = auto()
3544        BIT = auto()
3545        BOOLEAN = auto()
3546        CHAR = auto()
3547        DATE = auto()
3548        DATEMULTIRANGE = auto()
3549        DATERANGE = auto()
3550        DATETIME = auto()
3551        DATETIME64 = auto()
3552        DECIMAL = auto()
3553        DOUBLE = auto()
3554        ENUM = auto()
3555        ENUM8 = auto()
3556        ENUM16 = auto()
3557        FIXEDSTRING = auto()
3558        FLOAT = auto()
3559        GEOGRAPHY = auto()
3560        GEOMETRY = auto()
3561        HLLSKETCH = auto()
3562        HSTORE = auto()
3563        IMAGE = auto()
3564        INET = auto()
3565        INT = auto()
3566        INT128 = auto()
3567        INT256 = auto()
3568        INT4MULTIRANGE = auto()
3569        INT4RANGE = auto()
3570        INT8MULTIRANGE = auto()
3571        INT8RANGE = auto()
3572        INTERVAL = auto()
3573        IPADDRESS = auto()
3574        IPPREFIX = auto()
3575        JSON = auto()
3576        JSONB = auto()
3577        LONGBLOB = auto()
3578        LONGTEXT = auto()
3579        LOWCARDINALITY = auto()
3580        MAP = auto()
3581        MEDIUMBLOB = auto()
3582        MEDIUMINT = auto()
3583        MEDIUMTEXT = auto()
3584        MONEY = auto()
3585        NCHAR = auto()
3586        NESTED = auto()
3587        NULL = auto()
3588        NULLABLE = auto()
3589        NUMMULTIRANGE = auto()
3590        NUMRANGE = auto()
3591        NVARCHAR = auto()
3592        OBJECT = auto()
3593        ROWVERSION = auto()
3594        SERIAL = auto()
3595        SET = auto()
3596        SMALLINT = auto()
3597        SMALLMONEY = auto()
3598        SMALLSERIAL = auto()
3599        STRUCT = auto()
3600        SUPER = auto()
3601        TEXT = auto()
3602        TINYBLOB = auto()
3603        TINYTEXT = auto()
3604        TIME = auto()
3605        TIMETZ = auto()
3606        TIMESTAMP = auto()
3607        TIMESTAMPLTZ = auto()
3608        TIMESTAMPTZ = auto()
3609        TIMESTAMP_S = auto()
3610        TIMESTAMP_MS = auto()
3611        TIMESTAMP_NS = auto()
3612        TINYINT = auto()
3613        TSMULTIRANGE = auto()
3614        TSRANGE = auto()
3615        TSTZMULTIRANGE = auto()
3616        TSTZRANGE = auto()
3617        UBIGINT = auto()
3618        UINT = auto()
3619        UINT128 = auto()
3620        UINT256 = auto()
3621        UMEDIUMINT = auto()
3622        UDECIMAL = auto()
3623        UNIQUEIDENTIFIER = auto()
3624        UNKNOWN = auto()  # Sentinel value, useful for type annotation
3625        USERDEFINED = "USER-DEFINED"
3626        USMALLINT = auto()
3627        UTINYINT = auto()
3628        UUID = auto()
3629        VARBINARY = auto()
3630        VARCHAR = auto()
3631        VARIANT = auto()
3632        XML = auto()
3633        YEAR = auto()
3634
3635    TEXT_TYPES = {
3636        Type.CHAR,
3637        Type.NCHAR,
3638        Type.VARCHAR,
3639        Type.NVARCHAR,
3640        Type.TEXT,
3641    }
3642
3643    INTEGER_TYPES = {
3644        Type.INT,
3645        Type.TINYINT,
3646        Type.SMALLINT,
3647        Type.BIGINT,
3648        Type.INT128,
3649        Type.INT256,
3650    }
3651
3652    FLOAT_TYPES = {
3653        Type.FLOAT,
3654        Type.DOUBLE,
3655    }
3656
3657    NUMERIC_TYPES = {
3658        *INTEGER_TYPES,
3659        *FLOAT_TYPES,
3660    }
3661
3662    TEMPORAL_TYPES = {
3663        Type.TIME,
3664        Type.TIMETZ,
3665        Type.TIMESTAMP,
3666        Type.TIMESTAMPTZ,
3667        Type.TIMESTAMPLTZ,
3668        Type.TIMESTAMP_S,
3669        Type.TIMESTAMP_MS,
3670        Type.TIMESTAMP_NS,
3671        Type.DATE,
3672        Type.DATETIME,
3673        Type.DATETIME64,
3674    }
3675
3676    @classmethod
3677    def build(
3678        cls,
3679        dtype: str | DataType | DataType.Type,
3680        dialect: DialectType = None,
3681        udt: bool = False,
3682        **kwargs,
3683    ) -> DataType:
3684        """
3685        Constructs a DataType object.
3686
3687        Args:
3688            dtype: the data type of interest.
3689            dialect: the dialect to use for parsing `dtype`, in case it's a string.
3690            udt: when set to True, `dtype` will be used as-is if it can't be parsed into a
3691                DataType, thus creating a user-defined type.
3692            kawrgs: additional arguments to pass in the constructor of DataType.
3693
3694        Returns:
3695            The constructed DataType object.
3696        """
3697        from sqlglot import parse_one
3698
3699        if isinstance(dtype, str):
3700            if dtype.upper() == "UNKNOWN":
3701                return DataType(this=DataType.Type.UNKNOWN, **kwargs)
3702
3703            try:
3704                data_type_exp = parse_one(dtype, read=dialect, into=DataType)
3705            except ParseError:
3706                if udt:
3707                    return DataType(this=DataType.Type.USERDEFINED, kind=dtype, **kwargs)
3708                raise
3709        elif isinstance(dtype, DataType.Type):
3710            data_type_exp = DataType(this=dtype)
3711        elif isinstance(dtype, DataType):
3712            return dtype
3713        else:
3714            raise ValueError(f"Invalid data type: {type(dtype)}. Expected str or DataType.Type")
3715
3716        return DataType(**{**data_type_exp.args, **kwargs})
3717
3718    def is_type(self, *dtypes: str | DataType | DataType.Type) -> bool:
3719        """
3720        Checks whether this DataType matches one of the provided data types. Nested types or precision
3721        will be compared using "structural equivalence" semantics, so e.g. array<int> != array<float>.
3722
3723        Args:
3724            dtypes: the data types to compare this DataType to.
3725
3726        Returns:
3727            True, if and only if there is a type in `dtypes` which is equal to this DataType.
3728        """
3729        for dtype in dtypes:
3730            other = DataType.build(dtype, udt=True)
3731
3732            if (
3733                other.expressions
3734                or self.this == DataType.Type.USERDEFINED
3735                or other.this == DataType.Type.USERDEFINED
3736            ):
3737                matches = self == other
3738            else:
3739                matches = self.this == other.this
3740
3741            if matches:
3742                return True
3743        return False
arg_types = {'this': True, 'expressions': False, 'nested': False, 'values': False, 'prefix': False, 'kind': False}
TEXT_TYPES = {<Type.TEXT: 'TEXT'>, <Type.CHAR: 'CHAR'>, <Type.VARCHAR: 'VARCHAR'>, <Type.NVARCHAR: 'NVARCHAR'>, <Type.NCHAR: 'NCHAR'>}
INTEGER_TYPES = {<Type.SMALLINT: 'SMALLINT'>, <Type.BIGINT: 'BIGINT'>, <Type.INT128: 'INT128'>, <Type.INT: 'INT'>, <Type.TINYINT: 'TINYINT'>, <Type.INT256: 'INT256'>}
FLOAT_TYPES = {<Type.FLOAT: 'FLOAT'>, <Type.DOUBLE: 'DOUBLE'>}
NUMERIC_TYPES = {<Type.SMALLINT: 'SMALLINT'>, <Type.BIGINT: 'BIGINT'>, <Type.TINYINT: 'TINYINT'>, <Type.INT128: 'INT128'>, <Type.FLOAT: 'FLOAT'>, <Type.INT256: 'INT256'>, <Type.DOUBLE: 'DOUBLE'>, <Type.INT: 'INT'>}
TEMPORAL_TYPES = {<Type.TIMESTAMPLTZ: 'TIMESTAMPLTZ'>, <Type.TIMESTAMPTZ: 'TIMESTAMPTZ'>, <Type.TIMESTAMP_NS: 'TIMESTAMP_NS'>, <Type.DATETIME64: 'DATETIME64'>, <Type.TIME: 'TIME'>, <Type.TIMESTAMP_MS: 'TIMESTAMP_MS'>, <Type.DATE: 'DATE'>, <Type.DATETIME: 'DATETIME'>, <Type.TIMESTAMP: 'TIMESTAMP'>, <Type.TIMESTAMP_S: 'TIMESTAMP_S'>, <Type.TIMETZ: 'TIMETZ'>}
@classmethod
def build( cls, dtype: str | DataType | DataType.Type, dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, udt: bool = False, **kwargs) -> DataType:
3676    @classmethod
3677    def build(
3678        cls,
3679        dtype: str | DataType | DataType.Type,
3680        dialect: DialectType = None,
3681        udt: bool = False,
3682        **kwargs,
3683    ) -> DataType:
3684        """
3685        Constructs a DataType object.
3686
3687        Args:
3688            dtype: the data type of interest.
3689            dialect: the dialect to use for parsing `dtype`, in case it's a string.
3690            udt: when set to True, `dtype` will be used as-is if it can't be parsed into a
3691                DataType, thus creating a user-defined type.
3692            kawrgs: additional arguments to pass in the constructor of DataType.
3693
3694        Returns:
3695            The constructed DataType object.
3696        """
3697        from sqlglot import parse_one
3698
3699        if isinstance(dtype, str):
3700            if dtype.upper() == "UNKNOWN":
3701                return DataType(this=DataType.Type.UNKNOWN, **kwargs)
3702
3703            try:
3704                data_type_exp = parse_one(dtype, read=dialect, into=DataType)
3705            except ParseError:
3706                if udt:
3707                    return DataType(this=DataType.Type.USERDEFINED, kind=dtype, **kwargs)
3708                raise
3709        elif isinstance(dtype, DataType.Type):
3710            data_type_exp = DataType(this=dtype)
3711        elif isinstance(dtype, DataType):
3712            return dtype
3713        else:
3714            raise ValueError(f"Invalid data type: {type(dtype)}. Expected str or DataType.Type")
3715
3716        return DataType(**{**data_type_exp.args, **kwargs})

Constructs a DataType object.

Arguments:
  • dtype: the data type of interest.
  • dialect: the dialect to use for parsing dtype, in case it's a string.
  • udt: when set to True, dtype will be used as-is if it can't be parsed into a DataType, thus creating a user-defined type.
  • kawrgs: additional arguments to pass in the constructor of DataType.
Returns:

The constructed DataType object.

def is_type( self, *dtypes: str | DataType | DataType.Type) -> bool:
3718    def is_type(self, *dtypes: str | DataType | DataType.Type) -> bool:
3719        """
3720        Checks whether this DataType matches one of the provided data types. Nested types or precision
3721        will be compared using "structural equivalence" semantics, so e.g. array<int> != array<float>.
3722
3723        Args:
3724            dtypes: the data types to compare this DataType to.
3725
3726        Returns:
3727            True, if and only if there is a type in `dtypes` which is equal to this DataType.
3728        """
3729        for dtype in dtypes:
3730            other = DataType.build(dtype, udt=True)
3731
3732            if (
3733                other.expressions
3734                or self.this == DataType.Type.USERDEFINED
3735                or other.this == DataType.Type.USERDEFINED
3736            ):
3737                matches = self == other
3738            else:
3739                matches = self.this == other.this
3740
3741            if matches:
3742                return True
3743        return False

Checks whether this DataType matches one of the provided data types. Nested types or precision will be compared using "structural equivalence" semantics, so e.g. array != array.

Arguments:
  • dtypes: the data types to compare this DataType to.
Returns:

True, if and only if there is a type in dtypes which is equal to this DataType.

key = 'datatype'
class DataType.Type(sqlglot.helper.AutoName):
3538    class Type(AutoName):
3539        ARRAY = auto()
3540        BIGDECIMAL = auto()
3541        BIGINT = auto()
3542        BIGSERIAL = auto()
3543        BINARY = auto()
3544        BIT = auto()
3545        BOOLEAN = auto()
3546        CHAR = auto()
3547        DATE = auto()
3548        DATEMULTIRANGE = auto()
3549        DATERANGE = auto()
3550        DATETIME = auto()
3551        DATETIME64 = auto()
3552        DECIMAL = auto()
3553        DOUBLE = auto()
3554        ENUM = auto()
3555        ENUM8 = auto()
3556        ENUM16 = auto()
3557        FIXEDSTRING = auto()
3558        FLOAT = auto()
3559        GEOGRAPHY = auto()
3560        GEOMETRY = auto()
3561        HLLSKETCH = auto()
3562        HSTORE = auto()
3563        IMAGE = auto()
3564        INET = auto()
3565        INT = auto()
3566        INT128 = auto()
3567        INT256 = auto()
3568        INT4MULTIRANGE = auto()
3569        INT4RANGE = auto()
3570        INT8MULTIRANGE = auto()
3571        INT8RANGE = auto()
3572        INTERVAL = auto()
3573        IPADDRESS = auto()
3574        IPPREFIX = auto()
3575        JSON = auto()
3576        JSONB = auto()
3577        LONGBLOB = auto()
3578        LONGTEXT = auto()
3579        LOWCARDINALITY = auto()
3580        MAP = auto()
3581        MEDIUMBLOB = auto()
3582        MEDIUMINT = auto()
3583        MEDIUMTEXT = auto()
3584        MONEY = auto()
3585        NCHAR = auto()
3586        NESTED = auto()
3587        NULL = auto()
3588        NULLABLE = auto()
3589        NUMMULTIRANGE = auto()
3590        NUMRANGE = auto()
3591        NVARCHAR = auto()
3592        OBJECT = auto()
3593        ROWVERSION = auto()
3594        SERIAL = auto()
3595        SET = auto()
3596        SMALLINT = auto()
3597        SMALLMONEY = auto()
3598        SMALLSERIAL = auto()
3599        STRUCT = auto()
3600        SUPER = auto()
3601        TEXT = auto()
3602        TINYBLOB = auto()
3603        TINYTEXT = auto()
3604        TIME = auto()
3605        TIMETZ = auto()
3606        TIMESTAMP = auto()
3607        TIMESTAMPLTZ = auto()
3608        TIMESTAMPTZ = auto()
3609        TIMESTAMP_S = auto()
3610        TIMESTAMP_MS = auto()
3611        TIMESTAMP_NS = auto()
3612        TINYINT = auto()
3613        TSMULTIRANGE = auto()
3614        TSRANGE = auto()
3615        TSTZMULTIRANGE = auto()
3616        TSTZRANGE = auto()
3617        UBIGINT = auto()
3618        UINT = auto()
3619        UINT128 = auto()
3620        UINT256 = auto()
3621        UMEDIUMINT = auto()
3622        UDECIMAL = auto()
3623        UNIQUEIDENTIFIER = auto()
3624        UNKNOWN = auto()  # Sentinel value, useful for type annotation
3625        USERDEFINED = "USER-DEFINED"
3626        USMALLINT = auto()
3627        UTINYINT = auto()
3628        UUID = auto()
3629        VARBINARY = auto()
3630        VARCHAR = auto()
3631        VARIANT = auto()
3632        XML = auto()
3633        YEAR = auto()

An enumeration.

ARRAY = <Type.ARRAY: 'ARRAY'>
BIGDECIMAL = <Type.BIGDECIMAL: 'BIGDECIMAL'>
BIGINT = <Type.BIGINT: 'BIGINT'>
BIGSERIAL = <Type.BIGSERIAL: 'BIGSERIAL'>
BINARY = <Type.BINARY: 'BINARY'>
BIT = <Type.BIT: 'BIT'>
BOOLEAN = <Type.BOOLEAN: 'BOOLEAN'>
CHAR = <Type.CHAR: 'CHAR'>
DATE = <Type.DATE: 'DATE'>
DATEMULTIRANGE = <Type.DATEMULTIRANGE: 'DATEMULTIRANGE'>
DATERANGE = <Type.DATERANGE: 'DATERANGE'>
DATETIME = <Type.DATETIME: 'DATETIME'>
DATETIME64 = <Type.DATETIME64: 'DATETIME64'>
DECIMAL = <Type.DECIMAL: 'DECIMAL'>
DOUBLE = <Type.DOUBLE: 'DOUBLE'>
ENUM = <Type.ENUM: 'ENUM'>
ENUM8 = <Type.ENUM8: 'ENUM8'>
ENUM16 = <Type.ENUM16: 'ENUM16'>
FIXEDSTRING = <Type.FIXEDSTRING: 'FIXEDSTRING'>
FLOAT = <Type.FLOAT: 'FLOAT'>
GEOGRAPHY = <Type.GEOGRAPHY: 'GEOGRAPHY'>
GEOMETRY = <Type.GEOMETRY: 'GEOMETRY'>
HLLSKETCH = <Type.HLLSKETCH: 'HLLSKETCH'>
HSTORE = <Type.HSTORE: 'HSTORE'>
IMAGE = <Type.IMAGE: 'IMAGE'>
INET = <Type.INET: 'INET'>
INT = <Type.INT: 'INT'>
INT128 = <Type.INT128: 'INT128'>
INT256 = <Type.INT256: 'INT256'>
INT4MULTIRANGE = <Type.INT4MULTIRANGE: 'INT4MULTIRANGE'>
INT4RANGE = <Type.INT4RANGE: 'INT4RANGE'>
INT8MULTIRANGE = <Type.INT8MULTIRANGE: 'INT8MULTIRANGE'>
INT8RANGE = <Type.INT8RANGE: 'INT8RANGE'>
INTERVAL = <Type.INTERVAL: 'INTERVAL'>
IPADDRESS = <Type.IPADDRESS: 'IPADDRESS'>
IPPREFIX = <Type.IPPREFIX: 'IPPREFIX'>
JSON = <Type.JSON: 'JSON'>
JSONB = <Type.JSONB: 'JSONB'>
LONGBLOB = <Type.LONGBLOB: 'LONGBLOB'>
LONGTEXT = <Type.LONGTEXT: 'LONGTEXT'>
LOWCARDINALITY = <Type.LOWCARDINALITY: 'LOWCARDINALITY'>
MAP = <Type.MAP: 'MAP'>
MEDIUMBLOB = <Type.MEDIUMBLOB: 'MEDIUMBLOB'>
MEDIUMINT = <Type.MEDIUMINT: 'MEDIUMINT'>
MEDIUMTEXT = <Type.MEDIUMTEXT: 'MEDIUMTEXT'>
MONEY = <Type.MONEY: 'MONEY'>
NCHAR = <Type.NCHAR: 'NCHAR'>
NESTED = <Type.NESTED: 'NESTED'>
NULL = <Type.NULL: 'NULL'>
NULLABLE = <Type.NULLABLE: 'NULLABLE'>
NUMMULTIRANGE = <Type.NUMMULTIRANGE: 'NUMMULTIRANGE'>
NUMRANGE = <Type.NUMRANGE: 'NUMRANGE'>
NVARCHAR = <Type.NVARCHAR: 'NVARCHAR'>
OBJECT = <Type.OBJECT: 'OBJECT'>
ROWVERSION = <Type.ROWVERSION: 'ROWVERSION'>
SERIAL = <Type.SERIAL: 'SERIAL'>
SET = <Type.SET: 'SET'>
SMALLINT = <Type.SMALLINT: 'SMALLINT'>
SMALLMONEY = <Type.SMALLMONEY: 'SMALLMONEY'>
SMALLSERIAL = <Type.SMALLSERIAL: 'SMALLSERIAL'>
STRUCT = <Type.STRUCT: 'STRUCT'>
SUPER = <Type.SUPER: 'SUPER'>
TEXT = <Type.TEXT: 'TEXT'>
TINYBLOB = <Type.TINYBLOB: 'TINYBLOB'>
TINYTEXT = <Type.TINYTEXT: 'TINYTEXT'>
TIME = <Type.TIME: 'TIME'>
TIMETZ = <Type.TIMETZ: 'TIMETZ'>
TIMESTAMP = <Type.TIMESTAMP: 'TIMESTAMP'>
TIMESTAMPLTZ = <Type.TIMESTAMPLTZ: 'TIMESTAMPLTZ'>
TIMESTAMPTZ = <Type.TIMESTAMPTZ: 'TIMESTAMPTZ'>
TIMESTAMP_S = <Type.TIMESTAMP_S: 'TIMESTAMP_S'>
TIMESTAMP_MS = <Type.TIMESTAMP_MS: 'TIMESTAMP_MS'>
TIMESTAMP_NS = <Type.TIMESTAMP_NS: 'TIMESTAMP_NS'>
TINYINT = <Type.TINYINT: 'TINYINT'>
TSMULTIRANGE = <Type.TSMULTIRANGE: 'TSMULTIRANGE'>
TSRANGE = <Type.TSRANGE: 'TSRANGE'>
TSTZMULTIRANGE = <Type.TSTZMULTIRANGE: 'TSTZMULTIRANGE'>
TSTZRANGE = <Type.TSTZRANGE: 'TSTZRANGE'>
UBIGINT = <Type.UBIGINT: 'UBIGINT'>
UINT = <Type.UINT: 'UINT'>
UINT128 = <Type.UINT128: 'UINT128'>
UINT256 = <Type.UINT256: 'UINT256'>
UMEDIUMINT = <Type.UMEDIUMINT: 'UMEDIUMINT'>
UDECIMAL = <Type.UDECIMAL: 'UDECIMAL'>
UNIQUEIDENTIFIER = <Type.UNIQUEIDENTIFIER: 'UNIQUEIDENTIFIER'>
UNKNOWN = <Type.UNKNOWN: 'UNKNOWN'>
USERDEFINED = <Type.USERDEFINED: 'USER-DEFINED'>
USMALLINT = <Type.USMALLINT: 'USMALLINT'>
UTINYINT = <Type.UTINYINT: 'UTINYINT'>
UUID = <Type.UUID: 'UUID'>
VARBINARY = <Type.VARBINARY: 'VARBINARY'>
VARCHAR = <Type.VARCHAR: 'VARCHAR'>
VARIANT = <Type.VARIANT: 'VARIANT'>
XML = <Type.XML: 'XML'>
YEAR = <Type.YEAR: 'YEAR'>
Inherited Members
enum.Enum
name
value
class PseudoType(DataType):
3747class PseudoType(DataType):
3748    arg_types = {"this": True}
arg_types = {'this': True}
key = 'pseudotype'
class ObjectIdentifier(DataType):
3752class ObjectIdentifier(DataType):
3753    arg_types = {"this": True}
arg_types = {'this': True}
key = 'objectidentifier'
class SubqueryPredicate(Predicate):
3757class SubqueryPredicate(Predicate):
3758    pass
key = 'subquerypredicate'
class All(SubqueryPredicate):
3761class All(SubqueryPredicate):
3762    pass
key = 'all'
class Any(SubqueryPredicate):
3765class Any(SubqueryPredicate):
3766    pass
key = 'any'
class Exists(SubqueryPredicate):
3769class Exists(SubqueryPredicate):
3770    pass
key = 'exists'
class Command(Expression):
3775class Command(Expression):
3776    arg_types = {"this": True, "expression": False}
arg_types = {'this': True, 'expression': False}
key = 'command'
class Transaction(Expression):
3779class Transaction(Expression):
3780    arg_types = {"this": False, "modes": False, "mark": False}
arg_types = {'this': False, 'modes': False, 'mark': False}
key = 'transaction'
class Commit(Expression):
3783class Commit(Expression):
3784    arg_types = {"chain": False, "this": False, "durability": False}
arg_types = {'chain': False, 'this': False, 'durability': False}
key = 'commit'
class Rollback(Expression):
3787class Rollback(Expression):
3788    arg_types = {"savepoint": False, "this": False}
arg_types = {'savepoint': False, 'this': False}
key = 'rollback'
class AlterTable(Expression):
3791class AlterTable(Expression):
3792    arg_types = {"this": True, "actions": True, "exists": False, "only": False}
arg_types = {'this': True, 'actions': True, 'exists': False, 'only': False}
key = 'altertable'
class AddConstraint(Expression):
3795class AddConstraint(Expression):
3796    arg_types = {"this": False, "expression": False, "enforced": False}
arg_types = {'this': False, 'expression': False, 'enforced': False}
key = 'addconstraint'
class DropPartition(Expression):
3799class DropPartition(Expression):
3800    arg_types = {"expressions": True, "exists": False}
arg_types = {'expressions': True, 'exists': False}
key = 'droppartition'
class Binary(Condition):
3804class Binary(Condition):
3805    arg_types = {"this": True, "expression": True}
3806
3807    @property
3808    def left(self) -> Expression:
3809        return self.this
3810
3811    @property
3812    def right(self) -> Expression:
3813        return self.expression
arg_types = {'this': True, 'expression': True}
left: Expression
right: Expression
key = 'binary'
class Add(Binary):
3816class Add(Binary):
3817    pass
key = 'add'
class Connector(Binary):
3820class Connector(Binary):
3821    pass
key = 'connector'
class And(Connector):
3824class And(Connector):
3825    pass
key = 'and'
class Or(Connector):
3828class Or(Connector):
3829    pass
key = 'or'
class BitwiseAnd(Binary):
3832class BitwiseAnd(Binary):
3833    pass
key = 'bitwiseand'
class BitwiseLeftShift(Binary):
3836class BitwiseLeftShift(Binary):
3837    pass
key = 'bitwiseleftshift'
class BitwiseOr(Binary):
3840class BitwiseOr(Binary):
3841    pass
key = 'bitwiseor'
class BitwiseRightShift(Binary):
3844class BitwiseRightShift(Binary):
3845    pass
key = 'bitwiserightshift'
class BitwiseXor(Binary):
3848class BitwiseXor(Binary):
3849    pass
key = 'bitwisexor'
class Div(Binary):
3852class Div(Binary):
3853    pass
key = 'div'
class Overlaps(Binary):
3856class Overlaps(Binary):
3857    pass
key = 'overlaps'
class Dot(Binary):
3860class Dot(Binary):
3861    @property
3862    def name(self) -> str:
3863        return self.expression.name
3864
3865    @property
3866    def output_name(self) -> str:
3867        return self.name
3868
3869    @classmethod
3870    def build(self, expressions: t.Sequence[Expression]) -> Dot:
3871        """Build a Dot object with a sequence of expressions."""
3872        if len(expressions) < 2:
3873            raise ValueError(f"Dot requires >= 2 expressions.")
3874
3875        return t.cast(Dot, reduce(lambda x, y: Dot(this=x, expression=y), expressions))
name: str
output_name: str

Name of the output column if this expression is a selection.

If the Expression has no output name, an empty string is returned.

Example:
>>> from sqlglot import parse_one
>>> parse_one("SELECT a")sqlglot.expressions[0].output_name
'a'
>>> parse_one("SELECT b AS c")sqlglot.expressions[0].output_name
'c'
>>> parse_one("SELECT 1 + 2")sqlglot.expressions[0].output_name
''
@classmethod
def build( self, expressions: Sequence[Expression]) -> Dot:
3869    @classmethod
3870    def build(self, expressions: t.Sequence[Expression]) -> Dot:
3871        """Build a Dot object with a sequence of expressions."""
3872        if len(expressions) < 2:
3873            raise ValueError(f"Dot requires >= 2 expressions.")
3874
3875        return t.cast(Dot, reduce(lambda x, y: Dot(this=x, expression=y), expressions))

Build a Dot object with a sequence of expressions.

key = 'dot'
class DPipe(Binary):
3878class DPipe(Binary):
3879    pass
key = 'dpipe'
class SafeDPipe(DPipe):
3882class SafeDPipe(DPipe):
3883    pass
key = 'safedpipe'
class EQ(Binary, Predicate):
3886class EQ(Binary, Predicate):
3887    pass
key = 'eq'
class NullSafeEQ(Binary, Predicate):
3890class NullSafeEQ(Binary, Predicate):
3891    pass
key = 'nullsafeeq'
class NullSafeNEQ(Binary, Predicate):
3894class NullSafeNEQ(Binary, Predicate):
3895    pass
key = 'nullsafeneq'
class Distance(Binary):
3898class Distance(Binary):
3899    pass
key = 'distance'
class Escape(Binary):
3902class Escape(Binary):
3903    pass
key = 'escape'
class Glob(Binary, Predicate):
3906class Glob(Binary, Predicate):
3907    pass
key = 'glob'
class GT(Binary, Predicate):
3910class GT(Binary, Predicate):
3911    pass
key = 'gt'
class GTE(Binary, Predicate):
3914class GTE(Binary, Predicate):
3915    pass
key = 'gte'
class ILike(Binary, Predicate):
3918class ILike(Binary, Predicate):
3919    pass
key = 'ilike'
class ILikeAny(Binary, Predicate):
3922class ILikeAny(Binary, Predicate):
3923    pass
key = 'ilikeany'
class IntDiv(Binary):
3926class IntDiv(Binary):
3927    pass
key = 'intdiv'
class Is(Binary, Predicate):
3930class Is(Binary, Predicate):
3931    pass
key = 'is'
class Kwarg(Binary):
3934class Kwarg(Binary):
3935    """Kwarg in special functions like func(kwarg => y)."""

Kwarg in special functions like func(kwarg => y).

key = 'kwarg'
class Like(Binary, Predicate):
3938class Like(Binary, Predicate):
3939    pass
key = 'like'
class LikeAny(Binary, Predicate):
3942class LikeAny(Binary, Predicate):
3943    pass
key = 'likeany'
class LT(Binary, Predicate):
3946class LT(Binary, Predicate):
3947    pass
key = 'lt'
class LTE(Binary, Predicate):
3950class LTE(Binary, Predicate):
3951    pass
key = 'lte'
class Mod(Binary):
3954class Mod(Binary):
3955    pass
key = 'mod'
class Mul(Binary):
3958class Mul(Binary):
3959    pass
key = 'mul'
class NEQ(Binary, Predicate):
3962class NEQ(Binary, Predicate):
3963    pass
key = 'neq'
class SimilarTo(Binary, Predicate):
3966class SimilarTo(Binary, Predicate):
3967    pass
key = 'similarto'
class Slice(Binary):
3970class Slice(Binary):
3971    arg_types = {"this": False, "expression": False}
arg_types = {'this': False, 'expression': False}
key = 'slice'
class Sub(Binary):
3974class Sub(Binary):
3975    pass
key = 'sub'
class ArrayOverlaps(Binary):
3978class ArrayOverlaps(Binary):
3979    pass
key = 'arrayoverlaps'
class Unary(Condition):
3984class Unary(Condition):
3985    pass
key = 'unary'
class BitwiseNot(Unary):
3988class BitwiseNot(Unary):
3989    pass
key = 'bitwisenot'
class Not(Unary):
3992class Not(Unary):
3993    pass
key = 'not'
class Paren(Unary):
3996class Paren(Unary):
3997    arg_types = {"this": True, "with": False}
3998
3999    @property
4000    def output_name(self) -> str:
4001        return self.this.name
arg_types = {'this': True, 'with': False}
output_name: str

Name of the output column if this expression is a selection.

If the Expression has no output name, an empty string is returned.

Example:
>>> from sqlglot import parse_one
>>> parse_one("SELECT a")sqlglot.expressions[0].output_name
'a'
>>> parse_one("SELECT b AS c")sqlglot.expressions[0].output_name
'c'
>>> parse_one("SELECT 1 + 2")sqlglot.expressions[0].output_name
''
key = 'paren'
class Neg(Unary):
4004class Neg(Unary):
4005    pass
key = 'neg'
class Alias(Expression):
4008class Alias(Expression):
4009    arg_types = {"this": True, "alias": False}
4010
4011    @property
4012    def output_name(self) -> str:
4013        return self.alias
arg_types = {'this': True, 'alias': False}
output_name: str

Name of the output column if this expression is a selection.

If the Expression has no output name, an empty string is returned.

Example:
>>> from sqlglot import parse_one
>>> parse_one("SELECT a")sqlglot.expressions[0].output_name
'a'
>>> parse_one("SELECT b AS c")sqlglot.expressions[0].output_name
'c'
>>> parse_one("SELECT 1 + 2")sqlglot.expressions[0].output_name
''
key = 'alias'
class Aliases(Expression):
4016class Aliases(Expression):
4017    arg_types = {"this": True, "expressions": True}
4018
4019    @property
4020    def aliases(self):
4021        return self.expressions
arg_types = {'this': True, 'expressions': True}
aliases
key = 'aliases'
class AtTimeZone(Expression):
4024class AtTimeZone(Expression):
4025    arg_types = {"this": True, "zone": True}
arg_types = {'this': True, 'zone': True}
key = 'attimezone'
class Between(Predicate):
4028class Between(Predicate):
4029    arg_types = {"this": True, "low": True, "high": True}
arg_types = {'this': True, 'low': True, 'high': True}
key = 'between'
class Bracket(Condition):
4032class Bracket(Condition):
4033    arg_types = {"this": True, "expressions": True}
4034
4035    @property
4036    def output_name(self) -> str:
4037        if len(self.expressions) == 1:
4038            return self.expressions[0].output_name
4039
4040        return super().output_name
arg_types = {'this': True, 'expressions': True}
output_name: str

Name of the output column if this expression is a selection.

If the Expression has no output name, an empty string is returned.

Example:
>>> from sqlglot import parse_one
>>> parse_one("SELECT a")sqlglot.expressions[0].output_name
'a'
>>> parse_one("SELECT b AS c")sqlglot.expressions[0].output_name
'c'
>>> parse_one("SELECT 1 + 2")sqlglot.expressions[0].output_name
''
key = 'bracket'
class SafeBracket(Bracket):
4043class SafeBracket(Bracket):
4044    """Represents array lookup where OOB index yields NULL instead of causing a failure."""

Represents array lookup where OOB index yields NULL instead of causing a failure.

key = 'safebracket'
class Distinct(Expression):
4047class Distinct(Expression):
4048    arg_types = {"expressions": False, "on": False}
arg_types = {'expressions': False, 'on': False}
key = 'distinct'
class In(Predicate):
4051class In(Predicate):
4052    arg_types = {
4053        "this": True,
4054        "expressions": False,
4055        "query": False,
4056        "unnest": False,
4057        "field": False,
4058        "is_global": False,
4059    }
arg_types = {'this': True, 'expressions': False, 'query': False, 'unnest': False, 'field': False, 'is_global': False}
key = 'in'
class TimeUnit(Expression):
4062class TimeUnit(Expression):
4063    """Automatically converts unit arg into a var."""
4064
4065    arg_types = {"unit": False}
4066
4067    def __init__(self, **args):
4068        unit = args.get("unit")
4069        if isinstance(unit, (Column, Literal)):
4070            args["unit"] = Var(this=unit.name)
4071        elif isinstance(unit, Week):
4072            unit.set("this", Var(this=unit.this.name))
4073
4074        super().__init__(**args)
4075
4076    @property
4077    def unit(self) -> t.Optional[Var]:
4078        return self.args.get("unit")

Automatically converts unit arg into a var.

TimeUnit(**args)
4067    def __init__(self, **args):
4068        unit = args.get("unit")
4069        if isinstance(unit, (Column, Literal)):
4070            args["unit"] = Var(this=unit.name)
4071        elif isinstance(unit, Week):
4072            unit.set("this", Var(this=unit.this.name))
4073
4074        super().__init__(**args)
arg_types = {'unit': False}
unit: Optional[Var]
key = 'timeunit'
class IntervalOp(TimeUnit):
4081class IntervalOp(TimeUnit):
4082    arg_types = {"unit": True, "expression": True}
4083
4084    def interval(self):
4085        return Interval(
4086            this=self.expression.copy(),
4087            unit=self.unit.copy(),
4088        )
arg_types = {'unit': True, 'expression': True}
def interval(self):
4084    def interval(self):
4085        return Interval(
4086            this=self.expression.copy(),
4087            unit=self.unit.copy(),
4088        )
key = 'intervalop'
class IntervalSpan(DataType):
4094class IntervalSpan(DataType):
4095    arg_types = {"this": True, "expression": True}
arg_types = {'this': True, 'expression': True}
key = 'intervalspan'
class Interval(TimeUnit):
4098class Interval(TimeUnit):
4099    arg_types = {"this": False, "unit": False}
arg_types = {'this': False, 'unit': False}
key = 'interval'
class IgnoreNulls(Expression):
4102class IgnoreNulls(Expression):
4103    pass
key = 'ignorenulls'
class RespectNulls(Expression):
4106class RespectNulls(Expression):
4107    pass
key = 'respectnulls'
class Func(Condition):
4111class Func(Condition):
4112    """
4113    The base class for all function expressions.
4114
4115    Attributes:
4116        is_var_len_args (bool): if set to True the last argument defined in arg_types will be
4117            treated as a variable length argument and the argument's value will be stored as a list.
4118        _sql_names (list): determines the SQL name (1st item in the list) and aliases (subsequent items)
4119            for this function expression. These values are used to map this node to a name during parsing
4120            as well as to provide the function's name during SQL string generation. By default the SQL
4121            name is set to the expression's class name transformed to snake case.
4122    """
4123
4124    is_var_len_args = False
4125
4126    @classmethod
4127    def from_arg_list(cls, args):
4128        if cls.is_var_len_args:
4129            all_arg_keys = list(cls.arg_types)
4130            # If this function supports variable length argument treat the last argument as such.
4131            non_var_len_arg_keys = all_arg_keys[:-1] if cls.is_var_len_args else all_arg_keys
4132            num_non_var = len(non_var_len_arg_keys)
4133
4134            args_dict = {arg_key: arg for arg, arg_key in zip(args, non_var_len_arg_keys)}
4135            args_dict[all_arg_keys[-1]] = args[num_non_var:]
4136        else:
4137            args_dict = {arg_key: arg for arg, arg_key in zip(args, cls.arg_types)}
4138
4139        return cls(**args_dict)
4140
4141    @classmethod
4142    def sql_names(cls):
4143        if cls is Func:
4144            raise NotImplementedError(
4145                "SQL name is only supported by concrete function implementations"
4146            )
4147        if "_sql_names" not in cls.__dict__:
4148            cls._sql_names = [camel_to_snake_case(cls.__name__)]
4149        return cls._sql_names
4150
4151    @classmethod
4152    def sql_name(cls):
4153        return cls.sql_names()[0]
4154
4155    @classmethod
4156    def default_parser_mappings(cls):
4157        return {name: cls.from_arg_list for name in cls.sql_names()}

The base class for all function expressions.

Attributes:
  • is_var_len_args (bool): if set to True the last argument defined in arg_types will be treated as a variable length argument and the argument's value will be stored as a list.
  • _sql_names (list): determines the SQL name (1st item in the list) and aliases (subsequent items) for this function expression. These values are used to map this node to a name during parsing as well as to provide the function's name during SQL string generation. By default the SQL name is set to the expression's class name transformed to snake case.
is_var_len_args = False
@classmethod
def from_arg_list(cls, args):
4126    @classmethod
4127    def from_arg_list(cls, args):
4128        if cls.is_var_len_args:
4129            all_arg_keys = list(cls.arg_types)
4130            # If this function supports variable length argument treat the last argument as such.
4131            non_var_len_arg_keys = all_arg_keys[:-1] if cls.is_var_len_args else all_arg_keys
4132            num_non_var = len(non_var_len_arg_keys)
4133
4134            args_dict = {arg_key: arg for arg, arg_key in zip(args, non_var_len_arg_keys)}
4135            args_dict[all_arg_keys[-1]] = args[num_non_var:]
4136        else:
4137            args_dict = {arg_key: arg for arg, arg_key in zip(args, cls.arg_types)}
4138
4139        return cls(**args_dict)
@classmethod
def sql_names(cls):
4141    @classmethod
4142    def sql_names(cls):
4143        if cls is Func:
4144            raise NotImplementedError(
4145                "SQL name is only supported by concrete function implementations"
4146            )
4147        if "_sql_names" not in cls.__dict__:
4148            cls._sql_names = [camel_to_snake_case(cls.__name__)]
4149        return cls._sql_names
@classmethod
def sql_name(cls):
4151    @classmethod
4152    def sql_name(cls):
4153        return cls.sql_names()[0]
@classmethod
def default_parser_mappings(cls):
4155    @classmethod
4156    def default_parser_mappings(cls):
4157        return {name: cls.from_arg_list for name in cls.sql_names()}
key = 'func'
class AggFunc(Func):
4160class AggFunc(Func):
4161    pass
key = 'aggfunc'
class ParameterizedAgg(AggFunc):
4164class ParameterizedAgg(AggFunc):
4165    arg_types = {"this": True, "expressions": True, "params": True}
arg_types = {'this': True, 'expressions': True, 'params': True}
key = 'parameterizedagg'
class Abs(Func):
4168class Abs(Func):
4169    pass
key = 'abs'
class Flatten(Func):
4172class Flatten(Func):
4173    pass
key = 'flatten'
class Transform(Func):
4177class Transform(Func):
4178    arg_types = {"this": True, "expression": True}
arg_types = {'this': True, 'expression': True}
key = 'transform'
class Anonymous(Func):
4181class Anonymous(Func):
4182    arg_types = {"this": True, "expressions": False}
4183    is_var_len_args = True
arg_types = {'this': True, 'expressions': False}
is_var_len_args = True
key = 'anonymous'
class Hll(AggFunc):
4188class Hll(AggFunc):
4189    arg_types = {"this": True, "expressions": False}
4190    is_var_len_args = True
arg_types = {'this': True, 'expressions': False}
is_var_len_args = True
key = 'hll'
class ApproxDistinct(AggFunc):
4193class ApproxDistinct(AggFunc):
4194    arg_types = {"this": True, "accuracy": False}
4195    _sql_names = ["APPROX_DISTINCT", "APPROX_COUNT_DISTINCT"]
arg_types = {'this': True, 'accuracy': False}
key = 'approxdistinct'
class Array(Func):
4198class Array(Func):
4199    arg_types = {"expressions": False}
4200    is_var_len_args = True
arg_types = {'expressions': False}
is_var_len_args = True
key = 'array'
class ToChar(Func):
4204class ToChar(Func):
4205    arg_types = {"this": True, "format": False}
arg_types = {'this': True, 'format': False}
key = 'tochar'
class GenerateSeries(Func):
4208class GenerateSeries(Func):
4209    arg_types = {"start": True, "end": True, "step": False}
arg_types = {'start': True, 'end': True, 'step': False}
key = 'generateseries'
class ArrayAgg(AggFunc):
4212class ArrayAgg(AggFunc):
4213    pass
key = 'arrayagg'
class ArrayAll(Func):
4216class ArrayAll(Func):
4217    arg_types = {"this": True, "expression": True}
arg_types = {'this': True, 'expression': True}
key = 'arrayall'
class ArrayAny(Func):
4220class ArrayAny(Func):
4221    arg_types = {"this": True, "expression": True}
arg_types = {'this': True, 'expression': True}
key = 'arrayany'
class ArrayConcat(Func):
4224class ArrayConcat(Func):
4225    _sql_names = ["ARRAY_CONCAT", "ARRAY_CAT"]
4226    arg_types = {"this": True, "expressions": False}
4227    is_var_len_args = True
arg_types = {'this': True, 'expressions': False}
is_var_len_args = True
key = 'arrayconcat'
class ArrayContains(Binary, Func):
4230class ArrayContains(Binary, Func):
4231    pass
key = 'arraycontains'
class ArrayContained(Binary):
4234class ArrayContained(Binary):
4235    pass
key = 'arraycontained'
class ArrayFilter(Func):
4238class ArrayFilter(Func):
4239    arg_types = {"this": True, "expression": True}
4240    _sql_names = ["FILTER", "ARRAY_FILTER"]
arg_types = {'this': True, 'expression': True}
key = 'arrayfilter'
class ArrayJoin(Func):
4243class ArrayJoin(Func):
4244    arg_types = {"this": True, "expression": True, "null": False}
arg_types = {'this': True, 'expression': True, 'null': False}
key = 'arrayjoin'
class ArraySize(Func):
4247class ArraySize(Func):
4248    arg_types = {"this": True, "expression": False}
arg_types = {'this': True, 'expression': False}
key = 'arraysize'
class ArraySort(Func):
4251class ArraySort(Func):
4252    arg_types = {"this": True, "expression": False}
arg_types = {'this': True, 'expression': False}
key = 'arraysort'
class ArraySum(Func):
4255class ArraySum(Func):
4256    pass
key = 'arraysum'
class ArrayUnionAgg(AggFunc):
4259class ArrayUnionAgg(AggFunc):
4260    pass
key = 'arrayunionagg'
class Avg(AggFunc):
4263class Avg(AggFunc):
4264    pass
key = 'avg'
class AnyValue(AggFunc):
4267class AnyValue(AggFunc):
4268    arg_types = {"this": True, "having": False, "max": False, "ignore_nulls": False}
arg_types = {'this': True, 'having': False, 'max': False, 'ignore_nulls': False}
key = 'anyvalue'
class First(Func):
4271class First(Func):
4272    arg_types = {"this": True, "ignore_nulls": False}
arg_types = {'this': True, 'ignore_nulls': False}
key = 'first'
class Last(Func):
4275class Last(Func):
4276    arg_types = {"this": True, "ignore_nulls": False}
arg_types = {'this': True, 'ignore_nulls': False}
key = 'last'
class Case(Func):
4279class Case(Func):
4280    arg_types = {"this": False, "ifs": True, "default": False}
4281
4282    def when(self, condition: ExpOrStr, then: ExpOrStr, copy: bool = True, **opts) -> Case:
4283        instance = maybe_copy(self, copy)
4284        instance.append(
4285            "ifs",
4286            If(
4287                this=maybe_parse(condition, copy=copy, **opts),
4288                true=maybe_parse(then, copy=copy, **opts),
4289            ),
4290        )
4291        return instance
4292
4293    def else_(self, condition: ExpOrStr, copy: bool = True, **opts) -> Case:
4294        instance = maybe_copy(self, copy)
4295        instance.set("default", maybe_parse(condition, copy=copy, **opts))
4296        return instance
arg_types = {'this': False, 'ifs': True, 'default': False}
def when( self, condition: Union[str, Expression], then: Union[str, Expression], copy: bool = True, **opts) -> Case:
4282    def when(self, condition: ExpOrStr, then: ExpOrStr, copy: bool = True, **opts) -> Case:
4283        instance = maybe_copy(self, copy)
4284        instance.append(
4285            "ifs",
4286            If(
4287                this=maybe_parse(condition, copy=copy, **opts),
4288                true=maybe_parse(then, copy=copy, **opts),
4289            ),
4290        )
4291        return instance
def else_( self, condition: Union[str, Expression], copy: bool = True, **opts) -> Case:
4293    def else_(self, condition: ExpOrStr, copy: bool = True, **opts) -> Case:
4294        instance = maybe_copy(self, copy)
4295        instance.set("default", maybe_parse(condition, copy=copy, **opts))
4296        return instance
key = 'case'
class Cast(Func):
4299class Cast(Func):
4300    arg_types = {"this": True, "to": True, "format": False, "safe": False}
4301
4302    @property
4303    def name(self) -> str:
4304        return self.this.name
4305
4306    @property
4307    def to(self) -> DataType:
4308        return self.args["to"]
4309
4310    @property
4311    def output_name(self) -> str:
4312        return self.name
4313
4314    def is_type(self, *dtypes: str | DataType | DataType.Type) -> bool:
4315        """
4316        Checks whether this Cast's DataType matches one of the provided data types. Nested types
4317        like arrays or structs will be compared using "structural equivalence" semantics, so e.g.
4318        array<int> != array<float>.
4319
4320        Args:
4321            dtypes: the data types to compare this Cast's DataType to.
4322
4323        Returns:
4324            True, if and only if there is a type in `dtypes` which is equal to this Cast's DataType.
4325        """
4326        return self.to.is_type(*dtypes)
arg_types = {'this': True, 'to': True, 'format': False, 'safe': False}
name: str
to: DataType
output_name: str

Name of the output column if this expression is a selection.

If the Expression has no output name, an empty string is returned.

Example:
>>> from sqlglot import parse_one
>>> parse_one("SELECT a")sqlglot.expressions[0].output_name
'a'
>>> parse_one("SELECT b AS c")sqlglot.expressions[0].output_name
'c'
>>> parse_one("SELECT 1 + 2")sqlglot.expressions[0].output_name
''
def is_type( self, *dtypes: str | DataType | DataType.Type) -> bool:
4314    def is_type(self, *dtypes: str | DataType | DataType.Type) -> bool:
4315        """
4316        Checks whether this Cast's DataType matches one of the provided data types. Nested types
4317        like arrays or structs will be compared using "structural equivalence" semantics, so e.g.
4318        array<int> != array<float>.
4319
4320        Args:
4321            dtypes: the data types to compare this Cast's DataType to.
4322
4323        Returns:
4324            True, if and only if there is a type in `dtypes` which is equal to this Cast's DataType.
4325        """
4326        return self.to.is_type(*dtypes)

Checks whether this Cast's DataType matches one of the provided data types. Nested types like arrays or structs will be compared using "structural equivalence" semantics, so e.g. array != array.

Arguments:
  • dtypes: the data types to compare this Cast's DataType to.
Returns:

True, if and only if there is a type in dtypes which is equal to this Cast's DataType.

key = 'cast'
class TryCast(Cast):
4329class TryCast(Cast):
4330    pass
key = 'trycast'
class CastToStrType(Func):
4333class CastToStrType(Func):
4334    arg_types = {"this": True, "to": True}
arg_types = {'this': True, 'to': True}
key = 'casttostrtype'
class Collate(Binary, Func):
4337class Collate(Binary, Func):
4338    pass
key = 'collate'
class Ceil(Func):
4341class Ceil(Func):
4342    arg_types = {"this": True, "decimals": False}
4343    _sql_names = ["CEIL", "CEILING"]
arg_types = {'this': True, 'decimals': False}
key = 'ceil'
class Coalesce(Func):
4346class Coalesce(Func):
4347    arg_types = {"this": True, "expressions": False}
4348    is_var_len_args = True
4349    _sql_names = ["COALESCE", "IFNULL", "NVL"]
arg_types = {'this': True, 'expressions': False}
is_var_len_args = True
key = 'coalesce'
class Chr(Func):
4352class Chr(Func):
4353    arg_types = {"this": True, "charset": False, "expressions": False}
4354    is_var_len_args = True
4355    _sql_names = ["CHR", "CHAR"]
arg_types = {'this': True, 'charset': False, 'expressions': False}
is_var_len_args = True
key = 'chr'
class Concat(Func):
4358class Concat(Func):
4359    arg_types = {"expressions": True}
4360    is_var_len_args = True
arg_types = {'expressions': True}
is_var_len_args = True
key = 'concat'
class SafeConcat(Concat):
4363class SafeConcat(Concat):
4364    pass
key = 'safeconcat'
class ConcatWs(Concat):
4367class ConcatWs(Concat):
4368    _sql_names = ["CONCAT_WS"]
key = 'concatws'
class Count(AggFunc):
4371class Count(AggFunc):
4372    arg_types = {"this": False, "expressions": False}
4373    is_var_len_args = True
arg_types = {'this': False, 'expressions': False}
is_var_len_args = True
key = 'count'
class CountIf(AggFunc):
4376class CountIf(AggFunc):
4377    pass
key = 'countif'
class CurrentDate(Func):
4380class CurrentDate(Func):
4381    arg_types = {"this": False}
arg_types = {'this': False}
key = 'currentdate'
class CurrentDatetime(Func):
4384class CurrentDatetime(Func):
4385    arg_types = {"this": False}
arg_types = {'this': False}
key = 'currentdatetime'
class CurrentTime(Func):
4388class CurrentTime(Func):
4389    arg_types = {"this": False}
arg_types = {'this': False}
key = 'currenttime'
class CurrentTimestamp(Func):
4392class CurrentTimestamp(Func):
4393    arg_types = {"this": False}
arg_types = {'this': False}
key = 'currenttimestamp'
class CurrentUser(Func):
4396class CurrentUser(Func):
4397    arg_types = {"this": False}
arg_types = {'this': False}
key = 'currentuser'
class DateAdd(Func, IntervalOp):
4400class DateAdd(Func, IntervalOp):
4401    arg_types = {"this": True, "expression": True, "unit": False}
arg_types = {'this': True, 'expression': True, 'unit': False}
key = 'dateadd'
class DateSub(Func, IntervalOp):
4404class DateSub(Func, IntervalOp):
4405    arg_types = {"this": True, "expression": True, "unit": False}
arg_types = {'this': True, 'expression': True, 'unit': False}
key = 'datesub'
class DateDiff(Func, TimeUnit):
4408class DateDiff(Func, TimeUnit):
4409    _sql_names = ["DATEDIFF", "DATE_DIFF"]
4410    arg_types = {"this": True, "expression": True, "unit": False}
arg_types = {'this': True, 'expression': True, 'unit': False}
key = 'datediff'
class DateTrunc(Func):
4413class DateTrunc(Func):
4414    arg_types = {"unit": True, "this": True, "zone": False}
4415
4416    @property
4417    def unit(self) -> Expression:
4418        return self.args["unit"]
arg_types = {'unit': True, 'this': True, 'zone': False}
unit: Expression
key = 'datetrunc'
class DatetimeAdd(Func, IntervalOp):
4421class DatetimeAdd(Func, IntervalOp):
4422    arg_types = {"this": True, "expression": True, "unit": False}
arg_types = {'this': True, 'expression': True, 'unit': False}
key = 'datetimeadd'
class DatetimeSub(Func, IntervalOp):
4425class DatetimeSub(Func, IntervalOp):
4426    arg_types = {"this": True, "expression": True, "unit": False}
arg_types = {'this': True, 'expression': True, 'unit': False}
key = 'datetimesub'
class DatetimeDiff(Func, TimeUnit):
4429class DatetimeDiff(Func, TimeUnit):
4430    arg_types = {"this": True, "expression": True, "unit": False}
arg_types = {'this': True, 'expression': True, 'unit': False}
key = 'datetimediff'
class DatetimeTrunc(Func, TimeUnit):
4433class DatetimeTrunc(Func, TimeUnit):
4434    arg_types = {"this": True, "unit": True, "zone": False}
arg_types = {'this': True, 'unit': True, 'zone': False}
key = 'datetimetrunc'
class DayOfWeek(Func):
4437class DayOfWeek(Func):
4438    _sql_names = ["DAY_OF_WEEK", "DAYOFWEEK"]
key = 'dayofweek'
class DayOfMonth(Func):
4441class DayOfMonth(Func):
4442    _sql_names = ["DAY_OF_MONTH", "DAYOFMONTH"]
key = 'dayofmonth'
class DayOfYear(Func):
4445class DayOfYear(Func):
4446    _sql_names = ["DAY_OF_YEAR", "DAYOFYEAR"]
key = 'dayofyear'
class ToDays(Func):
4449class ToDays(Func):
4450    pass
key = 'todays'
class WeekOfYear(Func):
4453class WeekOfYear(Func):
4454    _sql_names = ["WEEK_OF_YEAR", "WEEKOFYEAR"]
key = 'weekofyear'
class MonthsBetween(Func):
4457class MonthsBetween(Func):
4458    arg_types = {"this": True, "expression": True, "roundoff": False}
arg_types = {'this': True, 'expression': True, 'roundoff': False}
key = 'monthsbetween'
class LastDateOfMonth(Func):
4461class LastDateOfMonth(Func):
4462    pass
key = 'lastdateofmonth'
class Extract(Func):
4465class Extract(Func):
4466    arg_types = {"this": True, "expression": True}
arg_types = {'this': True, 'expression': True}
key = 'extract'
class Timestamp(Func):
4469class Timestamp(Func):
4470    arg_types = {"this": False, "expression": False}
arg_types = {'this': False, 'expression': False}
key = 'timestamp'
class TimestampAdd(Func, TimeUnit):
4473class TimestampAdd(Func, TimeUnit):
4474    arg_types = {"this": True, "expression": True, "unit": False}
arg_types = {'this': True, 'expression': True, 'unit': False}
key = 'timestampadd'
class TimestampSub(Func, TimeUnit):
4477class TimestampSub(Func, TimeUnit):
4478    arg_types = {"this": True, "expression": True, "unit": False}
arg_types = {'this': True, 'expression': True, 'unit': False}
key = 'timestampsub'
class TimestampDiff(Func, TimeUnit):
4481class TimestampDiff(Func, TimeUnit):
4482    arg_types = {"this": True, "expression": True, "unit": False}
arg_types = {'this': True, 'expression': True, 'unit': False}
key = 'timestampdiff'
class TimestampTrunc(Func, TimeUnit):
4485class TimestampTrunc(Func, TimeUnit):
4486    arg_types = {"this": True, "unit": True, "zone": False}
arg_types = {'this': True, 'unit': True, 'zone': False}
key = 'timestamptrunc'
class TimeAdd(Func, TimeUnit):
4489class TimeAdd(Func, TimeUnit):
4490    arg_types = {"this": True, "expression": True, "unit": False}
arg_types = {'this': True, 'expression': True, 'unit': False}
key = 'timeadd'
class TimeSub(Func, TimeUnit):
4493class TimeSub(Func, TimeUnit):
4494    arg_types = {"this": True, "expression": True, "unit": False}
arg_types = {'this': True, 'expression': True, 'unit': False}
key = 'timesub'
class TimeDiff(Func, TimeUnit):
4497class TimeDiff(Func, TimeUnit):
4498    arg_types = {"this": True, "expression": True, "unit": False}
arg_types = {'this': True, 'expression': True, 'unit': False}
key = 'timediff'
class TimeTrunc(Func, TimeUnit):
4501class TimeTrunc(Func, TimeUnit):
4502    arg_types = {"this": True, "unit": True, "zone": False}
arg_types = {'this': True, 'unit': True, 'zone': False}
key = 'timetrunc'
class DateFromParts(Func):
4505class DateFromParts(Func):
4506    _sql_names = ["DATEFROMPARTS"]
4507    arg_types = {"year": True, "month": True, "day": True}
arg_types = {'year': True, 'month': True, 'day': True}
key = 'datefromparts'
class DateStrToDate(Func):
4510class DateStrToDate(Func):
4511    pass
key = 'datestrtodate'
class DateToDateStr(Func):
4514class DateToDateStr(Func):
4515    pass
key = 'datetodatestr'
class DateToDi(Func):
4518class DateToDi(Func):
4519    pass
key = 'datetodi'
class Date(Func):
4523class Date(Func):
4524    arg_types = {"this": False, "zone": False, "expressions": False}
4525    is_var_len_args = True
arg_types = {'this': False, 'zone': False, 'expressions': False}
is_var_len_args = True
key = 'date'
class Day(Func):
4528class Day(Func):
4529    pass
key = 'day'
class Decode(Func):
4532class Decode(Func):
4533    arg_types = {"this": True, "charset": True, "replace": False}
arg_types = {'this': True, 'charset': True, 'replace': False}
key = 'decode'
class DiToDate(Func):
4536class DiToDate(Func):
4537    pass
key = 'ditodate'
class Encode(Func):
4540class Encode(Func):
4541    arg_types = {"this": True, "charset": True}
arg_types = {'this': True, 'charset': True}
key = 'encode'
class Exp(Func):
4544class Exp(Func):
4545    pass
key = 'exp'
class Explode(Func):
4549class Explode(Func):
4550    arg_types = {"this": True, "expressions": False}
4551    is_var_len_args = True
arg_types = {'this': True, 'expressions': False}
is_var_len_args = True
key = 'explode'
class ExplodeOuter(Explode):
4554class ExplodeOuter(Explode):
4555    pass
key = 'explodeouter'
class Posexplode(Explode):
4558class Posexplode(Explode):
4559    pass
key = 'posexplode'
class PosexplodeOuter(Posexplode):
4562class PosexplodeOuter(Posexplode):
4563    pass
key = 'posexplodeouter'
class Floor(Func):
4566class Floor(Func):
4567    arg_types = {"this": True, "decimals": False}
arg_types = {'this': True, 'decimals': False}
key = 'floor'
class FromBase64(Func):
4570class FromBase64(Func):
4571    pass
key = 'frombase64'
class ToBase64(Func):
4574class ToBase64(Func):
4575    pass
key = 'tobase64'
class Greatest(Func):
4578class Greatest(Func):
4579    arg_types = {"this": True, "expressions": False}
4580    is_var_len_args = True
arg_types = {'this': True, 'expressions': False}
is_var_len_args = True
key = 'greatest'
class GroupConcat(AggFunc):
4583class GroupConcat(AggFunc):
4584    arg_types = {"this": True, "separator": False}
arg_types = {'this': True, 'separator': False}
key = 'groupconcat'
class Hex(Func):
4587class Hex(Func):
4588    pass
key = 'hex'
class Xor(Connector, Func):
4591class Xor(Connector, Func):
4592    arg_types = {"this": False, "expression": False, "expressions": False}
arg_types = {'this': False, 'expression': False, 'expressions': False}
key = 'xor'
class If(Func):
4595class If(Func):
4596    arg_types = {"this": True, "true": True, "false": False}
arg_types = {'this': True, 'true': True, 'false': False}
key = 'if'
class Initcap(Func):
4599class Initcap(Func):
4600    arg_types = {"this": True, "expression": False}
arg_types = {'this': True, 'expression': False}
key = 'initcap'
class IsNan(Func):
4603class IsNan(Func):
4604    _sql_names = ["IS_NAN", "ISNAN"]
key = 'isnan'
class FormatJson(Expression):
4607class FormatJson(Expression):
4608    pass
key = 'formatjson'
class JSONKeyValue(Expression):
4611class JSONKeyValue(Expression):
4612    arg_types = {"this": True, "expression": True}
arg_types = {'this': True, 'expression': True}
key = 'jsonkeyvalue'
class JSONObject(Func):
4615class JSONObject(Func):
4616    arg_types = {
4617        "expressions": False,
4618        "null_handling": False,
4619        "unique_keys": False,
4620        "return_type": False,
4621        "encoding": False,
4622    }
arg_types = {'expressions': False, 'null_handling': False, 'unique_keys': False, 'return_type': False, 'encoding': False}
key = 'jsonobject'
class JSONArray(Func):
4626class JSONArray(Func):
4627    arg_types = {
4628        "expressions": True,
4629        "null_handling": False,
4630        "return_type": False,
4631        "strict": False,
4632    }
arg_types = {'expressions': True, 'null_handling': False, 'return_type': False, 'strict': False}
key = 'jsonarray'
class JSONArrayAgg(Func):
4636class JSONArrayAgg(Func):
4637    arg_types = {
4638        "this": True,
4639        "order": False,
4640        "null_handling": False,
4641        "return_type": False,
4642        "strict": False,
4643    }
arg_types = {'this': True, 'order': False, 'null_handling': False, 'return_type': False, 'strict': False}
key = 'jsonarrayagg'
class JSONColumnDef(Expression):
4648class JSONColumnDef(Expression):
4649    arg_types = {"this": False, "kind": False, "path": False, "nested_schema": False}
arg_types = {'this': False, 'kind': False, 'path': False, 'nested_schema': False}
key = 'jsoncolumndef'
class JSONSchema(Expression):
4652class JSONSchema(Expression):
4653    arg_types = {"expressions": True}
arg_types = {'expressions': True}
key = 'jsonschema'
class JSONTable(Func):
4657class JSONTable(Func):
4658    arg_types = {
4659        "this": True,
4660        "schema": True,
4661        "path": False,
4662        "error_handling": False,
4663        "empty_handling": False,
4664    }
arg_types = {'this': True, 'schema': True, 'path': False, 'error_handling': False, 'empty_handling': False}
key = 'jsontable'
class OpenJSONColumnDef(Expression):
4667class OpenJSONColumnDef(Expression):
4668    arg_types = {"this": True, "kind": True, "path": False, "as_json": False}
arg_types = {'this': True, 'kind': True, 'path': False, 'as_json': False}
key = 'openjsoncolumndef'
class OpenJSON(Func):
4671class OpenJSON(Func):
4672    arg_types = {"this": True, "path": False, "expressions": False}
arg_types = {'this': True, 'path': False, 'expressions': False}
key = 'openjson'
class JSONBContains(Binary):
4675class JSONBContains(Binary):
4676    _sql_names = ["JSONB_CONTAINS"]
key = 'jsonbcontains'
class JSONExtract(Binary, Func):
4679class JSONExtract(Binary, Func):
4680    _sql_names = ["JSON_EXTRACT"]
key = 'jsonextract'
class JSONExtractScalar(JSONExtract):
4683class JSONExtractScalar(JSONExtract):
4684    _sql_names = ["JSON_EXTRACT_SCALAR"]
key = 'jsonextractscalar'
class JSONBExtract(JSONExtract):
4687class JSONBExtract(JSONExtract):
4688    _sql_names = ["JSONB_EXTRACT"]
key = 'jsonbextract'
class JSONBExtractScalar(JSONExtract):
4691class JSONBExtractScalar(JSONExtract):
4692    _sql_names = ["JSONB_EXTRACT_SCALAR"]
key = 'jsonbextractscalar'
class JSONFormat(Func):
4695class JSONFormat(Func):
4696    arg_types = {"this": False, "options": False}
4697    _sql_names = ["JSON_FORMAT"]
arg_types = {'this': False, 'options': False}
key = 'jsonformat'
class JSONArrayContains(Binary, Predicate, Func):
4701class JSONArrayContains(Binary, Predicate, Func):
4702    _sql_names = ["JSON_ARRAY_CONTAINS"]
key = 'jsonarraycontains'
class ParseJSON(Func):
4705class ParseJSON(Func):
4706    # BigQuery, Snowflake have PARSE_JSON, Presto has JSON_PARSE
4707    _sql_names = ["PARSE_JSON", "JSON_PARSE"]
4708    arg_types = {"this": True, "expressions": False}
4709    is_var_len_args = True
arg_types = {'this': True, 'expressions': False}
is_var_len_args = True
key = 'parsejson'
class Least(Func):
4712class Least(Func):
4713    arg_types = {"this": True, "expressions": False}
4714    is_var_len_args = True
arg_types = {'this': True, 'expressions': False}
is_var_len_args = True
key = 'least'
class Left(Func):
4717class Left(Func):
4718    arg_types = {"this": True, "expression": True}
arg_types = {'this': True, 'expression': True}
key = 'left'
class Length(Func):
4725class Length(Func):
4726    _sql_names = ["LENGTH", "LEN"]
key = 'length'
class Levenshtein(Func):
4729class Levenshtein(Func):
4730    arg_types = {
4731        "this": True,
4732        "expression": False,
4733        "ins_cost": False,
4734        "del_cost": False,
4735        "sub_cost": False,
4736    }
arg_types = {'this': True, 'expression': False, 'ins_cost': False, 'del_cost': False, 'sub_cost': False}
key = 'levenshtein'
class Ln(Func):
4739class Ln(Func):
4740    pass
key = 'ln'
class Log(Func):
4743class Log(Func):
4744    arg_types = {"this": True, "expression": False}
arg_types = {'this': True, 'expression': False}
key = 'log'
class Log2(Func):
4747class Log2(Func):
4748    pass
key = 'log2'
class Log10(Func):
4751class Log10(Func):
4752    pass
key = 'log10'
class LogicalOr(AggFunc):
4755class LogicalOr(AggFunc):
4756    _sql_names = ["LOGICAL_OR", "BOOL_OR", "BOOLOR_AGG"]
key = 'logicalor'
class LogicalAnd(AggFunc):
4759class LogicalAnd(AggFunc):
4760    _sql_names = ["LOGICAL_AND", "BOOL_AND", "BOOLAND_AGG"]
key = 'logicaland'
class Lower(Func):
4763class Lower(Func):
4764    _sql_names = ["LOWER", "LCASE"]
key = 'lower'
class Map(Func):
4767class Map(Func):
4768    arg_types = {"keys": False, "values": False}
arg_types = {'keys': False, 'values': False}
key = 'map'
class MapFromEntries(Func):
4771class MapFromEntries(Func):
4772    pass
key = 'mapfromentries'
class StarMap(Func):
4775class StarMap(Func):
4776    pass
key = 'starmap'
class VarMap(Func):
4779class VarMap(Func):
4780    arg_types = {"keys": True, "values": True}
4781    is_var_len_args = True
4782
4783    @property
4784    def keys(self) -> t.List[Expression]:
4785        return self.args["keys"].expressions
4786
4787    @property
4788    def values(self) -> t.List[Expression]:
4789        return self.args["values"].expressions
arg_types = {'keys': True, 'values': True}
is_var_len_args = True
keys: List[Expression]
values: List[Expression]
key = 'varmap'
class MatchAgainst(Func):
4793class MatchAgainst(Func):
4794    arg_types = {"this": True, "expressions": True, "modifier": False}
arg_types = {'this': True, 'expressions': True, 'modifier': False}
key = 'matchagainst'
class Max(AggFunc):
4797class Max(AggFunc):
4798    arg_types = {"this": True, "expressions": False}
4799    is_var_len_args = True
arg_types = {'this': True, 'expressions': False}
is_var_len_args = True
key = 'max'
class MD5(Func):
4802class MD5(Func):
4803    _sql_names = ["MD5"]
key = 'md5'
class MD5Digest(Func):
4807class MD5Digest(Func):
4808    _sql_names = ["MD5_DIGEST"]
key = 'md5digest'
class Min(AggFunc):
4811class Min(AggFunc):
4812    arg_types = {"this": True, "expressions": False}
4813    is_var_len_args = True
arg_types = {'this': True, 'expressions': False}
is_var_len_args = True
key = 'min'
class Month(Func):
4816class Month(Func):
4817    pass
key = 'month'
class Nvl2(Func):
4820class Nvl2(Func):
4821    arg_types = {"this": True, "true": True, "false": False}
arg_types = {'this': True, 'true': True, 'false': False}
key = 'nvl2'
class Predict(Func):
4825class Predict(Func):
4826    arg_types = {"this": True, "expression": True, "params_struct": False}
arg_types = {'this': True, 'expression': True, 'params_struct': False}
key = 'predict'
class Pow(Binary, Func):
4829class Pow(Binary, Func):
4830    _sql_names = ["POWER", "POW"]
key = 'pow'
class PercentileCont(AggFunc):
4833class PercentileCont(AggFunc):
4834    arg_types = {"this": True, "expression": False}
arg_types = {'this': True, 'expression': False}
key = 'percentilecont'
class PercentileDisc(AggFunc):
4837class PercentileDisc(AggFunc):
4838    arg_types = {"this": True, "expression": False}
arg_types = {'this': True, 'expression': False}
key = 'percentiledisc'
class Quantile(AggFunc):
4841class Quantile(AggFunc):
4842    arg_types = {"this": True, "quantile": True}
arg_types = {'this': True, 'quantile': True}
key = 'quantile'
class ApproxQuantile(Quantile):
4845class ApproxQuantile(Quantile):
4846    arg_types = {"this": True, "quantile": True, "accuracy": False, "weight": False}
arg_types = {'this': True, 'quantile': True, 'accuracy': False, 'weight': False}
key = 'approxquantile'
class RangeN(Func):
4849class RangeN(Func):
4850    arg_types = {"this": True, "expressions": True, "each": False}
arg_types = {'this': True, 'expressions': True, 'each': False}
key = 'rangen'
class ReadCSV(Func):
4853class ReadCSV(Func):
4854    _sql_names = ["READ_CSV"]
4855    is_var_len_args = True
4856    arg_types = {"this": True, "expressions": False}
is_var_len_args = True
arg_types = {'this': True, 'expressions': False}
key = 'readcsv'
class Reduce(Func):
4859class Reduce(Func):
4860    arg_types = {"this": True, "initial": True, "merge": True, "finish": False}
arg_types = {'this': True, 'initial': True, 'merge': True, 'finish': False}
key = 'reduce'
class RegexpExtract(Func):
4863class RegexpExtract(Func):
4864    arg_types = {
4865        "this": True,
4866        "expression": True,
4867        "position": False,
4868        "occurrence": False,
4869        "parameters": False,
4870        "group": False,
4871    }
arg_types = {'this': True, 'expression': True, 'position': False, 'occurrence': False, 'parameters': False, 'group': False}
key = 'regexpextract'
class RegexpReplace(Func):
4874class RegexpReplace(Func):
4875    arg_types = {
4876        "this": True,
4877        "expression": True,
4878        "replacement": True,
4879        "position": False,
4880        "occurrence": False,
4881        "parameters": False,
4882    }
arg_types = {'this': True, 'expression': True, 'replacement': True, 'position': False, 'occurrence': False, 'parameters': False}
key = 'regexpreplace'
class RegexpLike(Binary, Func):
4885class RegexpLike(Binary, Func):
4886    arg_types = {"this": True, "expression": True, "flag": False}
arg_types = {'this': True, 'expression': True, 'flag': False}
key = 'regexplike'
class RegexpILike(Binary, Func):
4889class RegexpILike(Binary, Func):
4890    arg_types = {"this": True, "expression": True, "flag": False}
arg_types = {'this': True, 'expression': True, 'flag': False}
key = 'regexpilike'
class RegexpSplit(Func):
4895class RegexpSplit(Func):
4896    arg_types = {"this": True, "expression": True, "limit": False}
arg_types = {'this': True, 'expression': True, 'limit': False}
key = 'regexpsplit'
class Repeat(Func):
4899class Repeat(Func):
4900    arg_types = {"this": True, "times": True}
arg_types = {'this': True, 'times': True}
key = 'repeat'
class Round(Func):
4903class Round(Func):
4904    arg_types = {"this": True, "decimals": False}
arg_types = {'this': True, 'decimals': False}
key = 'round'
class RowNumber(Func):
4907class RowNumber(Func):
4908    arg_types: t.Dict[str, t.Any] = {}
arg_types: Dict[str, Any] = {}
key = 'rownumber'
class SafeDivide(Func):
4911class SafeDivide(Func):
4912    arg_types = {"this": True, "expression": True}
arg_types = {'this': True, 'expression': True}
key = 'safedivide'
class SetAgg(AggFunc):
4915class SetAgg(AggFunc):
4916    pass
key = 'setagg'
class SHA(Func):
4919class SHA(Func):
4920    _sql_names = ["SHA", "SHA1"]
key = 'sha'
class SHA2(Func):
4923class SHA2(Func):
4924    _sql_names = ["SHA2"]
4925    arg_types = {"this": True, "length": False}
arg_types = {'this': True, 'length': False}
key = 'sha2'
class SortArray(Func):
4928class SortArray(Func):
4929    arg_types = {"this": True, "asc": False}
arg_types = {'this': True, 'asc': False}
key = 'sortarray'
class Split(Func):
4932class Split(Func):
4933    arg_types = {"this": True, "expression": True, "limit": False}
arg_types = {'this': True, 'expression': True, 'limit': False}
key = 'split'
class Substring(Func):
4938class Substring(Func):
4939    arg_types = {"this": True, "start": False, "length": False}
arg_types = {'this': True, 'start': False, 'length': False}
key = 'substring'
class StandardHash(Func):
4942class StandardHash(Func):
4943    arg_types = {"this": True, "expression": False}
arg_types = {'this': True, 'expression': False}
key = 'standardhash'
class StartsWith(Func):
4946class StartsWith(Func):
4947    _sql_names = ["STARTS_WITH", "STARTSWITH"]
4948    arg_types = {"this": True, "expression": True}
arg_types = {'this': True, 'expression': True}
key = 'startswith'
class StrPosition(Func):
4951class StrPosition(Func):
4952    arg_types = {
4953        "this": True,
4954        "substr": True,
4955        "position": False,
4956        "instance": False,
4957    }
arg_types = {'this': True, 'substr': True, 'position': False, 'instance': False}
key = 'strposition'
class StrToDate(Func):
4960class StrToDate(Func):
4961    arg_types = {"this": True, "format": True}
arg_types = {'this': True, 'format': True}
key = 'strtodate'
class StrToTime(Func):
4964class StrToTime(Func):
4965    arg_types = {"this": True, "format": True, "zone": False}
arg_types = {'this': True, 'format': True, 'zone': False}
key = 'strtotime'
class StrToUnix(Func):
4970class StrToUnix(Func):
4971    arg_types = {"this": False, "format": False}
arg_types = {'this': False, 'format': False}
key = 'strtounix'
class StrToMap(Func):
4976class StrToMap(Func):
4977    arg_types = {
4978        "this": True,
4979        "pair_delim": False,
4980        "key_value_delim": False,
4981        "duplicate_resolution_callback": False,
4982    }
arg_types = {'this': True, 'pair_delim': False, 'key_value_delim': False, 'duplicate_resolution_callback': False}
key = 'strtomap'
class NumberToStr(Func):
4985class NumberToStr(Func):
4986    arg_types = {"this": True, "format": True, "culture": False}
arg_types = {'this': True, 'format': True, 'culture': False}
key = 'numbertostr'
class FromBase(Func):
4989class FromBase(Func):
4990    arg_types = {"this": True, "expression": True}
arg_types = {'this': True, 'expression': True}
key = 'frombase'
class Struct(Func):
4993class Struct(Func):
4994    arg_types = {"expressions": True}
4995    is_var_len_args = True
arg_types = {'expressions': True}
is_var_len_args = True
key = 'struct'
class StructExtract(Func):
4998class StructExtract(Func):
4999    arg_types = {"this": True, "expression": True}
arg_types = {'this': True, 'expression': True}
key = 'structextract'
class Stuff(Func):
5004class Stuff(Func):
5005    _sql_names = ["STUFF", "INSERT"]
5006    arg_types = {"this": True, "start": True, "length": True, "expression": True}
arg_types = {'this': True, 'start': True, 'length': True, 'expression': True}
key = 'stuff'
class Sum(AggFunc):
5009class Sum(AggFunc):
5010    pass
key = 'sum'
class Sqrt(Func):
5013class Sqrt(Func):
5014    pass
key = 'sqrt'
class Stddev(AggFunc):
5017class Stddev(AggFunc):
5018    pass
key = 'stddev'
class StddevPop(AggFunc):
5021class StddevPop(AggFunc):
5022    pass
key = 'stddevpop'
class StddevSamp(AggFunc):
5025class StddevSamp(AggFunc):
5026    pass
key = 'stddevsamp'
class TimeToStr(Func):
5029class TimeToStr(Func):
5030    arg_types = {"this": True, "format": True, "culture": False}
arg_types = {'this': True, 'format': True, 'culture': False}
key = 'timetostr'
class TimeToTimeStr(Func):
5033class TimeToTimeStr(Func):
5034    pass
key = 'timetotimestr'
class TimeToUnix(Func):
5037class TimeToUnix(Func):
5038    pass
key = 'timetounix'
class TimeStrToDate(Func):
5041class TimeStrToDate(Func):
5042    pass
key = 'timestrtodate'
class TimeStrToTime(Func):
5045class TimeStrToTime(Func):
5046    pass
key = 'timestrtotime'
class TimeStrToUnix(Func):
5049class TimeStrToUnix(Func):
5050    pass
key = 'timestrtounix'
class Trim(Func):
5053class Trim(Func):
5054    arg_types = {
5055        "this": True,
5056        "expression": False,
5057        "position": False,
5058        "collation": False,
5059    }
arg_types = {'this': True, 'expression': False, 'position': False, 'collation': False}
key = 'trim'
class TsOrDsAdd(Func, TimeUnit):
5062class TsOrDsAdd(Func, TimeUnit):
5063    arg_types = {"this": True, "expression": True, "unit": False}
arg_types = {'this': True, 'expression': True, 'unit': False}
key = 'tsordsadd'
class TsOrDsToDateStr(Func):
5066class TsOrDsToDateStr(Func):
5067    pass
key = 'tsordstodatestr'
class TsOrDsToDate(Func):
5070class TsOrDsToDate(Func):
5071    arg_types = {"this": True, "format": False}
arg_types = {'this': True, 'format': False}
key = 'tsordstodate'
class TsOrDiToDi(Func):
5074class TsOrDiToDi(Func):
5075    pass
key = 'tsorditodi'
class Unhex(Func):
5078class Unhex(Func):
5079    pass
key = 'unhex'
class UnixToStr(Func):
5082class UnixToStr(Func):
5083    arg_types = {"this": True, "format": False}
arg_types = {'this': True, 'format': False}
key = 'unixtostr'
class UnixToTime(Func):
5088class UnixToTime(Func):
5089    arg_types = {"this": True, "scale": False, "zone": False, "hours": False, "minutes": False}
5090
5091    SECONDS = Literal.string("seconds")
5092    MILLIS = Literal.string("millis")
5093    MICROS = Literal.string("micros")
arg_types = {'this': True, 'scale': False, 'zone': False, 'hours': False, 'minutes': False}
SECONDS = (LITERAL this: seconds, is_string: True)
MILLIS = (LITERAL this: millis, is_string: True)
MICROS = (LITERAL this: micros, is_string: True)
key = 'unixtotime'
class UnixToTimeStr(Func):
5096class UnixToTimeStr(Func):
5097    pass
key = 'unixtotimestr'
class Upper(Func):
5100class Upper(Func):
5101    _sql_names = ["UPPER", "UCASE"]
key = 'upper'
class Variance(AggFunc):
5104class Variance(AggFunc):
5105    _sql_names = ["VARIANCE", "VARIANCE_SAMP", "VAR_SAMP"]
key = 'variance'
class VariancePop(AggFunc):
5108class VariancePop(AggFunc):
5109    _sql_names = ["VARIANCE_POP", "VAR_POP"]
key = 'variancepop'
class Week(Func):
5112class Week(Func):
5113    arg_types = {"this": True, "mode": False}
arg_types = {'this': True, 'mode': False}
key = 'week'
class XMLTable(Func):
5116class XMLTable(Func):
5117    arg_types = {"this": True, "passing": False, "columns": False, "by_ref": False}
arg_types = {'this': True, 'passing': False, 'columns': False, 'by_ref': False}
key = 'xmltable'
class Year(Func):
5120class Year(Func):
5121    pass
key = 'year'
class Use(Expression):
5124class Use(Expression):
5125    arg_types = {"this": True, "kind": False}
arg_types = {'this': True, 'kind': False}
key = 'use'
class Merge(Expression):
5128class Merge(Expression):
5129    arg_types = {"this": True, "using": True, "on": True, "expressions": True}
arg_types = {'this': True, 'using': True, 'on': True, 'expressions': True}
key = 'merge'
class When(Func):
5132class When(Func):
5133    arg_types = {"matched": True, "source": False, "condition": False, "then": True}
arg_types = {'matched': True, 'source': False, 'condition': False, 'then': True}
key = 'when'
class NextValueFor(Func):
5138class NextValueFor(Func):
5139    arg_types = {"this": True, "order": False}
arg_types = {'this': True, 'order': False}
key = 'nextvaluefor'
ALL_FUNCTIONS = [<class 'Abs'>, <class 'AnyValue'>, <class 'ApproxDistinct'>, <class 'ApproxQuantile'>, <class 'Array'>, <class 'ArrayAgg'>, <class 'ArrayAll'>, <class 'ArrayAny'>, <class 'ArrayConcat'>, <class 'ArrayContains'>, <class 'ArrayFilter'>, <class 'ArrayJoin'>, <class 'ArraySize'>, <class 'ArraySort'>, <class 'ArraySum'>, <class 'ArrayUnionAgg'>, <class 'Avg'>, <class 'Case'>, <class 'Cast'>, <class 'CastToStrType'>, <class 'Ceil'>, <class 'Chr'>, <class 'Coalesce'>, <class 'Collate'>, <class 'Concat'>, <class 'ConcatWs'>, <class 'Count'>, <class 'CountIf'>, <class 'CurrentDate'>, <class 'CurrentDatetime'>, <class 'CurrentTime'>, <class 'CurrentTimestamp'>, <class 'CurrentUser'>, <class 'Date'>, <class 'DateAdd'>, <class 'DateDiff'>, <class 'DateFromParts'>, <class 'DateStrToDate'>, <class 'DateSub'>, <class 'DateToDateStr'>, <class 'DateToDi'>, <class 'DateTrunc'>, <class 'DatetimeAdd'>, <class 'DatetimeDiff'>, <class 'DatetimeSub'>, <class 'DatetimeTrunc'>, <class 'Day'>, <class 'DayOfMonth'>, <class 'DayOfWeek'>, <class 'DayOfYear'>, <class 'Decode'>, <class 'DiToDate'>, <class 'Encode'>, <class 'Exp'>, <class 'Explode'>, <class 'ExplodeOuter'>, <class 'Extract'>, <class 'First'>, <class 'Flatten'>, <class 'Floor'>, <class 'FromBase'>, <class 'FromBase64'>, <class 'GenerateSeries'>, <class 'Greatest'>, <class 'GroupConcat'>, <class 'Hex'>, <class 'Hll'>, <class 'If'>, <class 'Initcap'>, <class 'IsNan'>, <class 'JSONArray'>, <class 'JSONArrayAgg'>, <class 'JSONArrayContains'>, <class 'JSONBExtract'>, <class 'JSONBExtractScalar'>, <class 'JSONExtract'>, <class 'JSONExtractScalar'>, <class 'JSONFormat'>, <class 'JSONObject'>, <class 'JSONTable'>, <class 'Last'>, <class 'LastDateOfMonth'>, <class 'Least'>, <class 'Left'>, <class 'Length'>, <class 'Levenshtein'>, <class 'Ln'>, <class 'Log'>, <class 'Log10'>, <class 'Log2'>, <class 'LogicalAnd'>, <class 'LogicalOr'>, <class 'Lower'>, <class 'MD5'>, <class 'MD5Digest'>, <class 'Map'>, <class 'MapFromEntries'>, <class 'MatchAgainst'>, <class 'Max'>, <class 'Min'>, <class 'Month'>, <class 'MonthsBetween'>, <class 'NextValueFor'>, <class 'NumberToStr'>, <class 'Nvl2'>, <class 'OpenJSON'>, <class 'ParameterizedAgg'>, <class 'ParseJSON'>, <class 'PercentileCont'>, <class 'PercentileDisc'>, <class 'Posexplode'>, <class 'PosexplodeOuter'>, <class 'Pow'>, <class 'Predict'>, <class 'Quantile'>, <class 'RangeN'>, <class 'ReadCSV'>, <class 'Reduce'>, <class 'RegexpExtract'>, <class 'RegexpILike'>, <class 'RegexpLike'>, <class 'RegexpReplace'>, <class 'RegexpSplit'>, <class 'Repeat'>, <class 'Right'>, <class 'Round'>, <class 'RowNumber'>, <class 'SHA'>, <class 'SHA2'>, <class 'SafeConcat'>, <class 'SafeDivide'>, <class 'SetAgg'>, <class 'SortArray'>, <class 'Split'>, <class 'Sqrt'>, <class 'StandardHash'>, <class 'StarMap'>, <class 'StartsWith'>, <class 'Stddev'>, <class 'StddevPop'>, <class 'StddevSamp'>, <class 'StrPosition'>, <class 'StrToDate'>, <class 'StrToMap'>, <class 'StrToTime'>, <class 'StrToUnix'>, <class 'Struct'>, <class 'StructExtract'>, <class 'Stuff'>, <class 'Substring'>, <class 'Sum'>, <class 'TimeAdd'>, <class 'TimeDiff'>, <class 'TimeStrToDate'>, <class 'TimeStrToTime'>, <class 'TimeStrToUnix'>, <class 'TimeSub'>, <class 'TimeToStr'>, <class 'TimeToTimeStr'>, <class 'TimeToUnix'>, <class 'TimeTrunc'>, <class 'Timestamp'>, <class 'TimestampAdd'>, <class 'TimestampDiff'>, <class 'TimestampSub'>, <class 'TimestampTrunc'>, <class 'ToBase64'>, <class 'ToChar'>, <class 'ToDays'>, <class 'Transform'>, <class 'Trim'>, <class 'TryCast'>, <class 'TsOrDiToDi'>, <class 'TsOrDsAdd'>, <class 'TsOrDsToDate'>, <class 'TsOrDsToDateStr'>, <class 'Unhex'>, <class 'UnixToStr'>, <class 'UnixToTime'>, <class 'UnixToTimeStr'>, <class 'Upper'>, <class 'VarMap'>, <class 'Variance'>, <class 'VariancePop'>, <class 'Week'>, <class 'WeekOfYear'>, <class 'When'>, <class 'XMLTable'>, <class 'Xor'>, <class 'Year'>]
def maybe_parse( sql_or_expression: Union[str, Expression], *, into: Union[str, Type[Expression], Collection[Union[str, Type[Expression]]], NoneType] = None, dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, prefix: Optional[str] = None, copy: bool = False, **opts) -> Expression:
5176def maybe_parse(
5177    sql_or_expression: ExpOrStr,
5178    *,
5179    into: t.Optional[IntoType] = None,
5180    dialect: DialectType = None,
5181    prefix: t.Optional[str] = None,
5182    copy: bool = False,
5183    **opts,
5184) -> Expression:
5185    """Gracefully handle a possible string or expression.
5186
5187    Example:
5188        >>> maybe_parse("1")
5189        (LITERAL this: 1, is_string: False)
5190        >>> maybe_parse(to_identifier("x"))
5191        (IDENTIFIER this: x, quoted: False)
5192
5193    Args:
5194        sql_or_expression: the SQL code string or an expression
5195        into: the SQLGlot Expression to parse into
5196        dialect: the dialect used to parse the input expressions (in the case that an
5197            input expression is a SQL string).
5198        prefix: a string to prefix the sql with before it gets parsed
5199            (automatically includes a space)
5200        copy: whether or not to copy the expression.
5201        **opts: other options to use to parse the input expressions (again, in the case
5202            that an input expression is a SQL string).
5203
5204    Returns:
5205        Expression: the parsed or given expression.
5206    """
5207    if isinstance(sql_or_expression, Expression):
5208        if copy:
5209            return sql_or_expression.copy()
5210        return sql_or_expression
5211
5212    if sql_or_expression is None:
5213        raise ParseError(f"SQL cannot be None")
5214
5215    import sqlglot
5216
5217    sql = str(sql_or_expression)
5218    if prefix:
5219        sql = f"{prefix} {sql}"
5220
5221    return sqlglot.parse_one(sql, read=dialect, into=into, **opts)

Gracefully handle a possible string or expression.

Example:
>>> maybe_parse("1")
(LITERAL this: 1, is_string: False)
>>> maybe_parse(to_identifier("x"))
(IDENTIFIER this: x, quoted: False)
Arguments:
  • sql_or_expression: the SQL code string or an expression
  • into: the SQLGlot Expression to parse into
  • dialect: the dialect used to parse the input expressions (in the case that an input expression is a SQL string).
  • prefix: a string to prefix the sql with before it gets parsed (automatically includes a space)
  • copy: whether or not to copy the expression.
  • **opts: other options to use to parse the input expressions (again, in the case that an input expression is a SQL string).
Returns:

Expression: the parsed or given expression.

def maybe_copy(instance, copy=True):
5234def maybe_copy(instance, copy=True):
5235    return instance.copy() if copy and instance else instance
def union( left: Union[str, Expression], right: Union[str, Expression], distinct: bool = True, dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, **opts) -> Union:
5416def union(
5417    left: ExpOrStr, right: ExpOrStr, distinct: bool = True, dialect: DialectType = None, **opts
5418) -> Union:
5419    """
5420    Initializes a syntax tree from one UNION expression.
5421
5422    Example:
5423        >>> union("SELECT * FROM foo", "SELECT * FROM bla").sql()
5424        'SELECT * FROM foo UNION SELECT * FROM bla'
5425
5426    Args:
5427        left: the SQL code string corresponding to the left-hand side.
5428            If an `Expression` instance is passed, it will be used as-is.
5429        right: the SQL code string corresponding to the right-hand side.
5430            If an `Expression` instance is passed, it will be used as-is.
5431        distinct: set the DISTINCT flag if and only if this is true.
5432        dialect: the dialect used to parse the input expression.
5433        opts: other options to use to parse the input expressions.
5434
5435    Returns:
5436        The new Union instance.
5437    """
5438    left = maybe_parse(sql_or_expression=left, dialect=dialect, **opts)
5439    right = maybe_parse(sql_or_expression=right, dialect=dialect, **opts)
5440
5441    return Union(this=left, expression=right, distinct=distinct)

Initializes a syntax tree from one UNION expression.

Example:
>>> union("SELECT * FROM foo", "SELECT * FROM bla").sql()
'SELECT * FROM foo UNION SELECT * FROM bla'
Arguments:
  • left: the SQL code string corresponding to the left-hand side. If an Expression instance is passed, it will be used as-is.
  • right: the SQL code string corresponding to the right-hand side. If an Expression instance is passed, it will be used as-is.
  • distinct: set the DISTINCT flag if and only if this is true.
  • dialect: the dialect used to parse the input expression.
  • opts: other options to use to parse the input expressions.
Returns:

The new Union instance.

def intersect( left: Union[str, Expression], right: Union[str, Expression], distinct: bool = True, dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, **opts) -> Intersect:
5444def intersect(
5445    left: ExpOrStr, right: ExpOrStr, distinct: bool = True, dialect: DialectType = None, **opts
5446) -> Intersect:
5447    """
5448    Initializes a syntax tree from one INTERSECT expression.
5449
5450    Example:
5451        >>> intersect("SELECT * FROM foo", "SELECT * FROM bla").sql()
5452        'SELECT * FROM foo INTERSECT SELECT * FROM bla'
5453
5454    Args:
5455        left: the SQL code string corresponding to the left-hand side.
5456            If an `Expression` instance is passed, it will be used as-is.
5457        right: the SQL code string corresponding to the right-hand side.
5458            If an `Expression` instance is passed, it will be used as-is.
5459        distinct: set the DISTINCT flag if and only if this is true.
5460        dialect: the dialect used to parse the input expression.
5461        opts: other options to use to parse the input expressions.
5462
5463    Returns:
5464        The new Intersect instance.
5465    """
5466    left = maybe_parse(sql_or_expression=left, dialect=dialect, **opts)
5467    right = maybe_parse(sql_or_expression=right, dialect=dialect, **opts)
5468
5469    return Intersect(this=left, expression=right, distinct=distinct)

Initializes a syntax tree from one INTERSECT expression.

Example:
>>> intersect("SELECT * FROM foo", "SELECT * FROM bla").sql()
'SELECT * FROM foo INTERSECT SELECT * FROM bla'
Arguments:
  • left: the SQL code string corresponding to the left-hand side. If an Expression instance is passed, it will be used as-is.
  • right: the SQL code string corresponding to the right-hand side. If an Expression instance is passed, it will be used as-is.
  • distinct: set the DISTINCT flag if and only if this is true.
  • dialect: the dialect used to parse the input expression.
  • opts: other options to use to parse the input expressions.
Returns:

The new Intersect instance.

def except_( left: Union[str, Expression], right: Union[str, Expression], distinct: bool = True, dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, **opts) -> Except:
5472def except_(
5473    left: ExpOrStr, right: ExpOrStr, distinct: bool = True, dialect: DialectType = None, **opts
5474) -> Except:
5475    """
5476    Initializes a syntax tree from one EXCEPT expression.
5477
5478    Example:
5479        >>> except_("SELECT * FROM foo", "SELECT * FROM bla").sql()
5480        'SELECT * FROM foo EXCEPT SELECT * FROM bla'
5481
5482    Args:
5483        left: the SQL code string corresponding to the left-hand side.
5484            If an `Expression` instance is passed, it will be used as-is.
5485        right: the SQL code string corresponding to the right-hand side.
5486            If an `Expression` instance is passed, it will be used as-is.
5487        distinct: set the DISTINCT flag if and only if this is true.
5488        dialect: the dialect used to parse the input expression.
5489        opts: other options to use to parse the input expressions.
5490
5491    Returns:
5492        The new Except instance.
5493    """
5494    left = maybe_parse(sql_or_expression=left, dialect=dialect, **opts)
5495    right = maybe_parse(sql_or_expression=right, dialect=dialect, **opts)
5496
5497    return Except(this=left, expression=right, distinct=distinct)

Initializes a syntax tree from one EXCEPT expression.

Example:
>>> except_("SELECT * FROM foo", "SELECT * FROM bla").sql()
'SELECT * FROM foo EXCEPT SELECT * FROM bla'
Arguments:
  • left: the SQL code string corresponding to the left-hand side. If an Expression instance is passed, it will be used as-is.
  • right: the SQL code string corresponding to the right-hand side. If an Expression instance is passed, it will be used as-is.
  • distinct: set the DISTINCT flag if and only if this is true.
  • dialect: the dialect used to parse the input expression.
  • opts: other options to use to parse the input expressions.
Returns:

The new Except instance.

def select( *expressions: Union[str, Expression], dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, **opts) -> Select:
5500def select(*expressions: ExpOrStr, dialect: DialectType = None, **opts) -> Select:
5501    """
5502    Initializes a syntax tree from one or multiple SELECT expressions.
5503
5504    Example:
5505        >>> select("col1", "col2").from_("tbl").sql()
5506        'SELECT col1, col2 FROM tbl'
5507
5508    Args:
5509        *expressions: the SQL code string to parse as the expressions of a
5510            SELECT statement. If an Expression instance is passed, this is used as-is.
5511        dialect: the dialect used to parse the input expressions (in the case that an
5512            input expression is a SQL string).
5513        **opts: other options to use to parse the input expressions (again, in the case
5514            that an input expression is a SQL string).
5515
5516    Returns:
5517        Select: the syntax tree for the SELECT statement.
5518    """
5519    return Select().select(*expressions, dialect=dialect, **opts)

Initializes a syntax tree from one or multiple SELECT expressions.

Example:
>>> select("col1", "col2").from_("tbl").sql()
'SELECT col1, col2 FROM tbl'
Arguments:
  • *expressions: the SQL code string to parse as the expressions of a SELECT statement. If an Expression instance is passed, this is used as-is.
  • dialect: the dialect used to parse the input expressions (in the case that an input expression is a SQL string).
  • **opts: other options to use to parse the input expressions (again, in the case that an input expression is a SQL string).
Returns:

Select: the syntax tree for the SELECT statement.

def from_( expression: Union[str, Expression], dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, **opts) -> Select:
5522def from_(expression: ExpOrStr, dialect: DialectType = None, **opts) -> Select:
5523    """
5524    Initializes a syntax tree from a FROM expression.
5525
5526    Example:
5527        >>> from_("tbl").select("col1", "col2").sql()
5528        'SELECT col1, col2 FROM tbl'
5529
5530    Args:
5531        *expression: the SQL code string to parse as the FROM expressions of a
5532            SELECT statement. If an Expression instance is passed, this is used as-is.
5533        dialect: the dialect used to parse the input expression (in the case that the
5534            input expression is a SQL string).
5535        **opts: other options to use to parse the input expressions (again, in the case
5536            that the input expression is a SQL string).
5537
5538    Returns:
5539        Select: the syntax tree for the SELECT statement.
5540    """
5541    return Select().from_(expression, dialect=dialect, **opts)

Initializes a syntax tree from a FROM expression.

Example:
>>> from_("tbl").select("col1", "col2").sql()
'SELECT col1, col2 FROM tbl'
Arguments:
  • *expression: the SQL code string to parse as the FROM expressions of a SELECT statement. If an Expression instance is passed, this is used as-is.
  • dialect: the dialect used to parse the input expression (in the case that the input expression is a SQL string).
  • **opts: other options to use to parse the input expressions (again, in the case that the input expression is a SQL string).
Returns:

Select: the syntax tree for the SELECT statement.

def update( table: str | Table, properties: dict, where: Union[str, Expression, NoneType] = None, from_: Union[str, Expression, NoneType] = None, dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, **opts) -> Update:
5544def update(
5545    table: str | Table,
5546    properties: dict,
5547    where: t.Optional[ExpOrStr] = None,
5548    from_: t.Optional[ExpOrStr] = None,
5549    dialect: DialectType = None,
5550    **opts,
5551) -> Update:
5552    """
5553    Creates an update statement.
5554
5555    Example:
5556        >>> update("my_table", {"x": 1, "y": "2", "z": None}, from_="baz", where="id > 1").sql()
5557        "UPDATE my_table SET x = 1, y = '2', z = NULL FROM baz WHERE id > 1"
5558
5559    Args:
5560        *properties: dictionary of properties to set which are
5561            auto converted to sql objects eg None -> NULL
5562        where: sql conditional parsed into a WHERE statement
5563        from_: sql statement parsed into a FROM statement
5564        dialect: the dialect used to parse the input expressions.
5565        **opts: other options to use to parse the input expressions.
5566
5567    Returns:
5568        Update: the syntax tree for the UPDATE statement.
5569    """
5570    update_expr = Update(this=maybe_parse(table, into=Table, dialect=dialect))
5571    update_expr.set(
5572        "expressions",
5573        [
5574            EQ(this=maybe_parse(k, dialect=dialect, **opts), expression=convert(v))
5575            for k, v in properties.items()
5576        ],
5577    )
5578    if from_:
5579        update_expr.set(
5580            "from",
5581            maybe_parse(from_, into=From, dialect=dialect, prefix="FROM", **opts),
5582        )
5583    if isinstance(where, Condition):
5584        where = Where(this=where)
5585    if where:
5586        update_expr.set(
5587            "where",
5588            maybe_parse(where, into=Where, dialect=dialect, prefix="WHERE", **opts),
5589        )
5590    return update_expr

Creates an update statement.

Example:
>>> update("my_table", {"x": 1, "y": "2", "z": None}, from_="baz", where="id > 1").sql()
"UPDATE my_table SET x = 1, y = '2', z = NULL FROM baz WHERE id > 1"
Arguments:
  • *properties: dictionary of properties to set which are auto converted to sql objects eg None -> NULL
  • where: sql conditional parsed into a WHERE statement
  • from_: sql statement parsed into a FROM statement
  • dialect: the dialect used to parse the input expressions.
  • **opts: other options to use to parse the input expressions.
Returns:

Update: the syntax tree for the UPDATE statement.

def delete( table: Union[str, Expression], where: Union[str, Expression, NoneType] = None, returning: Union[str, Expression, NoneType] = None, dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, **opts) -> Delete:
5593def delete(
5594    table: ExpOrStr,
5595    where: t.Optional[ExpOrStr] = None,
5596    returning: t.Optional[ExpOrStr] = None,
5597    dialect: DialectType = None,
5598    **opts,
5599) -> Delete:
5600    """
5601    Builds a delete statement.
5602
5603    Example:
5604        >>> delete("my_table", where="id > 1").sql()
5605        'DELETE FROM my_table WHERE id > 1'
5606
5607    Args:
5608        where: sql conditional parsed into a WHERE statement
5609        returning: sql conditional parsed into a RETURNING statement
5610        dialect: the dialect used to parse the input expressions.
5611        **opts: other options to use to parse the input expressions.
5612
5613    Returns:
5614        Delete: the syntax tree for the DELETE statement.
5615    """
5616    delete_expr = Delete().delete(table, dialect=dialect, copy=False, **opts)
5617    if where:
5618        delete_expr = delete_expr.where(where, dialect=dialect, copy=False, **opts)
5619    if returning:
5620        delete_expr = delete_expr.returning(returning, dialect=dialect, copy=False, **opts)
5621    return delete_expr

Builds a delete statement.

Example:
>>> delete("my_table", where="id > 1").sql()
'DELETE FROM my_table WHERE id > 1'
Arguments:
  • where: sql conditional parsed into a WHERE statement
  • returning: sql conditional parsed into a RETURNING statement
  • dialect: the dialect used to parse the input expressions.
  • **opts: other options to use to parse the input expressions.
Returns:

Delete: the syntax tree for the DELETE statement.

def insert( expression: Union[str, Expression], into: Union[str, Expression], columns: Optional[Sequence[Union[str, Expression]]] = None, overwrite: Optional[bool] = None, dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, copy: bool = True, **opts) -> Insert:
5624def insert(
5625    expression: ExpOrStr,
5626    into: ExpOrStr,
5627    columns: t.Optional[t.Sequence[ExpOrStr]] = None,
5628    overwrite: t.Optional[bool] = None,
5629    dialect: DialectType = None,
5630    copy: bool = True,
5631    **opts,
5632) -> Insert:
5633    """
5634    Builds an INSERT statement.
5635
5636    Example:
5637        >>> insert("VALUES (1, 2, 3)", "tbl").sql()
5638        'INSERT INTO tbl VALUES (1, 2, 3)'
5639
5640    Args:
5641        expression: the sql string or expression of the INSERT statement
5642        into: the tbl to insert data to.
5643        columns: optionally the table's column names.
5644        overwrite: whether to INSERT OVERWRITE or not.
5645        dialect: the dialect used to parse the input expressions.
5646        copy: whether or not to copy the expression.
5647        **opts: other options to use to parse the input expressions.
5648
5649    Returns:
5650        Insert: the syntax tree for the INSERT statement.
5651    """
5652    expr = maybe_parse(expression, dialect=dialect, copy=copy, **opts)
5653    this: Table | Schema = maybe_parse(into, into=Table, dialect=dialect, copy=copy, **opts)
5654
5655    if columns:
5656        this = _apply_list_builder(
5657            *columns,
5658            instance=Schema(this=this),
5659            arg="expressions",
5660            into=Identifier,
5661            copy=False,
5662            dialect=dialect,
5663            **opts,
5664        )
5665
5666    return Insert(this=this, expression=expr, overwrite=overwrite)

Builds an INSERT statement.

Example:
>>> insert("VALUES (1, 2, 3)", "tbl").sql()
'INSERT INTO tbl VALUES (1, 2, 3)'
Arguments:
  • expression: the sql string or expression of the INSERT statement
  • into: the tbl to insert data to.
  • columns: optionally the table's column names.
  • overwrite: whether to INSERT OVERWRITE or not.
  • dialect: the dialect used to parse the input expressions.
  • copy: whether or not to copy the expression.
  • **opts: other options to use to parse the input expressions.
Returns:

Insert: the syntax tree for the INSERT statement.

def condition( expression: Union[str, Expression], dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, copy: bool = True, **opts) -> Condition:
5669def condition(
5670    expression: ExpOrStr, dialect: DialectType = None, copy: bool = True, **opts
5671) -> Condition:
5672    """
5673    Initialize a logical condition expression.
5674
5675    Example:
5676        >>> condition("x=1").sql()
5677        'x = 1'
5678
5679        This is helpful for composing larger logical syntax trees:
5680        >>> where = condition("x=1")
5681        >>> where = where.and_("y=1")
5682        >>> Select().from_("tbl").select("*").where(where).sql()
5683        'SELECT * FROM tbl WHERE x = 1 AND y = 1'
5684
5685    Args:
5686        *expression: the SQL code string to parse.
5687            If an Expression instance is passed, this is used as-is.
5688        dialect: the dialect used to parse the input expression (in the case that the
5689            input expression is a SQL string).
5690        copy: Whether or not to copy `expression` (only applies to expressions).
5691        **opts: other options to use to parse the input expressions (again, in the case
5692            that the input expression is a SQL string).
5693
5694    Returns:
5695        The new Condition instance
5696    """
5697    return maybe_parse(
5698        expression,
5699        into=Condition,
5700        dialect=dialect,
5701        copy=copy,
5702        **opts,
5703    )

Initialize a logical condition expression.

Example:
>>> condition("x=1").sql()
'x = 1'

This is helpful for composing larger logical syntax trees:

>>> where = condition("x=1")
>>> where = where.and_("y=1")
>>> Select().from_("tbl").select("*").where(where).sql()
'SELECT * FROM tbl WHERE x = 1 AND y = 1'
Arguments:
  • *expression: the SQL code string to parse. If an Expression instance is passed, this is used as-is.
  • dialect: the dialect used to parse the input expression (in the case that the input expression is a SQL string).
  • copy: Whether or not to copy expression (only applies to expressions).
  • **opts: other options to use to parse the input expressions (again, in the case that the input expression is a SQL string).
Returns:

The new Condition instance

def and_( *expressions: Union[str, Expression, NoneType], dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, copy: bool = True, **opts) -> Condition:
5706def and_(
5707    *expressions: t.Optional[ExpOrStr], dialect: DialectType = None, copy: bool = True, **opts
5708) -> Condition:
5709    """
5710    Combine multiple conditions with an AND logical operator.
5711
5712    Example:
5713        >>> and_("x=1", and_("y=1", "z=1")).sql()
5714        'x = 1 AND (y = 1 AND z = 1)'
5715
5716    Args:
5717        *expressions: the SQL code strings to parse.
5718            If an Expression instance is passed, this is used as-is.
5719        dialect: the dialect used to parse the input expression.
5720        copy: whether or not to copy `expressions` (only applies to Expressions).
5721        **opts: other options to use to parse the input expressions.
5722
5723    Returns:
5724        And: the new condition
5725    """
5726    return t.cast(Condition, _combine(expressions, And, dialect, copy=copy, **opts))

Combine multiple conditions with an AND logical operator.

Example:
>>> and_("x=1", and_("y=1", "z=1")).sql()
'x = 1 AND (y = 1 AND z = 1)'
Arguments:
  • *expressions: the SQL code strings to parse. If an Expression instance is passed, this is used as-is.
  • dialect: the dialect used to parse the input expression.
  • copy: whether or not to copy expressions (only applies to Expressions).
  • **opts: other options to use to parse the input expressions.
Returns:

And: the new condition

def or_( *expressions: Union[str, Expression, NoneType], dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, copy: bool = True, **opts) -> Condition:
5729def or_(
5730    *expressions: t.Optional[ExpOrStr], dialect: DialectType = None, copy: bool = True, **opts
5731) -> Condition:
5732    """
5733    Combine multiple conditions with an OR logical operator.
5734
5735    Example:
5736        >>> or_("x=1", or_("y=1", "z=1")).sql()
5737        'x = 1 OR (y = 1 OR z = 1)'
5738
5739    Args:
5740        *expressions: the SQL code strings to parse.
5741            If an Expression instance is passed, this is used as-is.
5742        dialect: the dialect used to parse the input expression.
5743        copy: whether or not to copy `expressions` (only applies to Expressions).
5744        **opts: other options to use to parse the input expressions.
5745
5746    Returns:
5747        Or: the new condition
5748    """
5749    return t.cast(Condition, _combine(expressions, Or, dialect, copy=copy, **opts))

Combine multiple conditions with an OR logical operator.

Example:
>>> or_("x=1", or_("y=1", "z=1")).sql()
'x = 1 OR (y = 1 OR z = 1)'
Arguments:
  • *expressions: the SQL code strings to parse. If an Expression instance is passed, this is used as-is.
  • dialect: the dialect used to parse the input expression.
  • copy: whether or not to copy expressions (only applies to Expressions).
  • **opts: other options to use to parse the input expressions.
Returns:

Or: the new condition

def not_( expression: Union[str, Expression], dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, copy: bool = True, **opts) -> Not:
5752def not_(expression: ExpOrStr, dialect: DialectType = None, copy: bool = True, **opts) -> Not:
5753    """
5754    Wrap a condition with a NOT operator.
5755
5756    Example:
5757        >>> not_("this_suit='black'").sql()
5758        "NOT this_suit = 'black'"
5759
5760    Args:
5761        expression: the SQL code string to parse.
5762            If an Expression instance is passed, this is used as-is.
5763        dialect: the dialect used to parse the input expression.
5764        copy: whether to copy the expression or not.
5765        **opts: other options to use to parse the input expressions.
5766
5767    Returns:
5768        The new condition.
5769    """
5770    this = condition(
5771        expression,
5772        dialect=dialect,
5773        copy=copy,
5774        **opts,
5775    )
5776    return Not(this=_wrap(this, Connector))

Wrap a condition with a NOT operator.

Example:
>>> not_("this_suit='black'").sql()
"NOT this_suit = 'black'"
Arguments:
  • expression: the SQL code string to parse. If an Expression instance is passed, this is used as-is.
  • dialect: the dialect used to parse the input expression.
  • copy: whether to copy the expression or not.
  • **opts: other options to use to parse the input expressions.
Returns:

The new condition.

def paren( expression: Union[str, Expression], copy: bool = True) -> Paren:
5779def paren(expression: ExpOrStr, copy: bool = True) -> Paren:
5780    """
5781    Wrap an expression in parentheses.
5782
5783    Example:
5784        >>> paren("5 + 3").sql()
5785        '(5 + 3)'
5786
5787    Args:
5788        expression: the SQL code string to parse.
5789            If an Expression instance is passed, this is used as-is.
5790        copy: whether to copy the expression or not.
5791
5792    Returns:
5793        The wrapped expression.
5794    """
5795    return Paren(this=maybe_parse(expression, copy=copy))

Wrap an expression in parentheses.

Example:
>>> paren("5 + 3").sql()
'(5 + 3)'
Arguments:
  • expression: the SQL code string to parse. If an Expression instance is passed, this is used as-is.
  • copy: whether to copy the expression or not.
Returns:

The wrapped expression.

SAFE_IDENTIFIER_RE = re.compile('^[_a-zA-Z][\\w]*$')
def to_identifier(name, quoted=None, copy=True):
5813def to_identifier(name, quoted=None, copy=True):
5814    """Builds an identifier.
5815
5816    Args:
5817        name: The name to turn into an identifier.
5818        quoted: Whether or not force quote the identifier.
5819        copy: Whether or not to copy a passed in Identefier node.
5820
5821    Returns:
5822        The identifier ast node.
5823    """
5824
5825    if name is None:
5826        return None
5827
5828    if isinstance(name, Identifier):
5829        identifier = maybe_copy(name, copy)
5830    elif isinstance(name, str):
5831        identifier = Identifier(
5832            this=name,
5833            quoted=not SAFE_IDENTIFIER_RE.match(name) if quoted is None else quoted,
5834        )
5835    else:
5836        raise ValueError(f"Name needs to be a string or an Identifier, got: {name.__class__}")
5837    return identifier

Builds an identifier.

Arguments:
  • name: The name to turn into an identifier.
  • quoted: Whether or not force quote the identifier.
  • copy: Whether or not to copy a passed in Identefier node.
Returns:

The identifier ast node.

INTERVAL_STRING_RE = re.compile('\\s*([0-9]+)\\s*([a-zA-Z]+)\\s*')
def to_interval( interval: str | Literal) -> Interval:
5843def to_interval(interval: str | Literal) -> Interval:
5844    """Builds an interval expression from a string like '1 day' or '5 months'."""
5845    if isinstance(interval, Literal):
5846        if not interval.is_string:
5847            raise ValueError("Invalid interval string.")
5848
5849        interval = interval.this
5850
5851    interval_parts = INTERVAL_STRING_RE.match(interval)  # type: ignore
5852
5853    if not interval_parts:
5854        raise ValueError("Invalid interval string.")
5855
5856    return Interval(
5857        this=Literal.string(interval_parts.group(1)),
5858        unit=Var(this=interval_parts.group(2)),
5859    )

Builds an interval expression from a string like '1 day' or '5 months'.

def to_table( sql_path: Union[str, Table, NoneType], dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, **kwargs) -> Optional[Table]:
5872def to_table(
5873    sql_path: t.Optional[str | Table], dialect: DialectType = None, **kwargs
5874) -> t.Optional[Table]:
5875    """
5876    Create a table expression from a `[catalog].[schema].[table]` sql path. Catalog and schema are optional.
5877    If a table is passed in then that table is returned.
5878
5879    Args:
5880        sql_path: a `[catalog].[schema].[table]` string.
5881        dialect: the source dialect according to which the table name will be parsed.
5882        kwargs: the kwargs to instantiate the resulting `Table` expression with.
5883
5884    Returns:
5885        A table expression.
5886    """
5887    if sql_path is None or isinstance(sql_path, Table):
5888        return sql_path
5889    if not isinstance(sql_path, str):
5890        raise ValueError(f"Invalid type provided for a table: {type(sql_path)}")
5891
5892    table = maybe_parse(sql_path, into=Table, dialect=dialect)
5893    if table:
5894        for k, v in kwargs.items():
5895            table.set(k, v)
5896
5897    return table

Create a table expression from a [catalog].[schema].[table] sql path. Catalog and schema are optional. If a table is passed in then that table is returned.

Arguments:
  • sql_path: a [catalog].[schema].[table] string.
  • dialect: the source dialect according to which the table name will be parsed.
  • kwargs: the kwargs to instantiate the resulting Table expression with.
Returns:

A table expression.

def to_column( sql_path: str | Column, **kwargs) -> Column:
5900def to_column(sql_path: str | Column, **kwargs) -> Column:
5901    """
5902    Create a column from a `[table].[column]` sql path. Schema is optional.
5903
5904    If a column is passed in then that column is returned.
5905
5906    Args:
5907        sql_path: `[table].[column]` string
5908    Returns:
5909        Table: A column expression
5910    """
5911    if sql_path is None or isinstance(sql_path, Column):
5912        return sql_path
5913    if not isinstance(sql_path, str):
5914        raise ValueError(f"Invalid type provided for column: {type(sql_path)}")
5915    return column(*reversed(sql_path.split(".")), **kwargs)  # type: ignore

Create a column from a [table].[column] sql path. Schema is optional.

If a column is passed in then that column is returned.

Arguments:
  • sql_path: [table].[column] string
Returns:

Table: A column expression

def alias_( expression: Union[str, Expression], alias: str | Identifier, table: Union[bool, Sequence[str | Identifier]] = False, quoted: Optional[bool] = None, dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, copy: bool = True, **opts):
5918def alias_(
5919    expression: ExpOrStr,
5920    alias: str | Identifier,
5921    table: bool | t.Sequence[str | Identifier] = False,
5922    quoted: t.Optional[bool] = None,
5923    dialect: DialectType = None,
5924    copy: bool = True,
5925    **opts,
5926):
5927    """Create an Alias expression.
5928
5929    Example:
5930        >>> alias_('foo', 'bar').sql()
5931        'foo AS bar'
5932
5933        >>> alias_('(select 1, 2)', 'bar', table=['a', 'b']).sql()
5934        '(SELECT 1, 2) AS bar(a, b)'
5935
5936    Args:
5937        expression: the SQL code strings to parse.
5938            If an Expression instance is passed, this is used as-is.
5939        alias: the alias name to use. If the name has
5940            special characters it is quoted.
5941        table: Whether or not to create a table alias, can also be a list of columns.
5942        quoted: whether or not to quote the alias
5943        dialect: the dialect used to parse the input expression.
5944        copy: Whether or not to copy the expression.
5945        **opts: other options to use to parse the input expressions.
5946
5947    Returns:
5948        Alias: the aliased expression
5949    """
5950    exp = maybe_parse(expression, dialect=dialect, copy=copy, **opts)
5951    alias = to_identifier(alias, quoted=quoted)
5952
5953    if table:
5954        table_alias = TableAlias(this=alias)
5955        exp.set("alias", table_alias)
5956
5957        if not isinstance(table, bool):
5958            for column in table:
5959                table_alias.append("columns", to_identifier(column, quoted=quoted))
5960
5961        return exp
5962
5963    # We don't set the "alias" arg for Window expressions, because that would add an IDENTIFIER node in
5964    # the AST, representing a "named_window" [1] construct (eg. bigquery). What we want is an ALIAS node
5965    # for the complete Window expression.
5966    #
5967    # [1]: https://cloud.google.com/bigquery/docs/reference/standard-sql/window-function-calls
5968
5969    if "alias" in exp.arg_types and not isinstance(exp, Window):
5970        exp.set("alias", alias)
5971        return exp
5972    return Alias(this=exp, alias=alias)

Create an Alias expression.

Example:
>>> alias_('foo', 'bar').sql()
'foo AS bar'
>>> alias_('(select 1, 2)', 'bar', table=['a', 'b']).sql()
'(SELECT 1, 2) AS bar(a, b)'
Arguments:
  • expression: the SQL code strings to parse. If an Expression instance is passed, this is used as-is.
  • alias: the alias name to use. If the name has special characters it is quoted.
  • table: Whether or not to create a table alias, can also be a list of columns.
  • quoted: whether or not to quote the alias
  • dialect: the dialect used to parse the input expression.
  • copy: Whether or not to copy the expression.
  • **opts: other options to use to parse the input expressions.
Returns:

Alias: the aliased expression

def subquery( expression: Union[str, Expression], alias: Union[Identifier, str, NoneType] = None, dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, **opts) -> Select:
5975def subquery(
5976    expression: ExpOrStr,
5977    alias: t.Optional[Identifier | str] = None,
5978    dialect: DialectType = None,
5979    **opts,
5980) -> Select:
5981    """
5982    Build a subquery expression.
5983
5984    Example:
5985        >>> subquery('select x from tbl', 'bar').select('x').sql()
5986        'SELECT x FROM (SELECT x FROM tbl) AS bar'
5987
5988    Args:
5989        expression: the SQL code strings to parse.
5990            If an Expression instance is passed, this is used as-is.
5991        alias: the alias name to use.
5992        dialect: the dialect used to parse the input expression.
5993        **opts: other options to use to parse the input expressions.
5994
5995    Returns:
5996        A new Select instance with the subquery expression included.
5997    """
5998
5999    expression = maybe_parse(expression, dialect=dialect, **opts).subquery(alias)
6000    return Select().from_(expression, dialect=dialect, **opts)

Build a subquery expression.

Example:
>>> subquery('select x from tbl', 'bar').select('x').sql()
'SELECT x FROM (SELECT x FROM tbl) AS bar'
Arguments:
  • expression: the SQL code strings to parse. If an Expression instance is passed, this is used as-is.
  • alias: the alias name to use.
  • dialect: the dialect used to parse the input expression.
  • **opts: other options to use to parse the input expressions.
Returns:

A new Select instance with the subquery expression included.

def column( col: str | Identifier, table: Union[Identifier, str, NoneType] = None, db: Union[Identifier, str, NoneType] = None, catalog: Union[Identifier, str, NoneType] = None, quoted: Optional[bool] = None) -> Column:
6003def column(
6004    col: str | Identifier,
6005    table: t.Optional[str | Identifier] = None,
6006    db: t.Optional[str | Identifier] = None,
6007    catalog: t.Optional[str | Identifier] = None,
6008    quoted: t.Optional[bool] = None,
6009) -> Column:
6010    """
6011    Build a Column.
6012
6013    Args:
6014        col: Column name.
6015        table: Table name.
6016        db: Database name.
6017        catalog: Catalog name.
6018        quoted: Whether to force quotes on the column's identifiers.
6019
6020    Returns:
6021        The new Column instance.
6022    """
6023    return Column(
6024        this=to_identifier(col, quoted=quoted),
6025        table=to_identifier(table, quoted=quoted),
6026        db=to_identifier(db, quoted=quoted),
6027        catalog=to_identifier(catalog, quoted=quoted),
6028    )

Build a Column.

Arguments:
  • col: Column name.
  • table: Table name.
  • db: Database name.
  • catalog: Catalog name.
  • quoted: Whether to force quotes on the column's identifiers.
Returns:

The new Column instance.

def cast( expression: Union[str, Expression], to: str | DataType | DataType.Type, **opts) -> Cast:
6031def cast(expression: ExpOrStr, to: str | DataType | DataType.Type, **opts) -> Cast:
6032    """Cast an expression to a data type.
6033
6034    Example:
6035        >>> cast('x + 1', 'int').sql()
6036        'CAST(x + 1 AS INT)'
6037
6038    Args:
6039        expression: The expression to cast.
6040        to: The datatype to cast to.
6041
6042    Returns:
6043        The new Cast instance.
6044    """
6045    expression = maybe_parse(expression, **opts)
6046    data_type = DataType.build(to, **opts)
6047    expression = Cast(this=expression, to=data_type)
6048    expression.type = data_type
6049    return expression

Cast an expression to a data type.

Example:
>>> cast('x + 1', 'int').sql()
'CAST(x + 1 AS INT)'
Arguments:
  • expression: The expression to cast.
  • to: The datatype to cast to.
Returns:

The new Cast instance.

def table_( table: Identifier | str, db: Union[Identifier, str, NoneType] = None, catalog: Union[Identifier, str, NoneType] = None, quoted: Optional[bool] = None, alias: Union[Identifier, str, NoneType] = None) -> Table:
6052def table_(
6053    table: Identifier | str,
6054    db: t.Optional[Identifier | str] = None,
6055    catalog: t.Optional[Identifier | str] = None,
6056    quoted: t.Optional[bool] = None,
6057    alias: t.Optional[Identifier | str] = None,
6058) -> Table:
6059    """Build a Table.
6060
6061    Args:
6062        table: Table name.
6063        db: Database name.
6064        catalog: Catalog name.
6065        quote: Whether to force quotes on the table's identifiers.
6066        alias: Table's alias.
6067
6068    Returns:
6069        The new Table instance.
6070    """
6071    return Table(
6072        this=to_identifier(table, quoted=quoted) if table else None,
6073        db=to_identifier(db, quoted=quoted) if db else None,
6074        catalog=to_identifier(catalog, quoted=quoted) if catalog else None,
6075        alias=TableAlias(this=to_identifier(alias)) if alias else None,
6076    )

Build a Table.

Arguments:
  • table: Table name.
  • db: Database name.
  • catalog: Catalog name.
  • quote: Whether to force quotes on the table's identifiers.
  • alias: Table's alias.
Returns:

The new Table instance.

def values( values: Iterable[Tuple[Any, ...]], alias: Optional[str] = None, columns: Union[Iterable[str], Dict[str, DataType], NoneType] = None) -> Values:
6079def values(
6080    values: t.Iterable[t.Tuple[t.Any, ...]],
6081    alias: t.Optional[str] = None,
6082    columns: t.Optional[t.Iterable[str] | t.Dict[str, DataType]] = None,
6083) -> Values:
6084    """Build VALUES statement.
6085
6086    Example:
6087        >>> values([(1, '2')]).sql()
6088        "VALUES (1, '2')"
6089
6090    Args:
6091        values: values statements that will be converted to SQL
6092        alias: optional alias
6093        columns: Optional list of ordered column names or ordered dictionary of column names to types.
6094         If either are provided then an alias is also required.
6095
6096    Returns:
6097        Values: the Values expression object
6098    """
6099    if columns and not alias:
6100        raise ValueError("Alias is required when providing columns")
6101
6102    return Values(
6103        expressions=[convert(tup) for tup in values],
6104        alias=(
6105            TableAlias(this=to_identifier(alias), columns=[to_identifier(x) for x in columns])
6106            if columns
6107            else (TableAlias(this=to_identifier(alias)) if alias else None)
6108        ),
6109    )

Build VALUES statement.

Example:
>>> values([(1, '2')]).sql()
"VALUES (1, '2')"
Arguments:
  • values: values statements that will be converted to SQL
  • alias: optional alias
  • columns: Optional list of ordered column names or ordered dictionary of column names to types. If either are provided then an alias is also required.
Returns:

Values: the Values expression object

def var( name: Union[str, Expression, NoneType]) -> Var:
6112def var(name: t.Optional[ExpOrStr]) -> Var:
6113    """Build a SQL variable.
6114
6115    Example:
6116        >>> repr(var('x'))
6117        '(VAR this: x)'
6118
6119        >>> repr(var(column('x', table='y')))
6120        '(VAR this: x)'
6121
6122    Args:
6123        name: The name of the var or an expression who's name will become the var.
6124
6125    Returns:
6126        The new variable node.
6127    """
6128    if not name:
6129        raise ValueError("Cannot convert empty name into var.")
6130
6131    if isinstance(name, Expression):
6132        name = name.name
6133    return Var(this=name)

Build a SQL variable.

Example:
>>> repr(var('x'))
'(VAR this: x)'
>>> repr(var(column('x', table='y')))
'(VAR this: x)'
Arguments:
  • name: The name of the var or an expression who's name will become the var.
Returns:

The new variable node.

def rename_table( old_name: str | Table, new_name: str | Table) -> AlterTable:
6136def rename_table(old_name: str | Table, new_name: str | Table) -> AlterTable:
6137    """Build ALTER TABLE... RENAME... expression
6138
6139    Args:
6140        old_name: The old name of the table
6141        new_name: The new name of the table
6142
6143    Returns:
6144        Alter table expression
6145    """
6146    old_table = to_table(old_name)
6147    new_table = to_table(new_name)
6148    return AlterTable(
6149        this=old_table,
6150        actions=[
6151            RenameTable(this=new_table),
6152        ],
6153    )

Build ALTER TABLE... RENAME... expression

Arguments:
  • old_name: The old name of the table
  • new_name: The new name of the table
Returns:

Alter table expression

def convert(value: Any, copy: bool = False) -> Expression:
6156def convert(value: t.Any, copy: bool = False) -> Expression:
6157    """Convert a python value into an expression object.
6158
6159    Raises an error if a conversion is not possible.
6160
6161    Args:
6162        value: A python object.
6163        copy: Whether or not to copy `value` (only applies to Expressions and collections).
6164
6165    Returns:
6166        Expression: the equivalent expression object.
6167    """
6168    if isinstance(value, Expression):
6169        return maybe_copy(value, copy)
6170    if isinstance(value, str):
6171        return Literal.string(value)
6172    if isinstance(value, bool):
6173        return Boolean(this=value)
6174    if value is None or (isinstance(value, float) and math.isnan(value)):
6175        return NULL
6176    if isinstance(value, numbers.Number):
6177        return Literal.number(value)
6178    if isinstance(value, datetime.datetime):
6179        datetime_literal = Literal.string(
6180            (value if value.tzinfo else value.replace(tzinfo=datetime.timezone.utc)).isoformat()
6181        )
6182        return TimeStrToTime(this=datetime_literal)
6183    if isinstance(value, datetime.date):
6184        date_literal = Literal.string(value.strftime("%Y-%m-%d"))
6185        return DateStrToDate(this=date_literal)
6186    if isinstance(value, tuple):
6187        return Tuple(expressions=[convert(v, copy=copy) for v in value])
6188    if isinstance(value, list):
6189        return Array(expressions=[convert(v, copy=copy) for v in value])
6190    if isinstance(value, dict):
6191        return Map(
6192            keys=Array(expressions=[convert(k, copy=copy) for k in value]),
6193            values=Array(expressions=[convert(v, copy=copy) for v in value.values()]),
6194        )
6195    raise ValueError(f"Cannot convert {value}")

Convert a python value into an expression object.

Raises an error if a conversion is not possible.

Arguments:
  • value: A python object.
  • copy: Whether or not to copy value (only applies to Expressions and collections).
Returns:

Expression: the equivalent expression object.

def replace_children( expression: Expression, fun: Callable, *args, **kwargs) -> None:
6198def replace_children(expression: Expression, fun: t.Callable, *args, **kwargs) -> None:
6199    """
6200    Replace children of an expression with the result of a lambda fun(child) -> exp.
6201    """
6202    for k, v in expression.args.items():
6203        is_list_arg = type(v) is list
6204
6205        child_nodes = v if is_list_arg else [v]
6206        new_child_nodes = []
6207
6208        for cn in child_nodes:
6209            if isinstance(cn, Expression):
6210                for child_node in ensure_collection(fun(cn, *args, **kwargs)):
6211                    new_child_nodes.append(child_node)
6212                    child_node.parent = expression
6213                    child_node.arg_key = k
6214            else:
6215                new_child_nodes.append(cn)
6216
6217        expression.args[k] = new_child_nodes if is_list_arg else seq_get(new_child_nodes, 0)

Replace children of an expression with the result of a lambda fun(child) -> exp.

def column_table_names( expression: Expression, exclude: str = '') -> Set[str]:
6220def column_table_names(expression: Expression, exclude: str = "") -> t.Set[str]:
6221    """
6222    Return all table names referenced through columns in an expression.
6223
6224    Example:
6225        >>> import sqlglot
6226        >>> sorted(column_table_names(sqlglot.parse_one("a.b AND c.d AND c.e")))
6227        ['a', 'c']
6228
6229    Args:
6230        expression: expression to find table names.
6231        exclude: a table name to exclude
6232
6233    Returns:
6234        A list of unique names.
6235    """
6236    return {
6237        table
6238        for table in (column.table for column in expression.find_all(Column))
6239        if table and table != exclude
6240    }

Return all table names referenced through columns in an expression.

Example:
>>> import sqlglot
>>> sorted(column_table_names(sqlglot.parse_one("a.b AND c.d AND c.e")))
['a', 'c']
Arguments:
  • expression: expression to find table names.
  • exclude: a table name to exclude
Returns:

A list of unique names.

def table_name( table: Table | str, dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None) -> str:
6243def table_name(table: Table | str, dialect: DialectType = None) -> str:
6244    """Get the full name of a table as a string.
6245
6246    Args:
6247        table: Table expression node or string.
6248        dialect: The dialect to generate the table name for.
6249
6250    Examples:
6251        >>> from sqlglot import exp, parse_one
6252        >>> table_name(parse_one("select * from a.b.c").find(exp.Table))
6253        'a.b.c'
6254
6255    Returns:
6256        The table name.
6257    """
6258
6259    table = maybe_parse(table, into=Table, dialect=dialect)
6260
6261    if not table:
6262        raise ValueError(f"Cannot parse {table}")
6263
6264    return ".".join(
6265        part.sql(dialect=dialect, identify=True)
6266        if not SAFE_IDENTIFIER_RE.match(part.name)
6267        else part.name
6268        for part in table.parts
6269    )

Get the full name of a table as a string.

Arguments:
  • table: Table expression node or string.
  • dialect: The dialect to generate the table name for.
Examples:
>>> from sqlglot import exp, parse_one
>>> table_name(parse_one("select * from a.b.c").find(exp.Table))
'a.b.c'
Returns:

The table name.

def replace_tables(expression: ~E, mapping: Dict[str, str], copy: bool = True) -> ~E:
6272def replace_tables(expression: E, mapping: t.Dict[str, str], copy: bool = True) -> E:
6273    """Replace all tables in expression according to the mapping.
6274
6275    Args:
6276        expression: expression node to be transformed and replaced.
6277        mapping: mapping of table names.
6278        copy: whether or not to copy the expression.
6279
6280    Examples:
6281        >>> from sqlglot import exp, parse_one
6282        >>> replace_tables(parse_one("select * from a.b"), {"a.b": "c"}).sql()
6283        'SELECT * FROM c'
6284
6285    Returns:
6286        The mapped expression.
6287    """
6288
6289    def _replace_tables(node: Expression) -> Expression:
6290        if isinstance(node, Table):
6291            new_name = mapping.get(table_name(node))
6292            if new_name:
6293                return to_table(
6294                    new_name,
6295                    **{k: v for k, v in node.args.items() if k not in ("this", "db", "catalog")},
6296                )
6297        return node
6298
6299    return expression.transform(_replace_tables, copy=copy)

Replace all tables in expression according to the mapping.

Arguments:
  • expression: expression node to be transformed and replaced.
  • mapping: mapping of table names.
  • copy: whether or not to copy the expression.
Examples:
>>> from sqlglot import exp, parse_one
>>> replace_tables(parse_one("select * from a.b"), {"a.b": "c"}).sql()
'SELECT * FROM c'
Returns:

The mapped expression.

def replace_placeholders( expression: Expression, *args, **kwargs) -> Expression:
6302def replace_placeholders(expression: Expression, *args, **kwargs) -> Expression:
6303    """Replace placeholders in an expression.
6304
6305    Args:
6306        expression: expression node to be transformed and replaced.
6307        args: positional names that will substitute unnamed placeholders in the given order.
6308        kwargs: keyword arguments that will substitute named placeholders.
6309
6310    Examples:
6311        >>> from sqlglot import exp, parse_one
6312        >>> replace_placeholders(
6313        ...     parse_one("select * from :tbl where ? = ?"),
6314        ...     exp.to_identifier("str_col"), "b", tbl=exp.to_identifier("foo")
6315        ... ).sql()
6316        "SELECT * FROM foo WHERE str_col = 'b'"
6317
6318    Returns:
6319        The mapped expression.
6320    """
6321
6322    def _replace_placeholders(node: Expression, args, **kwargs) -> Expression:
6323        if isinstance(node, Placeholder):
6324            if node.name:
6325                new_name = kwargs.get(node.name)
6326                if new_name:
6327                    return convert(new_name)
6328            else:
6329                try:
6330                    return convert(next(args))
6331                except StopIteration:
6332                    pass
6333        return node
6334
6335    return expression.transform(_replace_placeholders, iter(args), **kwargs)

Replace placeholders in an expression.

Arguments:
  • expression: expression node to be transformed and replaced.
  • args: positional names that will substitute unnamed placeholders in the given order.
  • kwargs: keyword arguments that will substitute named placeholders.
Examples:
>>> from sqlglot import exp, parse_one
>>> replace_placeholders(
...     parse_one("select * from :tbl where ? = ?"),
...     exp.to_identifier("str_col"), "b", tbl=exp.to_identifier("foo")
... ).sql()
"SELECT * FROM foo WHERE str_col = 'b'"
Returns:

The mapped expression.

def expand( expression: Expression, sources: Dict[str, Subqueryable], copy: bool = True) -> Expression:
6338def expand(
6339    expression: Expression, sources: t.Dict[str, Subqueryable], copy: bool = True
6340) -> Expression:
6341    """Transforms an expression by expanding all referenced sources into subqueries.
6342
6343    Examples:
6344        >>> from sqlglot import parse_one
6345        >>> expand(parse_one("select * from x AS z"), {"x": parse_one("select * from y")}).sql()
6346        'SELECT * FROM (SELECT * FROM y) AS z /* source: x */'
6347
6348        >>> expand(parse_one("select * from x AS z"), {"x": parse_one("select * from y"), "y": parse_one("select * from z")}).sql()
6349        'SELECT * FROM (SELECT * FROM (SELECT * FROM z) AS y /* source: y */) AS z /* source: x */'
6350
6351    Args:
6352        expression: The expression to expand.
6353        sources: A dictionary of name to Subqueryables.
6354        copy: Whether or not to copy the expression during transformation. Defaults to True.
6355
6356    Returns:
6357        The transformed expression.
6358    """
6359
6360    def _expand(node: Expression):
6361        if isinstance(node, Table):
6362            name = table_name(node)
6363            source = sources.get(name)
6364            if source:
6365                subquery = source.subquery(node.alias or name)
6366                subquery.comments = [f"source: {name}"]
6367                return subquery.transform(_expand, copy=False)
6368        return node
6369
6370    return expression.transform(_expand, copy=copy)

Transforms an expression by expanding all referenced sources into subqueries.

Examples:
>>> from sqlglot import parse_one
>>> expand(parse_one("select * from x AS z"), {"x": parse_one("select * from y")}).sql()
'SELECT * FROM (SELECT * FROM y) AS z /* source: x */'
>>> expand(parse_one("select * from x AS z"), {"x": parse_one("select * from y"), "y": parse_one("select * from z")}).sql()
'SELECT * FROM (SELECT * FROM (SELECT * FROM z) AS y /* source: y */) AS z /* source: x */'
Arguments:
  • expression: The expression to expand.
  • sources: A dictionary of name to Subqueryables.
  • copy: Whether or not to copy the expression during transformation. Defaults to True.
Returns:

The transformed expression.

def func( name: str, *args, dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, **kwargs) -> Func:
6373def func(name: str, *args, dialect: DialectType = None, **kwargs) -> Func:
6374    """
6375    Returns a Func expression.
6376
6377    Examples:
6378        >>> func("abs", 5).sql()
6379        'ABS(5)'
6380
6381        >>> func("cast", this=5, to=DataType.build("DOUBLE")).sql()
6382        'CAST(5 AS DOUBLE)'
6383
6384    Args:
6385        name: the name of the function to build.
6386        args: the args used to instantiate the function of interest.
6387        dialect: the source dialect.
6388        kwargs: the kwargs used to instantiate the function of interest.
6389
6390    Note:
6391        The arguments `args` and `kwargs` are mutually exclusive.
6392
6393    Returns:
6394        An instance of the function of interest, or an anonymous function, if `name` doesn't
6395        correspond to an existing `sqlglot.expressions.Func` class.
6396    """
6397    if args and kwargs:
6398        raise ValueError("Can't use both args and kwargs to instantiate a function.")
6399
6400    from sqlglot.dialects.dialect import Dialect
6401
6402    converted: t.List[Expression] = [maybe_parse(arg, dialect=dialect) for arg in args]
6403    kwargs = {key: maybe_parse(value, dialect=dialect) for key, value in kwargs.items()}
6404
6405    parser = Dialect.get_or_raise(dialect)().parser()
6406    from_args_list = parser.FUNCTIONS.get(name.upper())
6407
6408    if from_args_list:
6409        function = from_args_list(converted) if converted else from_args_list.__self__(**kwargs)  # type: ignore
6410    else:
6411        kwargs = kwargs or {"expressions": converted}
6412        function = Anonymous(this=name, **kwargs)
6413
6414    for error_message in function.error_messages(converted):
6415        raise ValueError(error_message)
6416
6417    return function

Returns a Func expression.

Examples:
>>> func("abs", 5).sql()
'ABS(5)'
>>> func("cast", this=5, to=DataType.build("DOUBLE")).sql()
'CAST(5 AS DOUBLE)'
Arguments:
  • name: the name of the function to build.
  • args: the args used to instantiate the function of interest.
  • dialect: the source dialect.
  • kwargs: the kwargs used to instantiate the function of interest.
Note:

The arguments args and kwargs are mutually exclusive.

Returns:

An instance of the function of interest, or an anonymous function, if name doesn't correspond to an existing Func class.

def true() -> Boolean:
6420def true() -> Boolean:
6421    """
6422    Returns a true Boolean expression.
6423    """
6424    return Boolean(this=True)

Returns a true Boolean expression.

def false() -> Boolean:
6427def false() -> Boolean:
6428    """
6429    Returns a false Boolean expression.
6430    """
6431    return Boolean(this=False)

Returns a false Boolean expression.

def null() -> Null:
6434def null() -> Null:
6435    """
6436    Returns a Null expression.
6437    """
6438    return Null()

Returns a Null expression.

TRUE = (BOOLEAN this: True)
FALSE = (BOOLEAN this: False)
NULL = (NULL )