对于特定于数据库的呈现、返回类型和参数行为,SQLAlchemy已知的SQL函数。与所有SQL函数一样,使用 func
属性:
select(func.count()).select_from(sometable)
注意任何不知道的名字 func
按原样生成函数名-对于可以调用的、SQLAlchemy已知的或未知的、内置的或用户定义的SQL函数没有限制。这里的部分只描述那些SQLAlchemy已经知道使用了什么参数和返回类型的函数。
参见
使用SQL函数 - in the SQLAlchemy 1.4/2.0教程
SQL函数API、工厂和内置函数。
Object Name | Description |
---|---|
定义一个“ansi”格式的函数,它不会呈现圆括号。 |
|
对ARRAY_AGG函数的支持。 |
|
CHAR_LENGTH()SQL函数。 |
|
SQL CONCAT()函数,用于连接字符串。 |
|
ansi count聚合函数。如果没有参数,则发出count * . |
|
实施 |
|
实施 |
|
CURRENT_DATE()SQL函数。 |
|
CURRENT_TIME()SQL函数。 |
|
CURRENT_TIMESTAMP()SQL函数。 |
|
CURRENT_USER()SQL函数。 |
|
实施 |
|
描述一个命名的SQL函数。 |
|
面向SQL函数构造的基础。 |
|
定义“generic”函数。 |
|
实施 |
|
localtime()SQL函数。 |
|
localtimeamp()SQL函数。 |
|
SQL Max()聚合函数。 |
|
SQL min()聚合函数。 |
|
实施 |
|
表示“下一个值”,给定 |
|
SQL NOW()DATETIME函数。 |
|
定义一个函数,其中返回类型基于传递给的表达式所定义的排序表达式类型 |
|
实施 |
|
实施 |
|
实施 |
|
RANDOM()SQL函数。 |
|
实施 |
|
register_function(identifier, fn[, package]) |
将可调用项与特定的func关联。姓名。 |
定义返回类型与其参数相同的函数。 |
|
实施 |
|
SESSION_USER()SQL函数。 |
|
SQL SUM()聚合函数。 |
|
SYSDATE()SQL函数。 |
|
USER()SQL函数。 |
定义一个“ansi”格式的函数,它不会呈现圆括号。
描述一个命名的SQL函数。
*clauses¶ -- 构成SQL函数调用参数的列表达式的列表。
type_¶ -- 可选择的 TypeEngine
将用作此函数调用生成的列表达式的返回值的数据类型对象。
packagenames¶ -- 一个字符串,指示生成SQL时要在函数名前面加上包前缀名。这个 func
generator在使用虚线格式调用时创建这些文件,例如:func.mypackage.someu函数(第1列,第2列)
参见
使用SQL函数 - in the SQLAlchemy 1.4/2.0教程
func
-生成已注册或临时的命名空间 Function
实例。
GenericFunction
-允许创建已注册的函数类型。
sqlalchemy.sql.functions.Function.
__init__(name, *clauses, **kw)¶构建一个 Function
.
sqlalchemy.sql.functions.Function.
type = NullType()¶A TypeEngine
对象,该对象引用此SQL函数表示的SQL返回类型。
此数据类型可以在生成 Function
通过将 Function.type_
参数,例如::
>>> select(func.lower("some VALUE", type_=String))
的少量内置类 Function
提供适合函数类及其参数的内置数据类型。对于未知的函数,类型缺省为“null type”。
面向SQL函数构造的基础。
类签名
class sqlalchemy.sql.functions.FunctionElement
(sqlalchemy.sql.expression.Executable
, sqlalchemy.sql.expression.ColumnElement
, sqlalchemy.sql.expression.FromClause
, sqlalchemy.sql.expression.Generative
)
sqlalchemy.sql.functions.FunctionElement.
__init__(*clauses, **kwargs)¶构建一个 FunctionElement
.
sqlalchemy.sql.functions.FunctionElement.
alias(name=None)¶产生一个 Alias
在此基础上构建 FunctionElement
.
小技巧
这个 FunctionElement.alias()
方法是创建“表值”SQL函数的机制的一部分。但是,大多数用例都由 FunctionElement
包括 FunctionElement.table_valued()
,以及 FunctionElement.column_valued()
。
此构造将函数包装在一个适用于FROM子句的命名别名中,采用PostgreSQL等接受的样式。还使用特殊的 .column
属性,对于后端(如PostgreSQL),该属性可用于将函数的输出引用为COLUMNS或WHERE子句中的标量值。
对于完整的表值表达式,请使用 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
访问者
sqlalchemy.sql.functions.FunctionElement.
as_comparison(left_index, right_index)¶将此表达式解释为两个值之间的布尔比较。
此方法用于在中描述的ORM用例 基于SQL函数的自定义运算符 。
假设的SQL函数“is_equal()”(与相等值比较)将用核心表达式语言编写为::
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在加载相关对象或集合时,需要能够操作联接表达式的on子句的“左”和“右”边。此方法的目的是提供一个SQL函数构造,当与 relationship.primaryjoin
参数。返回值是一个名为 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”对象,例如,“parent1”将与“parent1/child1”匹配,但不与“parent2/child1”匹配。
可能的用例包括上面给出的“物化路径”示例,以及使用特殊的SQL函数(如几何函数)来创建连接条件。
1.3 新版功能.
参见
基于SQL函数的自定义运算符 -ORM中的示例使用
sqlalchemy.sql.functions.FunctionElement.
clauses¶返回基础 ClauseList
它包含这个的参数 FunctionElement
.
sqlalchemy.sql.functions.FunctionElement.
column_valued(name=None)¶把这个退掉 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.
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函数表达式。
sqlalchemy.sql.functions.FunctionElement.
entity_namespace¶重写FromClause.entity_NAMESPACE,因为函数通常是列表达式,而不是FromClaus。
sqlalchemy.sql.functions.FunctionElement.
execute()¶执行此 FunctionElement
针对嵌入的“bind”。
1.4 版后已移除: 这个 FunctionElement.execute()
方法被认为是SQLAlChemy 1.x系列的遗留方法,将在2.0中删除。SQLAlChemy 2.0中的所有语句都由 Connection.execute()
一种方法 Connection
,或在ORM中由 Session.execute()
一种方法 Session
。(有关SQLAlChemy 2.0的背景信息位于: 迁移到Alchemy )
这是第一个电话 FunctionElement.select()
生成选择构造。
注意 FunctionElement
可以传递给 Connectable.execute()
方法 Connection
或 Engine
.
sqlalchemy.sql.functions.FunctionElement.
exported_columns¶sqlalchemy.sql.functions.FunctionElement.
filter(*criterion)¶针对此函数生成筛选子句。
用于聚合函数和窗口函数,用于支持“filter”子句的数据库后端。
表达式:
func.count(1).filter(True)
缩写为:
from sqlalchemy import funcfilter
funcfilter(func.count(1), True)
1.0.0 新版功能.
sqlalchemy.sql.functions.FunctionElement.
over(partition_by=None, order_by=None, rows=None, range_=None)¶针对此函数生成一个over子句。
用于聚合或所谓的“窗口”函数,用于支持窗口函数的数据库后端。
表达式:
func.row_number().over(order_by='x')
缩写为:
from sqlalchemy import over
over(func.row_number(), order_by='x')
见 over()
完整描述。
sqlalchemy.sql.functions.FunctionElement.
scalar()¶执行此 FunctionElement
并返回一个标量值。
1.4 版后已移除: 这个 FunctionElement.scalar()
方法被认为是SQLAlChemy 1.x系列的遗留方法,将在2.0中删除。SQLAlChemy 2.0中的标量执行由 Connection.scalar()
一种方法 Connection
,或在ORM中由 Session.scalar()
一种方法 Session
。(有关SQLAlChemy 2.0的背景信息位于: 迁移到Alchemy )
这是第一个电话 FunctionElement.select()
生成选择构造。
注意 FunctionElement
可以传递给 Connectable.scalar()
方法 Connection
或 Engine
.
sqlalchemy.sql.functions.FunctionElement.
scalar_table_valued(name, type_=None)¶返回与此对应的列表达式 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 新版功能.
sqlalchemy.sql.functions.FunctionElement.
select()¶产生一个 select()
在此基础上构建 FunctionElement
.
以下简称:
s = select(function_element)
sqlalchemy.sql.functions.FunctionElement.
self_group(against=None)¶对此应用“分组” ClauseElement
.
此方法被子类重写以返回“grouping”构造,即括号。尤其是“binary”表达式使用它在放入更大的表达式时提供围绕其自身的分组,以及 select()
当放入另一个的FROM子句时构造 select()
. (请注意,通常应使用 Select.alias()
方法,因为许多平台都需要命名嵌套的select语句)。
当表达式组合在一起时,应用 self_group()
是自动的-最终用户代码不需要直接使用这个方法。请注意,sqlachemy的子句构造将运算符优先考虑在内,因此可能不需要括号,例如,在类似这样的表达式中 x OR (y AND z)
-优先于或。
底座 self_group()
方法 ClauseElement
只需返回自我。
sqlalchemy.sql.functions.FunctionElement.
table_valued(*expr, **kw)¶返回一个 TableValuedAlias
表示这一点 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_ORDERNITY”::来生成WITH CONTERNITY表达式:
>>> 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
。
1.4.0b2 新版功能.
参见
表值函数 - in the SQLAlchemy 1.4/2.0教程
表值函数 -在 《PostgreSQL》 文档
FunctionElement.scalar_table_valued()
-的变体 FunctionElement.table_valued()
它将完整的表值表达式作为标量列表达式提供
FunctionElement.column_valued()
TableValuedAlias.render_derived()
- renders the alias
using a derived column clause, e.g. AS name(col1, col2, ...)
sqlalchemy.sql.functions.FunctionElement.
within_group(*order_by)¶针对此函数生成一个组内(order by expr)子句。
用于所谓的“有序集聚合”和“假设集聚合”函数,包括 percentile_cont
, rank
, dense_rank
等。
见 within_group()
完整描述。
1.1 新版功能.
参见
集团内特殊修改器,过滤 - in the SQLAlchemy 1.4/2.0教程
sqlalchemy.sql.functions.FunctionElement.
within_group_type(within_group)¶对于根据内部组(order by)表达式中的条件定义其返回类型的类型,由 WithinGroup
构造。
默认情况下返回none,在这种情况下,函数是正常的 .type
使用。
定义“generic”函数。
一般函数是预先建立的 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
print(select(func.as_utc()))
通过在定义时指定“package”属性,可以将用户定义的通用函数组织到包中。 GenericFunction
. 包含许多函数的第三方库可能希望使用此函数,以避免与其他系统发生名称冲突。例如,如果我们的 as_utc()
函数是包“time”的一部分:
class as_utc(GenericFunction):
type = DateTime
package = "time"
上述功能可从 func
使用包名称 time
::
print(select(func.time.as_utc()))
最后一个选项是允许从 func
但以不同的名称呈现。这个 identifier
属性将重写用于访问从加载的函数的名称 func
,但将保留 name
作为呈现的名称:
class GeoBuffer(GenericFunction):
type = Geometry
package = "geo"
name = "ST_Buffer"
identifier = "buffer"
上面的函数将呈现如下:
>>> 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"
上述函数将呈现为:
>>> print(func.geo.buffer())
"ST_Buffer"()
1.3.13 新版功能: 这个 quoted_name
当与对象的“name”属性一起使用时,构造函数现在被识别为引用,因此可以对函数名强制启用或禁用引号。
定义一个函数,其中返回类型基于传递给的表达式所定义的排序表达式类型 FunctionElement.within_group()
方法。
sqlalchemy.sql.functions.OrderedSetAgg.
within_group_type(within_group)¶对于根据内部组(order by)表达式中的条件定义其返回类型的类型,由 WithinGroup
构造。
默认情况下返回none,在这种情况下,函数是正常的 .type
使用。
定义返回类型与其参数相同的函数。
类签名
class sqlalchemy.sql.functions.ScalarFunctionColumn
(sqlalchemy.sql.expression.NamedColumn
)
对ARRAY_AGG函数的支持。
这个 func.array_agg(expr)
构造返回类型为的表达式 ARRAY
.
例如。::
stmt = select(func.array_agg(table.c.values)[2:5])
1.1 新版功能.
参见
array_agg()
-返回的PostgreSQL特定版本 ARRAY
,添加了PG特定的运算符。
sqlalchemy.sql.functions.array_agg.
type¶alias of sqlalchemy.sql.sqltypes.ARRAY
CHAR_LENGTH()SQL函数。
sqlalchemy.sql.functions.char_length.
type¶alias of sqlalchemy.sql.sqltypes.Integer
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
sqlalchemy.sql.functions.concat.
type¶alias of sqlalchemy.sql.sqltypes.String
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
sqlalchemy.sql.functions.count.
type¶alias of sqlalchemy.sql.sqltypes.Integer
实施 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 新版功能.
实施 cume_dist
假设集聚合函数。
此函数必须与 FunctionElement.within_group()
提供要对其执行操作的排序表达式的修饰符。
此函数的返回类型为 Numeric
.
1.1 新版功能.
CURRENT_DATE()SQL函数。
sqlalchemy.sql.functions.current_date.
type¶alias of sqlalchemy.sql.sqltypes.Date
CURRENT_TIME()SQL函数。
sqlalchemy.sql.functions.current_time.
type¶alias of sqlalchemy.sql.sqltypes.Time
CURRENT_TIMESTAMP()SQL函数。
sqlalchemy.sql.functions.current_timestamp.
type¶alias of sqlalchemy.sql.sqltypes.DateTime
CURRENT_USER()SQL函数。
sqlalchemy.sql.functions.current_user.
type¶alias of sqlalchemy.sql.sqltypes.String
实施 dense_rank
假设集聚合函数。
此函数必须与 FunctionElement.within_group()
提供要对其执行操作的排序表达式的修饰符。
此函数的返回类型为 Integer
.
1.1 新版功能.
实施 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 新版功能.
localtime()SQL函数。
sqlalchemy.sql.functions.localtime.
type¶alias of sqlalchemy.sql.sqltypes.DateTime
localtimeamp()SQL函数。
sqlalchemy.sql.functions.localtimestamp.
type¶alias of sqlalchemy.sql.sqltypes.DateTime
SQL Max()聚合函数。
SQL min()聚合函数。
实施 mode
有序集聚合函数。
此函数必须与 FunctionElement.within_group()
提供要对其执行操作的排序表达式的修饰符。
此函数的返回类型与排序表达式相同。
1.1 新版功能.
表示“下一个值”,给定 Sequence
作为它的唯一论据。
编译到每个后端上的相应函数中,或者如果在不支持序列的后端上使用,将引发NotImplementederRor。
sqlalchemy.sql.functions.next_value.
compare(other, **kw)¶比较一下 ClauseElement
到给定的 ClauseElement
.
子类应该覆盖默认行为,这是一个直接的身份比较。
* *kw是子类消耗的参数 compare()
方法和可用于修改比较标准(请参见 ColumnElement
)
SQL NOW()DATETIME函数。
SQLAlChemy方言通常会以特定于后端的方式呈现此特定函数,例如将其呈现为 CURRENT_TIMESTAMP
。
sqlalchemy.sql.functions.now.
type¶alias of sqlalchemy.sql.sqltypes.DateTime
实施 percent_rank
假设集聚合函数。
此函数必须与 FunctionElement.within_group()
提供要对其执行操作的排序表达式的修饰符。
此函数的返回类型为 Numeric
.
1.1 新版功能.
实施 percentile_cont
有序集聚合函数。
此函数必须与 FunctionElement.within_group()
提供要对其执行操作的排序表达式的修饰符。
此函数的返回类型与排序表达式相同,或者如果参数是数组,则返回 ARRAY
排序表达式的类型。
1.1 新版功能.
实施 percentile_disc
有序集聚合函数。
此函数必须与 FunctionElement.within_group()
提供要对其执行操作的排序表达式的修饰符。
此函数的返回类型与排序表达式相同,或者如果参数是数组,则返回 ARRAY
排序表达式的类型。
1.1 新版功能.
RANDOM()SQL函数。
实施 rank
假设集聚合函数。
此函数必须与 FunctionElement.within_group()
提供要对其执行操作的排序表达式的修饰符。
此函数的返回类型为 Integer
.
1.1 新版功能.
将可调用项与特定的func关联。姓名。
这通常由u genericmeta调用,但本身也可用,以便非函数构造可以与 func
存取器(即铸造、提取)。
实施 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 新版功能.
SESSION_USER()SQL函数。
sqlalchemy.sql.functions.session_user.
type¶alias of sqlalchemy.sql.sqltypes.String
SQL SUM()聚合函数。
SYSDATE()SQL函数。
sqlalchemy.sql.functions.sysdate.
type¶alias of sqlalchemy.sql.sqltypes.DateTime
USER()SQL函数。
sqlalchemy.sql.functions.user.
type¶alias of sqlalchemy.sql.sqltypes.String
flambé! the dragon and The Alchemist image designs created and generously donated by Rotem Yaari.
Created using Sphinx 4.2.0.