SqlAlchemy 2.0 中文文档（三十六）（3）

SqlAlchemy 2.0 中文文档（三十六）（2）https://developer.aliyun.com/article/1562655

SQL 和通用函数

原文：docs.sqlalchemy.org/en/20/core/functions.html

通过使用 func 命名空间来调用 SQL 函数。请参阅 使用 SQL 函数 教程，了解如何使用 func 对象在语句中渲染 SQL 函数的背景知识。

另请参阅

使用 SQL 函数 - 在 SQLAlchemy 统一教程 中

函数 API

SQL 函数的基本 API，提供了 func 命名空间以及可用于可扩展性的类。

class sqlalchemy.sql.functions.AnsiFunction

以“ansi”格式定义函数，不会渲染括号。

类签名

类 sqlalchemy.sql.functions.AnsiFunction (sqlalchemy.sql.functions.GenericFunction)

class sqlalchemy.sql.functions.Function

描述一个命名的 SQL 函数。

Function 对象通常由 func 生成对象生成。

参数：

• *clauses – 形成 SQL 函数调用参数的列表达式列表。
  
• type_ – 可选的 TypeEngine 数据类型对象，将用作由此函数调用生成的列表达式的返回值。
  
• packagenames –
  一个字符串，指示在生成 SQL 时要在函数名前添加的包前缀名称。当使用点格式调用 func 生成器时会创建这些，例如：

func.mypackage.some_function(col1, col2)

另请参阅

使用 SQL 函数 - 在 SQLAlchemy 统一教程 中

func - 产生注册或特设的 Function 实例的命名空间。

GenericFunction - 允许创建注册的函数类型。

成员

init()

类签名

类 sqlalchemy.sql.functions.Function (sqlalchemy.sql.functions.FunctionElement)

method __init__(name: str, *clauses: _ColumnExpressionOrLiteralArgument[Any], type_: _TypeEngineArgument[_T] | None = None, packagenames: Tuple[str, ...] | None = None)

构造一个 Function。

通常使用 func 构造函数来构造新的 Function 实例。

class sqlalchemy.sql.functions.FunctionElement

用于 SQL 函数导向构造的基础。

这是一个 通用类型，意味着类型检查器和 IDE 可以指示在此函数的 Result 中期望的类型。参见 GenericFunction 以了解如何执行此操作的示例。

另请参阅

使用 SQL 函数 - 在 SQLAlchemy 统一教程 中

Function - SQL 函数的命名。

func - 产生注册或特设的 Function 实例的命名空间。

GenericFunction - 允许创建注册的函数类型。

成员

init(), alias(), as_comparison(), c, clauses,  column_valued(), columns, entity_namespace, exported_columns, filter(),  over(), scalar_table_valued(), select(), self_group(), table_valued(),  within_group(), within_group_type()

类签名

类sqlalchemy.sql.functions.FunctionElement（sqlalchemy.sql.expression.Executable，sqlalchemy.sql.expression.ColumnElement，sqlalchemy.sql.expression.FromClause，sqlalchemy.sql.expression.Generative）

method __init__(*clauses: _ColumnExpressionOrLiteralArgument[Any])

构建一个FunctionElement。

参数：

• *clauses – 列表，包含形成 SQL 函数调用参数的列表达式。
  
• **kwargs – 通常由子类消耗的额外 kwargs。
  

另请参阅

func

Function

method alias(name: str | None = None, joins_implicitly: bool = False) → TableValuedAlias

对这个FunctionElement构建一个别名。

提示

FunctionElement.alias() 方法是创建“表值”SQL 函数的机制的一部分。但是，大多数用例都通过FunctionElement上的更高级方法来处理，包括FunctionElement.table_valued()和FunctionElement.column_valued()。

此结构将函数包装在适合 FROM 子句的命名别名中，例如 PostgreSQL 所接受的风格。 还提供了使用特殊的 .column 属性的列表达式，该属性可用于在列或 where 子句中引用函数的输出，例如 PostgreSQL 等后端的标量值。

对于完整的表值表达式，请先使用 FunctionElement.table_valued() 方法来建立命名列。

例如：

>>> from sqlalchemy import func, select, column
>>> data_view = func.unnest([1, 2, 3]).alias("data_view")
>>> print(select(data_view.column))
SELECT  data_view
FROM  unnest(:unnest_1)  AS  data_view 

FunctionElement.column_valued() 方法为上述模式提供了一种快捷方式：

>>> data_view = func.unnest([1, 2, 3]).column_valued("data_view")
>>> print(select(data_view))
SELECT  data_view
FROM  unnest(:unnest_1)  AS  data_view 

新版本 1.4.0b2 中添加了 .column 访问器

参数：

