SQL和通用函数¶

对于特定于数据库的呈现、返回类型和参数行为,SQLAlchemy已知的SQL函数。与所有SQL函数一样,使用 func 属性:

select([func.count()]).select_from(sometable)

注意任何不知道的名字 func 按原样生成函数名-对于可以调用的、SQLAlchemy已知的或未知的、内置的或用户定义的SQL函数没有限制。这里的部分只描述那些SQLAlchemy已经知道使用了什么参数和返回类型的函数。

SQL函数API、工厂和内置函数。

class sqlalchemy.sql.functions.AnsiFunction(*args, **kwargs)

基地: sqlalchemy.sql.functions.GenericFunction

identifier = 'AnsiFunction'
name = 'AnsiFunction'
class sqlalchemy.sql.functions.Function(name, *clauses, **kw)

基地: sqlalchemy.sql.functions.FunctionElement

描述一个命名的SQL函数。

看超类 FunctionElement 对于公共方法的描述。

参见

func -生成已注册或临时的命名空间 Function 实例。

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

__init__(name, *clauses, **kw)

构建一个 Function .

这个 func 构造通常用于构造新的 Function 实例。

class sqlalchemy.sql.functions.FunctionAsBinary(fn, left_index, right_index)

基地: sqlalchemy.sql.expression.BinaryExpression

left
right
class sqlalchemy.sql.functions.FunctionElement(*clauses, **kwargs)

基地: sqlalchemy.sql.expression.Executablesqlalchemy.sql.expression.ColumnElementsqlalchemy.sql.expression.FromClause

面向SQL函数构造的基础。

参见

Function -命名的SQL函数。

func -生成已注册或临时的命名空间 Function 实例。

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

__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函数(如几何函数)来创建连接条件。

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

  • right_index -- 函数参数的基于1的整数索引,用作表达式的“右侧”。

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() 方法 ConnectionEngine .

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() 方法 ConnectionEngine .

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_contrankdense_rank 等。

within_group() 完整描述。

1.1 新版功能.

within_group_type(within_group)

对于根据内部组(order by)表达式中的条件定义其返回类型的类型,由 WithinGroup 构造。

默认情况下返回none,在这种情况下,函数是正常的 .type 使用。

class 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'
class 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 使用。

class sqlalchemy.sql.functions.ReturnTypeFromArgs(*args, **kwargs)

基地: sqlalchemy.sql.functions.GenericFunction

定义返回类型与其参数相同的函数。

identifier = 'ReturnTypeFromArgs'
name = 'ReturnTypeFromArgs'
class 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 的别名

class sqlalchemy.sql.functions.char_length(arg, **kwargs)

基地: sqlalchemy.sql.functions.GenericFunction

identifier = 'char_length'
name = 'char_length'
type

sqlalchemy.sql.sqltypes.Integer 的别名

class sqlalchemy.sql.functions.coalesce(*args, **kwargs)

基地: sqlalchemy.sql.functions.ReturnTypeFromArgs

identifier = 'coalesce'
name = 'coalesce'
class sqlalchemy.sql.functions.concat(*args, **kwargs)

基地: sqlalchemy.sql.functions.GenericFunction

identifier = 'concat'
name = 'concat'
type

sqlalchemy.sql.sqltypes.String 的别名

class 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 的别名

class 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'
class 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()
class sqlalchemy.sql.functions.current_date(*args, **kwargs)

基地: sqlalchemy.sql.functions.AnsiFunction

identifier = 'current_date'
name = 'current_date'
type

sqlalchemy.sql.sqltypes.Date 的别名

class sqlalchemy.sql.functions.current_time(*args, **kwargs)

基地: sqlalchemy.sql.functions.AnsiFunction

identifier = 'current_time'
name = 'current_time'
type

sqlalchemy.sql.sqltypes.Time 的别名

class sqlalchemy.sql.functions.current_timestamp(*args, **kwargs)

基地: sqlalchemy.sql.functions.AnsiFunction

identifier = 'current_timestamp'
name = 'current_timestamp'
type

sqlalchemy.sql.sqltypes.DateTime 的别名

class sqlalchemy.sql.functions.current_user(*args, **kwargs)

基地: sqlalchemy.sql.functions.AnsiFunction

identifier = 'current_user'
name = 'current_user'
type

sqlalchemy.sql.sqltypes.String 的别名

class 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()
class 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'
class sqlalchemy.sql.functions.localtime(*args, **kwargs)

基地: sqlalchemy.sql.functions.AnsiFunction

identifier = 'localtime'
name = 'localtime'
type

sqlalchemy.sql.sqltypes.DateTime 的别名

class sqlalchemy.sql.functions.localtimestamp(*args, **kwargs)

基地: sqlalchemy.sql.functions.AnsiFunction

identifier = 'localtimestamp'
name = 'localtimestamp'
type

sqlalchemy.sql.sqltypes.DateTime 的别名

class sqlalchemy.sql.functions.max(*args, **kwargs)

基地: sqlalchemy.sql.functions.ReturnTypeFromArgs

identifier = 'max'
name = 'max'
class sqlalchemy.sql.functions.min(*args, **kwargs)

基地: sqlalchemy.sql.functions.ReturnTypeFromArgs

identifier = 'min'
name = 'min'
class sqlalchemy.sql.functions.mode(*args, **kwargs)

基地: sqlalchemy.sql.functions.OrderedSetAgg

实施 mode 有序集聚合函数。

此函数必须与 FunctionElement.within_group() 提供要对其执行操作的排序表达式的修饰符。

此函数的返回类型与排序表达式相同。

1.1 新版功能.

identifier = 'mode'
name = 'mode'
class sqlalchemy.sql.functions.next_value(seq, **kw)

基地: sqlalchemy.sql.functions.GenericFunction

表示“下一个值”,给定 Sequence 作为它的唯一论据。

编译到每个后端上的相应函数中,或者如果在不支持序列的后端上使用,将引发NotImplementederRor。

identifier = 'next_value'
name = 'next_value'
type = Integer()
class sqlalchemy.sql.functions.now(*args, **kwargs)

基地: sqlalchemy.sql.functions.GenericFunction

identifier = 'now'
name = 'now'
type

sqlalchemy.sql.sqltypes.DateTime 的别名

class 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()
class 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'
class 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'
class sqlalchemy.sql.functions.random(*args, **kwargs)

基地: sqlalchemy.sql.functions.GenericFunction

identifier = 'random'
name = 'random'
class 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 存取器(即铸造、提取)。

class 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'
class sqlalchemy.sql.functions.session_user(*args, **kwargs)

基地: sqlalchemy.sql.functions.AnsiFunction

identifier = 'session_user'
name = 'session_user'
type

sqlalchemy.sql.sqltypes.String 的别名

class sqlalchemy.sql.functions.sum(*args, **kwargs)

基地: sqlalchemy.sql.functions.ReturnTypeFromArgs

identifier = 'sum'
name = 'sum'
class sqlalchemy.sql.functions.sysdate(*args, **kwargs)

基地: sqlalchemy.sql.functions.AnsiFunction

identifier = 'sysdate'
name = 'sysdate'
type

sqlalchemy.sql.sqltypes.DateTime 的别名

class sqlalchemy.sql.functions.user(*args, **kwargs)

基地: sqlalchemy.sql.functions.AnsiFunction

identifier = 'user'
name = 'user'
type

sqlalchemy.sql.sqltypes.String 的别名