列元素基础构造函数¶

从中导入的独立函数 sqlalchemy 在构建SQLAlchemy表达式语言构造时使用的命名空间。

function sqlalchemy.sql.expression.and_(*clauses)¶

生成由以下对象连接的表达式的连接 AND .

例如。：：

from sqlalchemy import and_

stmt = select(users_table).where(
                and_(
                    users_table.c.name == 'wendy',
                    users_table.c.enrolled == True
                )
            )

这个 and_() 也可以使用python & 运算符（不过请注意，复合表达式需要加括号才能使用python运算符优先行为运行）：：

stmt = select(users_table).where(
                (users_table.c.name == 'wendy') &
                (users_table.c.enrolled == True)
            )

这个 and_() 操作在某些情况下也是隐式的；在 Select.where() 例如，可以对一个语句多次调用方法，该语句将具有每个子句组合的效果，使用 and_() ：：

stmt = select(users_table).\
        where(users_table.c.name == 'wendy').\
        where(users_table.c.enrolled == True)

这个 and_() 构造必须至少有一个位置参数才能有效；a and_() 没有参数的构造是不明确的。产生“空”或动态生成 and_() 表达式，从给定的表达式列表中 True 应指定：

criteria = and_(True, *expressions)

上面的表达式将编译为SQL作为表达式 true 或 1 = 1 ，如果不存在其他表达式，则取决于后端。如果表达式存在，则 True 值被忽略，因为它不影响包含其他元素的AND表达式的结果。

1.4 版后已移除: 这个 and_() 元素现在要求至少传递一个参数；创建 and_() 不推荐使用不带参数的构造，并且将在继续生成空SQL字符串的同时发出不推荐使用的警告。

参见

or_()

function sqlalchemy.sql.expression.bindparam(key, value=symbol('NO_ARG'), type_=None, unique=False, required=symbol('NO_ARG'), quote=None, callable_=None, expanding=False, isoutparam=False, literal_execute=False, _compared_to_operator=None, _compared_to_type=None, _is_crud=False)¶

生成“绑定表达式”。

返回值是的实例 BindParameter 这是一个 ColumnElement 表示SQL表达式中所谓的“占位符”值的子类，该值在语句针对数据库连接执行时提供。

在SQL炼金术中， bindparam() construct能够携带最终在表达式时使用的实际值。这样，它不仅作为最终填充的“占位符”，而且作为表示所谓“不安全”值的方法，这些值不应直接在SQL语句中呈现，而是应传递给 DBAPI 作为需要正确转义并可能为类型安全处理的值。

使用时 bindparam() 明确地说，用例通常是传统的参数延迟之一； bindparam() 构造接受可在执行时引用的名称：：

from sqlalchemy import bindparam

stmt = select(users_table).\
            where(users_table.c.name == bindparam('username'))

上述语句在呈现时将生成类似以下内容的SQL：

SELECT id, name FROM user WHERE name = :username

为了填充 :username 上面，该值通常在执行时应用于 Connection.execute() ：：

result = connection.execute(stmt, username='wendy')

明确使用 bindparam() 在生成要多次调用的UPDATE或DELETE语句时也是常见的，其中语句的WHERE条件在每次调用时都要更改，例如：

stmt = (users_table.update().
        where(user_table.c.name == bindparam('username')).
        values(fullname=bindparam('fullname'))
        )

connection.execute(
    stmt, [{"username": "wendy", "fullname": "Wendy Smith"},
           {"username": "jack", "fullname": "Jack Jones"},
           ]
)

SQLAlchemy的核心表达式系统广泛使用 bindparam() 在一个隐含的意义上。通常，传递给几乎所有SQL表达式函数的python文本值都被强制为fixed bindparam() 构造。例如，给定一个比较操作，例如：

expr = users_table.c.name == 'Wendy'

上面的表达式将生成 BinaryExpression 在左侧为 Column 表示的对象 name 立柱，右侧为 BindParameter 表示文字值：

print(repr(expr.right))
BindParameter('%(4327771088 name)s', 'Wendy', type_=String())

上面的表达式将呈现SQL，例如：

user.name = :name_1

何处 :name_1 参数名是匿名名称。实际字符串 Wendy 不在呈现的字符串中，而是在以后语句执行中使用该字符串的位置进行。如果我们调用如下语句：

stmt = select(users_table).where(users_table.c.name == 'Wendy')
result = connection.execute(stmt)

我们将看到SQL日志记录输出为：

SELECT "user".id, "user".name
FROM "user"
WHERE "user".name = %(name_1)s
{'name_1': 'Wendy'}

上面，我们看到了 Wendy 作为参数传递到数据库，而占位符 :name_1 以目标数据库的适当形式呈现，在本例中是PostgreSQL数据库。

同样地， bindparam() 使用时自动调用 CRUD 关于“价值”部分的陈述。这个 insert() 构造生成 INSERT 表达式，它将在语句执行时根据传递的参数生成绑定的占位符，如：

stmt = users_table.insert()
result = connection.execute(stmt, name='Wendy')

上面将生成SQL输出，如下所示：

INSERT INTO "user" (name) VALUES (%(name)s)
{'name': 'Wendy'}

这个 Insert 在编译/执行时，构造 bindparam() 镜像列名 name 因为单身 name 我们传递给 Connection.execute() 方法。

参数

• key¶ -- 此绑定参数的键（例如名称）。将在生成的SQL语句中用于使用命名参数的方言。如果编译操作是编译操作的一部分，则可以修改此值 BindParameter 对象具有相同的键，或者其长度太长，需要截断。

• value¶ -- 此绑定参数的初始值。将在语句执行时用作传递给DBAPI的该参数的值，如果没有为该特定参数名的语句执行方法指示其他值。默认为 None .

• callable_¶ -- 代替“value”的可调用函数。函数将在语句执行时调用以确定最终值。用于在创建子句构造时无法确定实际绑定值，但仍需要嵌入绑定值的情况。

• type_¶ -- A TypeEngine 表示此的可选数据类型的类或实例 bindparam() . 如果没有传递，则可以根据给定的值自动确定绑定的类型；例如，简单的python类型，如 str ， int ， bool 可能导致 String ， Integer 或 Boolean 正在自动选择类型。A的类型 bindparam() 特别重要的是，类型将在传递给数据库之前对值应用预处理。例如，A bindparam() 它引用日期时间值，并指定为保存 DateTime 类型，可以在将值传递到数据库之前将所需的转换应用于该值（如sqlite上的字符串化）。

• unique¶ -- 如果为真，则为 BindParameter 如果另一个 BindParameter 已在包含表达式中找到相同名称的。当生成所谓的“匿名”绑定表达式时，内部通常使用此标志，它一般不适用于显式命名的 bindparam() 构造。

• required¶ -- 如果 True ，执行时需要一个值。如果未通过，则默认为 True 如果既不 bindparam.value 或 bindparam.callable 通过了。如果这些参数中有一个存在，那么 bindparam.required 默认为 False .

• quote¶ -- 如果此参数名需要引用，并且当前不被称为sqlAlchemy保留字，则为true；此参数名当前仅适用于Oracle后端，其中绑定名有时必须被引用。

• isoutparam¶ -- 如果为true，则应将参数视为存储过程“out”参数。这适用于后端，如支持out参数的Oracle。

• expanding¶ --

  如果为真，则该参数在执行时将被视为“展开”参数；参数值应为序列，而不是标量值；字符串SQL语句将按执行进行转换，以适应传递给DBAPI的参数槽数可变的序列。这是为了允许语句缓存与IN子句一起使用。

  参见

  ColumnOperators.in_()

  在表达式中使用 -使用烘焙查询

  注解

  “Expanding”功能不支持“ExecuteMany”样式的参数集。

  1.2 新版功能.

  在 1.3 版更改: “扩展”绑定参数功能现在支持空列表。

参见

绑定参数对象

插入表达式

outparam()

参数

