From 74a95f6cbf2d5a4e8023a3cd6b70b63da806c9e4 Mon Sep 17 00:00:00 2001
From: slene <vslene@gmail.com>
Date: Thu, 8 Aug 2013 11:07:08 +0800
Subject: [PATCH] docs update

---
 orm/README.md              |   2 +
 orm/docs/zh/Models.md      | 192 ++++++++++---------------------------
 orm/docs/zh/Object.md      |  16 ++--
 orm/docs/zh/Orm.md         |  58 ++++++++---
 orm/docs/zh/Query.md       |  96 ++++++++++---------
 orm/docs/zh/README.md      |  30 +++---
 orm/docs/zh/Raw.md         | 108 +++++++++++++++++++++
 orm/docs/zh/Transaction.md |   3 +
 8 files changed, 281 insertions(+), 224 deletions(-)
 create mode 100644 orm/docs/zh/Raw.md
 create mode 100644 orm/docs/zh/Transaction.md

diff --git a/orm/README.md b/orm/README.md
index 67b9eed3..b612672d 100644
--- a/orm/README.md
+++ b/orm/README.md
@@ -82,6 +82,8 @@ num, err := qs.Filter("User__Name", "slene").All(&posts)
 
 #### Use Raw sql
 
+If you don't like ORM，use Raw SQL to query / mapping without ORM setting
+
 ```go
 var maps []Params
 num, err := o.Raw("SELECT id FROM user WHERE name = ?", "slene").Values(&maps)
diff --git a/orm/docs/zh/Models.md b/orm/docs/zh/Models.md
index 76f8c345..d5ce7463 100644
--- a/orm/docs/zh/Models.md
+++ b/orm/docs/zh/Models.md
@@ -1,144 +1,8 @@
-## Model Definition
+## 模型定义
 
-比较全面的 Model 定义例子，后文所有的例子如无特殊说明都以这个为基础。
+复杂的模型定义不是必须的，此功能用作数据库数据转换和自动建表
 
-当前还没有完成自动创建表的功能，所以提供一个 [Models.sql](Models.sql) 测试
-
-note: 根据文档的更新，随时都可能更新这个 Model
-
-##### models.go:
-
-```go
-package main
-
-import (
-	"github.com/astaxie/beego/orm"
-	"time"
-)
-
-type User struct {
-	Id          int        `orm:"auto"`            // 设置为auto主键
-	UserName    string     `orm:"size(30);unique"` // 设置字段为unique
-	Email       string     `orm:"size(100)"`       // 设置string字段长度时,会使用varchar类型
-	Password    string     `orm:"size(100)"`
-	Status      int16      `orm:"choices(0,1,2,3);defalut(0)"` // choices设置可选值
-	IsStaff     bool       `orm:"default(false)"`              // default设置默认值
-	IsActive    bool       `orm:"default(0)"`
-	Created     time.Time  `orm:"auto_now_add;type(date)"`           // 创建时自动设置时间
-	Updated     time.Time  `orm:"auto_now"`                          // 每次更新时自动设置时间
-	Profile     *Profile   `orm:"null;rel(one);on_delete(set_null)"` // OneToOne relation, 级联删除时设置为NULL
-	Posts       []*Post `orm:"reverse(many)" json:"-"` // fk 的反向关系
-	orm.Manager `json:"-"` // 每个model都需要定义orm.Manager
-}
-
-// 定义NewModel进行orm.Manager的初始化(必须)
-func NewUser() *User {
-	obj := new(User)
-	obj.Manager.Init(obj)
-	return obj
-}
-
-type Profile struct {
-	Id          int     `orm:"auto"`
-	Age         int16   ``
-	Money       float64 ``
-	User        *User   `orm:"reverse(one)" json:"-"` // 设置反向关系(字段可选)
-	orm.Manager `json:"-"`
-}
-
-func (u *Profile) TableName() string {
-	return "profile" // 自定义表名
-}
-
-func NewProfile() *Profile {
-	obj := new(Profile)
-	obj.Manager.Init(obj)
-	return obj
-}
-
-type Post struct {
-	Id          int       `orm:"auto"`
-	User        *User     `orm:"rel(fk)"` // RelForeignKey relation
-	Title       string    `orm:"size(60)"`
-	Content     string    ``
-	Created     time.Time ``
-	Updated     time.Time ``
-	Tags        []*Tag    `orm:"rel(m2m)"` // ManyToMany relation
-	orm.Manager `json:"-"`
-}
-
-func NewPost() *Post {
-	obj := new(Post)
-	obj.Manager.Init(obj)
-	return obj
-}
-
-type Tag struct {
-	Id          int     `orm:"auto"`
-	Name        string  `orm:"size(30)"`
-	Status      int16   `orm:"choices(0,1,2);default(0)"`
-	Posts       []*Post `orm:"reverse(many)" json:"-"`
-	orm.Manager `json:"-"`
-}
-
-func NewTag() *Tag {
-	obj := new(Tag)
-	obj.Manager.Init(obj)
-	return obj
-}
-
-type Comment struct {
-	Id          int       `orm:"auto"`
-	Post        *Post     `orm:"rel(fk)"`
-	Content     string    ``
-	Parent      *Comment  `orm:"null;rel(fk)"` // null设置allow NULL
-	Status      int16     `orm:"choices(0,1,2);default(0)"`
-	Created     time.Time `orm:"auto_now_add"`
-	orm.Manager `json:"-"`
-}
-
-func NewComment() *Comment {
-	obj := new(Comment)
-	obj.Manager.Init(obj)
-	return obj
-}
-
-func init() {
-	// 需要在init中注册定义的model
-	orm.RegisterModel(new(User), new(Profile))
-	orm.RegisterModel(new(Post), new(Tag), new(Comment))
-}
-```
-
-## Field Type
-
-现在 orm 支持下面的字段形式
-
-| go type		   | field type  | mysql type
-| :---   	   | :---        | :---
-| bool | TypeBooleanField | tinyint
-| string | TypeCharField | varchar
-| string | TypeTextField | longtext
-| time.Time | TypeDateField | date
-| time.TIme | TypeDateTimeField | datetime
-|  int16 |TypeSmallIntegerField | int(4)
-|  int, int32 |TypeIntegerField | int(11)
-|  int64 |TypeBigIntegerField | bigint(20)
-|  uint, uint16 |TypePositiveSmallIntegerField | int(4) unsigned
-|  uint32 |TypePositiveIntegerField | int(11) unsigned
-|  uint64 |TypePositiveBigIntegerField | bigint(20) unsigned
-| float32, float64 | TypeFloatField | double
-| float32, float64 | TypeDecimalField | double(digits, decimals)
-
-关系型的字段，其字段类型取决于对应的主键。
-
-* RelForeignKey
-* RelOneToOne
-* RelManyToMany
-* RelReverseOne
-* RelReverseMany
-
-## Field Options
+## Struct Tag 设置参数
 ```go
 orm:"null;rel(fk)"
 ```
@@ -175,13 +39,26 @@ orm:"null;rel(fk)"
 
 为字段设置 db 字段的名称
 ```go
