r"""Produce a :class:`_expression.Alias` construct against this :class:`.FunctionElement`. .. tip:: The :meth:`_functions.FunctionElement.alias` method is part of the mechanism by which "table valued" SQL functions are created. However, most use
(
self, name: Optional[str] = None, joins_implicitly: bool = False
)
| 645 | return None |
| 646 | |
| 647 | def alias( |
| 648 | self, name: Optional[str] = None, joins_implicitly: bool = False |
| 649 | ) -> TableValuedAlias: |
| 650 | r"""Produce a :class:`_expression.Alias` construct against this |
| 651 | :class:`.FunctionElement`. |
| 652 | |
| 653 | .. tip:: |
| 654 | |
| 655 | The :meth:`_functions.FunctionElement.alias` method is part of the |
| 656 | mechanism by which "table valued" SQL functions are created. |
| 657 | However, most use cases are covered by higher level methods on |
| 658 | :class:`_functions.FunctionElement` including |
| 659 | :meth:`_functions.FunctionElement.table_valued`, and |
| 660 | :meth:`_functions.FunctionElement.column_valued`. |
| 661 | |
| 662 | This construct wraps the function in a named alias which |
| 663 | is suitable for the FROM clause, in the style accepted for example |
| 664 | by PostgreSQL. A column expression is also provided using the |
| 665 | special ``.column`` attribute, which may |
| 666 | be used to refer to the output of the function as a scalar value |
| 667 | in the columns or where clause, for a backend such as PostgreSQL. |
| 668 | |
| 669 | For a full table-valued expression, use the |
| 670 | :meth:`_functions.FunctionElement.table_valued` method first to |
| 671 | establish named columns. |
| 672 | |
| 673 | e.g.: |
| 674 | |
| 675 | .. sourcecode:: pycon+sql |
| 676 | |
| 677 | >>> from sqlalchemy import func, select, column |
| 678 | >>> data_view = func.unnest([1, 2, 3]).alias("data_view") |
| 679 | >>> print(select(data_view.column)) |
| 680 | {printsql}SELECT data_view |
| 681 | FROM unnest(:unnest_1) AS data_view |
| 682 | |
| 683 | The :meth:`_functions.FunctionElement.column_valued` method provides |
| 684 | a shortcut for the above pattern: |
| 685 | |
| 686 | .. sourcecode:: pycon+sql |
| 687 | |
| 688 | >>> data_view = func.unnest([1, 2, 3]).column_valued("data_view") |
| 689 | >>> print(select(data_view)) |
| 690 | {printsql}SELECT data_view |
| 691 | FROM unnest(:unnest_1) AS data_view |
| 692 | |
| 693 | .. versionadded:: 1.4.0b2 Added the ``.column`` accessor |
| 694 | |
| 695 | :param name: alias name, will be rendered as ``AS <name>`` in the |
| 696 | FROM clause |
| 697 | |
| 698 | :param joins_implicitly: when True, the table valued function may be |
| 699 | used in the FROM clause without any explicit JOIN to other tables |
| 700 | in the SQL query, and no "cartesian product" warning will be |
| 701 | generated. May be useful for SQL functions such as |
| 702 | ``func.json_each()``. |
| 703 | |
| 704 | .. versionadded:: 1.4.33 |
no test coverage detected