literal_execute¶ -- 如果为True，则绑定参数将在编译阶段使用特殊的“后编译”标记呈现，SQLAlchemy编译器将在语句执行时将参数的最终值呈现到SQL语句中，忽略传递给DBAPI的参数字典/列表中的值 cursor.execute() . 这将产生与使用 literal_binds ，编译标志，但在语句发送到DBAPI时发生 cursor.execute() 方法，而不是在编译语句时。此功能的主要用途是为数据库驱动程序呈现LIMIT/OFFSET子句，这些驱动程序无法适应这些上下文中的绑定参数，同时允许SQL构造在编译级别可缓存。。versionadded:：1.4添加了“后编译”绑定参数。。另请参见： 新的“后编译”绑定参数用于Oracle、SQL Server中的限制/偏移 .

function sqlalchemy.sql.expression.case(*whens, **kw)¶

产生一个 CASE 表达式。

这个 CASE SQL中的构造是一个条件对象，其行为与其他语言中的“if/then”构造有些类似。它返回的实例 Case .

case() 通常的形式是传递一系列“When”构造，即条件和结果的元组列表：

from sqlalchemy import case

stmt = select(users_table).\
            where(
                case(
                    (users_table.c.name == 'wendy', 'W'),
                    (users_table.c.name == 'jack', 'J'),
                    else_='E'
                )
            )

上面的语句将生成类似以下内容的SQL：

SELECT id, name FROM user
WHERE CASE
    WHEN (name = :name_1) THEN :param_1
    WHEN (name = :name_2) THEN :param_2
    ELSE :param_3
END

当需要对单个父列使用多个值的简单相等表达式时， case() 还具有通过 case.value 参数，传递一个要比较的列表达式。在这种形式下， case.whens 参数作为字典传递，该字典包含要与键入结果表达式进行比较的表达式。下面的语句等价于前面的语句：

stmt = select(users_table).\
            where(
                case(
                    {"wendy": "W", "jack": "J"},
                    value=users_table.c.name,
                    else_='E'
                )
            )

作为结果接受的值 case.whens 以及与 case.else_ 从python文本强制到 bindparam() 构造。SQL表达式，例如 ColumnElement 也接受构造。若要将文本字符串表达式强制为内联呈现的常量表达式，请使用 literal_column() 构造，如：

from sqlalchemy import case, literal_column

case(
    (
        orderline.c.qty > 100,
        literal_column("'greaterthan100'")
    ),
    (
        orderline.c.qty > 10,
        literal_column("'greaterthan10'")
    ),
    else_=literal_column("'lessthan10'")
)

上面将呈现给定的常量，而不使用结果值的绑定参数（但仍用于比较值），如：

CASE
    WHEN (orderline.qty > :qty_1) THEN 'greaterthan100'
    WHEN (orderline.qty > :qty_2) THEN 'greaterthan10'
    ELSE 'lessthan10'
END

参数

• *whens¶ -- 要比较的标准， case.whens 根据是否接受两种不同的形式 case.value 被使用。。版本更改：：1.4 case() 函数现在以位置方式接受WHEN条件系列；不推荐在列表中传递表达式。在第一种形式中，它接受2元组的列表；每个2元组由 (<sql expression>, <value>) ，其中SQL表达式是布尔表达式，“value”是结果值，例如：case（（users_table.c.name=='wendy'，'W'），（users_table.c.name=='jack'，'J'））在第二个表单中，它接受映射到结果值的比较值的Python字典；此表单需要 case.value 并将使用 == 运算符，例如：：case（“wendy”：“w”，“jack”：“j”，value=users_table.c.name）

• value¶ -- 一个可选的SQL表达式，将用作传递给的字典中候选值的固定“比较点”。 case.whens .

• else_¶ -- 可选的SQL表达式，它将是 CASE 如果所有表达式都在 case.whens 评估为假。当省略时，如果“when”表达式中没有一个计算结果为true，则大多数数据库都将生成空结果。

function sqlalchemy.sql.expression.cast(expression, type_)¶

产生一个 CAST 表达式。

cast() 返回的实例 Cast .

例如。：：

from sqlalchemy import cast, Numeric

stmt = select(cast(product_table.c.unit_price, Numeric(10, 4)))

上面的语句将生成类似以下内容的SQL：

SELECT CAST(unit_price AS NUMERIC(10, 4)) FROM product

这个 cast() 函数在使用时执行两个不同的函数。首先，它将 CAST 结果SQL字符串中的表达式。第二个问题是，它将给定类型（例如 TypeEngine 类或实例），这意味着表达式将采用与该类型关联的表达式运算符行为，以及该类型的绑定值处理和结果行处理行为。

在 0.9.0 版更改: cast() 现在，将给定的类型应用于表达式，使其对绑定值（例如，python to database方向）生效，此外，还有结果处理（例如，database to python方向）。

替代 cast() 是 type_coerce() 功能。此函数执行将表达式与特定类型关联的第二个任务，但不呈现 CAST SQL中的表达式。

参数

• expression¶ -- SQL表达式，如 ColumnElement 表达式或python字符串，它将被强制为绑定的文本值。

• type_¶ -- A TypeEngine 类或实例，指示 CAST 应适用。

参见

数据强制转换和类型强制

type_coerce() -强制类型转换的另一种方法是只在Python端强制类型，这通常足以生成正确的SQL和数据强制。

function sqlalchemy.sql.expression.column(text, type_=None, is_literal=False, _selectable=None)¶

产生一个 ColumnClause 对象。

这个 ColumnClause 是一个轻量级的模拟 Column 班级。这个 column() 只能使用名称调用函数，如：

from sqlalchemy import column

id, name = column("id"), column("name")
stmt = select(id, name).select_from("user")

上面的语句将生成类似SQL的：

SELECT id, name FROM user

一旦建成， column() 可以像任何其他SQL表达式元素一样使用，例如 select() 结构：

from sqlalchemy.sql import column

id, name = column("id"), column("name")
stmt = select(id, name).select_from("user")

文本由处理 column() 假定处理方式与数据库列的名称类似；如果字符串包含混合大小写、特殊字符或与目标后端上已知的保留字匹配，则列表达式将使用后端确定的引用行为进行呈现。要生成一个文本SQL表达式，该表达式完全没有任何引用，请使用 literal_column() 相反，或通过 True 作为价值 column.is_literal . 此外，最好使用 text() 构造。

column() 通过将其与 table() 功能（轻量级模拟 Table ）使用最小样板生成工作台结构：

from sqlalchemy import table, column, select

user = table("user",
        column("id"),
        column("name"),
        column("description"),
)

stmt = select(user.c.description).where(user.c.name == 'wendy')

A column() / table() 像上面描述的那样的构造可以以一种特别的方式创建，并且不与任何 MetaData ，ddl或事件，与 Table 对应的。

在 1.0.0 版更改: column() 现在可以从平原进口了 sqlalchemy 与任何其他SQL元素一样。

参数

• text¶ -- 元素的文本。

• type¶ -- TypeEngine 可以关联此的对象 ColumnClause 一种类型。

• is_literal¶ -- 如果是真的， ColumnClause 假定为将传递到输出的精确表达式，不应用任何区分大小写设置的引用规则。这个 literal_column() 函数本质上调用 column() 通过时 is_literal=True .

参见

Column

literal_column()

table()

text()

使用更具体的文本 table() ， _expression.literal_column() 和 _expression.column()

class sqlalchemy.sql.expression.custom_op(opstring, precedence=0, is_comparison=False, return_type=None, natural_self_precedent=False, eager_grouping=False)¶

表示“自定义”运算符。

custom_op 通常在 Operators.op() 或 Operators.bool_op() 方法用于创建可调用的自定义运算符。当以编程方式构造表达式时，也可以直接使用类。例如，表示“阶乘”运算：

from sqlalchemy.sql import UnaryExpression
from sqlalchemy.sql import operators
from sqlalchemy import Numeric

unary = UnaryExpression(table.c.somecolumn,
        modifier=operators.custom_op("!"),
        type_=Numeric)

参见

Operators.op()

Operators.bool_op()

function sqlalchemy.sql.expression.distinct(expr)¶

生成列表达式级别一元 DISTINCT 条款。

这适用于 DISTINCT 关键字到单个列表达式，通常包含在聚合函数中，如：：

from sqlalchemy import distinct, func
stmt = select(func.count(distinct(users_table.c.name)))

上面的表达式类似于：

SELECT COUNT(DISTINCT name) FROM user