• name – 别名，将在 FROM 子句中渲染为 AS
  
• joins_implicitly –
  当为 True 时，可以在 SQL 查询的 FROM 子句中使用表值函数，而无需显式连接到其他表，并且不会生成“笛卡尔积”警告。 对于 func.json_each() 等 SQL 函数可能很有用。
  新版本 1.4.33 中添加。
  

另请参阅

表值函数 - 在 SQLAlchemy Unified Tutorial 中

FunctionElement.table_valued()

FunctionElement.scalar_table_valued()

FunctionElement.column_valued()

method as_comparison(left_index: int, right_index: int) → FunctionAsBinary

将此表达式解释为两个值之间的布尔比较。

此方法用于描述 Custom operators based on SQL functions 中的 ORM 用例。

假设的 SQL 函数“is_equal()”，用于比较两个值是否相等，可以用 Core 表达式语言编写为：

expr = func.is_equal("a", "b")

如果上面的“is_equal()”是在比较“a”和“b”是否相等，那么FunctionElement.as_comparison()方法将被调用为：

expr = func.is_equal("a", "b").as_comparison(1, 2)

在上面的例子中，“1”这个整数值是指“is_equal()”函数的第一个参数，“2”这个整数值是指第二个参数。

这将创建一个等效于BinaryExpression的表达式：

BinaryExpression("a", "b", operator=op.eq)

但是，在 SQL 级别上，它仍然会呈现为“is_equal(‘a’，‘b’)”。

当 ORM 加载相关对象或集合时，需要能够操作 JOIN 表达式的 ON 子句的“left”和“right”两边。此方法的目的是在与relationship.primaryjoin参数一起使用时，为 ORM 提供也可以向其提供此信息的 SQL 函数构造。返回值是一个名为FunctionAsBinary的包含对象。

一个 ORM 示例如下：

class Venue(Base):
    __tablename__ = 'venue'
    id = Column(Integer, primary_key=True)
    name = Column(String)
    descendants = relationship(
        "Venue",
        primaryjoin=func.instr(
            remote(foreign(name)), name + "/"
        ).as_comparison(1, 2) == 1,
        viewonly=True,
        order_by=name
    )

上面，“Venue”类可以通过确定父 Venue 的名称是否包含在假设的后代值的名称的开头来加载后代“Venue”对象，例如“parent1”将匹配到“parent1/child1”，但不会匹配到“parent2/child1”。

可能的用例包括上面给出的“材料化路径”示例，以及利用特殊的 SQL 函数（例如几何函数）创建连接条件。

参数：

• left_index - 作为表达式“left”侧的函数参数的整数基于 1 的索引。
  
• right_index - 作为表达式“right”侧的函数参数的整数基于 1 的索引。
  

版本 1.3 中的新内容。

另请参见

基于 SQL 函数的自定义运算符 - ORM 中的示例用法

attribute c

joins_implicitly - FunctionElement.columns的同义词。

attribute clauses

返回包含此FunctionElement参数的基础ClauseList。

method column_valued(name: str | None = None, joins_implicitly: bool = False) → TableValuedColumn[_T]

将此FunctionElement作为选择自身的 FROM 子句的列表达式返回。

例如：

>>> from sqlalchemy import select, func
>>> gs = func.generate_series(1, 5, -1).column_valued()
>>> print(select(gs))
SELECT  anon_1
FROM  generate_series(:generate_series_1,  :generate_series_2,  :generate_series_3)  AS  anon_1 

这是的简写形式：

gs = func.generate_series(1, 5, -1).alias().column

参数：

• name - 分配给生成的别名的可选名称。如果省略，将使用唯一的匿名名称。
  
• joins_implicitly –
  当为 True 时，列值函数的“表”部分可以成为 SQL 查询中 FROM 子句的成员，而无需对其他表进行显式 JOIN，并且不会生成“笛卡尔积”警告。可能对诸如 func.json_array_elements() 等 SQL 函数有用。
  1.4.46 版本中的新功能。
  

另请参见

列值函数 - 表值函数作为标量列 - 在 SQLAlchemy 统一教程中

列值函数 - 在 PostgreSQL 文档中

FunctionElement.table_valued()

attribute columns

此FunctionElement导出的一组列。

这是一个占位符集合，允许将函数放置在语句的 FROM 子句中：

>>> from sqlalchemy import column, select, func
>>> stmt = select(column('x'), column('y')).select_from(func.myfunction())
>>> print(stmt)
SELECT  x,  y  FROM  myfunction() 

上述形式是一个已过时的功能，现在已被完全功能的FunctionElement.table_valued()方法取代；请参阅该方法以获取详情。

另请参见

FunctionElement.table_valued() - 生成表值 SQL 函数表达式。

