SqlAlchemy 2.0 中文文档（八十一）（1）https://developer.aliyun.com/article/1559896
SQL 表达式
全新的、确定性的标签/别名生成
所有“匿名”标签和别名现在都使用简单的 _ 格式。SQL 更容易阅读，并且与计划优化器缓存兼容。只需查看一些教程中的示例：www.sqlalchemy.org/docs/04/ormtutorial.html www.sqlalchemy.org/docs/04/sqlexpression.html
生成式 select() 构造
这绝对是使用select()的方法。请参阅 htt p://www.sqlalchemy.org/docs/04/sqlexpression.html#sql_transf orm 。
新的运算符系统
SQL 运算符和几乎每个 SQL 关键字现在都被抽象为编译器层。它们现在表现智能，并且具有类型/后端感知性，参见：www.sqlalchemy.org/docs/04/sqlexpression.html#sql_operators
所有type关键字参数重命名为type_
就像它说的那样：
b = bindparam("foo", type_=String)
in_函数更改为接受序列或可选择的
in_函数现在接受一个值序列或可选择的可选参数。仍然可以使用以前将值作为位置参数传递的 API，但现在已被弃用。这意味着
my_table.select(my_table.c.id.in_(1, 2, 3)) my_table.select(my_table.c.id.in_(*listOfIds))
应更改为
my_table.select(my_table.c.id.in_([1, 2, 3])) my_table.select(my_table.c.id.in_(listOfIds))
模式和反射
MetaData、BoundMetaData、DynamicMetaData…
在 0.3.x 系列中，BoundMetaData和DynamicMetaData已被弃用，取而代之的是MetaData和ThreadLocalMetaData。旧名称已在 0.4 版本中移除。更新很简单：
+-------------------------------------+-------------------------+ |If You Had | Now Use | +=====================================+=========================+ | ``MetaData`` | ``MetaData`` | +-------------------------------------+-------------------------+ | ``BoundMetaData`` | ``MetaData`` | +-------------------------------------+-------------------------+ | ``DynamicMetaData`` (with one | ``MetaData`` | | engine or threadlocal=False) | | +-------------------------------------+-------------------------+ | ``DynamicMetaData`` | ``ThreadLocalMetaData`` | | (with different engines per thread) | | +-------------------------------------+-------------------------+
很少使用的name参数已从MetaData类型中删除。ThreadLocalMetaData构造函数现在不再接受参数。这两种类型现在都可以绑定到一个Engine或一个单独的Connection。
一步多表反射
现在您可以加载表定义，并在一个步骤中自动创建整个数据库或模式的Table对象：
>>> metadata = MetaData(myengine, reflect=True) >>> metadata.tables.keys() ['table_a', 'table_b', 'table_c', '...']
MetaData还增加了一个.reflect()方法，可以更精细地控制加载过程，包括指定要加载的可用表的子集。
SQL 执行
engine、connectable和bind_to现在都是bind
Transactions、NestedTransactions和TwoPhaseTransactions
连接池事件
连接池现在在创建新的 DB-API 连接、检出和检入池时触发事件。您可以使用这些事件在新连接上执行会话范围的 SQL 设置语句，例如。
修复了 Oracle Engine
在 0.3.11 版本中，Oracle Engine 在处理主键时存在错误。这些错误可能导致在使用 Oracle Engine 时，其他引擎（如 sqlite）正常工作的程序失败。在 0.4 版本中，Oracle Engine 已经重新设计，修复了这些主键问题。
Oracle 的输出参数
result = engine.execute( text( "begin foo(:x, :y, :z); end;", bindparams=[ bindparam("x", Numeric), outparam("y", Numeric), outparam("z", Numeric), ], ), x=5, ) assert result.out_parameters == {"y": 10, "z": 75}
连接绑定的MetaData、Sessions
MetaData和Session可以显式绑定到连接：
conn = engine.connect() sess = create_session(bind=conn)
更快、更可靠的ResultProxy对象
首要事项
如果您正在使用任何 ORM 功能，请确保从sqlalchemy.orm导入：
from sqlalchemy import * from sqlalchemy.orm import *
其次，无论您以前使用engine=、connectable=、bind_to=、something.engine、metadata.connect()，现在都使用bind：
myengine = create_engine("sqlite://") meta = MetaData(myengine) meta2 = MetaData() meta2.bind = myengine session = create_session(bind=myengine) statement = select([table], bind=myengine)
明白了吗？很好！您现在（95%）兼容 0.4 版本。如果您正在使用 0.3.10 版本，您可以立即进行这些更改；它们也适用于那里。
模块导入
在 0.3 版本中，“from sqlalchemy import *” 将所有 sqlalchemy 的子模块导入到您的命名空间中。0.4 版本不再将子模块导入到命名空间中。这可能意味着您需要在代码中添加额外的导入。
在 0.3 版本中，这段代码有效：
from sqlalchemy import * class UTCDateTime(types.TypeDecorator): pass
在 0.4 版本中，必须执行：
from sqlalchemy import * from sqlalchemy import types class UTCDateTime(types.TypeDecorator): pass
对象关系映射
查询
新的查询 API
查询标准化为生成式接口（旧接口仍然存在，只是已弃用）。虽然大部分生成式接口在 0.3 版本中可用，但 0.4 版本的 Query 具有与生成式外部匹配的内部实现，并且有更多技巧。所有结果缩小都通过 filter() 和 filter_by() 进行，限制/偏移要么通过数组切片要么通过 limit()/offset() 进行，连接通过 join() 和 outerjoin() 进行（或者更手动地，通过 select_from() 以及手动形成的条件）。
为了避免弃用警告，您必须对您的 03 代码进行一些更改
User.query.get_by( **kwargs )
User.query.filter_by(**kwargs).first()
User.query.select_by( **kwargs )
User.query.filter_by(**kwargs).all()
User.query.select()
User.query.filter(xxx).all()
新的基于属性的表达式构造
在 ORM 中最明显的区别是，现在您可以直接使用基于类的属性构建查询条件。在处理映射类时不再需要“.c.”前缀：
session.query(User).filter(and_(User.name == "fred", User.id > 17))
虽然简单的基于列的比较不是什么大问题，但类属性具有一些新的“更高级”构造可用，包括以前仅在 filter_by() 中可用的内容：
# comparison of scalar relations to an instance filter(Address.user == user) # return all users who contain a particular address filter(User.addresses.contains(address)) # return all users who *dont* contain the address filter(~User.address.contains(address)) # return all users who contain a particular address with # the email_address like '%foo%' filter(User.addresses.any(Address.email_address.like("%foo%"))) # same, email address equals 'foo@bar.com'. can fall back to keyword # args for simple comparisons filter(User.addresses.any(email_address="foo@bar.com")) # return all Addresses whose user attribute has the username 'ed' filter(Address.user.has(name="ed")) # return all Addresses whose user attribute has the username 'ed' # and an id > 5 (mixing clauses with kwargs) filter(Address.user.has(User.id > 5, name="ed"))
Column 集合仍然可以在 .c 属性中的映射类中使用。请注意，基于属性的表达式仅适用于映射类的映射属性。.c 仍然用于访问常规表中的列以及从 SQL 表达式生成的可选择对象。
自动连接别名
我们已经有了 join() 和 outerjoin() 一段时间了：
session.query(Order).join("items")
现在您可以为它们创建别名：
session.query(Order).join("items", aliased=True).filter(Item.name="item 1").join( "items", aliased=True ).filter(Item.name == "item 3")
以上将使用别名从 orders->items 创建两个连接。每个连接后续的 filter() 调用将调整其表条件以符合别名。要访问 Item 对象，请使用 add_entity() 并将每个连接的 id 作为目标：
session.query(Order).join("items", id="j1", aliased=True).filter( Item.name == "item 1" ).join("items", aliased=True, id="j2").filter(Item.name == "item 3").add_entity( Item, id="j1" ).add_entity( Item, id="j2" )
返回元组形式：(Order, Item, Item)。
自引用查询
因此 query.join() 现在可以创建别名。这给我们带来了什么？自引用查询！可以在没有任何 Alias 对象的情况下进行连接：
# standard self-referential TreeNode mapper with backref mapper( TreeNode, tree_nodes, properties={ "children": relation( TreeNode, backref=backref("parent", remote_side=tree_nodes.id) ) }, ) # query for node with child containing "bar" two levels deep session.query(TreeNode).join(["children", "children"], aliased=True).filter_by( name="bar" )
要为每个表添加条件，可以使用 from_joinpoint 在别名连接中保持针对相同别名行的连接：
# search for the treenode along the path "n1/n12/n122" # first find a Node with name="n122" q = sess.query(Node).filter_by(name="n122") # then join to parent with "n12" q = q.join("parent", aliased=True).filter_by(name="n12") # join again to the next parent with 'n1'. use 'from_joinpoint' # so we join from the previous point, instead of joining off the # root table q = q.join("parent", aliased=True, from_joinpoint=True).filter_by(name="n1") node = q.first()
query.populate_existing()
query.load() 的贪婪版本（或 session.refresh()）。从查询加载的每个实例，包括所有贪婪加载的项目，如果已经存在于会话中，则立即刷新：
session.query(Blah).populate_existing().all()
关系
嵌入在更新/插入中的 SQL 子句
对于内联执行 SQL 子句，嵌入在 flush() 中的 UPDATE 或 INSERT 中：
myobject.foo = mytable.c.value + 1 user.pwhash = func.md5(password) order.hash = text("select hash from hashing_table")
在操作后，列属性设置为延迟加载器，因此当您下次访问时，它会发出 SQL 来加载新值。
自引用和循环贪婪加载
由于我们的别名技术已经改进，relation()可以沿着相同的表任意次数连接；你告诉它你想要多深。让我们更清楚地展示自引用的TreeNode：
nodes = Table( "nodes", metadata, Column("id", Integer, primary_key=True), Column("parent_id", Integer, ForeignKey("nodes.id")), Column("name", String(30)), ) class TreeNode(object): pass mapper( TreeNode, nodes, properties={"children": relation(TreeNode, lazy=False, join_depth=3)}, )
那么当我们说：
create_session().query(TreeNode).all()
? 通过别名连接，从父级开始深入三级：
SELECT nodes_3.id AS nodes_3_id, nodes_3.parent_id AS nodes_3_parent_id, nodes_3.name AS nodes_3_name, nodes_2.id AS nodes_2_id, nodes_2.parent_id AS nodes_2_parent_id, nodes_2.name AS nodes_2_name, nodes_1.id AS nodes_1_id, nodes_1.parent_id AS nodes_1_parent_id, nodes_1.name AS nodes_1_name, nodes.id AS nodes_id, nodes.parent_id AS nodes_parent_id, nodes.name AS nodes_name FROM nodes LEFT OUTER JOIN nodes AS nodes_1 ON nodes.id = nodes_1.parent_id LEFT OUTER JOIN nodes AS nodes_2 ON nodes_1.id = nodes_2.parent_id LEFT OUTER JOIN nodes AS nodes_3 ON nodes_2.id = nodes_3.parent_id ORDER BY nodes.oid, nodes_1.oid, nodes_2.oid, nodes_3.oid
注意漂亮干净的别名名称。连接不在乎是否针对同一个直接表或一些其他对象，然后循环回开始。当指定join_depth时，任何类型的链式急切加载可以循环回自身。当不存在时，急切加载在遇到循环时会自动停止。
复合类型
这是来自 Hibernate 阵营的一个。复合类型让你定义一个由多个列（或一个列，如果你愿意）组成的自定义数据类型。让我们定义一个新类型，Point。存储一个 x/y 坐标：
class Point(object): def __init__(self, x, y): self.x = x self.y = y def __composite_values__(self): return self.x, self.y def __eq__(self, other): return other.x == self.x and other.y == self.y def __ne__(self, other): return not self.__eq__(other)
Point对象的定义方式是特定于自定义类型的；构造函数接受一个参数列表，__composite_values__()方法生成这些参数的序列。顺序将与我们的映射器匹配，我们马上就会看到。
让我们创建一个存储每行两个点的顶点表：
vertices = Table( "vertices", metadata, Column("id", Integer, primary_key=True), Column("x1", Integer), Column("y1", Integer), Column("x2", Integer), Column("y2", Integer), )
然后，映射它！我们将创建一个存储两个Point对象的Vertex对象：
class Vertex(object): def __init__(self, start, end): self.start = start self.end = end mapper( Vertex, vertices, properties={ "start": composite(Point, vertices.c.x1, vertices.c.y1), "end": composite(Point, vertices.c.x2, vertices.c.y2), }, )
一旦设置了复合类型，它就可以像任何其他类型一样使用：
v = Vertex(Point(3, 4), Point(26, 15)) session.save(v) session.flush() # works in queries too q = session.query(Vertex).filter(Vertex.start == Point(3, 4))
如果你想定义映射属性在表达式中生成 SQL 子句的方式，创建自己的sqlalchemy.orm.PropComparator子类，定义任何常见操作符（如__eq__()，__le__()等），并将其发送到composite()。复合类型也可以作为主键，并且可用于query.get()：
# a Document class which uses a composite Version # object as primary key document = query.get(Version(1, "a"))
dynamic_loader()关系
一个返回所有读操作的实时Query对象的relation()。写操作仅限于append()和remove()，对集合的更改在会话刷新之前不可见。这个特性在“自动刷新”会话中特别方便，它会在每次查询之前刷新。
mapper( Foo, foo_table, properties={ "bars": dynamic_loader( Bar, backref="foo", # <other relation() opts> ) }, ) session = create_session(autoflush=True) foo = session.query(Foo).first() foo.bars.append(Bar(name="lala")) for bar in foo.bars.filter(Bar.name == "lala"): print(bar) session.commit()
新选项：undefer_group()，eagerload_all()
一些方便的查询选项。undefer_group()将整个“延迟”列组标记为未延迟：
mapper( Class, table, properties={ "foo": deferred(table.c.foo, group="group1"), "bar": deferred(table.c.bar, group="group1"), "bat": deferred(table.c.bat, group="group1"), }, ) session.query(Class).options(undefer_group("group1")).filter(...).all()
eagerload_all()设置一系列属性在一次遍历中急切加载：
mapper(Foo, foo_table, properties={"bar": relation(Bar)}) mapper(Bar, bar_table, properties={"bat": relation(Bat)}) mapper(Bat, bat_table) # eager load bar and bat session.query(Foo).options(eagerload_all("bar.bat")).filter(...).all()
新的集合 API
集合不再由{{{InstrumentedList}}}代理进行代理，对成员、方法和属性的访问是直接的。装饰器现在拦截进入和离开集合的对象，现在可以轻松编写一个自定义集合类来管理自己的成员。灵活的装饰器还取代了 0.3 版本中自定义集合的命名方法接口，允许任何类轻松适应用作集合容器。
基于字典的集合现在更容易使用，完全类似于dict。不再需要更改dict的__iter__，新的内置dict类型涵盖了许多需求：
# use a dictionary relation keyed by a column relation(Item, collection_class=column_mapped_collection(items.c.keyword)) # or named attribute relation(Item, collection_class=attribute_mapped_collection("keyword")) # or any function you like relation(Item, collection_class=mapped_collection(lambda entity: entity.a + entity.b))
现有的 0.3 版本的类似 dict 和自由形式对象派生的集合类需要更新到新的 API。在大多数情况下，这只是在类定义中添加几个装饰器的问题。
SqlAlchemy 2.0 中文文档（八十一）（3）https://developer.aliyun.com/article/1559911