这个 distinct() 函数也可用作列级方法，例如 ColumnElement.distinct() ，如：

stmt = select(func.count(users_table.c.name.distinct()))

这个 distinct() 操作员不同于 Select.distinct() 方法 Select ，它产生一个 SELECT 语句与 DISTINCT 应用于整个结果集，例如 SELECT DISTINCT 表达式。有关更多信息，请参阅该方法。

参见

ColumnElement.distinct()

Select.distinct()

func

function sqlalchemy.sql.expression.extract(field, expr, **kwargs)¶

返回A Extract 构造。

这通常可用作 extract() 以及 func.extract 从 func 命名空间。

参数

• field¶ -- 要提取的字段。

• expr¶ -- 用作右侧的列或Python标量表达式 EXTRACT 表达式。

例如。：：

from sqlalchemy import extract
from sqlalchemy import table, column

logged_table = table("user",
        column("id"),
        column("date_created"),
)

stmt = select(logged_table.c.id).where(
    extract("YEAR", logged_table.c.date_created) == 2021
)

在上面的示例中，语句用于从数据库中选择ID，其中 YEAR 组件与特定值匹配。

同样，用户也可以选择提取的零部件：：

stmt = select(
    extract("YEAR", logged_table.c.date_created)
).where(logged_table.c.id == 1)

该计划的实施 EXTRACT 可能因数据库后端而异。提醒用户查阅他们的数据库文档。

function sqlalchemy.sql.expression.false()¶

返回A False_ 构造。

例如。：：

>>> from sqlalchemy import false
>>> print(select(t.c.x).where(false()))
SELECT x FROM t WHERE false

不支持真/假常量的后端将呈现为针对1或0的表达式：：

>>> print(select(t.c.x).where(false()))
SELECT x FROM t WHERE 0 = 1

这个 true() 和 false() 常量还具有在 and_() 或 or_() 连词：

>>> print(select(t.c.x).where(or_(t.c.x > 5, true())))
SELECT x FROM t WHERE true

>>> print(select(t.c.x).where(and_(t.c.x > 5, false())))
SELECT x FROM t WHERE false

在 0.9 版更改: true() 和 false() 在连词和不支持真/假常量的方言中具有更好的整合行为。

参见

true()

sqlalchemy.sql.expression.func = <sqlalchemy.sql.functions._FunctionGenerator object>¶

生成SQL函数表达式。

func 是一个特殊的对象实例，它基于基于名称的属性生成SQL函数，例如：

>>> print(func.count(1))
count(:param_1)

返回的对象是 Function ，和其他元素一样是面向列的SQL元素，使用方式如下：

>>> print(select(func.count(table.c.id)))
SELECT count(sometable.id) FROM sometable

任何名字都可以给 func . 如果函数名对于SQLAlchemy是未知的，那么它将按原样呈现。对于SQLAlchemy知道的常见SQL函数，名称可以解释为 通用函数 将适当地编译到目标数据库：

>>> print(func.current_timestamp())
CURRENT_TIMESTAMP

要调用以点分隔的包中存在的函数，请以相同的方式指定它们：

>>> print(func.stats.yield_curve(5, 10))
stats.yield_curve(:yield_curve_1, :yield_curve_2)

SQLAlchemy可以知道函数的返回类型，以支持特定于类型的词法和基于结果的行为。例如，要确保基于字符串的函数返回Unicode值并在表达式中类似地被视为字符串，请指定 Unicode 作为类型：

>>> print(func.my_string(u'hi', type_=Unicode) + ' ' +
...       func.my_string(u'there', type_=Unicode))
my_string(:my_string_1) || :my_string_2 || my_string(:my_string_3)

返回的对象 func 调用通常是 Function . 此对象满足“列”接口，包括比较和标记函数。对象也可以传递给 Connectable.execute() A方法 Connection 或 Engine ，其中它将首先包装在SELECT语句中：

print(connection.execute(func.current_timestamp()).scalar())

在少数例外情况下 func 访问器会将名称重定向到内置表达式，例如 cast() 或 extract() ，因为这些名称具有众所周知的含义，但从SQLAlchemy的角度来看，它们与“函数”并不完全相同。

被解释为“泛型”函数的函数知道如何自动计算它们的返回类型。有关已知泛型函数的列表，请参阅 SQL和通用函数 .

注解

这个 func construct对调用独立的“存储过程”的支持有限，尤其是那些有特殊参数化问题的存储过程。

见剖面图 调用存储过程和用户定义函数 有关如何使用DBAPI级别的详细信息 callproc() 完全传统存储过程的方法。

参见

功能 -在核心教程中

Function

function sqlalchemy.sql.expression.lambda_stmt(lmb, enable_tracking=True, track_closure_variables=True, track_on=None, global_track_bound_values=True, track_bound_values=True, lambda_cache=None)¶

生成缓存为lambda的SQL语句。

将扫描lambda中的Python代码对象，以查找将成为绑定参数的Python文本，以及引用可能变化的核心或ORM构造的闭包变量。对于检测到的每个特定的构造集，lambda本身将只被调用一次。

例如。：：

from sqlalchemy import lambda_stmt

stmt = lambda_stmt(lambda: table.select())
stmt += lambda s: s.where(table.c.id == 5)

result = connection.execute(stmt)

返回的对象是的实例 StatementLambdaElement .

1.4 新版功能.

参数

• lmb¶ -- 一个Python函数，通常是lambda，它不接受参数并返回SQL表达式结构

• enable_tracking¶ -- 如果为false，则禁用给定lambda的所有闭包变量或绑定参数更改扫描。用于在没有参数化的情况下在所有情况下产生相同结果的lambda。

• track_closure_variables¶ -- 如果为false，则不会扫描lambda内的闭包变量的更改。用于lambda，其中其闭包变量的状态永远不会更改lambda返回的SQL结构。

• track_bound_values¶ -- 如果为false，则将禁用给定lambda的绑定参数跟踪。用于不生成任何绑定值或初始绑定值从不更改的lambda。

• global_track_bound_values¶ -- 为false时，将对整个语句禁用绑定参数跟踪，包括通过 StatementLambdaElement.add_criteria() 方法。

• lambda_cache¶ -- 字典或其他类似映射的对象，其中将存储有关lambda的Python代码以及lambda本身中跟踪的闭包变量的信息。默认为全局LRU缓存。此缓存独立于 Connection 对象。

参见

使用Lambdas为语句生成添加显著的速度增益

function sqlalchemy.sql.expression.literal(value, type_=None)¶

返回绑定到绑定参数的literal子句。

当非- ClauseElement 对象（如字符串、int、日期等）用于与 ColumnElement 子类，例如 Column 对象。使用此函数强制生成文本子句，该子句将创建为 BindParameter 具有绑定值。

参数

• value¶ -- 要绑定的值。可以是底层db-api支持的任何python对象，也可以通过给定的类型参数进行转换。

• type_¶ -- 可选的 TypeEngine 它将为此文本提供绑定参数转换。

function sqlalchemy.sql.expression.literal_column(text, type_=None)¶

产生一个 ColumnClause 对象具有 column.is_literal 标志设置为真。

literal_column() 类似于 column() ，但它更常被用作“独立”列表达式，该表达式完全按照说明呈现；而 column() 存储一个字符串名称，该名称将被假定为表的一部分，并可以这样引用， literal_column() 可以是该表达式，也可以是任何其他面向列的任意表达式。

参数

• text¶ -- 表达式的文本；可以是任何SQL表达式。不适用报价规则。要指定应遵循引用规则的列名表达式，请使用 column() 功能。

• type_¶ -- 可选的 TypeEngine 对象，该对象将为此列提供结果集转换和其他表达式语义。如果留下来 None 类型将是 NullType .

参见

column()

text()

使用更具体的文本 table() ， _expression.literal_column() 和 _expression.column()

function sqlalchemy.sql.expression.not_(clause)¶

返回给定子句的否定，即 NOT(clause) .

这个 ~ 操作员也在所有 ColumnElement 子类产生相同的结果。

function sqlalchemy.sql.expression.null()¶

返回常量 Null 构造。

function sqlalchemy.sql.expression.or_(*clauses)¶

