SQLAlchemy技术文档（中文版）（全）

原文连接：http://www.cnblogs.com/iwangzc/p/4112078.html（感谢做者的分享）
https://blog.csdn.net/Lotfee/article/details/57406450（感谢做者的分享）

sqlalchemy 官方文档：http://docs.sqlalchemy.org/en/latest/contents.html

1.版本检查

import sqlalchemy
sqlalchemy.version

2.链接

from sqlalchemy import create_engine
engine = create_engine('sqlite:///:memory:',echo=True)
echo参数为True时，会显示每条执行的SQL语句，能够关闭。create_engine()返回一个Engine的实例，而且它表示经过数据库语法处理细节的核心接口，在这种状况下，数据库语法将会被解释称Python的类方法。

3.声明映像

当使用ORM【1】时，构造进程首先描述数据库的表，而后定义咱们用来映射那些表的类。在现版本的SQLAlchemy中，这两个任务一般一块儿执行，经过使用Declarative方法，咱们能够建立一些包含描述要被映射的实际数据库表的准则的映射类。

使用Declarative方法定义的映射类依据一个基类，这个基类是维系类和数据表关系的目录——咱们所说的Declarative base class。在一个普通的模块入口中，应用一般只须要有一个base的实例。咱们经过declarative_base()功能建立一个基类：

from sqlalchemy.ext.declarativeimportdeclarative_base
Base = declarative_base()
有了这个base，咱们能够依据这个base定义任意数量的映射类。一个简单的user例子：

from sqlalchemy import Column, Integer, String
class User(Base):
tablename= 'users'
id= Column(Integer, primary_key=True)
name = Column(String)
用Declarative构造的一个类至少须要一个tablename属性，一个主键行。

4.构造模式（项目中没用到）

5.建立映射类的实例

ed_user = User(name='ed',fullname='Ed Jones', password='edspassword')
6.建立会话

如今咱们已经准备毫和数据库开始会话了。ORM经过Session与数据库创建链接的。当应用第一次载入时，咱们定义一个Session类（声明create_engine()的同时），这个Session类为新的Session对象提供工厂服务。

from sqlalchemy.orm import sessionmaker
Session = sessionmaker(bind=engine)
这个定制的Session类会建立绑定到数据库的Session对象。若是须要和数据库创建链接，只须要实例化一个Session：

session = Session()
虽然上面的Session已经和数据库引擎Engine关联，可是尚未打开任何链接。当它第一次被使用时，就会从Engine维护的一个链接池中检索是否存在链接，若是存在便会保持链接知道咱们提交全部更改而且/或者关闭session对象。

7.添加新对象（简略）

ed_user = User(name='ed', fullname='Ed Jones', password='edspassword')
session.add(ed_user)
至此，咱们能够认为，新添加的这个对象实例仍在等待中；ed_user对象如今并不表明数据库中的一行数据。直到使用flush进程，Session才会让SQL保持链接。若是查询这条数据的话，全部等待信息会被第一时间刷新，查询结果也会当即发行。

session.commit()
经过commit()能够提交全部剩余的更改到数据库。

8.回滚

session.rollback()
9.查询

经过Session的query()方法建立一个查询对象。这个函数的参数数量是可变的，参数能够是任何类或者是类的描述的集合。下面是一个迭代输出User类的例子：

for instance in session.query(User).order_by(User.id):
print instance.name,instance.fullname
Query也支持ORM描述做为参数。任什么时候候，多个类的实体或者是基于列的实体表达均可以做为query()函数的参数，返回类型是元组：

for name, fullname in session.query(User.name,User.fullname):

print name, fullname
Query返回的元组被命名为KeyedTuple类的实例元组。而且能够把它当成一个普通的Python数据类操做。元组的名字就至关于属性的属性名，类的类名同样。

for row in session.query(User, User.name).all():

print row.User,row.name
<User(name='ed',fullname='Ed Jones', password='f8s7ccs')>ed
label()不知道怎么解释，看下例子就明白了。至关于row.name

for row in session.query(User.name.label('name_label')).all():

print(row.name_label)
aliased()个人理解是类的别名，若是有多个实体都要查询一个类，能够用aliased()

from sqlalchemy.orm import aliased
user_alias = aliased(User, name='user_alias')
for row in session.query(user_alias,user_alias.name).all():

