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
)
| 686 | return None |
| 687 | |
| 688 | def alias( |
| 689 | self, name: Optional[str] = None, joins_implicitly: bool = False |
| 690 | ) -> TableValuedAlias: |
| 691 | r"""Produce a :class:`_expression.Alias` construct against this |
| 692 | :class:`.FunctionElement`. |
| 693 | |
| 694 | .. tip:: |
| 695 | |
| 696 | The :meth:`_functions.FunctionElement.alias` method is part of the |
| 697 | mechanism by which "table valued" SQL functions are created. |
| 698 | However, most use cases are covered by higher level methods on |
| 699 | :class:`_functions.FunctionElement` including |
| 700 | :meth:`_functions.FunctionElement.table_valued`, and |
| 701 | :meth:`_functions.FunctionElement.column_valued`. |
| 702 | |
| 703 | This construct wraps the function in a named alias which |
| 704 | is suitable for the FROM clause, in the style accepted for example |
| 705 | by PostgreSQL. A column expression is also provided using the |
| 706 | special ``.column`` attribute, which may |
| 707 | be used to refer to the output of the function as a scalar value |
| 708 | in the columns or where clause, for a backend such as PostgreSQL. |
| 709 | |
| 710 | For a full table-valued expression, use the |
| 711 | :meth:`_functions.FunctionElement.table_valued` method first to |
| 712 | establish named columns. |
| 713 | |
| 714 | e.g.: |
| 715 | |
| 716 | .. sourcecode:: pycon+sql |
| 717 | |
| 718 | >>> from sqlalchemy import func, select, column |
| 719 | >>> data_view = func.unnest([1, 2, 3]).alias("data_view") |
| 720 | >>> print(select(data_view.column)) |
| 721 | {printsql}SELECT data_view |
| 722 | FROM unnest(:unnest_1) AS data_view |
| 723 | |
| 724 | The :meth:`_functions.FunctionElement.column_valued` method provides |
| 725 | a shortcut for the above pattern: |
| 726 | |
| 727 | .. sourcecode:: pycon+sql |
| 728 | |
| 729 | >>> data_view = func.unnest([1, 2, 3]).column_valued("data_view") |
| 730 | >>> print(select(data_view)) |
| 731 | {printsql}SELECT data_view |
| 732 | FROM unnest(:unnest_1) AS data_view |
| 733 | |
| 734 | .. versionadded:: 1.4.0b2 Added the ``.column`` accessor |
| 735 | |
| 736 | :param name: alias name, will be rendered as ``AS <name>`` in the |
| 737 | FROM clause |
| 738 | |
| 739 | :param joins_implicitly: when True, the table valued function may be |
| 740 | used in the FROM clause without any explicit JOIN to other tables |
| 741 | in the SQL query, and no "cartesian product" warning will be |
| 742 | generated. May be useful for SQL functions such as |
| 743 | ``func.json_each()``. |
| 744 | |
| 745 | .. versionadded:: 1.4.33 |
no test coverage detected