生成由以下对象连接的表达式的连接 OR .

例如。：：

from sqlalchemy import or_

stmt = select(users_table).where(
                or_(
                    users_table.c.name == 'wendy',
                    users_table.c.name == 'jack'
                )
            )

这个 or_() 也可以使用python | 运算符（不过请注意，复合表达式需要加括号才能使用python运算符优先行为运行）：：

stmt = select(users_table).where(
                (users_table.c.name == 'wendy') |
                (users_table.c.name == 'jack')
            )

这个 or_() 构造必须至少有一个位置参数才能有效；a or_() 没有参数的构造是不明确的。产生“空”或动态生成 or_() 表达式，从给定的表达式列表中 False 应指定：

or_criteria = or_(False, *expressions)

上面的表达式将编译为SQL作为表达式 false 或 0 = 1 ，如果不存在其他表达式，则取决于后端。如果表达式存在，则 False 值被忽略，因为它不影响包含其他元素的OR表达式的结果。

1.4 版后已移除: 这个 or_() 元素现在要求至少传递一个参数；创建 or_() 不推荐使用不带参数的构造，并且将在继续生成空SQL字符串的同时发出不推荐使用的警告。

参见

and_()

function sqlalchemy.sql.expression.outparam(key, type_=None)¶

为支持函数（存储过程）的数据库创建用于函数（存储过程）的“out”参数。

这个 outparam 可用作常规函数参数。“输出”值可从 CursorResult 对象通过其 out_parameters 属性，返回包含值的字典。

function sqlalchemy.sql.expression.text(text, bind=None)¶

构建新的 TextClause 子句，直接表示文本SQL字符串。

例如。：：

from sqlalchemy import text

t = text("SELECT * FROM users")
result = connection.execute(t)

优势 text() 在普通字符串上提供对绑定参数、每语句执行选项以及绑定参数和结果列类型行为的后端中性支持，允许在执行逐字指定的语句时，sqlAlchemy类型构造发挥作用。构造还可以提供 .c 列元素的集合，允许它作为子查询嵌入到其他SQL表达式构造中。

绑定参数由名称指定，格式为 :name . 例如。：：

t = text("SELECT * FROM users WHERE id=:user_id")
result = connection.execute(t, user_id=12)

对于需要逐字冒号的SQL语句（如在内联字符串中），请使用反斜杠转义：：

t = text("SELECT * FROM users WHERE name='\:username'")

这个 TextClause construct包含一些方法，这些方法可以提供有关绑定参数的信息，以及假设它是可执行的select类型语句，则从文本语句返回的列值。这个 TextClause.bindparams() 方法用于提供绑定参数详细信息，以及 TextClause.columns() 方法允许指定返回列，包括名称和类型：

t = text("SELECT * FROM users WHERE id=:user_id").\
        bindparams(user_id=7).\
        columns(id=Integer, name=String)

for id, name in connection.execute(t):
    print(id, name)

这个 text() 构造用于将文本字符串SQL片段指定为较大查询的一部分时，例如对于select语句的where子句：

s = select(users.c.id, users.c.name).where(text("id=:user_id"))
result = connection.execute(s, user_id=12)

text() 也用于使用纯文本构造完整、独立的语句。因此，sqlAlchemy将其称为 Executable 对象，它支持 Executable.execution_options() 方法。例如，A text() 应服从“autocommit”的构造可以显式设置，以便使用 Connection.execution_options.autocommit 选项：

t = text("EXEC my_procedural_thing()").\
        execution_options(autocommit=True)

1.4 版后已移除: “autocommit”执行选项已弃用，将在SQLAlchemy 2.0中删除。看到了吗 库级（但不是驱动程序级）“自动提交”从核心和ORM中删除 供讨论。

参数

• text¶ -- 要创建的SQL语句的文本。使用 :<param> 指定绑定参数；它们将被编译为特定于引擎的格式。…警告：： text.text 参数 text() 可以作为python字符串参数传递，该参数将被视为 可信SQL文本 并按规定呈现。 不要将不受信任的输入传递给此参数 .

• bind¶ -- 用于此文本查询的可选连接或引擎。。已弃用：：1.4 text.bind 参数已弃用，将在SQLAlchemy 2.0中删除。

参见

使用文本SQL -在核心教程中

function sqlalchemy.sql.expression.true()¶

返回常量 True_ 构造。

例如。：：

>>> from sqlalchemy import true
>>> print(select(t.c.x).where(true()))
SELECT x FROM t WHERE true

不支持真/假常量的后端将呈现为针对1或0的表达式：：

>>> print(select(t.c.x).where(true()))
SELECT x FROM t WHERE 1 = 1

这个 true() 和 false() 常量还具有在 and_() 或 or_() 连词：

>>> print(select(t.c.x).where(or_(t.c.x > 5, true())))
SELECT x FROM t WHERE true

>>> print(select(t.c.x).where(and_(t.c.x > 5, false())))
SELECT x FROM t WHERE false

在 0.9 版更改: true() 和 false() 在连词和不支持真/假常量的方言中具有更好的整合行为。

参见

false()

function sqlalchemy.sql.expression.tuple_(*clauses, **kw)¶

返回A Tuple .

主要用途是使用 ColumnOperators.in_() ：：

from sqlalchemy import tuple_

tuple_(table.c.col1, table.c.col2).in_(
    [(1, 2), (5, 12), (10, 19)]
)

在 1.3.6 版更改: 增加了对元组中SQLite的支持。

警告

并非所有后端都支持composite-IN构造，目前已知它可以用于PostgreSQL、MySQL和SQLite。不受支持的后端将引发 DBAPIError 当调用这样的表达式时。

function sqlalchemy.sql.expression.type_coerce(expression, type_)¶

将SQL表达式与特定类型关联，而不呈现 CAST .

例如。：：

from sqlalchemy import type_coerce

stmt = select(type_coerce(log_table.date_string, StringDateTime()))

上述结构将产生 TypeCoerce 对象，它不会在SQL端以任何方式修改呈现，但如果在columns子句上下文中使用，则可能会出现生成标签的异常：

SELECT date_string AS date_string FROM log

当提取结果行时， StringDateTime 类型处理器将代表 date_string 列。

注解

这个 type_coerce() construct不呈现它自己的任何SQL语法，包括它不包含括号。请使用 TypeCoerce.self_group() 如果需要显式括号。

要为表达式提供命名标签，请使用 ColumnElement.label() ：：

stmt = select(
    type_coerce(log_table.date_string, StringDateTime()).label('date')
)

具有绑定值处理功能的类型在文本值或 bindparam() 结构传递给 type_coerce() 作为目标。例如，如果类型实现 TypeEngine.bind_expression() 方法或 TypeEngine.bind_processor() 方法或等效方法，当传递文本值时，这些函数将在语句编译/执行时生效，如：：

# bound-value handling of MyStringType will be applied to the
# literal value "some string"
stmt = select(type_coerce("some string", MyStringType))

使用时 type_coerce() 对于合成表达式，请注意 括号不适用 . 如果 type_coerce() 正在运算符上下文中使用，其中通常需要从CAST中出现括号，请使用 TypeCoerce.self_group() 方法：

>>> some_integer = column("someint", Integer)
>>> some_string = column("somestr", String)
>>> expr = type_coerce(some_integer + 5, String) + some_string
>>> print(expr)
someint + :someint_1 || somestr
>>> expr = type_coerce(some_integer + 5, String).self_group() + some_string
>>> print(expr)
(someint + :someint_1) || somestr

参数

• expression¶ -- SQL表达式，如 ColumnElement 表达式或python字符串，它将被强制为绑定的文本值。

• type_¶ -- A TypeEngine 指示强制表达式的类型的类或实例。

参见

数据强制转换和类型强制

cast()

class sqlalchemy.sql.expression.quoted_name(value, quote)¶

表示结合引用首选项的SQL标识符。

quoted_name 是一个python unicode/str子类，它表示一个特定的标识符名称以及 quote 旗帜。这个 quote 标志，设置为时 True 或 False ，重写此标识符的自动引用行为，以便无条件地引用或不引用名称。如果不履行 None ，根据对令牌本身的检查，在每个后端的基础上对标识符应用引用行为。