print row.user_alias
Query的 基本操做包括LIMIT和OFFSET，使用Python数组切片和ORDERBY结合可让操做变得很方便。

for u in session.query(User).order_by(User.id)[1:3]:

#只查询第二条和第三条数据
9.1使用关键字变量过滤查询结果，filter 和 filter_by都适用。【2】使用很简单，下面列出几个经常使用的操做：

query.filter(User.name == 'ed') #equals
query.filter(User.name != 'ed') #not equals
query.filter(User.name.like('%ed%')) #LIKE
uery.filter(User.name.in(['ed','wendy', 'jack'])) #IN
query.filter(User.name.in(session.query(User.name).filter(User.name.like('%ed%'))#IN
query.filter(~User.name.in(['ed','wendy', 'jack']))#not IN
query.filter(User.name == None)#is None
query.filter(User.name != None)#not None
from sqlalchemy import and
query.filter(and(User.name =='ed',User.fullname =='Ed Jones')) # and
query.filter(User.name == 'ed',User.fullname =='Ed Jones') # and
query.filter(User.name == 'ed').filter(User.fullname == 'Ed Jones')# and
from sqlalchemy import or
query.filter(or_(User.name =='ed', User.name =='wendy')) #or
query.filter(User.name.match('wendy')) #match
9.2.返回列表和数量（标量？）

all()返回一个列表：能够进行Python列表的操做。

query = session.query(User).filter(User.name.like('%ed')).order_by(User.id)
query.all()

[<User(name='ed',fullname='EdJones', password='f8s7ccs')>,<User(name='fred',
fullname='FredFlinstone', password='blah')>]

first()适用于限制一个状况，返回查询到的第一个结果做为标量？：好像只能做为属性，类

query.first()

<User(name='ed',fullname='Ed Jones', password='f8s7ccs')>
one()彻底获取全部行，而且若是查询到的不仅有一个对象或是有复合行，就会抛出异常。

from sqlalchemy.orm.exc import MultipleResultsFound
user = query.one()
try:

　　user = query.one()
except
　　MultipleResultsFound, e:
　　print e
Multiple rows were found for one()
若是一行也没有：

from sqlalchemy.orm.exc import NoResultFound
try:

　　user = query.filter(User.id == 99).one()
except
NoResultFound, e:
　　print e
No row was found for one()
one()方法对于想要解决“no items found”和“multiple items found”是不一样的系统是极好的。（这句有语病啊）例如web服务返回，原本是在no results found状况下返回”404“的，结果在多个results found状况下也会跑出一个应用异常。

scalar()做为one()方法的依据，而且在one()成功基础上返回行的第一列。

query = session.query(User.id).filter(User.name == 'ed')
query.scalar()

7
9.3.使用字符串SQL

字符串能使Query更加灵活，经过text()构造指定字符串的使用，这种方法能够用在不少方法中，像filter()和order_by()。

from sqlalchemy import text
for user in session.query(User).filter(text("id<224")).order_by(text("id")).all()
绑定参数能够指定字符串，用params()方法指定数值。

session.query(User).filter(text("id<:value and name=:name")).\

params(value=224, name='fred').order_by(User.id).one()

若是要用一个完整的SQL语句，可使用from_statement()。

ession.query(User).from_statement(text("SELECT* FROM users where name=:name")).\
params(name='ed').all()
也能够用from_statement()获取完整的”raw”，用字符名肯定但愿被查询的特定列:

session.query("id","name", "thenumber12").\

from_statement(text("SELECT id, name, 12 as ""thenumber12 FROM users where name=:name")).\
　params(name='ed').all()

[(1,u'ed', 12)]
感受这个不太符合ORM的思想啊。。。

9.4 计数

count()用来统计查询结果的数量。

session.query(User).filter(User.name.like('%ed')).count()

func.count()方法比count()更高级一点【3】

from sqlalchemy import func

session.query(func.count(User.name),User.name).group_by(User.name).all()

[(1,u'ed'), (1,u'fred'), (1,u'mary'), (1,u'wendy')]
为了实现简单计数SELECT count(*) FROM table，能够这么写：

session.query(func.count('*')).select_from(User).scalar()

若是咱们明确表达计数是根据User表的主键的话，能够省略select_from(User):

session.query(func.count(User.id)).scalar()

上面两行结果均为4。

Go to （下）

10.创建联系（外键）

是时候考虑怎样映射和查询一个和Users表关联的第二张表了。假设咱们系统的用户能够存储任意数量的email地址。咱们须要定义一个新表Address与User相关联。

from sqlalchemyimport ForeignKey

from sqlalchemy.ormimport relationship, backref
class Address(Base):
tablename = 'addresses'
id= Column(Integer, primary_key=True)
email_address = Column(String, nullable=False)
user_id = Column(Integer, ForeignKey('users.id'))
user = relationship("User", backref=backref('addresses',order_by=id))
defrepr(self):
return"<Address(email_address='%s')>"%self.email_address
构造类和外键简单，就不过多赘述。主要说明如下relationship()函数：这个函数告诉ORM，Address类应该和User类链接起来，经过使用addresses.user。relationship()使用外键明确这两张表的关系。决定Adderess.user属性是多对一的。relationship()的子函数backref()提供表达反向关系的细节：relationship()对象的集合被User.address引用。多对一的反向关系老是一对多。更多的细节参考Basic RelRational Patterns。

这两个互补关系：Address.user和User.addresses被称为双向关系。这是SQLAlchemy ORM的一个很是关键的功能。更多关系backref的细节参见Linking Relationships with Backref。

假设声明的方法已经开始使用，relationship()中和其余类关联的参数能够经过strings指定。在上文的User类中，一旦全部映射成功，为了产生实际的参数，这些字符串会被当作Python的表达式。下面是一个在User类中建立双向联系的例子：

class User(Base):
addresses = relationship("Address", order_by="Address.id", backref="user")
一些知识：

在大多数的外键约束（尽管不是全部的）关系数据库只能连接到一个主键列，或具备惟一约束的列。

外键约束若是是指向多个列的主键，而且它自己也具备多列，这种被称为“复合外键”。

外键列能够自动更新本身来相应它所引用的行或者列。这被称为级联，是一种创建在关系数据库的功能。

外键能够参考本身的表格。这种被称为“自引”外键。

咱们须要在数据库中建立一个addresses表，因此咱们会建立另外一个元数据，这将会跳过已经建立的表。

11.操做主外键关联的对象

如今咱们已经在User类中建立了一个空的addresser集合，可变集合类型，例如set和dict，均可以用，可是默认的集合类型是list。

jack = User(name='jack', fullname='Jack Bean', password='gjffdd')
jack.addresses
[]
如今能够直接在User对象中添加Address对象。只须要指定一个完整的列表：

jack.addresses = [Address(email_address='jack@google.com'),Address(email_address='j25@yahoo.com')]
当使用双向关系时，元素在一个类中被添加后便会自动在另外一个类中添加。这种行为发生在Python的更改事件属性中而不是用SQL语句：

jack.addresses[1]br/><Address(email_address='j25@yahoo.com')>
jack.addresses[1].user
<User(name='jack', fullname='Jack Bean', password='gjffdd')>
把jack提交到数据库中，再次查询Jack，（No SQL is yet issued for Jack’s addresses:）这句实在是翻译不了了，看看代码就明白是什么意思：
jack = session.query(User).\
...
filter_by(name='jack').one()

jack
<User(name='jack',fullname='Jack Bean', password='gjffdd')>

jack.addresses br/>[<Address(email_address='jack@google.com')>,
<Address(email_address='j25@yahoo.com')>]
当咱们访问uaddresses集合时，SQL会被忽然执行，这是一个延迟加载（lazy loading）关系的典型例子。如今addresses集合加载完成而且能够像对待普通列表同样对其进行操做。之后咱们会优化这种加载方式。
12.使用JOINS查询
如今咱们有了两张表，能够进行更多的查询操做，特别是怎样对两张表同时进行查询，Wikipediapage on SQL JOIN提供了很详细的说明，其中一些咱们将在这里说明。以前用Query.filter()时，咱们已经用过JOIN了，filter是一种简单的隐式join：
for u, a in session.query(User, Address).filter(User.id==Address.user_id).filter(Address.email_address=='jack@google.com').all():
print u
print a
<User(name='jack',fullname='JackBean', password='gjffdd')>br/><Address(email_address='jack@google.com')>
用Query.join()方法会更加简单：br/>session.query(User).join(Address).\
...
filter(Address.email_address=='jack@google.com').\
...
all()
[<User(name='jack',fullname='JackBean', password='gjffdd')>]
之因此Query.join()知道怎么join两张表是由于它们之间只有一个外键。若是两张表中没有外键或者有一个以上的外键，当下列几种形式使用的时候，Query.join()能够表现的更好：
query.join(Address,User.id==Address.user_id)# 明确的条件
query.join(User.addresses)# 指定从左到右的关系
query.join(Address,User.addresses) #一样，有明确的目标
query.join('addresses') # 一样，使用字符串
outerjoin()和join()用法相同
query.outerjoin(User.addresses)# LEFT OUTER JOIN
12.1使用别名
当在多个表中查询时，若是同一张表须要被引用好几回，SQL一般要求对这个表起一个别名，所以，SQL能够区分对这个表进行的其余操做。Query也支持别名的操做。下面咱们joinAddress实体两次，找到同时拥有两个不一样email的用户：
from sqlalchemy.ormimport aliased
adalias1 = aliased(Address)
adalias2 = aliased(Address)
for username, email1, email2 in\
...
session.query(User.name,adalias1.email_address,adalias2.email_address).\
...
join(adalias1, User.addresses).\
...
join(adalias2, User.addresses).\br/>...
filter(adalias1.email_address=='jack@google.com').\
...br/>filter(adalias2.email_address=='j25@yahoo.com'):
...
print username, email1,
email2
jack
jack@google.com j25@yahoo.com
12.1使用子查询（暂时理解不了啊，多看代码研究吧：(）
from sqlalchemy.sqlimport func
stmt = session.query(Address.user_id,func.count('*').\
...
label('address_count')).\
...
group_by(Address.user_id).subquery()

for u, count in session.query(User,stmt.c.address_count).\
...
outerjoin(stmt, User.id==stmt.c.user_id).order_by(User.id):
print u, count
<User(name='ed',fullname='EdJones', password='f8s7ccs')>
None
<User(name='wendy',fullname='Wendy Williams', password='foobar')>
None
<User(name='mary',fullname='Mary Contrary', password='xxg527')>
None
<User(name='fred',fullname='Fred Flinstone', password='blah')>
None
<User(name='jack',fullname='Jack Bean', password='gjffdd')>
2
12.2从子查询中选择实体？
上面的代码中咱们只返回了包含子查询的一个列的结果。若是想要子查询映射到一个实体的话，使用aliased()设置一个要映射类的子查询别名：

stmt = session.query(Address).\
...
filter(Address.email_address!= 'j25@yahoo.com').\
...
subquery()

adalias = aliased(Address, stmt)
#？为何有两个参数？

for user, address in session.query(User, adalias).\
...
join(adalias, User.addresses):
...
print user
...
print address
<User(name='jack',fullname='Jack Bean', password='gjffdd')>br/><Address(email_address='jack@google.com')>
12.3使用EXISTS（存在？）

若是表达式返回任何行，EXISTS为真，这是一个布尔值。它能够用在jions中，也能够用来定位在一个关系表中没有相应行的状况：

from sqlalchemy.sqlimport exists

stmt = exists().where(Address.user_id==User.id)
for name, in session.query(User.name).filter(stmt):
print name
jack
等价于：

for name, in session.query(User.name).\
...
　　filter(User.addresses.any()):

...
print name
jack
any()限制行匹配：

for name, in session.query(User.name).\
...

filter(User.addresses.any(Address.email_address.like('%google%'))):

...
print name
jack
has()和any()同样在应对多对一关系的状况下（注意“～“意味着”NOT”）

session.query(Address).\
...
filter(~Address.user.has(User.name=='jack')).all()

[]
12.4 常见的关系运算符

== ！= None 都是用在多对一中，而contains()用在一对多的集合中：

query.filter(Address.user == someuser)
query.filter(User.addresses.contains(someaddress))
Any()（用于集合中）：

query.filter(User.addresses.any(Address.email_address == 'bar'))#also takes keyword arguments:
query.filter(User.addresses.any(email_address='bar'))
as()（用在标量？不在集合中）：

query.filter(Address.user.has(name='ed'))
Query.with_parent()（全部关系都适用）：

session.query(Address).with_parent(someuser,'addresses')
13 预先加载（跟性能有关）和lazy loading相对，建议直接查看文档吧

待补充。。。