对于特定于数据库的呈现、返回类型和参数行为,SQLAlchemy已知的SQL函数。与所有SQL函数一样,使用 func
属性:
select([func.count()]).select_from(sometable)
注意任何不知道的名字 func
按原样生成函数名-对于可以调用的、SQLAlchemy已知的或未知的、内置的或用户定义的SQL函数没有限制。这里的部分只描述那些SQLAlchemy已经知道使用了什么参数和返回类型的函数。
SQL函数API、工厂和内置函数。
sqlalchemy.sql.functions.
AnsiFunction
(*args, **kwargs)¶基地: sqlalchemy.sql.functions.GenericFunction
identifier
= 'AnsiFunction'¶name
= 'AnsiFunction'¶sqlalchemy.sql.functions.
Function
(name, *clauses, **kw)¶基地: sqlalchemy.sql.functions.FunctionElement
描述一个命名的SQL函数。
看超类 FunctionElement
对于公共方法的描述。
sqlalchemy.sql.functions.
FunctionAsBinary
(fn, left_index, right_index)¶基地: sqlalchemy.sql.expression.BinaryExpression
left
¶right
¶sqlalchemy.sql.functions.
FunctionElement
(*clauses, **kwargs)¶基地: sqlalchemy.sql.expression.Executable
, sqlalchemy.sql.expression.ColumnElement
, sqlalchemy.sql.expression.FromClause
面向SQL函数构造的基础。
__init__
(*clauses, **kwargs)¶构建一个 FunctionElement
.
alias
(name=None, flat=False)¶产生一个 Alias
在此基础上构建 FunctionElement
.
此构造将函数包装在一个命名别名中,该别名适用于FROM子句,其样式为PostgreSQL所接受的样式。
例如。::
from sqlalchemy.sql import column
stmt = select([column('data_view')]).\
select_from(SomeTable).\
select_from(func.unnest(SomeTable.data).alias('data_view')
)
会产生:
SELECT data_view
FROM sometable, unnest(sometable.data) AS data_view
0.9.8 新版功能: 这个 FunctionElement.alias()
现在支持方法。以前,此方法的行为是未定义的,并且在不同版本之间的行为不一致。
as_comparison
(left_index, right_index)¶将此表达式解释为两个值之间的布尔比较。
假设的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 新版功能.
clauses
¶返回基础 ClauseList
它包含这个的参数 FunctionElement
.
columns
¶由此导出的列集 FunctionElement
.
函数对象当前没有内置结果列名称;此方法返回具有匿名命名列的单个元素列集合。
为函数提供命名列作为FROM子句的临时方法是 select()
使用所需列:
from sqlalchemy.sql import column
stmt = select([column('x'), column('y')]). select_from(func.myfunction())
execute
()¶执行此 FunctionElement
针对嵌入的“bind”。
这是第一个调用 select()
生成选择构造。
注意 FunctionElement
可以传递给 Connectable.execute()
方法 Connection
或 Engine
.
filter
(*criterion)¶针对此函数生成筛选子句。
用于聚合函数和窗口函数,用于支持“filter”子句的数据库后端。
表达式:
func.count(1).filter(True)
缩写为:
from sqlalchemy import funcfilter
funcfilter(func.count(1), True)
1.0.0 新版功能.
get_children
(**kwargs)¶返回此的直接子元素 ClauseElement
.
用于访问遍历。
* *Kwargs可能包含更改返回的集合的标志,例如返回项的子集以减少更大的遍历,或从不同上下文返回子项(例如架构级集合而不是子句级)。
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()
完整描述。
packagenames
= ()¶scalar
()¶执行此 FunctionElement
并返回一个标量值。
这是第一个调用 select()
生成选择构造。
注意 FunctionElement
可以传递给 Connectable.scalar()
方法 Connection
或 Engine
.
select
()¶产生一个 select()
在此基础上构建 FunctionElement
.
以下简称:
s = select([function_element])
self_group
(against=None)¶对此应用“分组” ClauseElement
.
此方法被子类重写以返回“grouping”构造,即括号。尤其是“binary”表达式使用它在放入更大的表达式时提供围绕其自身的分组,以及 select()
当放入另一个的FROM子句时构造 select()
. (请注意,通常应使用 Select.alias()
方法,因为许多平台都需要命名嵌套的select语句)。
当表达式组合在一起时,应用 self_group()
是自动的-最终用户代码不需要直接使用这个方法。请注意,sqlachemy的子句构造将运算符优先考虑在内,因此可能不需要括号,例如,在类似这样的表达式中 x OR (y AND z)
-优先于或。
底座 self_group()
方法 ClauseElement
只需返回自我。
within_group
(*order_by)¶针对此函数生成一个组内(order by expr)子句。
用于所谓的“有序集聚合”和“假设集聚合”函数,包括 percentile_cont
, rank
, dense_rank
等。
见 within_group()
完整描述。
1.1 新版功能.
within_group_type
(within_group)¶对于根据内部组(order by)表达式中的条件定义其返回类型的类型,由 WithinGroup
构造。
默认情况下返回none,在这种情况下,函数是正常的 .type
使用。
sqlalchemy.sql.functions.
GenericFunction
(*args, **kwargs)¶基地: sqlalchemy.sql.functions.Function
定义“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()
coerce_arguments
= True¶identifier
= 'GenericFunction'¶name
= 'GenericFunction'¶sqlalchemy.sql.functions.
OrderedSetAgg
(*args, **kwargs)¶基地: sqlalchemy.sql.functions.GenericFunction
定义一个函数,其中返回类型基于传递给的表达式所定义的排序表达式类型 FunctionElement.within_group()
方法。
array_for_multi_clause
= False¶identifier
= 'OrderedSetAgg'¶name
= 'OrderedSetAgg'¶within_group_type
(within_group)¶对于根据内部组(order by)表达式中的条件定义其返回类型的类型,由 WithinGroup
构造。
默认情况下返回none,在这种情况下,函数是正常的 .type
使用。
sqlalchemy.sql.functions.
ReturnTypeFromArgs
(*args, **kwargs)¶基地: sqlalchemy.sql.functions.GenericFunction
定义返回类型与其参数相同的函数。
identifier
= 'ReturnTypeFromArgs'¶name
= 'ReturnTypeFromArgs'¶sqlalchemy.sql.functions.
array_agg
(*args, **kwargs)¶基地: sqlalchemy.sql.functions.GenericFunction
支持array_agg函数。
这个 func.array_agg(expr)
构造返回类型为的表达式 types.ARRAY
.
例如。::
stmt = select([func.array_agg(table.c.values)[2:5]])
1.1 新版功能.
参见
postgresql.array_agg()
-返回的PostgreSQL特定版本 postgresql.ARRAY
,添加了PG特定的运算符。
identifier
= 'array_agg'¶name
= 'array_agg'¶type
¶sqlalchemy.sql.sqltypes.ARRAY
的别名
sqlalchemy.sql.functions.
char_length
(arg, **kwargs)¶基地: sqlalchemy.sql.functions.GenericFunction
identifier
= 'char_length'¶name
= 'char_length'¶type
¶sqlalchemy.sql.sqltypes.Integer
的别名
sqlalchemy.sql.functions.
coalesce
(*args, **kwargs)¶基地: sqlalchemy.sql.functions.ReturnTypeFromArgs
identifier
= 'coalesce'¶name
= 'coalesce'¶sqlalchemy.sql.functions.
concat
(*args, **kwargs)¶基地: sqlalchemy.sql.functions.GenericFunction
identifier
= 'concat'¶name
= 'concat'¶type
¶sqlalchemy.sql.sqltypes.String
的别名
sqlalchemy.sql.functions.
count
(expression=None, **kwargs)¶基地: sqlalchemy.sql.functions.GenericFunction
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
identifier
= 'count'¶name
= 'count'¶type
¶sqlalchemy.sql.sqltypes.Integer
的别名
sqlalchemy.sql.functions.
cube
(*args, **kwargs)¶基地: sqlalchemy.sql.functions.GenericFunction
实施 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 新版功能.
identifier
= 'cube'¶name
= 'cube'¶sqlalchemy.sql.functions.
cume_dist
(*args, **kwargs)¶基地: sqlalchemy.sql.functions.GenericFunction
实施 cume_dist
假设集聚合函数。
此函数必须与 FunctionElement.within_group()
提供要对其执行操作的排序表达式的修饰符。
此函数的返回类型为 Numeric
.
1.1 新版功能.
identifier
= 'cume_dist'¶name
= 'cume_dist'¶type
= Numeric()¶sqlalchemy.sql.functions.
current_date
(*args, **kwargs)¶基地: sqlalchemy.sql.functions.AnsiFunction
identifier
= 'current_date'¶name
= 'current_date'¶type
¶sqlalchemy.sql.sqltypes.Date
的别名
sqlalchemy.sql.functions.
current_time
(*args, **kwargs)¶基地: sqlalchemy.sql.functions.AnsiFunction
identifier
= 'current_time'¶name
= 'current_time'¶type
¶sqlalchemy.sql.sqltypes.Time
的别名
sqlalchemy.sql.functions.
current_timestamp
(*args, **kwargs)¶基地: sqlalchemy.sql.functions.AnsiFunction
identifier
= 'current_timestamp'¶name
= 'current_timestamp'¶type
¶sqlalchemy.sql.sqltypes.DateTime
的别名
sqlalchemy.sql.functions.
current_user
(*args, **kwargs)¶基地: sqlalchemy.sql.functions.AnsiFunction
identifier
= 'current_user'¶name
= 'current_user'¶type
¶sqlalchemy.sql.sqltypes.String
的别名
sqlalchemy.sql.functions.
dense_rank
(*args, **kwargs)¶基地: sqlalchemy.sql.functions.GenericFunction
实施 dense_rank
假设集聚合函数。
此函数必须与 FunctionElement.within_group()
提供要对其执行操作的排序表达式的修饰符。
此函数的返回类型为 Integer
.
1.1 新版功能.
identifier
= 'dense_rank'¶name
= 'dense_rank'¶type
= Integer()¶sqlalchemy.sql.functions.
grouping_sets
(*args, **kwargs)¶基地: sqlalchemy.sql.functions.GenericFunction
实施 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 新版功能.
identifier
= 'grouping_sets'¶name
= 'grouping_sets'¶sqlalchemy.sql.functions.
localtime
(*args, **kwargs)¶基地: sqlalchemy.sql.functions.AnsiFunction
identifier
= 'localtime'¶name
= 'localtime'¶type
¶sqlalchemy.sql.sqltypes.DateTime
的别名
sqlalchemy.sql.functions.
localtimestamp
(*args, **kwargs)¶基地: sqlalchemy.sql.functions.AnsiFunction
identifier
= 'localtimestamp'¶name
= 'localtimestamp'¶type
¶sqlalchemy.sql.sqltypes.DateTime
的别名
sqlalchemy.sql.functions.
max
(*args, **kwargs)¶基地: sqlalchemy.sql.functions.ReturnTypeFromArgs
identifier
= 'max'¶name
= 'max'¶sqlalchemy.sql.functions.
min
(*args, **kwargs)¶基地: sqlalchemy.sql.functions.ReturnTypeFromArgs
identifier
= 'min'¶name
= 'min'¶sqlalchemy.sql.functions.
mode
(*args, **kwargs)¶基地: sqlalchemy.sql.functions.OrderedSetAgg
实施 mode
有序集聚合函数。
此函数必须与 FunctionElement.within_group()
提供要对其执行操作的排序表达式的修饰符。
此函数的返回类型与排序表达式相同。
1.1 新版功能.
identifier
= 'mode'¶name
= 'mode'¶sqlalchemy.sql.functions.
next_value
(seq, **kw)¶基地: sqlalchemy.sql.functions.GenericFunction
表示“下一个值”,给定 Sequence
作为它的唯一论据。
编译到每个后端上的相应函数中,或者如果在不支持序列的后端上使用,将引发NotImplementederRor。
identifier
= 'next_value'¶name
= 'next_value'¶type
= Integer()¶sqlalchemy.sql.functions.
now
(*args, **kwargs)¶基地: sqlalchemy.sql.functions.GenericFunction
identifier
= 'now'¶name
= 'now'¶type
¶sqlalchemy.sql.sqltypes.DateTime
的别名
sqlalchemy.sql.functions.
percent_rank
(*args, **kwargs)¶基地: sqlalchemy.sql.functions.GenericFunction
实施 percent_rank
假设集聚合函数。
此函数必须与 FunctionElement.within_group()
提供要对其执行操作的排序表达式的修饰符。
此函数的返回类型为 Numeric
.
1.1 新版功能.
identifier
= 'percent_rank'¶name
= 'percent_rank'¶type
= Numeric()¶sqlalchemy.sql.functions.
percentile_cont
(*args, **kwargs)¶基地: sqlalchemy.sql.functions.OrderedSetAgg
实施 percentile_cont
有序集聚合函数。
此函数必须与 FunctionElement.within_group()
提供要对其执行操作的排序表达式的修饰符。
此函数的返回类型与排序表达式相同,或者如果参数是数组,则返回 types.ARRAY
排序表达式的类型。
1.1 新版功能.
array_for_multi_clause
= True¶identifier
= 'percentile_cont'¶name
= 'percentile_cont'¶sqlalchemy.sql.functions.
percentile_disc
(*args, **kwargs)¶基地: sqlalchemy.sql.functions.OrderedSetAgg
实施 percentile_disc
有序集聚合函数。
此函数必须与 FunctionElement.within_group()
提供要对其执行操作的排序表达式的修饰符。
此函数的返回类型与排序表达式相同,或者如果参数是数组,则返回 types.ARRAY
排序表达式的类型。
1.1 新版功能.
array_for_multi_clause
= True¶identifier
= 'percentile_disc'¶name
= 'percentile_disc'¶sqlalchemy.sql.functions.
random
(*args, **kwargs)¶基地: sqlalchemy.sql.functions.GenericFunction
identifier
= 'random'¶name
= 'random'¶sqlalchemy.sql.functions.
rank
(*args, **kwargs)¶基地: sqlalchemy.sql.functions.GenericFunction
实施 rank
假设集聚合函数。
此函数必须与 FunctionElement.within_group()
提供要对其执行操作的排序表达式的修饰符。
此函数的返回类型为 Integer
.
1.1 新版功能.
identifier
= 'rank'¶name
= 'rank'¶type
= Integer()¶sqlalchemy.sql.functions.
register_function
(identifier, fn, package='_default')¶将可调用项与特定的func关联。姓名。
这通常由u genericmeta调用,但本身也可用,以便非函数构造可以与 func
存取器(即铸造、提取)。
sqlalchemy.sql.functions.
rollup
(*args, **kwargs)¶基地: sqlalchemy.sql.functions.GenericFunction
实施 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 新版功能.
identifier
= 'rollup'¶name
= 'rollup'¶sqlalchemy.sql.functions.
session_user
(*args, **kwargs)¶基地: sqlalchemy.sql.functions.AnsiFunction
identifier
= 'session_user'¶name
= 'session_user'¶type
¶sqlalchemy.sql.sqltypes.String
的别名
sqlalchemy.sql.functions.
sum
(*args, **kwargs)¶基地: sqlalchemy.sql.functions.ReturnTypeFromArgs
identifier
= 'sum'¶name
= 'sum'¶sqlalchemy.sql.functions.
sysdate
(*args, **kwargs)¶基地: sqlalchemy.sql.functions.AnsiFunction
identifier
= 'sysdate'¶name
= 'sysdate'¶type
¶sqlalchemy.sql.sqltypes.DateTime
的别名
sqlalchemy.sql.functions.
user
(*args, **kwargs)¶基地: sqlalchemy.sql.functions.AnsiFunction
identifier
= 'user'¶name
= 'user'¶type
¶sqlalchemy.sql.sqltypes.String
的别名