A quoted_name 对象与 quote=True 在所谓的“名称规范化”选项的情况下，还可以防止进行修改。某些数据库后端（如Oracle、Firebird和DB2）将不区分大小写的名称“规范化”为大写。这些后端的sqlAlchemy方言从sqlAlchemy的小写表示不敏感约定转换为大写表示不敏感约定。这个 quote=True 此处的标志将阻止进行此转换以支持引用为此类后端所有小写的标识符。

这个 quoted_name 对象通常在指定键架构构造的名称时自动创建，例如 Table ， Column ，以及其他。该类也可以显式地作为名称传递给任何接收到可引用名称的函数。例如使用 Engine.has_table() 具有无条件引用名称的方法：：

from sqlalchemy import create_engine
from sqlalchemy.sql import quoted_name

engine = create_engine("oracle+cx_oracle://some_dsn")
engine.has_table(quoted_name("some_table", True))

上面的逻辑将针对Oracle后端运行“has table”逻辑，并将名称 "some_table" 不转换为大写。

0.9.0 新版功能.

在 1.2 版更改: 这个 quoted_name 构造现在可从导入 sqlalchemy.sql ，除了之前的位置 sqlalchemy.sql.elements .

类签名

class sqlalchemy.sql.expression.quoted_name (sqlalchemy.util.langhelpers.MemoizedSlots, builtins.str)

attribute sqlalchemy.sql.expression.quoted_name.quote¶

字符串是否应无条件引用

列元素修饰符构造函数¶

这里列出的函数通常作为方法从任何 ColumnElement 例如，构造 label() 函数通常通过 ColumnElement.label() 方法。

function sqlalchemy.sql.expression.all_(expr)¶

生成一个all表达式。

对于PostgreSQL等方言，此运算符适用于 ARRAY 数据类型，对于MySQL，它可以用于子查询。例如：

# renders on PostgreSQL:
# '5 = ALL (somearray)'
expr = 5 == all_(mytable.c.somearray)

# renders on MySQL:
# '5 = ALL (SELECT value FROM table)'
expr = 5 == all_(select(table.c.value))

与NULL的比较可以使用 None ：：

None == all_(mytable.c.somearray)

ANY_()/ALL_()运算符还具有特殊的“操作数翻转”行为，因此如果在使用独立运算符的比较左侧使用ANY_()/ALL_()，例如 == ， != 等(不包括运算符方法，如 ColumnOperators.is_() )将翻转呈现的表达式：：

# would render '5 = ALL (column)`
all_(mytable.c.column) == 5

或与 None ，哪个注释不会像通常的NULL：：那样执行呈现“is”的通常步骤：

# would render 'NULL = ALL(somearray)'
all_(mytable.c.somearray) == None

在 1.4.26 版更改: 修复了将右侧的ANY_()/ALL_()与NULL进行比较以翻转到左侧的用法。

列级 ColumnElement.all_() 方法(不要与 ARRAY 级别 Comparator.all() )是 all_(col) ：：

5 == mytable.c.somearray.all_()

参见

ColumnOperators.all_()

any_()

function sqlalchemy.sql.expression.any_(expr)¶

生成任意表达式。

对于PostgreSQL等方言，此运算符适用于 ARRAY 数据类型，对于MySQL，它可以用于子查询。例如：

# renders on PostgreSQL:
# '5 = ANY (somearray)'
expr = 5 == any_(mytable.c.somearray)

# renders on MySQL:
# '5 = ANY (SELECT value FROM table)'
expr = 5 == any_(select(table.c.value))

与NULL的比较可以使用 None 或 null() ：：

None == any_(mytable.c.somearray)

ANY_()/ALL_()运算符还具有特殊的“操作数翻转”行为，因此如果在使用独立运算符的比较左侧使用ANY_()/ALL_()，例如 == ， != 等(不包括运算符方法，如 ColumnOperators.is_() )将翻转呈现的表达式：：

# would render '5 = ANY (column)`
any_(mytable.c.column) == 5

或与 None ，哪个注释不会像通常的NULL：：那样执行呈现“is”的通常步骤：

# would render 'NULL = ANY(somearray)'
any_(mytable.c.somearray) == None

在 1.4.26 版更改: 修复了将右侧的ANY_()/ALL_()与NULL进行比较以翻转到左侧的用法。

列级 ColumnElement.any_() 方法(不要与 ARRAY 级别 Comparator.any() )是 any_(col) ：：

5 = mytable.c.somearray.any_()

参见

ColumnOperators.any_()

all_()

function sqlalchemy.sql.expression.asc(column)¶

产生一个上升的 ORDER BY 子句元素。

例如。：：

from sqlalchemy import asc
stmt = select(users_table).order_by(asc(users_table.c.name))

将生成以下SQL:：

SELECT id, name FROM user ORDER BY name ASC

这个 asc() 函数是 ColumnElement.asc() 方法可用于所有SQL表达式，例如：

stmt = select(users_table).order_by(users_table.c.name.asc())

参数

column¶ -- A ColumnElement （例如，标量SQL表达式）用于应用 asc() 操作。

参见

desc()

nulls_first()

nulls_last()

Select.order_by()

function sqlalchemy.sql.expression.between(expr, lower_bound, upper_bound, symmetric=False)¶

产生一个 BETWEEN 谓词子句。

例如。：：

from sqlalchemy import between
stmt = select(users_table).where(between(users_table.c.id, 5, 7))

将生成类似以下内容的SQL:

SELECT id, name FROM user WHERE id BETWEEN :id_1 AND :id_2

这个 between() 函数是 ColumnElement.between() 方法可用于所有SQL表达式，如：

stmt = select(users_table).where(users_table.c.id.between(5, 7))

传递给的所有参数 between() 如果值不是 ColumnElement 子类。例如，可以比较三个固定值，如中所示：

print(between(5, 3, 7))

会产生：

:param_1 BETWEEN :param_2 AND :param_3

参数

• expr¶ -- 列表达式，通常是 ColumnElement 实例，或者将python标量表达式强制为列表达式，用作 BETWEEN 表达式。

• lower_bound¶ -- 列或python标量表达式，用作 BETWEEN 表达式。

• upper_bound¶ -- 列或python标量表达式，用作 BETWEEN 表达式。

• symmetric¶ -- 如果为真，将呈现“在对称之间”。请注意，并非所有数据库都支持此语法。…添加的版本：0.9.5

参见

ColumnElement.between()

function sqlalchemy.sql.expression.collate(expression, collation)¶

退回条款 expression COLLATE collation .

例如。：：

collate(mycolumn, 'utf8_bin')

生产：：

mycolumn COLLATE utf8_bin

如果排序规则表达式是区分大小写的标识符，例如包含大写字符，则也会对其进行引用。

在 1.2 版更改: 如果表达式区分大小写，则自动应用引用对其进行排序。

function sqlalchemy.sql.expression.desc(column)¶

生成降序 ORDER BY 子句元素。

例如。：：

from sqlalchemy import desc

stmt = select(users_table).order_by(desc(users_table.c.name))

将生成以下SQL:：

SELECT id, name FROM user ORDER BY name DESC

这个 desc() 函数是 ColumnElement.desc() 方法可用于所有SQL表达式，例如：

stmt = select(users_table).order_by(users_table.c.name.desc())

参数

column¶ -- A ColumnElement （例如，标量SQL表达式）用于应用 desc() 操作。

参见

asc()

nulls_first()

nulls_last()

Select.order_by()

function sqlalchemy.sql.expression.funcfilter(func, *criterion)¶

产生一个 FunctionFilter 对象对函数。

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

例如。：：

from sqlalchemy import funcfilter
funcfilter(func.count(1), MyClass.name == 'some name')

将生成“count（1）filter（其中myclass.name='some name'）”。

此功能也可从 func 通过 FunctionElement.filter() 方法。

1.0.0 新版功能.

参见

集团内特殊修改器，过滤 - in the SQLAlchemy 1.4/2.0教程

FunctionElement.filter()

function sqlalchemy.sql.expression.label(name, element, type_=None)¶

返回A Label 给定对象 ColumnElement .

标签更改了的columns子句中元素的名称。 SELECT 语句，通常通过 AS SQL关键字。

