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