-UserName `orm:"column(db_user_name)"`
+Name `orm:"column(user_name)"`
 ```
 #### default
 
 为字段设置默认值，类型必须符合
 ```go
-Status int `orm:"default(1)"`
+type User struct {
+	...
+	Status int `orm:"default(1)"`
+```
+仅当进行 orm.Manager 初始化时才会赋值
+```go
+func NewUser() *User {
+	obj := new(User)
+	obj.Manager.Init(obj)
+	return obj
+}
+
+u := NewUser()
+fmt.Println(u.Status) // 1
 ```
 #### choices
 
@@ -219,7 +96,7 @@ Updated     time.Time `auto_now`
 ```go
 Created time.Time `orm:"auto_now_add;type(date)"`
 ```
-## Relation Field Options
+## 表关系设置
 
 #### rel / reverse
 
@@ -290,4 +167,33 @@ type Profile struct {
 	User *User `orm:"reverse(one)" json:"-"`
 
 // 删除 Profile 时将设置 User.Profile 的数据库字段为 NULL
-```
\ No newline at end of file
+```
+
+
+## Struct Field 类型与数据库的对应
+
+现在 orm 支持下面的字段形式
+
+| go type		   | field type  | mysql type
+| :---   	   | :---        | :---
+| bool | TypeBooleanField | tinyint
+| string | TypeCharField | varchar
+| string | TypeTextField | longtext
+| time.Time | TypeDateField | date
+| time.TIme | TypeDateTimeField | datetime
+|  int16 |TypeSmallIntegerField | int(4)
+|  int, int32 |TypeIntegerField | int(11)
+|  int64 |TypeBigIntegerField | bigint(20)
+|  uint, uint16 |TypePositiveSmallIntegerField | int(4) unsigned
+|  uint32 |TypePositiveIntegerField | int(11) unsigned
+|  uint64 |TypePositiveBigIntegerField | bigint(20) unsigned
+| float32, float64 | TypeFloatField | double
+| float32, float64 | TypeDecimalField | double(digits, decimals)
+
+关系型的字段，其字段类型取决于对应的主键。
+
+* RelForeignKey
+* RelOneToOne
+* RelManyToMany
+* RelReverseOne
+* RelReverseMany
\ No newline at end of file
diff --git a/orm/docs/zh/Object.md b/orm/docs/zh/Object.md
index 684f6067..3cb39d29 100644
--- a/orm/docs/zh/Object.md
+++ b/orm/docs/zh/Object.md
@@ -1,16 +1,14 @@
-## Object
+## 对象的CRUD操作
 
 对 object 操作简单的三个方法 Read / Insert / Update / Delete
 ```go
 o := orm.NewOrm()
 user := NewUser()
-user.UserName = "slene"
-user.Password = "password"
-user.Email = "vslene@gmail.com"
+user.Name = "slene"
 
 fmt.Println(o.Insert(user))
 
-user.UserName = "Your"
+user.Name = "Your"
 fmt.Println(o.Update(user))
 fmt.Println(o.Read(user))
 fmt.Println(o.Delete(user))
@@ -27,16 +25,14 @@ if err == sql.ErrNoRows {
 } else if err == orm.ErrMissPK {
 	fmt.Println("找不到主键")
 } else {
-	fmt.Println(user.Id, user.UserName)
+	fmt.Println(user.Id, user.Name)
 }
 ```
 ### Insert
 ```go
 o := orm.NewOrm()
 var user User
-user.UserName = "slene"
-user.Password = "password"
-user.Email = "vslene@gmail.com"[]()
+user.Name = "slene"
 user.IsActive = true
 
 fmt.Println(o.Insert(&user))
@@ -49,7 +45,7 @@ fmt.Println(user.Id)
 o := orm.NewOrm()
 user := User{Id: 1}
 if o.Read(&user) == nil {
-	user.UserName = "MyName"
+	user.Name = "MyName"
 	o.Update(&user)
 }
 ```
diff --git a/orm/docs/zh/Orm.md b/orm/docs/zh/Orm.md
index a7ed5f61..db02d481 100644
--- a/orm/docs/zh/Orm.md
+++ b/orm/docs/zh/Orm.md
@@ -1,6 +1,40 @@
-## Orm
+## Orm 使用方法
 
 beego/orm 的使用例子
+
+后文例子如无特殊说明都以这个为基础。
+
+##### models.go:
+
+```go
+package main
+
+import (
+	"github.com/astaxie/beego/orm"
+)
+
+type User struct {
+	Id          int        `orm:"auto"`     // 设置为auto主键
+	Name        string
+	Profile     *Profile   `orm:"rel(one)"` // OneToOne relation
+	orm.Manager // 每个model都需要定义orm.Manager
+}
+
+type Profile struct {
+	Id          int     `orm:"auto"`
+	Age         int16
+	User        *User   `orm:"reverse(one)"` // 设置反向关系(可选)
+	orm.Manager
+}
+
+func init() {
+	// 需要在init中注册定义的model
+	orm.RegisterModel(new(User), new(Profile))
+}
+```
+
+##### main.go
+
 ```go
 package main
 
@@ -22,20 +56,18 @@ func main() {
 
 	profile := NewProfile()
 	profile.Age = 30
-	profile.Money = 9.8
 
 	user := NewUser()
 	user.Profile = profile
-	user.UserName = "slene"
-	user.Password = "password"
-	user.Email = "vslene@gmail.com"
-	user.IsActive = true
+	user.Name = "slene"
 
 	fmt.Println(o.Insert(profile))
 	fmt.Println(o.Insert(user))
 }
 ```
 
+## 数据库的设置
+
 #### RegisterDriver
 
 三种数据库类型
@@ -66,12 +98,14 @@ orm 必须注册一个名称为 `default` 的数据库，用以作为默认使
 orm.RegisterDataBase("default", "mysql", "root:root@/orm_test?charset=utf8", 30)
 ```
 
-## Ormer
+## ORM 接口使用
+
+使用 orm 必然接触的 Ormer 接口，我们来熟悉一下
 
 ```go
 var o Ormer
 o = orm.NewOrm() // 创建一个 Ormer
-// NewOrm 的同时会执行一次 orm.BootStrap，用以验证模型之间的定义并缓存。
+// NewOrm 的同时会执行 orm.BootStrap (整个 app 只执行一次)，用以验证模型之间的定义并缓存。
 ```
 
 * type Ormer interface {
@@ -84,9 +118,9 @@ o = orm.NewOrm() // 创建一个 Ormer
 	* [LoadRel(Modeler, string) (int64, error)](Object.md#loadRel)
 	* [QueryTable(interface{}) QuerySeter](#querytable)
 	* [Using(string) error](#using)
-	* [Begin() error](Transaction.md#begin)
-	* [Commit() error](Transaction.md#commit)
-	* [Rollback() error](Transaction.md#rollback)
+	* [Begin() error](Transaction.md)
+	* [Commit() error](Transaction.md)
+	* [Rollback() error](Transaction.md)
 	* [Raw(string, ...interface{}) RawSeter](#raw)
 	* [Driver() Driver](#driver)
 * }
@@ -133,7 +167,7 @@ Raw 函数，返回一个 [RawSeter](Raw.md) 用以对设置的 sql 语句和参
 ```go
 o := NewOrm()
 var r RawSeter
-r = o.Raw("UPDATE user SET user_name = ? WHERE user_name = ?", "testing", "slene")
+r = o.Raw("UPDATE user SET name = ? WHERE name = ?", "testing", "slene")
 ```
 
 #### Driver
diff --git a/orm/docs/zh/Query.md b/orm/docs/zh/Query.md
index 2e50997a..0ec31fcc 100644
--- a/orm/docs/zh/Query.md
+++ b/orm/docs/zh/Query.md
@@ -1,4 +1,4 @@
-## Query
+## 高级查询
 
 orm 以 **QuerySeter** 来组织查询，每个返回 **QuerySeter** 的方法都会获得一个新的 **QuerySeter** 对象。
 
@@ -29,8 +29,8 @@ qs.Filter("profile__age__gt", 18) // WHERE profile.age > 18
 qs.Filter("profile__age__gte", 18) // WHERE profile.age >= 18
 qs.Filter("profile__age__in", 18, 20) // WHERE profile.age IN (18, 20)
 
-qs.Filter("profile__age__in", 18, 20).Exclude("profile__money__lt", 1000)
-// WHERE profile.age IN (18, 20) AND NOT profile.money < 1000
+qs.Filter("profile__age__in", 18, 20).Exclude("profile__lt", 1000)
+// WHERE profile.age IN (18, 20) AND NOT profile_id < 1000
 ```
 ## Operators
 
@@ -51,27 +51,27 @@ qs.Filter("profile__age__in", 18, 20).Exclude("profile__money__lt", 1000)
 
 Filter / Exclude / Condition expr 的默认值
 ```go
-qs.Filter("user_name", "slene") // WHERE user_name = 'slene'
-qs.Filter("user_name__exact", "slene") // WHERE user_name = 'slene'
+qs.Filter("name", "slene") // WHERE name = 'slene'
+qs.Filter("name__exact", "slene") // WHERE name = 'slene'
 // 使用 = 匹配，大小写是否敏感取决于数据表使用的 collation
 qs.Filter("profile", nil) // WHERE profile_id IS NULL
 ```
 #### iexact
 ```go
-qs.Filter("user_name__iexact", "slene")
-// WHERE user_name LIKE 'slene'
+qs.Filter("name__iexact", "slene")
+// WHERE name LIKE 'slene'
 // 大小写不敏感，匹配任意 'Slene' 'sLENE'
 ```
 #### contains
 ```go
-qs.Filter("user_name__contains", "slene")
-// WHERE user_name LIKE BINARY '%slene%'
+qs.Filter("name__contains", "slene")
+// WHERE name LIKE BINARY '%slene%'
 // 大小写敏感, 匹配包含 slene 的字符
 ```
 #### icontains
 ```go
-qs.Filter("user_name__icontains", "slene")
-// WHERE user_name LIKE '%slene%'
+qs.Filter("name__icontains", "slene")
+// WHERE name LIKE '%slene%'
 // 大小写不敏感, 匹配任意 'im Slene', 'im sLENE'
 ```
 #### in
@@ -97,26 +97,26 @@ qs.Filter("profile__age__lte", 18)
 ```
 #### startswith
 ```go
-qs.Filter("user_name__startswith", "slene")
-// WHERE user_name LIKE BINARY 'slene%'
+qs.Filter("name__startswith", "slene")
+// WHERE name LIKE BINARY 'slene%'
 // 大小写敏感, 匹配以 'slene' 起始的字符串
 ```
 #### istartswith
 ```go
-qs.Filter("user_name__istartswith", "slene")
-// WHERE user_name LIKE 'slene%'
+qs.Filter("name__istartswith", "slene")
+// WHERE name LIKE 'slene%'
 // 大小写不敏感, 匹配任意以 'slene', 'Slene' 起始的字符串
 ```
 #### endswith
 ```go
-qs.Filter("user_name__endswith", "slene")
-// WHERE user_name LIKE BINARY '%slene'
+qs.Filter("name__endswith", "slene")
+// WHERE name LIKE BINARY '%slene'
 // 大小写敏感, 匹配以 'slene' 结束的字符串
 ```
 #### iendswith
 ```go
-qs.Filter("user_name__startswith", "slene")
-// WHERE user_name LIKE '%slene'
+qs.Filter("name__startswith", "slene")
+// WHERE name LIKE '%slene'
 // 大小写不敏感, 匹配任意以 'slene', 'Slene' 结束的字符串
 ```
 #### isnull
@@ -128,9 +128,9 @@ qs.Filter("profile_id__isnull", true)
 qs.Filter("profile__isnull", false)
 // WHERE profile_id IS NOT NULL
 ```
-## QuerySeter
+## 高级查询接口使用
 
-QuerySeter 当前支持的方法
+QuerySeter 是高级查询使用的接口，我们来熟悉下他的接口方法
 
 * type QuerySeter interface {
 	* [Filter(string, ...interface{}) QuerySeter](#filter)
@@ -151,24 +151,30 @@ QuerySeter 当前支持的方法
 	* [ValuesFlat(*ParamsList, string) (int64, error)](#valuesflat)
 * }
 
-每个返回 QuerySeter 的 api 调用时都会新建一个 QuerySeter，不影响之前创建的。
+* 每个返回 QuerySeter 的 api 调用时都会新建一个 QuerySeter，不影响之前创建的。
+
+* 高级查询使用 Filter 和 Exclude 来做常用的条件查询。囊括两种清晰的过滤规则：包含， 排除
 
 #### Filter
 
+用来过滤查询结果，起到 **包含条件** 的作用
+
 多个 Filter 之间使用 `AND` 连接
 ```go
-qs.Filter("profile__isnull", true).Filter("user_name", "slene")
-// WHERE profile_id IS NULL AND user_name = 'slene'
+qs.Filter("profile__isnull", true).Filter("name", "slene")
+// WHERE profile_id IS NULL AND name = 'slene'
 ```
 
 #### Exclude
 
+用来过滤查询结果，起到 **排除条件** 的作用
+
 使用 `NOT` 排除条件
 
 多个 Exclude 之间使用 `AND` 连接
 ```go
-qs.Exclude("profile__isnull", true).Filter("user_name", "slene")
-// WHERE NOT profile_id IS NULL AND user_name = 'slene'
+qs.Exclude("profile__isnull", true).Filter("name", "slene")
+// WHERE NOT profile_id IS NULL AND name = 'slene'
 ```
 
 #### SetCond
@@ -183,7 +189,7 @@ qs := orm.QueryTable("user")
 qs = qs.SetCond(cond1)
 // WHERE ... AND ... AND NOT ... OR ...
 
-cond2 := cond.AndCond(cond1).OrCond(cond.And("user_name", "slene"))
+cond2 := cond.AndCond(cond1).OrCond(cond.And("name", "slene"))
 qs = qs.SetCond(cond2).Count()
 // WHERE (... AND ... AND NOT ... OR ...) OR ( ... )
 ```
@@ -228,8 +234,8 @@ qs.Offset(20)
 qs.OrderBy("id", "-profile__age")
 // ORDER BY id ASC, profile.age DESC
 
-qs.OrderBy("-profile__money", "profile")
-// ORDER BY profile.money DESC, profile_id ASC
+qs.OrderBy("-profile__age", "profile")
+// ORDER BY profile.age DESC, profile_id ASC
 ```
 
 #### RelatedSel
@@ -260,19 +266,19 @@ fmt.Printf("Count Num: %s, %s", cnt, err)
 #### Update
 依据当前查询条件，进行批量更新操作
 ```go
-num, err := o.QueryTable("user").Filter("user_name", "slene").Update(orm.Params{
-	"user_name": "astaxie",
+num, err := o.QueryTable("user").Filter("name", "slene").Update(orm.Params{
+	"name": "astaxie",
 })
 fmt.Printf("Affected Num: %s, %s", num, err)
-// SET user_name = "astaixe" WHERE user_name = "slene"
+// SET name = "astaixe" WHERE name = "slene"
 ```
 
 #### Delete
 依据当前查询条件，进行批量删除操作
 ```go
-num, err := o.QueryTable("user").Filter("user_name", "slene").Delete()
+num, err := o.QueryTable("user").Filter("name", "slene").Delete()
 fmt.Printf("Affected Num: %s, %s", num, err)
-// DELETE FROM user WHERE user_name = "slene"
+// DELETE FROM user WHERE name = "slene"
 ```
 
 #### PrepareInsert
@@ -282,7 +288,7 @@ fmt.Printf("Affected Num: %s, %s", num, err)
 ```go
 var users []*User
 ...
-qs := dORM.QueryTable("user")
+qs := o.QueryTable("user")
 i, _ := qs.PrepareInsert()
 for _, user := range users {
 	id, err := i.Insert(user)
@@ -290,8 +296,8 @@ for _, user := range users {
 		...
 	}
 }
-// PREPARE INSERT INTO user (`user_name`, ...) VALUES (?, ...)
-// EXECUTE INSERT INTO user (`user_name`, ...) VALUES ("slene", ...)
+// PREPARE INSERT INTO user (`name`, ...) VALUES (?, ...)
+// EXECUTE INSERT INTO user (`name`, ...) VALUES ("slene", ...)
 // EXECUTE ...
 // ...
 i.Close() // 别忘记关闭 statement
@@ -301,7 +307,7 @@ i.Close() // 别忘记关闭 statement
 返回对应的结果集对象
 ```go
 var users []*User
-num, err := o.QueryTable("user").Filter("user_name", "slene").All(&users)
+num, err := o.QueryTable("user").Filter("name", "slene").All(&users)
 fmt.Printf("Returned Rows Num: %s, %s", num, err)
 ```
 
@@ -311,7 +317,7 @@ fmt.Printf("Returned Rows Num: %s, %s", num, err)
 
 ```go
 var user *User
-err := o.QueryTable("user").Filter("user_name", "slene").One(&user)
+err := o.QueryTable("user").Filter("name", "slene").One(&user)
 if err == orm.ErrMultiRows {
 	// 多条的时候报错
 	fmt.Printf("Returned Multi Rows Not One")
@@ -333,7 +339,7 @@ num, err := o.QueryTable("user").Values(&maps)
 if err != nil {
 	fmt.Printf("Result Nums: %d\n", num)
 	for _, m := range maps {
-		fmt.Println(m["Id"], m["UserName"])
+		fmt.Println(m["Id"], m["Name"])
 	}
 }
 ```
@@ -346,11 +352,11 @@ if err != nil {
 
 ```go
 var maps []orm.Params
-num, err := o.QueryTable("user").Values(&maps, "id", "user_name", "profile", "profile__age")
+num, err := o.QueryTable("user").Values(&maps, "id", "name", "profile", "profile__age")
 if err != nil {
 	fmt.Printf("Result Nums: %d\n", num)
 	for _, m := range maps {
-		fmt.Println(m["Id"], m["UserName"], m["Profile"], m["Profile__Age"])
+		fmt.Println(m["Id"], m["Name"], m["Profile"], m["Profile__Age"])
 		// map 中的数据都是展开的，没有复杂的嵌套
 	}
 }
@@ -379,11 +385,11 @@ if err != nil {
 
 ```go
 var lists []orm.ParamsList
-num, err := o.QueryTable("user").ValuesList(&lists, "user_name", "profile__age")
+num, err := o.QueryTable("user").ValuesList(&lists, "name", "profile__age")
 if err != nil {
 	fmt.Printf("Result Nums: %d\n", num)
 	for _, row := range lists {
-		fmt.Printf("UserName: %s, Age: %s\m", row[0], row[1])
+		fmt.Printf("Name: %s, Age: %s\m", row[0], row[1])
 	}
 }
 ```
@@ -394,7 +400,7 @@ if err != nil {
 
 ```go
 var list orm.ParamsList
-num, err := o.QueryTable("user").ValuesFlat(&list, "user_name")
+num, err := o.QueryTable("user").ValuesFlat(&list, "name")
 if err != nil {
 	fmt.Printf("Result Nums: %d\n", num)
 	fmt.Printf("All User Names: %s", strings.Join(list, ", ")
diff --git a/orm/docs/zh/README.md b/orm/docs/zh/README.md
index a8ed158e..e7d80cc5 100644
--- a/orm/docs/zh/README.md
+++ b/orm/docs/zh/README.md
@@ -1,17 +1,19 @@
 ## 文档目录
 
-1. [模型定义](Models.md)
-	- [支持的 Field 类型](Models.md#field-type)
-	- [Field 设置参数](Models.md#field-options)
-	- [关系型 Field 设置](Models.md#relation-field-options)
-2. Custom Fields
-3. [Orm 使用方法](Orm.md)
-	- [Ormer 接口](Orm.md#ormer)
-4. [对象操作](Object.md)
-5. [复杂查询](Query.md)
-	- [查询使用的表达式语法](Query.md#expr)
-	- [查询支持的操作符号](Query.md#operators)
-	- [QuerySeter 接口](Query.md#queryseter)
-6. Raw
-7. Transaction
+
+1. [Orm 使用方法](Orm.md)
+	- [数据库的设置](Orm.md#数据库的设置)
+	- [ORM 接口使用](Orm.md#orm-接口使用)
+2. [对象的CRUD操作](Object.md)
+3. [高级查询](Query.md)
+	- [使用的表达式语法](Query.md#expr)
+	- [支持的操作符号](Query.md#operators)
+	- [高级查询接口使用](Query.md#高级查询接口使用)
+4. [使用SQL语句进行查询](Raw.md)
+5. [事务处理](Transaction.md)
+6. [模型定义](Models.md)
+	- [Struct Tag 设置参数](Models.md#struct-tag-设置参数)
+	- [表关系设置](Models.md#表关系设置)
+	- [Struct Field 类型与数据库的对应](Models.md#struct-field-类型与数据库的对应)
+7. Custom Fields
 8. Faq
diff --git a/orm/docs/zh/Raw.md b/orm/docs/zh/Raw.md
new file mode 100644
index 00000000..c01e5467
--- /dev/null
+++ b/orm/docs/zh/Raw.md
@@ -0,0 +1,108 @@
+## 使用SQL语句进行查询
+
+使用 Raw SQL 查询，无需使用 ORM 表定义
+
+创建一个 **RawSeter**
+
+```go
+o := NewOrm()
+var r RawSeter
+r = o.Raw("UPDATE user SET name = ? WHERE name = ?", "testing", "slene")
+```
+
+* type RawSeter interface {
+	* [Exec() (int64, error)](#exec)
+	* [QueryRow(...interface{}) error](#queryrow)
+	* [QueryRows(...interface{}) (int64, error)](#queryrows)
+	* [SetArgs(...interface{}) RawSeter](#setargs)
+	* [Values(*[]Params) (int64, error)](#values)
+	* [ValuesList(*[]ParamsList) (int64, error)](#valueslist)
+	* [ValuesFlat(*ParamsList) (int64, error)](#valuesflat)
+	* [Prepare() (RawPreparer, error)](#prepare)
+* }
+
+#### Exec
+
+执行sql语句
+
+```go
+num, err := r.Exec()
+```
+
+#### QueryRow
+
+TODO
+
+#### QueryRows
+
+TODO
+
+#### SetArgs
+
+改变 Raw(sql, args...) 中的 args 参数，返回一个新的 RawSeter
+
+用于单条 sql 语句，重复利用，替换参数然后执行。
+
+```go
+num, err := r.SetArgs("set name", "name1").Exec()
+num, err := r.SetArgs("set name", "name2").Exec()
+```
+#### Values / ValuesList / ValuesFlat
+
+Raw SQL 查询获得的结果集 Value 为 `string` 类型，NULL 字段的值为空 ``
+
+#### Values
+
+
+返回结果集的 key => value 值
+
+```go
+var maps []orm.Params
+num, err = o.Raw("SELECT user_name FROM user WHERE status = ?", 1).Values(&maps)
+if err == nil && num > 0 {
+	fmt.Println(maps[0]["user_name"]) // slene
+}
+```
+
+#### ValuesList
+
+返回结果集 slice
+
+```go
+var lists []orm.ParamsList
+num, err = o.Raw("SELECT user_name FROM user WHERE status = ?", 1).ValuesList(&lists)
+if err == nil && num > 0 {
+	fmt.Println(lists[0][0]) // slene
+}
+```
+
+#### ValuesFlat
+
+返回单一字段的平铺 slice 数据
+
+```go
+var list orm.ParamsList
+num, err = o.Raw("SELECT id FROM user WHERE id < ?", 10).ValuesList(&list)
+if err == nil && num > 0 {
+	fmt.Println(list) // []{"1","2","3",...}
+}
+```
+
+#### Prepare
+
+用于一次 prepare 多次 exec，以提高批量执行的速度。
+
+```go
+p, err := o.Raw("UPDATE user SET name = ? WHERE name = ?").Prepare()
+num, err := p.Exec("testing", "slene")
+num, err  = p.Exec("testing", "astaxie")
+...
+...
+p.Close() // 别忘记关闭 statement
+```
+
+## FAQ
+
+1. 我的 app 需要支持多类型数据库，如何在使用 Raw SQL 的时候判断当前使用的数据库类型。
+
+使用 Ormer 的 [Driver方法](Orm.md#driver) 可以进行判断
diff --git a/orm/docs/zh/Transaction.md b/orm/docs/zh/Transaction.md
new file mode 100644
index 00000000..2742529c
--- /dev/null
+++ b/orm/docs/zh/Transaction.md
@@ -0,0 +1,3 @@
+## 事务处理
+
+