此功能通过 ColumnElement.label() 方法对 ColumnElement .

参数

• name¶ -- 标签名

• obj¶ -- 一 ColumnElement .

function sqlalchemy.sql.expression.nulls_first(column)¶

生产 NULLS FIRST AN的修饰符 ORDER BY 表达式。

nulls_first() 用于修改 asc() 或 desc() ，并指示在排序期间遇到空值时应如何处理它们：：

from sqlalchemy import desc, nulls_first

stmt = select(users_table).order_by(
    nulls_first(desc(users_table.c.name)))

上面的SQL表达式类似于：

SELECT id, name FROM user ORDER BY name DESC NULLS FIRST

喜欢 asc() 和 desc() ， nulls_first() 通常从列表达式本身调用，使用 ColumnElement.nulls_first() 而不是作为它的独立函数版本，如：

stmt = select(users_table).order_by(
    users_table.c.name.desc().nulls_first())

在 1.4 版更改: nulls_first() 重命名自 nullsfirst() 在以前的版本中。以前的名称仍然可以向后兼容。

参见

asc()

desc()

nulls_last()

Select.order_by()

function sqlalchemy.sql.expression.nulls_last(column)¶

生产 NULLS LAST AN的修饰符 ORDER BY 表达式。

nulls_last() 用于修改 asc() 或 desc() ，并指示在排序期间遇到空值时应如何处理它们：：

from sqlalchemy import desc, nulls_last

stmt = select(users_table).order_by(
    nulls_last(desc(users_table.c.name)))

上面的SQL表达式类似于：

SELECT id, name FROM user ORDER BY name DESC NULLS LAST

喜欢 asc() 和 desc() ， nulls_last() 通常从列表达式本身调用，使用 ColumnElement.nulls_last() 而不是作为它的独立函数版本，如：

stmt = select(users_table).order_by(
    users_table.c.name.desc().nulls_last())

在 1.4 版更改: nulls_last() 重命名自 nullslast() 在以前的版本中。以前的名称仍然可以向后兼容。

参见

asc()

desc()

nulls_first()

Select.order_by()

function sqlalchemy.sql.expression.over(element, partition_by=None, order_by=None, range_=None, rows=None)¶

产生一个 Over 对象对函数。

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

over() 通常使用 FunctionElement.over() 方法，例如：

func.row_number().over(order_by=mytable.c.some_column)

将产生：

ROW_NUMBER() OVER(ORDER BY some_column)

也可以使用 over.range_ 和 over.rows 参数。这些互斥参数都接受一个2元组，其中包含整数和无的组合：

func.row_number().over(
    order_by=my_table.c.some_column, range_=(None, 0))

以上内容将产生：

ROW_NUMBER() OVER(ORDER BY some_column
RANGE BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW)

一个值 None 表示“无界”，零值表示“当前行”，正/负整数表示“前”和“后”：

• 前5个和后10个之间的范围：

  func.row_number().over(order_by='x', range_=(-5, 10))

• 前一行和当前行之间无边界的行：：

  func.row_number().over(order_by='x', rows=(None, 0))

• 前两个和后两个之间的范围：：

  func.row_number().over(order_by='x', range_=(-2, None))

• 以下1项到以下3项之间的范围：

  func.row_number().over(order_by='x', range_=(1, 3))

1.1 新版功能: 支持窗口中的范围/行

参数

• element¶ -- 一 FunctionElement ， WithinGroup 或其他兼容结构。

• partition_by¶ -- 一个列元素或字符串，或这样的列表，将用作over构造的partition by子句。

• order_by¶ -- 将用作over构造的order by子句的列元素或字符串或此类元素的列表。

• range_¶ -- 窗口的可选范围子句。这是一个元组值，可以包含整数值或 None ，并将呈现介于前/后子句之间的范围。。版本添加：：1.1

• rows¶ -- 窗口的可选行子句。这是一个tuple值，可以包含整数值，也可以不包含整数值，并且将在前面/后面的子句之间呈现一行。…添加的版本：1.1

此功能也可从 func 通过 FunctionElement.over() 方法。

参见

使用窗口函数 - in the SQLAlchemy 1.4/2.0教程

func

within_group()

function sqlalchemy.sql.expression.within_group(element, *order_by)¶

产生一个 WithinGroup 对象对函数。

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

within_group() 通常使用 FunctionElement.within_group() 方法，例如：

from sqlalchemy import within_group
stmt = select(
    department.c.id,
    func.percentile_cont(0.5).within_group(
        department.c.salary.desc()
    )
)

上面的语句将生成类似于 SELECT department.id, percentile_cont(0.5) WITHIN GROUP (ORDER BY department.salary DESC) .

参数

• element¶ -- 一 FunctionElement 构造，通常由 func .

• *order_by¶ -- 将用作内部组构造的ORDER BY子句的一个或多个列元素。

1.1 新版功能.

参见

集团内特殊修改器，过滤 - in the SQLAlchemy 1.4/2.0教程

func

over()

列元素类文档¶

这里的类是使用中列出的构造函数生成的 列元素基础构造函数 和 列元素修饰符构造函数 .

class sqlalchemy.sql.expression.BinaryExpression(left, right, operator, type_=None, negate=None, modifiers=None)¶

表示一个表达式 LEFT <operator> RIGHT .

A BinaryExpression 每当在python二进制表达式中使用两个列表达式时自动生成：

>>> from sqlalchemy.sql import column
>>> column('a') + column('b')
<sqlalchemy.sql.expression.BinaryExpression object at 0x101029dd0>
>>> print(column('a') + column('b'))
a + b

类签名

class sqlalchemy.sql.expression.BinaryExpression (sqlalchemy.sql.expression.ColumnElement)

method sqlalchemy.sql.expression.BinaryExpression.self_group(against=None)¶

对此应用“分组” ClauseElement .

此方法被子类重写以返回“grouping”构造，即括号。尤其是“binary”表达式使用它在放入更大的表达式时提供围绕其自身的分组，以及 select() 当放入另一个的FROM子句时构造 select() . （请注意，通常应使用 Select.alias() 方法，因为许多平台都需要命名嵌套的select语句）。

当表达式组合在一起时，应用 self_group() 是自动的-最终用户代码不需要直接使用这个方法。请注意，sqlachemy的子句构造将运算符优先考虑在内，因此可能不需要括号，例如，在类似这样的表达式中 x OR (y AND z) -优先于或。

底座 self_group() 方法 ClauseElement 只需返回自我。

class sqlalchemy.sql.expression.BindParameter(key, value=symbol('NO_ARG'), type_=None, unique=False, required=symbol('NO_ARG'), quote=None, callable_=None, expanding=False, isoutparam=False, literal_execute=False, _compared_to_operator=None, _compared_to_type=None, _is_crud=False)¶

表示“绑定表达式”。

BindParameter 是使用 bindparam() 功能，如：

from sqlalchemy import bindparam

stmt = select(users_table).\
            where(users_table.c.name == bindparam('username'))

详细讨论如何 BindParameter 使用的是 bindparam() .

参见

bindparam()

类签名

class sqlalchemy.sql.expression.BindParameter (sqlalchemy.sql.roles.InElementRole, sqlalchemy.sql.expression.ColumnElement)

method sqlalchemy.sql.expression.BindParameter.__init__(key, value=symbol('NO_ARG'), type_=None, unique=False, required=symbol('NO_ARG'), quote=None, callable_=None, expanding=False, isoutparam=False, literal_execute=False, _compared_to_operator=None, _compared_to_type=None, _is_crud=False)¶

构建新的 BindParameter 对象。

此构造函数被镜像为公共API函数；请参见 sqlalchemy.sql.expression.bindparam() 完整的用法和参数描述。

attribute sqlalchemy.sql.expression.BindParameter.effective_value¶

返回此绑定参数的值，并考虑 callable 参数已设置。

这个 callable 值将被评估并返回（如果存在），否则 value .

method sqlalchemy.sql.expression.BindParameter.render_literal_execute()¶

生成此绑定参数的副本，它将启用 BindParameter.literal_execute 旗帜。

