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

在学习SQLAlchemy的过程当中，好多时候须要查官方Tutorial，发现网上并无完整的中文版，因而利用这两天空余时间粗略翻译了一下。

翻译效果不好。。。。但也算是强迫本身通读一遍Tutorial，收获不少。

 

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 （下）