SQL 和泛型函数¶
SQL 函数是使用 func 命名空间调用的。有关如何使用 func 对象在语句中呈现 SQL 函数的背景信息，请参阅使用 SQL 函数中的教程。
另请参阅
函数 API¶
SQL 函数的基本 API，它为 func
命名空间以及可用于扩展性的类。
对象名称 |
描述 |
|---|---|
|
|
|
|
|
|
|
|
|
|
-
class sqlalchemy.sql.functions 的函数。Ansi函数¶
以 “ansi” 格式定义一个函数，该函数不呈现括号。
-
class sqlalchemy.sql.functions 的函数。功能¶
描述命名的 SQL 函数。
参数
*clauses¶ – 构成 SQL 函数调用参数的列表达式列表。
type_¶– 可选的TypeEngine数据类型对象，将用作此函数调用生成的列表达式的返回值。
包名称¶ –
一个字符串，指示在生成 SQL 时要添加到函数名称前面的包前缀名称。func生成器在使用点格式调用时创建这些，例如：func.mypackage.some_function(col1, col2)
另请参阅
使用 SQL 函数 - 在 SQLAlchemy Unified 教程中func- 生成 Registered 或 ad-hoc 的命名空间Function实例。GenericFunction- 允许创建已注册的函数类型。
成员-
方法sqlalchemy.sql.functions.Function.__init__（name： str， *clauses： _ColumnExpressionOrLiteralArgument[Any]， type_：_TypeEngineArgument[_T]None=None， packagenames：Tuple[str,...]None=无）¶
构造一个函数。
-
class sqlalchemy.sql.functions 的函数。函数元素¶
面向 SQL 函数的构造的基础。
这是一个泛型类型，这意味着类型检查器和 IDE 可以被指示此函数的Result中预期的类型。看GenericFunction的示例。
另请参阅
使用 SQL 函数 - 在 SQLAlchemy Unified 教程中Function- 命名的 SQL 函数。func- 生成 Registered 或 ad-hoc 的命名空间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）-
methodsqlalchemy.sql.functions.FunctionElement.__init__（*clauses： _ColumnExpressionOrLiteralArgument[Any]）¶
构造FunctionElement。
-
methodsqlalchemy.sql.functions.FunctionElement.alias（name：strNone=None， joins_implicitly： bool = False） TableValuedAlias¶
针对此生成Alias构造FunctionElement 的 FunctionElement中。
提示FunctionElement.alias（）方法是 创建 “table valued” SQL 函数的机制。 但是，大多数用例都由更高级别的方法覆盖FunctionElement包括FunctionElement.table_valued()和FunctionElement.column_valued()。
此结构将函数包装在适合 FROM 子句的命名别名中，其样式为 PostgreSQL 接受的样式。还使用特殊的.column属性提供了列表达式，该属性可用于将函数的输出引用为 columns 或 where 子句中的标量值，用于后端（如 PostgreSQL）。
对于完整的表值表达式，请使用FunctionElement.table_valued()method 首先建立命名列。
例如：>>> 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访问器
-
方法sqlalchemy.sql.functions.FunctionElement.as_comparison（left_index： int， right_index： int） FunctionAsBinary¶
将此表达式解释为两个值之间的布尔比较。
此方法用于 ORM 用例，如 基于 SQL 函数的自定义运算符。
一个假设的 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 子句的“左”侧和“右”侧。此方法的目的是提供一个 SQL 函数构造，当与relationship.primaryjoin参数一起使用时，该构造也可以向 ORM 提供此信息。返回值是名为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 函数（如几何函数）来创建连接条件。
在 1.3 版本加入.
另请参阅
基于 SQL 函数的自定义运算符 - ORM 中的示例使用
-
attributesqlalchemy.sql.functions.FunctionElement.子句¶
返回包含此FunctionElement的参数的基础ClauseList。
-
方法sqlalchemy.sql.functions.FunctionElement.column_valued（name：strNone=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
-
属性sqlalchemy.sql.functions.FunctionElement.列¶
此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 函数表达式。
-
属性sqlalchemy.sql.functions.FunctionElement.entity_namespace¶
作为函数FromClause.entity_namespace的覆盖通常是列表达式，而不是 FromClauses。
-
属性sqlalchemy.sql.functions.FunctionElement.exported_columns¶
-
methodsqlalchemy.sql.functions.FunctionElement.filter（*criterion： _ColumnExpressionArgument[bool]）→SelfFunctionFilter[_T]¶
针对此函数生成 FILTER 子句。
用于聚合和窗口函数，用于支持 “FILTER” 子句的数据库后端。
表达式：func.count(1).filter(True)
是以下各项的简写：from sqlalchemy import funcfilter funcfilter(func.count(1), True)
-
methodsqlalchemy.sql.functions.FunctionElement.over（*， partition_by：_ByArgumentNone=None， order_by：_ByArgumentNone=None， rows：Tuple[intNone，intNone]None=None， range_：Tuple[intNone，intNone]None=None） over[_T]¶
针对此函数生成 OVER 子句。
用于聚合或所谓的 “window” 函数，用于支持 window 函数的数据库后端。
表达式：func.row_number().over(order_by="x")
是以下各项的简写：from sqlalchemy import over over(func.row_number(), order_by="x")
有关完整描述，请参见over（）。
-
方法sqlalchemy.sql.functions.FunctionElement.scalar_table_valued（name： str， type_：_TypeEngineArgument[_T]None=None） ScalarFunctionColumn[_T]¶
返回与 this 相反的列表达式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 版本的新Function。
-
方法sqlalchemy.sql.functions.FunctionElement.select（） Select¶
针对此FunctionElement生成select（）构造。
这是以下各项的简写：s = select(function_element)
-
方法sqlalchemy.sql.functions.FunctionElement.self_group（against：OperatorTypeNone=None） ClauseElement¶
将 'grouping' 应用于此ClauseElement。
此方法被 subclasses 覆盖以返回 “grouping” 结构，即括号。特别是，当它被 “binary” 表达式用于在放入更大的表达式时提供围绕自身的分组，以及select（）构造select（）的（请注意，子查询通常应使用Select.alias（）方法创建，因为许多平台需要命名嵌套的 SELECT 语句）。
由于表达式是组合在一起的，因此self_group（）是自动的 - 最终用户代码永远不需要直接使用此方法。请注意，SQLAlchemy 的子句构造考虑了运算符优先级 - 因此可能不需要括号，例如，在像x OR （y AND z）这样的表达式中 - AND 优先于 OR。
的base self_group（）方法子句元素只返回 self。
-
methodsqlalchemy.sql.functions.FunctionElement.table_valued（*expr： _ColumnExpressionOrStrLabelArgument[Any]， **kw： Any TableValued别名¶
返回此 添加了表值表达式的FunctionElement。
例如：>>> 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¶– 将添加到.c集合的结果TableValuedAlias构造为列。 也可以使用带有或不带有数据类型的column（）对象。
name¶ – 分配给生成的别名的可选名称。如果省略，则使用唯一的匿名名称。
with_ordinality¶ – 字符串名称，如果存在，则会导致WITH ORDINALITY子句被添加到别名中，并且给定的字符串名称将作为列添加到生成的TableValuedAlias的 .c 集合中。joins_implicitly¶ –
如果为 True，则可以在 FROM 子句中使用表值函数，而无需对 SQL 查询中的其他表进行任何显式 JOIN，并且不会生成“笛卡尔积”警告。可能对 SQL 函数（如func.json_each（））有用。
在 1.4.33 版本加入.
1.4.0b2 版本的新Function。
另请参阅
表值函数 - 在 SQLAlchemy Unified 教程中
表值函数 - PostgreSQL 文档中
FunctionElement.scalar_table_valued()- 的变体FunctionElement.table_valued()它将完整的表值表达式作为标量列表达式提供FunctionElement.column_valued()
TableValuedAlias.render_derived()- 使用派生列子句呈现别名，例如AS name（col1， col2， ...）
-
方法sqlalchemy.sql.functions.FunctionElement.within_group（*order_by： _ColumnExpressionArgument[Any]） WithinGroup[_T]¶
针对此函数生成 WITHIN GROUP （ORDER BY expr） 子句。
用于所谓的“有序集聚合”和“假设集聚合”函数，包括percentile_cont、等级、dense_rank等
有关完整描述，请参阅within_group（）。
-
方法sqlalchemy.sql.functions.FunctionElement.within_group_type（within_group： WithinGroup[_S]）→TypeEngineNone¶
对于根据条件定义其返回类型的类型 在 WITHIN GROUP （ORDER BY） 表达式中，由WithinGroup构造。
默认情况下返回 None，在这种情况下，函数的正常.type被使用。
-
-
class sqlalchemy.sql.functions 的函数。GenericFunction（通用函数）¶
定义一个 'generic' 函数。
泛型函数是预先建立的函数类，该类在调用时自动实例化 by name 从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()))
用户定义的通用函数可以组织成 packages 通过在定义时指定 “package” 属性GenericFunction的包含许多函数的第三方库可能希望使用它来避免与其他系统的名称冲突。例如，如果我们的as_utc（）函数是包 “time” 的一部分：class as_utc(GenericFunction): type = DateTime() package = "time" inherit_cache = True
上述函数可从func获得 使用包名time：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结构进行引用，因此可以强制打开或关闭函数名称的引用。
选定的 “已知” 函数¶
这些是一组选定
为每个函数设置预期返回类型的常用 SQL 函数
自然而然。 的调用方式与
func 命名空间：
select(func.count("*")).select_from(some_table)
请注意，func 不知道的任何名称都会按原样生成函数名称 - 对可以调用的 SQL 函数、SQLAlchemy 已知或未知的、内置或用户定义的 SQL 函数没有限制。此处的部分仅描述 SQLAlchemy 已经知道正在使用的参数和返回类型的那些函数。
对象名称 |
描述 |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
-
class sqlalchemy.sql.functions 的函数。aggregate_strings¶
实现通用字符串聚合函数。
此函数会将非 null 值连接成一个字符串，并用分隔符分隔值。
此函数在每个后端的基础上编译为group_concat（）、string_agg（）或LISTAGG（）等函数。
例如，使用分隔符 '.' 的示例用法：stmt = select(func.aggregate_strings(table.c.str_col, "."))
此函数的返回类型为String。
-
class sqlalchemy.sql.functions 的函数。array_agg¶
支持 ARRAY_AGG 功能。func.array_agg（expr）构造返回ARRAY类型的表达式。
例如：stmt = select(func.array_agg(table.c.values)[2:5])
另请参阅array_agg（）- 返回ARRAY的 PostgreSQL 特定版本，其中添加了特定于 PG 的运算符。
-
class sqlalchemy.sql.functions 的函数。char_length¶
CHAR_LENGTH（） SQL 函数。
-
class sqlalchemy.sql.functions 的函数。合并¶
类签名
类sqlalchemy.sql.functions.coalesce（sqlalchemy.sql.functions.ReturnTypeFromArgs）
-
class sqlalchemy.sql.functions 的函数。连接¶
SQL CONCAT（） 函数，用于连接字符串。
例如：>>> print(select(func.concat("a", "b")))
SELECT concat(:concat_2, :concat_3) AS concat_1
SQLAlchemy 中的字符串连接更常见于使用带有字符串数据类型的 Python+运算符，这将呈现特定于后端的串联运算符，例如：>>> print(select(literal("a") + "b"))
SELECT :param_1 || :param_2 AS anon_1
-
class sqlalchemy.sql.functions 的函数。计数¶
ANSI COUNT 聚合函数。在没有参数的情况下，发出 COUNT *。
例如：from sqlalchemy import func from sqlalchemy import select from sqlalchemy import table, column my_table = table("some_table", column("id")) stmt = select(func.count()).select_from(my_table)
执行stmt将发出：SELECT count(*) AS count_1 FROM some_table
-
class sqlalchemy.sql.functions 的函数。立方体¶
实施CUBE分组作。
此函数用作语句的 GROUP BY 的一部分，例如Select.group_by（）：stmt = select( func.sum(table.c.value), table.c.col_1, table.c.col_2 ).group_by(func.cube(table.c.col_1, table.c.col_2))
在 1.2 版本加入.
-
class sqlalchemy.sql.functions 的函数。cume_dist¶
实现cume_disthypothetical-set 聚合函数。
此函数必须与FunctionElement.within_group()修饰符提供要作的排序表达式。
此函数的返回类型为Numeric。
-
class sqlalchemy.sql.functions 的函数。current_date¶
CURRENT_DATE（） SQL 函数。
-
class sqlalchemy.sql.functions 的函数。current_time¶
CURRENT_TIME（） SQL 函数。
-
class sqlalchemy.sql.functions 的函数。current_timestamp¶
CURRENT_TIMESTAMP（） SQL 函数。
-
class sqlalchemy.sql.functions 的函数。current_user¶
CURRENT_USER（） SQL 函数。
-
class sqlalchemy.sql.functions 的函数。dense_rank¶
实现dense_rankhypothetical-set 聚合函数。
此函数必须与FunctionElement.within_group()修饰符提供要作的排序表达式。
此函数的返回类型为Integer。
-
class sqlalchemy.sql.functions 的函数。grouping_sets¶
实现GROUPING SETS分组作。
此函数用作语句的 GROUP BY 的一部分，例如Select.group_by（）：stmt = select( func.sum(table.c.value), table.c.col_1, table.c.col_2 ).group_by(func.grouping_sets(table.c.col_1, table.c.col_2))
为了按多个集合进行分组，请使用tuple_（）构造：from sqlalchemy import tuple_ stmt = select( func.sum(table.c.value), table.c.col_1, table.c.col_2, table.c.col_3 ).group_by( func.grouping_sets( tuple_(table.c.col_1, table.c.col_2), tuple_(table.c.value, table.c.col_3), ) )
在 1.2 版本加入.
-
class sqlalchemy.sql.functions 的函数。本地时间¶
localtime（） SQL 函数。
-
class sqlalchemy.sql.functions 的函数。localtimestamp（本地时间戳）¶
localtimestamp（） SQL 函数。
-
class sqlalchemy.sql.functions 的函数。最大值¶
SQL MAX（） 聚合函数。
类签名sqlalchemy.sql.functions.max类 （sqlalchemy.sql.functions.ReturnTypeFromArgs）
-
class sqlalchemy.sql.functions 的函数。分钟¶
SQL MIN（） 聚合函数。
类签名
类sqlalchemy.sql.functions.min（）sqlalchemy.sql.functions.ReturnTypeFromArgs
-
class sqlalchemy.sql.functions 的函数。模式¶
实现modeordered-set 聚合函数。
此函数必须与FunctionElement.within_group()修饰符提供要作的排序表达式。
此函数的返回类型与 sort 表达式相同。
类签名
类sqlalchemy.sql.functions.mode（）sqlalchemy.sql.functions.OrderedSetAgg
-
class sqlalchemy.sql.functions 的函数。next_value¶
表示给定Sequence的 'next value' 作为其单个参数。
编译为每个后端上的适当函数，或者在不支持序列的后端上使用时将引发 NotImplementedError 。
-
class sqlalchemy.sql.functions 的函数。现在¶
SQL now（） datetime 函数。
SQLAlchemy 方言通常会以特定于后端的方式呈现此特定函数，例如将其呈现为CURRENT_TIMESTAMP。
-
class sqlalchemy.sql.functions 的函数。percent_rank¶
实现percent_rank假设集聚合函数。
此函数必须与FunctionElement.within_group()修饰符提供要作的排序表达式。
此函数的返回类型为Numeric。
-
class sqlalchemy.sql.functions 的函数。percentile_cont¶
实现percentile_contordered-set 聚合函数。
此函数必须与FunctionElement.within_group()修饰符提供要作的排序表达式。
此函数的返回类型与 sort 表达式相同，或者如果参数是数组，则为 sort 表达式类型的ARRAY。
类签名
类sqlalchemy.sql.functions.percentile_cont（sqlalchemy.sql.functions.OrderedSetAgg）
-
class sqlalchemy.sql.functions 的函数。percentile_disc¶
实现percentile_discordered-set 聚合函数。
此函数必须与FunctionElement.within_group()修饰符提供要作的排序表达式。
此函数的返回类型与 sort 表达式相同，或者如果参数是数组，则为 sort 表达式类型的ARRAY。
类签名
类sqlalchemy.sql.functions.percentile_disc（sqlalchemy.sql.functions.OrderedSetAgg）
-
class sqlalchemy.sql.functions 的函数。随机¶
RANDOM（） SQL 函数。
-
class sqlalchemy.sql.functions 的函数。排名¶
实现rankhypothetical-set 聚合函数。
此函数必须与FunctionElement.within_group()修饰符提供要作的排序表达式。
此函数的返回类型为Integer。
-
class sqlalchemy.sql.functions 的函数。汇总¶
实现ROLLUP分组作。
此函数用作语句的 GROUP BY 的一部分，例如Select.group_by（）：stmt = select( func.sum(table.c.value), table.c.col_1, table.c.col_2 ).group_by(func.rollup(table.c.col_1, table.c.col_2))
在 1.2 版本加入.
-
class sqlalchemy.sql.functions 的函数。session_user¶
SESSION_USER（） SQL 函数。
-
class sqlalchemy.sql.functions 的函数。求和¶
SQL SUM（） 聚合函数。
类签名
类sqlalchemy.sql.functions.sum（）sqlalchemy.sql.functions.ReturnTypeFromArgs
-
class sqlalchemy.sql.functions 的函数。sysdate¶
SYSDATE（） SQL 函数。
-
class sqlalchemy.sql.functions 的函数。用户¶
USER（） SQL 函数。