这个 BindParameter.literal_execute 标志将具有在编译的SQL字符串中呈现的参数的效果，使用 [POSTCOMPILE] 表单，它是一种特殊的表单，在SQL执行时转换为参数文字值的呈现形式。其基本原理是支持缓存SQL语句字符串，这些字符串可以在传递给DBAPI的最终SQL字符串中嵌入每个语句的文字值，如限制和偏移参数。尤其是方言可能希望在自定义编译方案中使用此方法。

1.4.5 新版功能.

参见

第三方方言的缓存

class sqlalchemy.sql.expression.CacheKey(key, bindparams)¶

类签名

class sqlalchemy.sql.expression.CacheKey (sqlalchemy.sql.traversals.CacheKey)

method sqlalchemy.sql.expression.CacheKey.to_offline_string(statement_cache, statement, parameters)¶

生成一个“脱机字符串”形式 CacheKey

“offline string”基本上是语句的字符串SQL加上绑定参数值的repr。鉴于 CacheKey 对象依赖于内存中的标识以便用作缓存键，“脱机”版本适用于也将用于其他进程的缓存。

给定的 statement_cache 是一个类似字典的对象，语句本身的字符串形式将被缓存。这个字典应该在一个较长的生存期内，以减少字符串化语句所花费的时间。

class sqlalchemy.sql.expression.Case(*whens, **kw)¶

代表一个 CASE 表达式。

Case 是使用 case() 工厂功能，如：

from sqlalchemy import case

stmt = select(users_table).                    where(
                case(
                    (users_table.c.name == 'wendy', 'W'),
                    (users_table.c.name == 'jack', 'J'),
                    else_='E'
                )
            )

细节 Case 用法是 case() .

参见

case()

类签名

class sqlalchemy.sql.expression.Case (sqlalchemy.sql.expression.ColumnElement)

method sqlalchemy.sql.expression.Case.__init__(*whens, **kw)¶

构建新的 Case 对象。

此构造函数被镜像为公共API函数；请参见 sqlalchemy.sql.expression.case() 完整的用法和参数描述。

class sqlalchemy.sql.expression.Cast(expression, type_)¶

代表一个 CAST 表达式。

Cast 是使用 cast() 工厂功能，如：

from sqlalchemy import cast, Numeric

stmt = select(cast(product_table.c.unit_price, Numeric(10, 4)))

细节 Cast 用法是 cast() .

参见

数据强制转换和类型强制

cast()

type_coerce() -强制类型转换的另一种方法是只在Python端强制类型，这通常足以生成正确的SQL和数据强制。

类签名

class sqlalchemy.sql.expression.Cast (sqlalchemy.sql.expression.WrapsColumnExpression, sqlalchemy.sql.expression.ColumnElement)

method sqlalchemy.sql.expression.Cast.__init__(expression, type_)¶

构建新的 Cast 对象。

此构造函数被镜像为公共API函数；请参见 sqlalchemy.sql.expression.cast() 完整的用法和参数描述。

class sqlalchemy.sql.expression.ClauseElement¶

以编程方式构造的SQL表达式的元素的基类。

类签名

class sqlalchemy.sql.expression.ClauseElement (sqlalchemy.sql.roles.SQLRole, sqlalchemy.sql.annotation.SupportsWrappingAnnotations, sqlalchemy.sql.traversals.MemoizedHasCacheKey, sqlalchemy.sql.traversals.HasCopyInternals, sqlalchemy.sql.visitors.Traversible)

method sqlalchemy.sql.expression.ClauseElement.compare(other, **kw)¶

比较一下 ClauseElement 到给定的 ClauseElement .

子类应该覆盖默认行为，这是一个直接的身份比较。

* *kw是子类消耗的参数 compare() 方法和可用于修改比较标准（请参见 ColumnElement ）

method sqlalchemy.sql.expression.ClauseElement.compile(bind=None, dialect=None, **kw)¶

编译此SQL表达式。

返回值为 Compiled 对象。打电话 str() 或 unicode() 返回的值将生成结果的字符串表示形式。这个 Compiled 对象还可以返回绑定参数名称和值的字典，方法是 params 访问器。

参数

• bind¶ -- 安 Engine 或 Connection 从哪一个 Compiled 将被收购。此参数优先于此 ClauseElement 如果有绑定的引擎。

• column_keys¶ -- 用于insert和update语句，列名称的列表，应出现在编译语句的values子句中。如果 None ，将呈现目标表对象中的所有列。

• dialect¶ -- A Dialect 实例，其中 Compiled 将被收购。此参数优先于 bind argument as well as this :class:`_ 子句元素表达式`如果有的话。

• compile_kwargs¶ -- 附加参数的可选字典，这些参数将在所有“访问”方法中传递给编译器。例如，这允许将任何自定义标志传递给自定义编译构造。它还用于传递 literal_binds 标志通过：FROM sqlalChemy.sql导入表，列，SELECT t=TABLE(‘t’，COLUMN(‘x’))s=SELECT(T).WHERE(t.c.x==5)print(s.compile(compile_kwargs={“literal_binds”：True}))..添加的版本：：0.9.0

参见

如何将SQL表达式呈现为字符串（可能是内联绑定参数）？

method sqlalchemy.sql.expression.ClauseElement.get_children(omit_attrs=(), **kw)¶

inherited from the Traversible.get_children() method of Traversible

返回直接子项 Traversible 其中的要素 Traversible .

用于访问遍历。

* *kw可能包含更改返回的集合的标志，例如返回一个子集以减少较大的遍历，或者从不同的上下文返回子项（例如模式级集合而不是子句级集合）。

class memoized_attribute(fget, doc=None)¶

只读@属性，只计算一次。

method sqlalchemy.sql.expression.ClauseElement.classmethod memoized_instancemethod(fn)¶

inherited from the HasMemoized.memoized_instancemethod() method of HasMemoized

装饰一个方法记下它的返回值。

method sqlalchemy.sql.expression.ClauseElement.params(*optionaldict, **kwargs)¶

返回副本 bindparam() 元素被替换。

返回此条款的副本 bindparam() 用给定字典中的值替换的元素：：

>>> clause = column('x') + bindparam('foo')
>>> print(clause.compile().params)
{'foo':None}
>>> print(clause.params({'foo':7}).compile().params)
{'foo':7}

method sqlalchemy.sql.expression.ClauseElement.self_group(against=None)¶

对此应用“分组” ClauseElement .

此方法被子类重写以返回“grouping”构造，即括号。尤其是“binary”表达式使用它在放入更大的表达式时提供围绕其自身的分组，以及 select() 当放入另一个的FROM子句时构造 select() . （请注意，通常应使用 Select.alias() 方法，因为许多平台都需要命名嵌套的select语句）。

当表达式组合在一起时，应用 self_group() 是自动的-最终用户代码不需要直接使用这个方法。请注意，sqlachemy的子句构造将运算符优先考虑在内，因此可能不需要括号，例如，在类似这样的表达式中 x OR (y AND z) -优先于或。

底座 self_group() 方法 ClauseElement 只需返回自我。

method sqlalchemy.sql.expression.ClauseElement.unique_params(*optionaldict, **kwargs)¶

返回副本 bindparam() 元素被替换。

功能与 ClauseElement.params() ，除了添加 unique=True 以影响绑定参数，以便可以使用多个语句。

class sqlalchemy.sql.expression.ClauseList(*clauses, **kwargs)¶

描述由运算符分隔的子句列表。

默认情况下，是逗号分隔的，例如列列表。

类签名

class sqlalchemy.sql.expression.ClauseList (sqlalchemy.sql.roles.InElementRole, sqlalchemy.sql.roles.OrderByRole, sqlalchemy.sql.roles.ColumnsClauseRole, sqlalchemy.sql.roles.DMLColumnRole, sqlalchemy.sql.expression.ClauseElement)

method sqlalchemy.sql.expression.ClauseList.self_group(against=None)¶

对此应用“分组” ClauseElement .

此方法被子类重写以返回“grouping”构造，即括号。尤其是“binary”表达式使用它在放入更大的表达式时提供围绕其自身的分组，以及 select() 当放入另一个的FROM子句时构造 select() . （请注意，通常应使用 Select.alias() 方法，因为许多平台都需要命名嵌套的select语句）。