attribute entity_namespace

覆盖 FromClause.entity_namespace，因为函数通常是列表达式而不是 FromClauses。

attribute exported_columns

method filter(*criterion: _ColumnExpressionArgument[bool]) → Self | FunctionFilter[_T]

针对此函数生成一个 FILTER 子句。

用于针对支持“FILTER”子句的聚合和窗口函数的数据库后端。

表达式：

func.count(1).filter(True)

是的缩写：

from sqlalchemy import funcfilter
funcfilter(func.count(1), True)

另请参见

组内特殊修饰符，过滤器 - 在 SQLAlchemy 统一教程中

FunctionFilter

funcfilter()

method over(*, partition_by: _ByArgument | None = None, order_by: _ByArgument | None = None, rows: Tuple[int | None, int | None] | None = None, range_: Tuple[int | None, int | None] | None = None) → Over[_T]

针对此函数生成一个 OVER 子句。

用于针对聚合或所谓的“窗口”函数，适用于支持窗口函数的数据库后端。

表达式：

func.row_number().over(order_by='x')

是的缩写：

from sqlalchemy import over
over(func.row_number(), order_by='x')

有关完整描述，请参阅over()。

另请参见

over()

使用窗口函数 - 在 SQLAlchemy 统一教程中

method scalar_table_valued(name: str, type_: _TypeEngineArgument[_T] | None = None) → ScalarFunctionColumn[_T]

返回一个列表达式，作为标量表值表达式针对这个FunctionElement。

返回的表达式类似于从FunctionElement.table_valued()结构中访问的单个列返回的表达式，只是不生成 FROM 子句；该函数以类似于标量子查询的方式呈现。

例如：

>>> from sqlalchemy import func, select
>>> fn = func.jsonb_each("{'k', 'v'}").scalar_table_valued("key")
>>> print(select(fn))
SELECT  (jsonb_each(:jsonb_each_1)).key 

版本 1.4.0b2 中的新功能。

另见

FunctionElement.table_valued()

FunctionElement.alias()

FunctionElement.column_valued()

method select() → Select

产生针对这个FunctionElement的select()构造。

这是的缩写：

s = select(function_element)

method self_group(against: OperatorType | None = None) → ClauseElement

对这个ClauseElement应用一个“分组”。

此方法被子类重写为返回“分组”构造，即括号。特别是，它被“二元”表达式使用，当将它们放入较大的表达式中时，提供对自身的分组，以及当将它们放入另一个select()构造的 FROM 子句中时，被select()构造使用。（请注意，子查询通常应使用Select.alias()方法创建，因为许多平台要求嵌套的 SELECT 语句具有名称）。

随着表达式组合在一起，self_group()的应用是自动的 - 最终用户代码不应直接使用此方法。请注意，SQLAlchemy 的子句构造考虑了运算符优先级 - 因此可能不需要括号，例如，在表达式x OR (y AND z)中可能不需要括号 - AND 优先于 OR。

ClauseElement 的基本方法self_group()只是返回自身。

method table_valued(*expr: _ColumnExpressionOrStrLabelArgument[Any], **kw: Any) → TableValuedAlias

返回一个 FunctionElement 的 TableValuedAlias 表示形式，其中添加了表值表达式。

例如：

>>> fn = (
...     func.generate_series(1, 5).
...     table_valued("value", "start", "stop", "step")
... )
>>> print(select(fn))
SELECT  anon_1.value,  anon_1.start,  anon_1.stop,  anon_1.step
FROM  generate_series(:generate_series_1,  :generate_series_2)  AS  anon_1
>>> print(select(fn.c.value, fn.c.stop).where(fn.c.value > 2))
SELECT  anon_1.value,  anon_1.stop
FROM  generate_series(:generate_series_1,  :generate_series_2)  AS  anon_1
WHERE  anon_1.value  >  :value_1 

通过传递关键字参数“with_ordinality”可以生成一个 WITH ORDINALITY 表达式：

>>> fn = func.generate_series(4, 1, -1).table_valued("gen", with_ordinality="ordinality")
>>> print(select(fn))
SELECT  anon_1.gen,  anon_1.ordinality
FROM  generate_series(:generate_series_1,  :generate_series_2,  :generate_series_3)  WITH  ORDINALITY  AS  anon_1 

参数：

• *expr - 将添加到结果 TableValuedAlias 构造的 .c 集合中的一系列字符串列名。也可以使用具有或不具有数据类型的 column() 对象。
  
• name - 分配给生成的别名的可选名称。如果省略，将使用唯一的匿名化名称。
  
• with_ordinality - 存在时，将 WITH ORDINALITY 子句添加到别名，并将给定的字符串名称添加为结果 TableValuedAlias 的 .c 集合中的列。
  
