1"""sqlglot expressions query."""
   2
   3from __future__ import annotations
   4
   5import typing as t
   6
   7from sqlglot.errors import ParseError
   8from sqlglot.helper import trait, ensure_list
   9from sqlglot.expressions.core import (
  10    Aliases,
  11    Condition,
  12    Distinct,
  13    Dot,
  14    Expr,
  15    Expression,
  16    Func,
  17    Hint,
  18    Identifier,
  19    In,
  20    _apply_builder,
  21    _apply_child_list_builder,
  22    _apply_list_builder,
  23    _apply_conjunction_builder,
  24    _apply_set_operation,
  25    ExpOrStr,
  26    QUERY_MODIFIERS,
  27    maybe_parse,
  28    maybe_copy,
  29    to_identifier,
  30    convert,
  31    and_,
  32    alias_,
  33    column,
  34)
  35
  36if t.TYPE_CHECKING:
  37    from sqlglot.dialects.dialect import DialectType
  38    from sqlglot.expressions.datatypes import DataType
  39    from sqlglot.expressions.constraints import ColumnConstraint
  40    from sqlglot.expressions.ddl import Create
  41    from sqlglot.expressions.array import Unnest
  42    from sqlglot._typing import E, ParserArgs, ParserNoDialectArgs
  43    from typing_extensions import Unpack
  44
  45    S = t.TypeVar("S", bound="SetOperation")
  46    Q = t.TypeVar("Q", bound="Query")
  47
  48
  49def _apply_cte_builder(
  50    instance: E,
  51    alias: ExpOrStr,
  52    as_: ExpOrStr,
  53    recursive: bool | None = None,
  54    materialized: bool | None = None,
  55    append: bool = True,
  56    dialect: DialectType = None,
  57    copy: bool = True,
  58    scalar: bool | None = None,
  59    **opts: Unpack[ParserNoDialectArgs],
  60) -> E:
  61    alias_expression = maybe_parse(alias, dialect=dialect, into=TableAlias, **opts)
  62    as_expression = maybe_parse(as_, dialect=dialect, copy=copy, **opts)
  63    if scalar and not isinstance(as_expression, Subquery):
  64        # scalar CTE must be wrapped in a subquery
  65        as_expression = Subquery(this=as_expression)
  66    cte = CTE(this=as_expression, alias=alias_expression, materialized=materialized, scalar=scalar)
  67    return _apply_child_list_builder(
  68        cte,
  69        instance=instance,
  70        arg="with_",
  71        append=append,
  72        copy=copy,
  73        into=With,
  74        properties={"recursive": recursive} if recursive else {},
  75    )
  76
  77
  78@trait
  79class Selectable(Expr):
  80    @property
  81    def selects(self) -> list[Expr]:
  82        raise NotImplementedError("Subclasses must implement selects")
  83
  84    @property
  85    def named_selects(self) -> list[str]:
  86        return _named_selects(self)
  87
  88
  89def _named_selects(self: Expr) -> list[str]:
  90    selectable = t.cast(Selectable, self)
  91    return [select.output_name for select in selectable.selects]
  92
  93
  94@trait
  95class DerivedTable(Selectable):
  96    @property
  97    def selects(self) -> list[Expr]:
  98        this = self.this
  99        return this.selects if isinstance(this, Query) else []
 100
 101
 102@trait
 103class UDTF(DerivedTable):
 104    @property
 105    def selects(self) -> list[Expr]:
 106        alias = self.args.get("alias")
 107        return alias.columns if alias else []
 108
 109
 110@trait
 111class Query(Selectable):
 112    """Trait for any SELECT/UNION/etc. query expression."""
 113
 114    @property
 115    def ctes(self) -> list[CTE]:
 116        with_ = self.args.get("with_")
 117        return with_.expressions if with_ else []
 118
 119    def select(
 120        self: Q,
 121        *expressions: ExpOrStr | None,
 122        append: bool = True,
 123        dialect: DialectType = None,
 124        copy: bool = True,
 125        **opts: Unpack[ParserNoDialectArgs],
 126    ) -> Q:
 127        raise NotImplementedError("Query objects must implement `select`")
 128
 129    def subquery(self, alias: ExpOrStr | None = None, copy: bool = True) -> Subquery:
 130        """
 131        Returns a `Subquery` that wraps around this query.
 132
 133        Example:
 134            >>> subquery = Select().select("x").from_("tbl").subquery()
 135            >>> Select().select("x").from_(subquery).sql()
 136            'SELECT x FROM (SELECT x FROM tbl)'
 137
 138        Args:
 139            alias: an optional alias for the subquery.
 140            copy: if `False`, modify this expression instance in-place.
 141        """
 142        instance = maybe_copy(self, copy)
 143        if not isinstance(alias, Expr):
 144            alias = TableAlias(this=to_identifier(alias)) if alias else None
 145
 146        return Subquery(this=instance, alias=alias)
 147
 148    def limit(
 149        self: Q,
 150        expression: ExpOrStr | int,
 151        dialect: DialectType = None,
 152        copy: bool = True,
 153        **opts: Unpack[ParserNoDialectArgs],
 154    ) -> Q:
 155        """
 156        Adds a LIMIT clause to this query.
 157
 158        Example:
 159            >>> Select().select("1").union(Select().select("1")).limit(1).sql()
 160            'SELECT 1 UNION SELECT 1 LIMIT 1'
 161
 162        Args:
 163            expression: the SQL code string to parse.
 164                This can also be an integer.
 165                If a `Limit` instance is passed, it will be used as-is.
 166                If another `Expr` instance is passed, it will be wrapped in a `Limit`.
 167            dialect: the dialect used to parse the input expression.
 168            copy: if `False`, modify this expression instance in-place.
 169            opts: other options to use to parse the input expressions.
 170
 171        Returns:
 172            A limited Select expression.
 173        """
 174        return _apply_builder(
 175            expression=expression,
 176            instance=self,
 177            arg="limit",
 178            into=Limit,
 179            prefix="LIMIT",
 180            dialect=dialect,
 181            copy=copy,
 182            into_arg="expression",
 183            **opts,
 184        )
 185
 186    def offset(
 187        self: Q,
 188        expression: ExpOrStr | int,
 189        dialect: DialectType = None,
 190        copy: bool = True,
 191        **opts: Unpack[ParserNoDialectArgs],
 192    ) -> Q:
 193        """
 194        Set the OFFSET expression.
 195
 196        Example:
 197            >>> Select().from_("tbl").select("x").offset(10).sql()
 198            'SELECT x FROM tbl OFFSET 10'
 199
 200        Args:
 201            expression: the SQL code string to parse.
 202                This can also be an integer.
 203                If a `Offset` instance is passed, this is used as-is.
 204                If another `Expr` instance is passed, it will be wrapped in a `Offset`.
 205            dialect: the dialect used to parse the input expression.
 206            copy: if `False`, modify this expression instance in-place.
 207            opts: other options to use to parse the input expressions.
 208
 209        Returns:
 210            The modified Select expression.
 211        """
 212        return _apply_builder(
 213            expression=expression,
 214            instance=self,
 215            arg="offset",
 216            into=Offset,
 217            prefix="OFFSET",
 218            dialect=dialect,
 219            copy=copy,
 220            into_arg="expression",
 221            **opts,
 222        )
 223
 224    def order_by(
 225        self: Q,
 226        *expressions: ExpOrStr | None,
 227        append: bool = True,
 228        dialect: DialectType = None,
 229        copy: bool = True,
 230        **opts: Unpack[ParserNoDialectArgs],
 231    ) -> Q:
 232        """
 233        Set the ORDER BY expression.
 234
 235        Example:
 236            >>> Select().from_("tbl").select("x").order_by("x DESC").sql()
 237            'SELECT x FROM tbl ORDER BY x DESC'
 238
 239        Args:
 240            *expressions: the SQL code strings to parse.
 241                If a `Group` instance is passed, this is used as-is.
 242                If another `Expr` instance is passed, it will be wrapped in a `Order`.
 243            append: if `True`, add to any existing expressions.
 244                Otherwise, this flattens all the `Order` expression into a single expression.
 245            dialect: the dialect used to parse the input expression.
 246            copy: if `False`, modify this expression instance in-place.
 247            opts: other options to use to parse the input expressions.
 248
 249        Returns:
 250            The modified Select expression.
 251        """
 252        return _apply_child_list_builder(
 253            *expressions,
 254            instance=self,
 255            arg="order",
 256            append=append,
 257            copy=copy,
 258            prefix="ORDER BY",
 259            into=Order,
 260            dialect=dialect,
 261            **opts,
 262        )
 263
 264    def where(
 265        self: Q,
 266        *expressions: ExpOrStr | None,
 267        append: bool = True,
 268        dialect: DialectType = None,
 269        copy: bool = True,
 270        **opts: Unpack[ParserNoDialectArgs],
 271    ) -> Q:
 272        """
 273        Append to or set the WHERE expressions.
 274
 275        Examples:
 276            >>> Select().select("x").from_("tbl").where("x = 'a' OR x < 'b'").sql()
 277            "SELECT x FROM tbl WHERE x = 'a' OR x < 'b'"
 278
 279        Args:
 280            *expressions: the SQL code strings to parse.
 281                If an `Expr` instance is passed, it will be used as-is.
 282                Multiple expressions are combined with an AND operator.
 283            append: if `True`, AND the new expressions to any existing expression.
 284                Otherwise, this resets the expression.
 285            dialect: the dialect used to parse the input expressions.
 286            copy: if `False`, modify this expression instance in-place.
 287            opts: other options to use to parse the input expressions.
 288
 289        Returns:
 290            The modified expression.
 291        """
 292        return _apply_conjunction_builder(
 293            *[expr.this if isinstance(expr, Where) else expr for expr in expressions],
 294            instance=self,
 295            arg="where",
 296            append=append,
 297            into=Where,
 298            dialect=dialect,
 299            copy=copy,
 300            **opts,
 301        )
 302
 303    def with_(
 304        self: Q,
 305        alias: ExpOrStr,
 306        as_: ExpOrStr,
 307        recursive: bool | None = None,
 308        materialized: bool | None = None,
 309        append: bool = True,
 310        dialect: DialectType = None,
 311        copy: bool = True,
 312        scalar: bool | None = None,
 313        **opts: Unpack[ParserNoDialectArgs],
 314    ) -> Q:
 315        """
 316        Append to or set the common table expressions.
 317
 318        Example:
 319            >>> Select().with_("tbl2", as_="SELECT * FROM tbl").select("x").from_("tbl2").sql()
 320            'WITH tbl2 AS (SELECT * FROM tbl) SELECT x FROM tbl2'
 321
 322        Args:
 323            alias: the SQL code string to parse as the table name.
 324                If an `Expr` instance is passed, this is used as-is.
 325            as_: the SQL code string to parse as the table expression.
 326                If an `Expr` instance is passed, it will be used as-is.
 327            recursive: set the RECURSIVE part of the expression. Defaults to `False`.
 328            materialized: set the MATERIALIZED part of the expression.
 329            append: if `True`, add to any existing expressions.
 330                Otherwise, this resets the expressions.
 331            dialect: the dialect used to parse the input expression.
 332            copy: if `False`, modify this expression instance in-place.
 333            scalar: if `True`, this is a scalar common table expression.
 334            opts: other options to use to parse the input expressions.
 335
 336        Returns:
 337            The modified expression.
 338        """
 339        return _apply_cte_builder(
 340            self,
 341            alias,
 342            as_,
 343            recursive=recursive,
 344            materialized=materialized,
 345            append=append,
 346            dialect=dialect,
 347            copy=copy,
 348            scalar=scalar,
 349            **opts,
 350        )
 351
 352    def union(
 353        self,
 354        *expressions: ExpOrStr,
 355        distinct: bool = True,
 356        dialect: DialectType = None,
 357        copy: bool = True,
 358        **opts: Unpack[ParserNoDialectArgs],
 359    ) -> Union:
 360        """
 361        Builds a UNION expression.
 362
 363        Example:
 364            >>> import sqlglot
 365            >>> sqlglot.parse_one("SELECT * FROM foo").union("SELECT * FROM bla").sql()
 366            'SELECT * FROM foo UNION SELECT * FROM bla'
 367
 368        Args:
 369            expressions: the SQL code strings.
 370                If `Expr` instances are passed, they will be used as-is.
 371            distinct: set the DISTINCT flag if and only if this is true.
 372            dialect: the dialect used to parse the input expression.
 373            opts: other options to use to parse the input expressions.
 374
 375        Returns:
 376            The new Union expression.
 377        """
 378        return union(self, *expressions, distinct=distinct, dialect=dialect, copy=copy, **opts)
 379
 380    def intersect(
 381        self,
 382        *expressions: ExpOrStr,
 383        distinct: bool = True,
 384        dialect: DialectType = None,
 385        copy: bool = True,
 386        **opts: Unpack[ParserNoDialectArgs],
 387    ) -> Intersect:
 388        """
 389        Builds an INTERSECT expression.
 390
 391        Example:
 392            >>> import sqlglot
 393            >>> sqlglot.parse_one("SELECT * FROM foo").intersect("SELECT * FROM bla").sql()
 394            'SELECT * FROM foo INTERSECT SELECT * FROM bla'
 395
 396        Args:
 397            expressions: the SQL code strings.
 398                If `Expr` instances are passed, they will be used as-is.
 399            distinct: set the DISTINCT flag if and only if this is true.
 400            dialect: the dialect used to parse the input expression.
 401            opts: other options to use to parse the input expressions.
 402
 403        Returns:
 404            The new Intersect expression.
 405        """
 406        return intersect(self, *expressions, distinct=distinct, dialect=dialect, copy=copy, **opts)
 407
 408    def except_(
 409        self,
 410        *expressions: ExpOrStr,
 411        distinct: bool = True,
 412        dialect: DialectType = None,
 413        copy: bool = True,
 414        **opts: Unpack[ParserNoDialectArgs],
 415    ) -> Except:
 416        """
 417        Builds an EXCEPT expression.
 418
 419        Example:
 420            >>> import sqlglot
 421            >>> sqlglot.parse_one("SELECT * FROM foo").except_("SELECT * FROM bla").sql()
 422            'SELECT * FROM foo EXCEPT SELECT * FROM bla'
 423
 424        Args:
 425            expressions: the SQL code strings.
 426                If `Expr` instance are passed, they will be used as-is.
 427            distinct: set the DISTINCT flag if and only if this is true.
 428            dialect: the dialect used to parse the input expression.
 429            opts: other options to use to parse the input expressions.
 430
 431        Returns:
 432            The new Except expression.
 433        """
 434        return except_(self, *expressions, distinct=distinct, dialect=dialect, copy=copy, **opts)
 435
 436
 437class QueryBand(Expression):
 438    arg_types = {"this": True, "scope": False, "update": False}
 439
 440
 441class RecursiveWithSearch(Expression):
 442    arg_types = {"kind": True, "this": True, "expression": True, "using": False}
 443
 444
 445class With(Expression):
 446    arg_types = {"expressions": True, "recursive": False, "search": False}
 447
 448    @property
 449    def recursive(self) -> bool:
 450        return bool(self.args.get("recursive"))
 451
 452
 453class CTE(Expression, DerivedTable):
 454    arg_types = {
 455        "this": True,
 456        "alias": True,
 457        "scalar": False,
 458        "materialized": False,
 459        "key_expressions": False,
 460    }
 461
 462
 463class ProjectionDef(Expression):
 464    arg_types = {"this": True, "expression": True}
 465
 466
 467class TableAlias(Expression):
 468    arg_types = {"this": False, "columns": False}
 469
 470    @property
 471    def columns(self) -> list[t.Any]:
 472        return self.args.get("columns") or []
 473
 474
 475class BitString(Expression, Condition):
 476    is_primitive = True
 477
 478
 479class HexString(Expression, Condition):
 480    arg_types = {"this": True, "is_integer": False}
 481    is_primitive = True
 482
 483
 484class ByteString(Expression, Condition):
 485    arg_types = {"this": True, "is_bytes": False}
 486    is_primitive = True
 487
 488
 489class RawString(Expression, Condition):
 490    is_primitive = True
 491
 492
 493class UnicodeString(Expression, Condition):
 494    arg_types = {"this": True, "escape": False}
 495
 496
 497class ColumnPosition(Expression):
 498    arg_types = {"this": False, "position": True}
 499
 500
 501class ColumnDef(Expression):
 502    arg_types = {
 503        "this": True,
 504        "kind": False,
 505        "constraints": False,
 506        "exists": False,
 507        "position": False,
 508        "default": False,
 509        "output": False,
 510    }
 511
 512    @property
 513    def constraints(self) -> list[ColumnConstraint]:
 514        return self.args.get("constraints") or []
 515
 516    @property
 517    def kind(self) -> DataType | None:
 518        return self.args.get("kind")
 519
 520
 521class Changes(Expression):
 522    arg_types = {"information": True, "at_before": False, "end": False}
 523
 524
 525class Connect(Expression):
 526    arg_types = {"start": False, "connect": True, "nocycle": False}
 527
 528
 529class Prior(Expression):
 530    pass
 531
 532
 533class Into(Expression):
 534    arg_types = {
 535        "this": False,
 536        "temporary": False,
 537        "unlogged": False,
 538        "bulk_collect": False,
 539        "expressions": False,
 540    }
 541
 542
 543class From(Expression):
 544    @property
 545    def name(self) -> str:
 546        return self.this.name
 547
 548    @property
 549    def alias_or_name(self) -> str:
 550        return self.this.alias_or_name
 551
 552
 553class Having(Expression):
 554    pass
 555
 556
 557class Index(Expression):
 558    arg_types = {
 559        "this": False,
 560        "table": False,
 561        "unique": False,
 562        "primary": False,
 563        "amp": False,  # teradata
 564        "params": False,
 565    }
 566
 567
 568class ConditionalInsert(Expression):
 569    arg_types = {"this": True, "expression": False, "else_": False}
 570
 571
 572class MultitableInserts(Expression):
 573    arg_types = {"expressions": True, "kind": True, "source": True}
 574
 575
 576class OnCondition(Expression):
 577    arg_types = {"error": False, "empty": False, "null": False}
 578
 579
 580class Introducer(Expression):
 581    arg_types = {"this": True, "expression": True}
 582
 583
 584class National(Expression):
 585    is_primitive = True
 586
 587
 588class Partition(Expression):
 589    arg_types = {"expressions": True, "subpartition": False}
 590
 591
 592class PartitionRange(Expression):
 593    arg_types = {"this": True, "expression": False, "expressions": False}
 594
 595
 596class PartitionId(Expression):
 597    pass
 598
 599
 600class Fetch(Expression):
 601    arg_types = {
 602        "direction": False,
 603        "count": False,
 604        "limit_options": False,
 605    }
 606
 607
 608class Grant(Expression):
 609    arg_types = {
 610        "privileges": True,
 611        "kind": False,
 612        "securable": True,
 613        "principals": True,
 614        "grant_option": False,
 615    }
 616
 617
 618class Revoke(Expression):
 619    arg_types = {**Grant.arg_types, "cascade": False}
 620
 621
 622class Group(Expression):
 623    arg_types = {
 624        "expressions": False,
 625        "grouping_sets": False,
 626        "cube": False,
 627        "rollup": False,
 628        "totals": False,
 629        "all": False,
 630    }
 631
 632
 633class Cube(Expression):
 634    arg_types = {"expressions": False}
 635
 636
 637class Rollup(Expression):
 638    arg_types = {"expressions": False}
 639
 640
 641class GroupingSets(Expression):
 642    arg_types = {"expressions": True}
 643
 644
 645class Lambda(Expression):
 646    arg_types = {"this": True, "expressions": True, "colon": False}
 647
 648
 649class Limit(Expression):
 650    arg_types = {
 651        "this": False,
 652        "expression": True,
 653        "offset": False,
 654        "limit_options": False,
 655        "expressions": False,
 656    }
 657
 658
 659class LimitOptions(Expression):
 660    arg_types = {
 661        "percent": False,
 662        "rows": False,
 663        "with_ties": False,
 664    }
 665
 666
 667class Join(Expression):
 668    arg_types = {
 669        "this": True,
 670        "on": False,
 671        "side": False,
 672        "kind": False,
 673        "using": False,
 674        "method": False,
 675        "global_": False,
 676        "hint": False,
 677        "match_condition": False,  # Snowflake
 678        "directed": False,  # Snowflake
 679        "expressions": False,
 680        "pivots": False,
 681    }
 682
 683    @property
 684    def method(self) -> str:
 685        return self.text("method").upper()
 686
 687    @property
 688    def kind(self) -> str:
 689        return self.text("kind").upper()
 690
 691    @property
 692    def side(self) -> str:
 693        return self.text("side").upper()
 694
 695    @property
 696    def hint(self) -> str:
 697        return self.text("hint").upper()
 698
 699    @property
 700    def alias_or_name(self) -> str:
 701        return self.this.alias_or_name
 702
 703    @property
 704    def is_semi_or_anti_join(self) -> bool:
 705        return self.kind in ("SEMI", "ANTI")
 706
 707    def on(
 708        self,
 709        *expressions: ExpOrStr | None,
 710        append: bool = True,
 711        dialect: DialectType = None,
 712        copy: bool = True,
 713        **opts: Unpack[ParserNoDialectArgs],
 714    ) -> Join:
 715        """
 716        Append to or set the ON expressions.
 717
 718        Example:
 719            >>> import sqlglot
 720            >>> sqlglot.parse_one("JOIN x", into=Join).on("y = 1").sql()
 721            'JOIN x ON y = 1'
 722
 723        Args:
 724            *expressions: the SQL code strings to parse.
 725                If an `Expr` instance is passed, it will be used as-is.
 726                Multiple expressions are combined with an AND operator.
 727            append: if `True`, AND the new expressions to any existing expression.
 728                Otherwise, this resets the expression.
 729            dialect: the dialect used to parse the input expressions.
 730            copy: if `False`, modify this expression instance in-place.
 731            opts: other options to use to parse the input expressions.
 732
 733        Returns:
 734            The modified Join expression.
 735        """
 736        join = _apply_conjunction_builder(
 737            *expressions,
 738            instance=self,
 739            arg="on",
 740            append=append,
 741            dialect=dialect,
 742            copy=copy,
 743            **opts,
 744        )
 745
 746        if join.kind == "CROSS":
 747            join.set("kind", None)
 748
 749        return join
 750
 751    def using(
 752        self,
 753        *expressions: ExpOrStr | None,
 754        append: bool = True,
 755        dialect: DialectType = None,
 756        copy: bool = True,
 757        **opts: Unpack[ParserNoDialectArgs],
 758    ) -> Join:
 759        """
 760        Append to or set the USING expressions.
 761
 762        Example:
 763            >>> import sqlglot
 764            >>> sqlglot.parse_one("JOIN x", into=Join).using("foo", "bla").sql()
 765            'JOIN x USING (foo, bla)'
 766
 767        Args:
 768            *expressions: the SQL code strings to parse.
 769                If an `Expr` instance is passed, it will be used as-is.
 770            append: if `True`, concatenate the new expressions to the existing "using" list.
 771                Otherwise, this resets the expression.
 772            dialect: the dialect used to parse the input expressions.
 773            copy: if `False`, modify this expression instance in-place.
 774            opts: other options to use to parse the input expressions.
 775
 776        Returns:
 777            The modified Join expression.
 778        """
 779        join = _apply_list_builder(
 780            *expressions,
 781            instance=self,
 782            arg="using",
 783            append=append,
 784            dialect=dialect,
 785            copy=copy,
 786            **opts,
 787        )
 788
 789        if join.kind == "CROSS":
 790            join.set("kind", None)
 791
 792        return join
 793
 794
 795class Lateral(Expression, UDTF):
 796    arg_types = {
 797        "this": True,
 798        "view": False,
 799        "outer": False,
 800        "alias": False,
 801        "cross_apply": False,  # True -> CROSS APPLY, False -> OUTER APPLY
 802        "ordinality": False,
 803    }
 804
 805
 806class TableFromRows(Expression, UDTF):
 807    arg_types = {
 808        "this": True,
 809        "alias": False,
 810        "joins": False,
 811        "pivots": False,
 812        "sample": False,
 813    }
 814
 815
 816class MatchRecognizeMeasure(Expression):
 817    arg_types = {
 818        "this": True,
 819        "window_frame": False,
 820    }
 821
 822
 823class MatchRecognize(Expression):
 824    arg_types = {
 825        "partition_by": False,
 826        "order": False,
 827        "measures": False,
 828        "rows": False,
 829        "after": False,
 830        "pattern": False,
 831        "define": False,
 832        "alias": False,
 833    }
 834
 835
 836class Final(Expression):
 837    pass
 838
 839
 840class Offset(Expression):
 841    arg_types = {"this": False, "expression": True, "expressions": False}
 842
 843
 844class Order(Expression):
 845    arg_types = {"this": False, "expressions": True, "siblings": False}
 846
 847
 848class WithFill(Expression):
 849    arg_types = {
 850        "from_": False,
 851        "to": False,
 852        "step": False,
 853        "interpolate": False,
 854    }
 855
 856
 857class SkipJSONColumn(Expression):
 858    arg_types = {"regexp": False, "expression": True}
 859
 860
 861class Cluster(Order):
 862    pass
 863
 864
 865class Distribute(Order):
 866    pass
 867
 868
 869class Sort(Order):
 870    pass
 871
 872
 873class Qualify(Expression):
 874    pass
 875
 876
 877class InputOutputFormat(Expression):
 878    arg_types = {"input_format": False, "output_format": False}
 879
 880
 881class Return(Expression):
 882    pass
 883
 884
 885class Tuple(Expression):
 886    arg_types = {"expressions": False}
 887
 888    def isin(
 889        self,
 890        *expressions: t.Any,
 891        query: ExpOrStr | None = None,
 892        unnest: ExpOrStr | None | list[ExpOrStr] | tuple[ExpOrStr, ...] = None,
 893        copy: bool = True,
 894        **opts: Unpack[ParserArgs],
 895    ) -> In:
 896        return In(
 897            this=maybe_copy(self, copy),
 898            expressions=[convert(e, copy=copy) for e in expressions],
 899            query=maybe_parse(query, copy=copy, **opts) if query else None,
 900            unnest=(
 901                Unnest(
 902                    expressions=[
 903                        maybe_parse(e, copy=copy, **opts)
 904                        for e in t.cast(list[ExpOrStr], ensure_list(unnest))
 905                    ]
 906                )
 907                if unnest
 908                else None
 909            ),
 910        )
 911
 912
 913class QueryOption(Expression):
 914    arg_types = {"this": True, "expression": False}
 915
 916
 917class WithTableHint(Expression):
 918    arg_types = {"expressions": True}
 919
 920
 921class IndexTableHint(Expression):
 922    arg_types = {"this": True, "expressions": False, "target": False}
 923
 924
 925class HistoricalData(Expression):
 926    arg_types = {"this": True, "kind": True, "expression": True}
 927
 928
 929class Put(Expression):
 930    arg_types = {"this": True, "target": True, "properties": False}
 931
 932
 933class Get(Expression):
 934    arg_types = {"this": True, "target": True, "properties": False}
 935
 936
 937class Table(Expression, Selectable):
 938    arg_types = {
 939        "this": False,
 940        "alias": False,
 941        "db": False,
 942        "catalog": False,
 943        "laterals": False,
 944        "joins": False,
 945        "pivots": False,
 946        "hints": False,
 947        "system_time": False,
 948        "version": False,
 949        "format": False,
 950        "pattern": False,
 951        "ordinality": False,
 952        "when": False,
 953        "only": False,
 954        "partition": False,
 955        "changes": False,
 956        "rows_from": False,
 957        "sample": False,
 958        "indexed": False,
 959    }
 960
 961    @property
 962    def name(self) -> str:
 963        if not self.this or isinstance(self.this, Func):
 964            return ""
 965        return self.this.name
 966
 967    @property
 968    def db(self) -> str:
 969        return self.text("db")
 970
 971    @property
 972    def catalog(self) -> str:
 973        return self.text("catalog")
 974
 975    @property
 976    def selects(self) -> list[Expr]:
 977        return []
 978
 979    @property
 980    def named_selects(self) -> list[str]:
 981        return []
 982
 983    @property
 984    def parts(self) -> list[Expr]:
 985        """Return the parts of a table in order catalog, db, table."""
 986        parts: list[Expr] = []
 987
 988        for arg in ("catalog", "db", "this"):
 989            part = self.args.get(arg)
 990
 991            if isinstance(part, Dot):
 992                parts.extend(part.flatten())
 993            elif isinstance(part, Expr):
 994                parts.append(part)
 995
 996        return parts
 997
 998    def to_column(self, copy: bool = True) -> Expr:
 999        parts = self.parts