当表达式组合在一起时，应用 self_group() 是自动的-最终用户代码不需要直接使用这个方法。请注意，sqlachemy的子句构造将运算符优先考虑在内，因此可能不需要括号，例如，在类似这样的表达式中 x OR (y AND z) -优先于或。

底座 self_group() 方法 ClauseElement 只需返回自我。

class sqlalchemy.sql.expression.ColumnClause(text, type_=None, is_literal=False, _selectable=None)¶

表示任何文本字符串中的列表达式。

这个 ColumnClause 一个轻量级的模拟 Column 类，通常使用 column() 功能，如：

from sqlalchemy import column

id, name = column("id"), column("name")
stmt = select(id, name).select_from("user")

上面的语句将生成类似SQL的：

SELECT id, name FROM user

ColumnClause 是模式特定的直接超类 Column 对象。而 Column 类具有与 ColumnClause , the ColumnClause 在行为需求仅限于简单的SQL表达式生成的情况下，类本身是可用的。对象没有与架构级元数据或执行时间行为的关联 Column 是的，所以在这个意义上是 Column .

详情 ColumnClause 用法是 column() .

参见

column()

Column

类签名

class sqlalchemy.sql.expression.ColumnClause (sqlalchemy.sql.roles.DDLReferredColumnRole, sqlalchemy.sql.roles.LabeledColumnExprRole, sqlalchemy.sql.roles.StrAsPlainColumnRole, sqlalchemy.sql.expression.Immutable, sqlalchemy.sql.expression.NamedColumn)

method sqlalchemy.sql.expression.ColumnClause.__init__(text, type_=None, is_literal=False, _selectable=None)¶

构建新的 ColumnClause 对象。

此构造函数被镜像为公共API函数；请参见 sqlalchemy.sql.expression.column() 完整的用法和参数描述。

method sqlalchemy.sql.expression.ColumnClause.get_children(column_tables=False, **kw)¶

返回直接子项 Traversible 其中的要素 Traversible .

用于访问遍历。

* *kw可能包含更改返回的集合的标志，例如返回一个子集以减少较大的遍历，或者从不同的上下文返回子项（例如模式级集合而不是子句级集合）。

class sqlalchemy.sql.expression.ColumnCollection(columns=None)¶

集合 ColumnElement 实例，通常用于 FromClause 对象。

这个 ColumnCollection 对象最常见的可用形式是 Table.c 或 Table.columns 上的集合 Table 对象，在 访问表和列 。

这个 ColumnCollection 具有类似映射和类似序列的行为。一个 ColumnCollection 通常在商店里 Column 对象，然后可以通过映射样式访问和属性访问样式访问这些对象。

要访问 Column 使用普通属性样式访问的对象，可以像指定任何其他对象属性一样指定名称，例如在名为 employee_name 已访问：

>>> employee_table.c.employee_name

要访问名称包含特殊字符或空格的列，可以使用索引式访问，如下所示说明了名为的列 employee ' payment 已访问：

>>> employee_table.c["employee ' payment"]

作为 ColumnCollection 对象提供了Python字典接口，常见的字典方法名称如下 ColumnCollection.keys() ， ColumnCollection.values() ，以及 ColumnCollection.items() 都是可用的，这意味着以这些名称为关键字的数据库列也需要使用索引访问：：

>>> employee_table.c["values"]

对象为其指定的名称 Column 将会出现的通常是 Column.key 参数。在某些上下文中，例如 Select 属性使用标签样式集的 Select.set_label_style() 方法时，某个键的列可以改用特定的标签名表示，例如 tablename_columnname ：：

>>> from sqlalchemy import select, column, table
>>> from sqlalchemy import LABEL_STYLE_TABLENAME_PLUS_COL
>>> t = table("t", column("c"))
>>> stmt = select(t).set_label_style(LABEL_STYLE_TABLENAME_PLUS_COL)
>>> subq = stmt.subquery()
>>> subq.c.t_c
<sqlalchemy.sql.elements.ColumnClause at 0x7f59dcf04fa0; t_c>

ColumnCollection 同时按顺序索引列，并允许按整数位置访问它们：

>>> cc[0]
Column('x', Integer(), table=None)
>>> cc[1]
Column('y', Integer(), table=None)

1.4 新版功能: ColumnCollection 允许对集合进行基于整数的索引访问。

迭代集合将按以下顺序生成列表达式：

>>> list(cc)
[Column('x', Integer(), table=None),
 Column('y', Integer(), table=None)]

底座 ColumnCollection 对象可以存储重复项，这可能意味着具有相同键的两列中的任何一列，在这种情况下，键访问返回的列是 任意的 ：：

>>> x1, x2 = Column('x', Integer), Column('x', Integer)
>>> cc = ColumnCollection(columns=[(x1.name, x1), (x2.name, x2)])
>>> list(cc)
[Column('x', Integer(), table=None),
 Column('x', Integer(), table=None)]
>>> cc['x'] is x1
False
>>> cc['x'] is x2
True

也可以多次表示同一列。这些案例被支持为 ColumnCollection 用于表示select语句中可能包含重复项的列。

一个特殊的子类 DedupeColumnCollection 存在，它维护SQLAlchemy不允许重复的旧行为；此集合用于架构级对象，如 Table 和 PrimaryKeyConstraint 在这种情况下，除尘是有帮助的。这个 DedupeColumnCollection 类还具有其他的突变方法，因为模式构造具有更多需要删除和替换列的用例。

在 1.4 版更改: ColumnCollection 现在在多个位置存储重复的列键以及同一列。这个 DedupeColumnCollection 类用于在需要重复数据消除和其他替换/删除操作的情况下保持以前的行为。

method sqlalchemy.sql.expression.ColumnCollection.add(column, key=None)¶

向此添加一列 ColumnCollection 。

注解

此方法是 not normally used by user-facing code ，作为 ColumnCollection 通常是现有对象的一部分，如 Table 。要添加 Column 添加到现有的 Table 对象，请使用 Table.append_column() 方法。

method sqlalchemy.sql.expression.ColumnCollection.as_immutable()¶

返回此函数的“不可变”形式 ColumnCollection 。

method sqlalchemy.sql.expression.ColumnCollection.clear()¶

没有为以下对象实现字典清除() ColumnCollection 。

method sqlalchemy.sql.expression.ColumnCollection.compare(other)¶

比较一下这个 ColumnCollection 根据密钥的名称添加到另一个密钥

method sqlalchemy.sql.expression.ColumnCollection.contains_column(col)¶

检查此集合中是否存在列对象

method sqlalchemy.sql.expression.ColumnCollection.corresponding_column(column, require_embedded=False)¶

给出了一个 ColumnElement ，返回导出的 ColumnElement 来自此的对象 ColumnCollection 与原件相对应 ColumnElement 通过一个共同的祖先列。

参数

• column¶ -- 目标 ColumnElement 相配。

• require_embedded¶ -- 仅返回给定的对应列 ColumnElement ，如果给定的 ColumnElement 实际存在于此子元素中 Selectable . 通常情况下，如果该列仅与该列的导出列共享一个共同的祖先，则该列将匹配 Selectable .

参见

Selectable.corresponding_column() -对返回的集合调用此方法 Selectable.exported_columns .

在 1.4 版更改: 实施 corresponding_column 被转移到 ColumnCollection 本身。

method sqlalchemy.sql.expression.ColumnCollection.get(key, default=None)¶

拿到一个 ColumnClause 或 Column 基于此中的字符串键名称创建 ColumnCollection 。

method sqlalchemy.sql.expression.ColumnCollection.items()¶

返回此集合中所有列的(key，column)元组序列，每个元组由字符串键名称和 ColumnClause 或 Column 对象。

method sqlalchemy.sql.expression.ColumnCollection.keys()¶

返回此集合中所有列的字符串键名称序列。

method sqlalchemy.sql.expression.ColumnCollection.remove(column)¶

字典Remove()未针对以下对象实现 ColumnCollection 。

method sqlalchemy.sql.expression.ColumnCollection.update(iter_)¶

字典update()未针对以下对象实现 ColumnCollection 。

method sqlalchemy.sql.expression.ColumnCollection.values()¶

返回一个序列 ColumnClause 或 Column 此集合中所有列的。