• joins_implicitly -
  当为 True 时，可以在 SQL 查询的 FROM 子句中使用表值函数，而无需对其他表进行显式的 JOIN，并且不会生成“笛卡尔积”警告。对于 SQL 函数（例如 func.json_each()）可能很有用。
  新版本 1.4.33 中的新增功能。
  

新版本 1.4.0b2 中的新增功能。

另请参见

表值函数 - 在 SQLAlchemy 统一教程 中

表值函数 - 在 PostgreSQL 文档中

FunctionElement.scalar_table_valued() - FunctionElement.table_valued() 的变体，将完整的表值表达式作为标量列表达式传递

FunctionElement.column_valued()

TableValuedAlias.render_derived() - 使用派生列子句渲染别名，例如 AS name(col1, col2, ...)

method within_group(*order_by: _ColumnExpressionArgument[Any]) → WithinGroup[_T]

生成针对此函数的 WITHIN GROUP (ORDER BY expr) 子句。

用于所谓的“有序集合聚合”和“假设集合聚合”函数，包括 percentile_cont、rank、dense_rank 等。

有关完整描述，请参阅 within_group()。

另请参阅

WITHIN GROUP、FILTER 特殊修饰符 - 在 SQLAlchemy 统一教程 中

method within_group_type(within_group: WithinGroup[_S]) → TypeEngine | None

对于将其返回类型定义为基于 WITHIN GROUP (ORDER BY) 表达式中的条件的类型，由 WithinGroup 构造调用。

默认情况下返回 None，在这种情况下，函数的正常.type被使用。

class sqlalchemy.sql.functions.GenericFunction

定义一个‘通用’函数。

泛型函数是预先定义的 Function 类，在从 func 属性按名称调用时会自动实例化。请注意，从 func 调用任何名称的效果是自动创建一个新的 Function 实例，给定该名称。定义 GenericFunction 类的主要用例是为特定名称的函数指定固定的返回类型。它还可以包括自定义参数解析方案以及其他方法。

GenericFunction 的子类会自动注册到类的名称下。例如，用户定义的函数 as_utc() 将立即可用：

from sqlalchemy.sql.functions import GenericFunction
from sqlalchemy.types import DateTime
class as_utc(GenericFunction):
    type = DateTime()
    inherit_cache = True
print(select(func.as_utc()))

用户定义的通用函数可以通过在定义 GenericFunction 时指定“package”属性来组织成包。包含许多函数的第三方库可能希望这样做，以避免与其他系统的名称冲突。例如，如果我们的 as_utc() 函数是包 “time” 的一部分：

class as_utc(GenericFunction):
    type = DateTime()
    package = "time"
    inherit_cache = True

上述函数可以通过使用包名 time 从 func 中获得：

print(select(func.time.as_utc()))

最后一种选择是允许从func中的一个名称访问函数，但呈现为不同的名称。identifier属性将覆盖从func加载的函数名称，但将保留name作为呈现名称的用法：

class GeoBuffer(GenericFunction):
    type = Geometry()
    package = "geo"
    name = "ST_Buffer"
    identifier = "buffer"
    inherit_cache = True

以上函数将呈现如下：

>>> print(func.geo.buffer())
ST_Buffer() 

名称将原样显示，但不会加引号，除非名称包含需要加引号的特殊字符。要在名称上强制加引号或取消引号，请使用quoted_name结构：

from sqlalchemy.sql import quoted_name
class GeoBuffer(GenericFunction):
    type = Geometry()
    package = "geo"
    name = quoted_name("ST_Buffer", True)
    identifier = "buffer"
    inherit_cache = True

以上函数将呈现为：

>>> print(func.geo.buffer())
"ST_Buffer"() 

可以传递此类作为泛型类型的类的类型参数，并应与Result中看到的类型相匹配。例如：

class as_utc(GenericFunction[datetime.datetime]):
    type = DateTime()
    inherit_cache = True

以上表明以下表达式返回一个datetime对象：

connection.scalar(select(func.as_utc()))

从版本 1.3.13 开始：在对象的“name”属性中使用quoted_name结构现在被识别为引用，因此可以强制对函数名称进行引用或取消引用。

类签名

类sqlalchemy.sql.functions.GenericFunction（sqlalchemy.sql.functions.Function）

function sqlalchemy.sql.functions.register_function(identifier: str, fn: Type[Function[Any]], package: str = '_default') → None

将可调用对象与特定的函数名关联起来。

通常由 GenericFunction 调用，但也可单独使用，以便将非 Function 构造与func访问器关联起来（即 CAST，EXTRACT）。

SqlAlchemy 2.0 中文文档（三十六）（4）https://developer.aliyun.com/article/1562669