1000        last_part = parts[-1]
1001
1002        if isinstance(last_part, Identifier):
1003            col: Expr = column(*reversed(parts[0:4]), fields=parts[4:], copy=copy)  # type: ignore
1004        else:
1005            # This branch will be reached if a function or array is wrapped in a `Table`
1006            col = last_part
1007
1008        alias = self.args.get("alias")
1009        if alias:
1010            col = alias_(col, alias.this, copy=copy)
1011
1012        return col
1013
1014
1015class SetOperation(Expression, Query):
1016    arg_types = {
1017        "with_": False,
1018        "this": True,
1019        "expression": True,
1020        "distinct": False,
1021        "by_name": False,
1022        "side": False,
1023        "kind": False,
1024        "on": False,
1025        **QUERY_MODIFIERS,
1026    }
1027
1028    def select(
1029        self: S,
1030        *expressions: ExpOrStr | None,
1031        append: bool = True,
1032        dialect: DialectType = None,
1033        copy: bool = True,
1034        **opts: Unpack[ParserNoDialectArgs],
1035    ) -> S:
1036        this = maybe_copy(self, copy)
1037        this.this.unnest().select(*expressions, append=append, dialect=dialect, copy=False, **opts)
1038        this.expression.unnest().select(
1039            *expressions, append=append, dialect=dialect, copy=False, **opts
1040        )
1041        return this
1042
1043    @property
1044    def named_selects(self) -> list[str]:
1045        expr: Expr = self
1046        while isinstance(expr, SetOperation):
1047            expr = expr.this.unnest()
1048        return _named_selects(expr)
1049
1050    @property
1051    def is_star(self) -> bool:
1052        return self.this.is_star or self.expression.is_star
1053
1054    @property
1055    def selects(self) -> list[Expr]:
1056        expr: Expr = self
1057        while isinstance(expr, SetOperation):
1058            expr = expr.this.unnest()
1059        return getattr(expr, "selects", [])
1060
1061    @property
1062    def left(self) -> Query:
1063        return self.this
1064
1065    @property
1066    def right(self) -> Query:
1067        return self.expression
1068
1069    @property
1070    def kind(self) -> str:
1071        return self.text("kind").upper()
1072
1073    @property
1074    def side(self) -> str:
1075        return self.text("side").upper()
1076
1077
1078class Union(SetOperation):
1079    pass
1080
1081
1082class Except(SetOperation):
1083    pass
1084
1085
1086class Intersect(SetOperation):
1087    pass
1088
1089
1090class Values(Expression, UDTF):
1091    arg_types = {
1092        "expressions": True,
1093        "alias": False,
1094        "order": False,
1095        "limit": False,
1096        "offset": False,
1097    }
1098
1099
1100class Version(Expression):
1101    """
1102    Time travel, iceberg, bigquery etc
1103    https://trino.io/docs/current/connector/iceberg.html?highlight=snapshot#using-snapshots
1104    https://www.databricks.com/blog/2019/02/04/introducing-delta-time-travel-for-large-scale-data-lakes.html
1105    https://cloud.google.com/bigquery/docs/reference/standard-sql/query-syntax#for_system_time_as_of
1106    https://learn.microsoft.com/en-us/sql/relational-databases/tables/querying-data-in-a-system-versioned-temporal-table?view=sql-server-ver16
1107    this is either TIMESTAMP or VERSION
1108    kind is ("AS OF", "BETWEEN")
1109    """
1110
1111    arg_types = {"this": True, "kind": True, "expression": False}
1112
1113
1114class Schema(Expression):
1115    arg_types = {"this": False, "expressions": False}
1116
1117
1118class Lock(Expression):
1119    arg_types = {"update": True, "expressions": False, "wait": False, "key": False}
1120
1121
1122class Select(Expression, Query):
1123    arg_types = {
1124        "with_": False,
1125        "kind": False,
1126        "expressions": False,
1127        "hint": False,
1128        "distinct": False,
1129        "into": False,
1130        "from_": False,
1131        "operation_modifiers": False,
1132        "exclude": False,
1133        **QUERY_MODIFIERS,
1134    }
1135
1136    def from_(
1137        self,
1138        expression: ExpOrStr,
1139        dialect: DialectType = None,
1140        copy: bool = True,
1141        **opts: Unpack[ParserNoDialectArgs],
1142    ) -> Select:
1143        """
1144        Set the FROM expression.
1145
1146        Example:
1147            >>> Select().from_("tbl").select("x").sql()
1148            'SELECT x FROM tbl'
1149
1150        Args:
1151            expression : the SQL code strings to parse.
1152                If a `From` instance is passed, this is used as-is.
1153                If another `Expr` instance is passed, it will be wrapped in a `From`.
1154            dialect: the dialect used to parse the input expression.
1155            copy: if `False`, modify this expression instance in-place.
1156            opts: other options to use to parse the input expressions.
1157
1158        Returns:
1159            The modified Select expression.
1160        """
1161        return _apply_builder(
1162            expression=expression,
1163            instance=self,
1164            arg="from_",
1165            into=From,
1166            prefix="FROM",
1167            dialect=dialect,
1168            copy=copy,
1169            **opts,
1170        )
1171
1172    def group_by(
1173        self,
1174        *expressions: ExpOrStr | None,
1175        append: bool = True,
1176        dialect: DialectType = None,
1177        copy: bool = True,
1178        **opts: Unpack[ParserNoDialectArgs],
1179    ) -> Select:
1180        """
1181        Set the GROUP BY expression.
1182
1183        Example:
1184            >>> Select().from_("tbl").select("x", "COUNT(1)").group_by("x").sql()
1185            'SELECT x, COUNT(1) FROM tbl GROUP BY x'
1186
1187        Args:
1188            *expressions: the SQL code strings to parse.
1189                If a `Group` instance is passed, this is used as-is.
1190                If another `Expr` instance is passed, it will be wrapped in a `Group`.
1191                If nothing is passed in then a group by is not applied to the expression
1192            append: if `True`, add to any existing expressions.
1193                Otherwise, this flattens all the `Group` expression into a single expression.
1194            dialect: the dialect used to parse the input expression.
1195            copy: if `False`, modify this expression instance in-place.
1196            opts: other options to use to parse the input expressions.
1197
1198        Returns:
1199            The modified Select expression.
1200        """
1201        if not expressions:
1202            return self if not copy else self.copy()
1203
1204        return _apply_child_list_builder(
1205            *expressions,
1206            instance=self,
1207            arg="group",
1208            append=append,
1209            copy=copy,
1210            prefix="GROUP BY",
1211            into=Group,
1212            dialect=dialect,
1213            **opts,
1214        )
1215
1216    def sort_by(
1217        self,
1218        *expressions: ExpOrStr | None,
1219        append: bool = True,
1220        dialect: DialectType = None,
1221        copy: bool = True,
1222        **opts: Unpack[ParserNoDialectArgs],
1223    ) -> Select:
1224        """
1225        Set the SORT BY expression.
1226
1227        Example:
1228            >>> Select().from_("tbl").select("x").sort_by("x DESC").sql(dialect="hive")
1229            'SELECT x FROM tbl SORT BY x DESC'
1230
1231        Args:
1232            *expressions: the SQL code strings to parse.
1233                If a `Group` instance is passed, this is used as-is.
1234                If another `Expr` instance is passed, it will be wrapped in a `SORT`.
1235            append: if `True`, add to any existing expressions.
1236                Otherwise, this flattens all the `Order` expression into a single expression.
1237            dialect: the dialect used to parse the input expression.
1238            copy: if `False`, modify this expression instance in-place.
1239            opts: other options to use to parse the input expressions.
1240
1241        Returns:
1242            The modified Select expression.
1243        """
1244        return _apply_child_list_builder(
1245            *expressions,
1246            instance=self,
1247            arg="sort",
1248            append=append,
1249            copy=copy,
1250            prefix="SORT BY",
1251            into=Sort,
1252            dialect=dialect,
1253            **opts,
1254        )
1255
1256    def cluster_by(
1257        self,
1258        *expressions: ExpOrStr | None,
1259        append: bool = True,
1260        dialect: DialectType = None,
1261        copy: bool = True,
1262        **opts: Unpack[ParserNoDialectArgs],
1263    ) -> Select:
1264        """
1265        Set the CLUSTER BY expression.
1266
1267        Example:
1268            >>> Select().from_("tbl").select("x").cluster_by("x DESC").sql(dialect="hive")
1269            'SELECT x FROM tbl CLUSTER BY x DESC'
1270
1271        Args:
1272            *expressions: the SQL code strings to parse.
1273                If a `Group` instance is passed, this is used as-is.
1274                If another `Expr` instance is passed, it will be wrapped in a `Cluster`.
1275            append: if `True`, add to any existing expressions.
1276                Otherwise, this flattens all the `Order` expression into a single expression.
1277            dialect: the dialect used to parse the input expression.
1278            copy: if `False`, modify this expression instance in-place.
1279            opts: other options to use to parse the input expressions.
1280
1281        Returns:
1282            The modified Select expression.
1283        """
1284        return _apply_child_list_builder(
1285            *expressions,
1286            instance=self,
1287            arg="cluster",
1288            append=append,
1289            copy=copy,
1290            prefix="CLUSTER BY",
1291            into=Cluster,
1292            dialect=dialect,
1293            **opts,
1294        )
1295
1296    def select(
1297        self,
1298        *expressions: ExpOrStr | None,
1299        append: bool = True,
1300        dialect: DialectType = None,
1301        copy: bool = True,
1302        **opts: Unpack[ParserNoDialectArgs],
1303    ) -> Select:
1304        return _apply_list_builder(
1305            *expressions,
1306            instance=self,
1307            arg="expressions",
1308            append=append,
1309            dialect=dialect,
1310            into=Expr,
1311            copy=copy,
1312            **opts,
1313        )
1314
1315    def lateral(
1316        self,
1317        *expressions: ExpOrStr | None,
1318        append: bool = True,
1319        dialect: DialectType = None,
1320        copy: bool = True,
1321        **opts: Unpack[ParserNoDialectArgs],
1322    ) -> Select:
1323        """
1324        Append to or set the LATERAL expressions.
1325
1326        Example:
1327            >>> Select().select("x").lateral("OUTER explode(y) tbl2 AS z").from_("tbl").sql()
1328            'SELECT x FROM tbl LATERAL VIEW OUTER EXPLODE(y) tbl2 AS z'
1329
1330        Args:
1331            *expressions: the SQL code strings to parse.
1332                If an `Expr` instance is passed, it will be used as-is.
1333            append: if `True`, add to any existing expressions.
1334                Otherwise, this resets the expressions.
1335            dialect: the dialect used to parse the input expressions.
1336            copy: if `False`, modify this expression instance in-place.
1337            opts: other options to use to parse the input expressions.
1338
1339        Returns:
1340            The modified Select expression.
1341        """
1342        return _apply_list_builder(
1343            *expressions,
1344            instance=self,
1345            arg="laterals",
1346            append=append,
1347            into=Lateral,
1348            prefix="LATERAL VIEW",
1349            dialect=dialect,
1350            copy=copy,
1351            **opts,
1352        )
1353
1354    def join(
1355        self,
1356        expression: ExpOrStr,
1357        on: ExpOrStr | list[ExpOrStr] | tuple[ExpOrStr, ...] | None = None,
1358        using: ExpOrStr | list[ExpOrStr] | tuple[ExpOrStr, ...] | None = None,
1359        append: bool = True,
1360        join_type: str | None = None,
1361        join_alias: Identifier | str | None = None,
1362        dialect: DialectType = None,
1363        copy: bool = True,
1364        **opts: Unpack[ParserNoDialectArgs],
1365    ) -> Select:
1366        """
1367        Append to or set the JOIN expressions.
1368
1369        Example:
1370            >>> Select().select("*").from_("tbl").join("tbl2", on="tbl1.y = tbl2.y").sql()
1371            'SELECT * FROM tbl JOIN tbl2 ON tbl1.y = tbl2.y'
1372
1373            >>> Select().select("1").from_("a").join("b", using=["x", "y", "z"]).sql()
1374            'SELECT 1 FROM a JOIN b USING (x, y, z)'
1375
1376            Use `join_type` to change the type of join:
1377
1378            >>> Select().select("*").from_("tbl").join("tbl2", on="tbl1.y = tbl2.y", join_type="left outer").sql()
1379            'SELECT * FROM tbl LEFT OUTER JOIN tbl2 ON tbl1.y = tbl2.y'
1380
1381        Args:
1382            expression: the SQL code string to parse.
1383                If an `Expr` instance is passed, it will be used as-is.
1384            on: optionally specify the join "on" criteria as a SQL string.
1385                If an `Expr` instance is passed, it will be used as-is.
1386            using: optionally specify the join "using" criteria as a SQL string.
1387                If an `Expr` instance is passed, it will be used as-is.
1388            append: if `True`, add to any existing expressions.
1389                Otherwise, this resets the expressions.
1390            join_type: if set, alter the parsed join type.
1391            join_alias: an optional alias for the joined source.
1392            dialect: the dialect used to parse the input expressions.
1393            copy: if `False`, modify this expression instance in-place.
1394            opts: other options to use to parse the input expressions.
1395
1396        Returns:
1397            Select: the modified expression.
1398        """
1399        parse_args: ParserArgs = {"dialect": dialect, **opts}
1400        try:
1401            expression = maybe_parse(expression, into=Join, prefix="JOIN", **parse_args)
1402        except ParseError:
1403            expression = maybe_parse(expression, into=(Join, Expr), **parse_args)
1404
1405        join = expression if isinstance(expression, Join) else Join(this=expression)
1406
1407        if isinstance(join.this, Select):
1408            join.this.replace(join.this.subquery())
1409
1410        if join_type:
1411            new_join: Join = maybe_parse(f"FROM _ {join_type} JOIN _", **parse_args).find(Join)
1412            method = new_join.method
1413            side = new_join.side
1414            kind = new_join.kind
1415
1416            if method:
1417                join.set("method", method)
1418            if side:
1419                join.set("side", side)
1420            if kind:
1421                join.set("kind", kind)
1422
1423        if on:
1424            on_exprs: list[ExpOrStr] = ensure_list(on)
1425            on = and_(*on_exprs, dialect=dialect, copy=copy, **opts)
1426            join.set("on", on)
1427
1428        if using:
1429            using_exprs: list[ExpOrStr] = ensure_list(using)
1430            join = _apply_list_builder(
1431                *using_exprs,
1432                instance=join,
1433                arg="using",
1434                append=append,
1435                copy=copy,
1436                into=Identifier,
1437                **opts,
1438            )
1439
1440        if join_alias:
1441            join.set("this", alias_(join.this, join_alias, table=True))
1442
1443        return _apply_list_builder(
1444            join,
1445            instance=self,
1446            arg="joins",
1447            append=append,
1448            copy=copy,
1449            **opts,
1450        )
1451
1452    def having(
1453        self,
1454        *expressions: ExpOrStr | None,
1455        append: bool = True,
1456        dialect: DialectType = None,
1457        copy: bool = True,
1458        **opts: Unpack[ParserNoDialectArgs],
1459    ) -> Select:
1460        """
1461        Append to or set the HAVING expressions.
1462
1463        Example:
1464            >>> Select().select("x", "COUNT(y)").from_("tbl").group_by("x").having("COUNT(y) > 3").sql()
1465            'SELECT x, COUNT(y) FROM tbl GROUP BY x HAVING COUNT(y) > 3'
1466
1467        Args:
1468            *expressions: the SQL code strings to parse.
1469                If an `Expr` instance is passed, it will be used as-is.
1470                Multiple expressions are combined with an AND operator.
1471            append: if `True`, AND the new expressions to any existing expression.
1472                Otherwise, this resets the expression.
1473            dialect: the dialect used to parse the input expressions.
1474            copy: if `False`, modify this expression instance in-place.
1475            opts: other options to use to parse the input expressions.
1476
1477        Returns:
1478            The modified Select expression.
1479        """
1480        return _apply_conjunction_builder(
1481            *expressions,
1482            instance=self,
1483            arg="having",
1484            append=append,
1485            into=Having,
1486            dialect=dialect,
1487            copy=copy,
1488            **opts,
1489        )
1490
1491    def window(
1492        self,
1493        *expressions: ExpOrStr | None,
1494        append: bool = True,
1495        dialect: DialectType = None,
1496        copy: bool = True,
1497        **opts: Unpack[ParserNoDialectArgs],
1498    ) -> Select:
1499        return _apply_list_builder(
1500            *expressions,
1501            instance=self,
1502            arg="windows",
1503            append=append,
1504            into=Window,
1505            dialect=dialect,
1506            copy=copy,
1507            **opts,
1508        )
1509
1510    def qualify(
1511        self,
1512        *expressions: ExpOrStr | None,
1513        append: bool = True,
1514        dialect: DialectType = None,
1515        copy: bool = True,
1516        **opts: Unpack[ParserNoDialectArgs],
1517    ) -> Select:
1518        return _apply_conjunction_builder(
1519            *expressions,
1520            instance=self,
1521            arg="qualify",
1522            append=append,
1523            into=Qualify,
1524            dialect=dialect,
1525            copy=copy,
1526            **opts,
1527        )
1528
1529    def distinct(self, *ons: ExpOrStr | None, distinct: bool = True, copy: bool = True) -> Select:
1530        """
1531        Set the OFFSET expression.
1532
1533        Example:
1534            >>> Select().from_("tbl").select("x").distinct().sql()
1535            'SELECT DISTINCT x FROM tbl'
1536
1537        Args:
1538            ons: the expressions to distinct on
1539            distinct: whether the Select should be distinct
1540            copy: if `False`, modify this expression instance in-place.
1541
1542        Returns:
1543            Select: the modified expression.
1544        """
1545        instance = maybe_copy(self, copy)
1546        on = Tuple(expressions=[maybe_parse(on, copy=copy) for on in ons if on]) if ons else None
1547        instance.set("distinct", Distinct(on=on) if distinct else None)
1548        return instance
1549
1550    def ctas(
1551        self,
1552        table: ExpOrStr,
1553        properties: dict | None = None,
1554        dialect: DialectType = None,
1555        copy: bool = True,
1556        **opts: Unpack[ParserNoDialectArgs],
1557    ) -> Create:
1558        """
1559        Convert this expression to a CREATE TABLE AS statement.
1560
1561        Example:
1562            >>> Select().select("*").from_("tbl").ctas("x").sql()
1563            'CREATE TABLE x AS SELECT * FROM tbl'
1564
1565        Args:
1566            table: the SQL code string to parse as the table name.
1567                If another `Expr` instance is passed, it will be used as-is.
1568            properties: an optional mapping of table properties
1569            dialect: the dialect used to parse the input table.
1570            copy: if `False`, modify this expression instance in-place.
1571            opts: other options to use to parse the input table.
1572
1573        Returns:
1574            The new Create expression.
1575        """
1576        instance = maybe_copy(self, copy)
1577        table_expression = maybe_parse(table, into=Table, dialect=dialect, **opts)
1578
1579        properties_expression = None
1580        if properties:
1581            from sqlglot.expressions.properties import Properties as _Properties
1582
1583            properties_expression = _Properties.from_dict(properties)
1584
1585        from sqlglot.expressions.ddl import Create as _Create
1586
1587        return _Create(
1588            this=table_expression,
1589            kind="TABLE",
1590            expression=instance,
1591            properties=properties_expression,
1592        )
1593
1594    def lock(self, update: bool = True, copy: bool = True) -> Select:
1595        """
1596        Set the locking read mode for this expression.
1597
1598        Examples:
1599            >>> Select().select("x").from_("tbl").where("x = 'a'").lock().sql("mysql")
1600            "SELECT x FROM tbl WHERE x = 'a' FOR UPDATE"
1601
1602            >>> Select().select("x").from_("tbl").where("x = 'a'").lock(update=False).sql("mysql")
1603            "SELECT x FROM tbl WHERE x = 'a' FOR SHARE"
1604
1605        Args:
1606            update: if `True`, the locking type will be `FOR UPDATE`, else it will be `FOR SHARE`.
1607            copy: if `False`, modify this expression instance in-place.
1608
1609        Returns:
1610            The modified expression.
1611        """
1612        inst = maybe_copy(self, copy)
1613        inst.set("locks", [Lock(update=update)])
1614
1615        return inst
1616
1617    def hint(self, *hints: ExpOrStr, dialect: DialectType = None, copy: bool = True) -> Select:
1618        """
1619        Set hints for this expression.
1620
1621        Examples:
1622            >>> Select().select("x").from_("tbl").hint("BROADCAST(y)").sql(dialect="spark")
1623            'SELECT /*+ BROADCAST(y) */ x FROM tbl'
1624
1625        Args:
1626            hints: The SQL code strings to parse as the hints.
1627                If an `Expr` instance is passed, it will be used as-is.
1628            dialect: The dialect used to parse the hints.
1629            copy: If `False`, modify this expression instance in-place.
1630
1631        Returns:
1632            The modified expression.
1633        """
1634        inst = maybe_copy(self, copy)
1635        inst.set(
1636            "hint", Hint(expressions=[maybe_parse(h, copy=copy, dialect=dialect) for h in hints])
1637        )
1638
1639        return inst
1640
1641    @property
1642    def named_selects(self) -> list[str]:
1643        selects = []
1644
1645        for e in self.expressions:
1646            if e.alias_or_name:
1647                selects.append(e.output_name)
1648            elif isinstance(e, Aliases):
1649                selects.extend([a.name for a in e.aliases])
1650        return selects
1651
1652    @property
1653    def is_star(self) -> bool:
1654        return any(expression.is_star for expression in self.expressions)
1655
1656    @property
1657    def selects(self) -> list[Expr]:
1658        return self.expressions
1659
1660
1661class Subquery(Expression, DerivedTable, Query):
1662    is_subquery: t.ClassVar[bool] = True
1663    arg_types = {
1664        "this": True,
1665        "alias": False,
1666        "with_": False,
1667        **QUERY_MODIFIERS,
1668    }
1669
1670    def unnest(self) -> Expr:
1671        """Returns the first non subquery."""
1672        expression: Expr = self
1673        while isinstance(expression, Subquery):
1674            expression = expression.this
1675        return expression
1676
1677    def unwrap(self) -> Subquery:
1678        expression = self
1679        while expression.same_parent and expression.is_wrapper:
1680            expression = t.cast(Subquery, expression.parent)
1681        return expression
1682
1683    def select(
1684        self,
1685        *expressions: ExpOrStr | None,
1686        append: bool = True,
1687        dialect: DialectType = None,
1688        copy: bool = True,
1689        **opts: Unpack[ParserNoDialectArgs],
1690    ) -> Subquery:
1691        this = maybe_copy(self, copy)
1692        inner = this.unnest()
1693        if hasattr(inner, "select"):
1694            inner.select(*expressions, append=append, dialect=dialect, copy=False, **opts)
1695        return this
1696
1697    @property
1698    def is_wrapper(self) -> bool:
1699        """
1700        Whether this Subquery acts as a simple wrapper around another expression.
1701
1702        SELECT * FROM (((SELECT * FROM t)))
1703                      ^
1704                      This corresponds to a "wrapper" Subquery node
1705        """
1706        return all(v is None for k, v in self.args.items() if k != "this")
1707
1708    @property
1709    def is_star(self) -> bool:
1710        return self.this.is_star
1711
1712    @property
1713    def output_name(self) -> str:
1714        return self.alias
1715
1716
1717class TableSample(Expression):
1718    arg_types = {
1719        "expressions": False,
1720        "method": False,
1721        "bucket_numerator": False,
1722        "bucket_denominator": False,
1723        "bucket_field": False,
1724        "percent": False,
1725        "rows": False,
1726        "size": False,
1727        "seed": False,
1728    }
1729
1730
1731class Tag(Expression):
1732    """Tags are used for generating arbitrary sql like SELECT <span>x</span>."""
1733
1734    arg_types = {
1735        "this": False,
1736        "prefix": False,
1737        "postfix": False,
1738    }
1739
1740
1741class Pivot(Expression):
1742    arg_types = {
1743        "this": False,
1744        "alias": False,
1745        "expressions": False,
1746        "fields": False,
1747        "unpivot": False,
1748        "using": False,
1749        "group": False,
1750        "columns": False,
1751        "include_nulls": False,
1752        "default_on_null": False,
1753        "into": False,
1754        "with_": False,
1755    }
1756
1757    @property
1758    def unpivot(self) -> bool:
1759        return bool(self.args.get("unpivot"))
1760
1761    @property
1762    def fields(self) -> list[Expr]:
1763        return self.args.get("fields", [])
1764
1765
1766class UnpivotColumns(Expression):
1767    arg_types = {"this": True, "expressions": True}
1768
1769
1770class Window(Expression, Condition):
1771    arg_types = {
1772        "this": True,
1773        "partition_by": False,
1774        "order": False,
1775        "spec": False,
1776        "alias": False,
1777        "over": False,
1778        "first": False,
1779    }
1780
1781
1782class WindowSpec(Expression):
1783    arg_types = {
1784        "kind": False,
1785        "start": False,
1786        "start_side": False,
1787        "end": False,
1788        "end_side": False,
1789        "exclude": False,
1790    }
1791
1792
1793class PreWhere(Expression):
1794    pass
1795
1796
1797class Where(Expression):
1798    pass
1799
1800
1801class Analyze(Expression):
1802    arg_types = {
1803        "kind": False,
1804        "this": False,
1805        "options": False,
1806        "mode": False,
1807        "partition": False,
1808        "expression": False,
1809        "properties": False,
1810    }
1811
1812
1813class AnalyzeStatistics(Expression):
1814    arg_types = {
1815        "kind": True,
1816        "option": False,
1817        "this": False,
1818        "expressions": False,
1819    }
1820
1821
1822class AnalyzeHistogram(Expression):
1823    arg_types = {
1824        "this": True,
1825        "expressions": True,
1826        "expression": False,
1827        "update_options": False,
1828    }
1829
1830
1831class AnalyzeSample(Expression):
1832    arg_types = {"kind": True, "sample": True}
1833
1834
1835class AnalyzeListChainedRows(Expression):
1836    arg_types = {"expression": False}
1837
1838
1839class AnalyzeDelete(Expression):
1840    arg_types = {"kind": False}
1841
1842
1843class AnalyzeWith(Expression):
1844    arg_types = {"expressions": True}
1845
1846
1847class AnalyzeValidate(Expression):
1848    arg_types = {
1849        "kind": True,
1850        "this": False,
1851        "expression": False,
1852    }
1853
1854
1855class AnalyzeColumns(Expression):
1856    pass
1857
1858
1859class UsingData(Expression):
1860    pass
1861
1862
1863class AddPartition(Expression):
1864    arg_types = {"this": True, "exists": False, "location": False}
1865
1866
1867class AttachOption(Expression):
1868    arg_types = {"this": True, "expression": False}
1869
1870
1871class DropPartition(Expression):
1872    arg_types = {"expressions": True, "exists": False}
1873
1874
1875class ReplacePartition(Expression):
1876    arg_types = {"expression": True, "source": True}
1877
1878
1879class TranslateCharacters(Expression):
1880    arg_types = {"this": True, "expression": True, "with_error": False}
1881
1882
1883class OverflowTruncateBehavior(Expression):
1884    arg_types = {"this": False, "with_count": True}
1885
1886
1887class JSON(Expression):
1888    arg_types = {"this": False, "with_": False, "unique": False}
1889
1890
1891class JSONPath(Expression):
1892    arg_types = {"expressions": True, "escape": False}
1893
1894    @property
1895    def output_name(self) -> str:
1896        last_segment = self.expressions[-1].this
1897        return last_segment if isinstance(last_segment, str) else ""
1898
1899
1900class JSONPathPart(Expression):
1901    arg_types = {}
1902
1903
1904class JSONPathFilter(JSONPathPart):
1905    arg_types = {"this": True}
1906
1907
1908class JSONPathKey(JSONPathPart):
1909    arg_types = {"this": True}
1910
1911
1912class JSONPathRecursive(JSONPathPart):
1913    arg_types = {"this": False}
1914
1915
1916class JSONPathRoot(JSONPathPart):
1917    pass
1918
1919
1920class JSONPathScript(JSONPathPart):
1921    arg_types = {"this": True}
1922
1923
1924class JSONPathSlice(JSONPathPart):
1925    arg_types = {"start": False, "end": False, "step": False}
1926
1927
1928class JSONPathSelector(JSONPathPart):
1929    arg_types = {"this": True}
1930
1931
1932class JSONPathSubscript(JSONPathPart):
1933    arg_types = {"this": True}
1934
1935
1936class JSONPathUnion(JSONPathPart):
1937    arg_types = {"expressions": True}
1938
1939
1940class JSONPathWildcard(JSONPathPart):
1941    pass
1942
1943
1944class FormatJson(Expression):
1945    pass
1946
1947
1948class JSONKeyValue(Expression):
1949    arg_types = {"this": True, "expression": True}
1950
1951
1952class JSONColumnDef(Expression):
1953    arg_types = {
1954        "this": False,
1955        "kind": False,
1956        "path": False,
1957        "nested_schema": False,
1958        "ordinality": False,
1959    }
1960
1961
1962class JSONSchema(Expression):
1963    arg_types = {"expressions": True}
1964
1965
1966class JSONValue(Expression):
1967    arg_types = {
1968        "this": True,
1969        "path": True,
1970        "returning": False,
1971        "on_condition": False,
1972    }
1973
1974
1975class JSONValueArray(Expression, Func):
1976    arg_types = {"this": True, "expression": False}
1977
1978
1979class OpenJSONColumnDef(Expression):
1980    arg_types = {"this": True, "kind": True, "path": False, "as_json": False}
1981
1982
1983class JSONExtractQuote(Expression):
1984    arg_types = {
1985        "option": True,
1986        "scalar": False,
1987    }
1988
1989
1990class ScopeResolution(Expression):
1991    arg_types = {"this": False, "expression": True}
1992
1993
1994class Stream(Expression):
1995    pass
1996
1997
1998class ModelAttribute(Expression):
1999    arg_types = {"this": True, "expression": True}
2000
2001
2002class XMLNamespace(Expression):
2003    pass
2004
2005
2006class XMLKeyValueOption(Expression):
2007    arg_types = {"this": True, "expression": False}
2008
2009
2010class Semicolon(Expression):
2011    arg_types = {}
2012
2013
2014class TableColumn(Expression):
2015    pass
2016
2017
2018class Variadic(Expression):
2019    pass
2020
2021
2022class StoredProcedure(Expression):
2023    arg_types = {"this": True, "expressions": False, "wrapped": False}
2024
2025
2026class Block(Expression):
2027    arg_types = {"expressions": True}
2028
2029
2030class IfBlock(Expression):
2031    arg_types = {"this": True, "true": True, "false": False}
2032
2033
2034class WhileBlock(Expression):
2035    arg_types = {"this": True, "body": True}
2036
2037
2038class EndStatement(Expression):
2039    arg_types = {}
2040
2041
2042UNWRAPPED_QUERIES = (Select, SetOperation)
2043
2044
2045def union(
2046    *expressions: ExpOrStr,
2047    distinct: bool = True,
2048    dialect: DialectType = None,
2049    copy: bool = True,
2050    **opts: Unpack[ParserNoDialectArgs],
2051) -> Union:
2052    """
2053    Initializes a syntax tree for the `UNION` operation.
2054
2055    Example:
2056        >>> union("SELECT * FROM foo", "SELECT * FROM bla").sql()
2057        'SELECT * FROM foo UNION SELECT * FROM bla'
2058
2059    Args:
2060        expressions: the SQL code strings, corresponding to the `UNION`'s operands.
2061            If `Expr` instances are passed, they will be used as-is.
2062        distinct: set the DISTINCT flag if and only if this is true.
2063        dialect: the dialect used to parse the input expression.
2064        copy: whether to copy the expression.
2065        opts: other options to use to parse the input expressions.
2066
2067    Returns:
2068        The new Union instance.
2069    """
2070    assert len(expressions) >= 2, "At least two expressions are required by `union`."
2071    return _apply_set_operation(
2072        *expressions, set_operation=Union, distinct=distinct, dialect=dialect, copy=copy, **opts
2073    )
2074
2075
2076def intersect(
2077    *expressions: ExpOrStr,
2078    distinct: bool = True,
2079    dialect: DialectType = None,
2080    copy: bool = True,
2081    **opts: Unpack[ParserNoDialectArgs],
2082) -> Intersect:
2083    """
2084    Initializes a syntax tree for the `INTERSECT` operation.
2085
2086    Example:
2087        >>> intersect("SELECT * FROM foo", "SELECT * FROM bla").sql()
2088        'SELECT * FROM foo INTERSECT SELECT * FROM bla'
2089
2090    Args:
2091        expressions: the SQL code strings, corresponding to the `INTERSECT`'s operands.
2092            If `Expr` instances are passed, they will be used as-is.
2093        distinct: set the DISTINCT flag if and only if this is true.
2094        dialect: the dialect used to parse the input expression.
2095        copy: whether to copy the expression.
2096        opts: other options to use to parse the input expressions.
2097
2098    Returns:
2099        The new Intersect instance.
2100    """
2101    assert len(expressions) >= 2, "At least two expressions are required by `intersect`."
2102    return _apply_set_operation(
2103        *expressions, set_operation=Intersect, distinct=distinct, dialect=dialect, copy=copy, **opts
2104    )
2105
2106
2107def except_(
2108    *expressions: ExpOrStr,
2109    distinct: bool = True,
2110    dialect: DialectType = None,
2111    copy: bool = True,
2112    **opts: Unpack[ParserNoDialectArgs],
2113) -> Except:
2114    """
2115    Initializes a syntax tree for the `EXCEPT` operation.
2116
2117    Example:
2118        >>> except_("SELECT * FROM foo", "SELECT * FROM bla").sql()
2119        'SELECT * FROM foo EXCEPT SELECT * FROM bla'
2120
2121    Args:
2122        expressions: the SQL code strings, corresponding to the `EXCEPT`'s operands.
2123            If `Expr` instances are passed, they will be used as-is.
2124        distinct: set the DISTINCT flag if and only if this is true.
2125        dialect: the dialect used to parse the input expression.
2126        copy: whether to copy the expression.
2127        opts: other options to use to parse the input expressions.
2128
2129    Returns:
2130        The new Except instance.
2131    """
2132    assert len(expressions) >= 2, "At least two expressions are required by `except_`."
2133    return _apply_set_operation(
2134        *expressions, set_operation=Except, distinct=distinct, dialect=dialect, copy=copy, **opts
2135    )