# QuerySeter 复杂查询

ORM 以 QuerySeter 来组织查询，每个返回 QuerySeter 的方法都会获得一个新的 QuerySeter 对象。

基本使用方法:

o := orm.NewOrm()

// 获取 QuerySeter 对象，user 为表名
qs := o.QueryTable("user")

// 也可以直接使用 Model 结构体作为表名
qs = o.QueryTable(&User)

// 也可以直接使用对象作为表名
user := new(User)
qs = o.QueryTable(user) // 返回 QuerySeter

// 后面可以调用qs上的方法，执行复杂查询。

QuerySeter的方法大体上可以分成两类：

中间方法：用于构造查询
终结方法：用于执行查询并且封装结果

每个返回 QuerySeter 的 api 调用时都会新建一个 QuerySeter，不影响之前创建的。
高级查询使用 Filter 和 Exclude 来做常用的条件查询。囊括两种清晰的过滤规则：包含，排除

# 查询表达式

Beego 设计了自己的查询表达式，这些表达式可以用在很多方法上。

一般来说，你可以对单表的字段使用表达式，也可以在关联表上使用表达式。例如单个使用：

qs.Filter("id", 1) // WHERE id = 1

或者在关联表里面使用：

qs.Filter("profile__age", 18) // WHERE profile.age = 18
qs.Filter("Profile__Age", 18) // 使用字段名和 Field 名都是允许的
qs.Filter("profile__age__gt", 18) // WHERE profile.age > 18
// WHERE profile.age IN (18, 20) AND NOT profile_id < 1000

字段组合的前后顺序依照表的关系，比如 User 表拥有 Profile 的外键，那么对 User 表查询对应的 Profile.Age 为条件，则使用 Profile__Age 注意，字段的分隔符号使用双下划线 __。

除了描述字段，表达式的尾部可以增加操作符以执行对应的 sql 操作。比如 Profile__Age__gt 代表 Profile.Age > 18 的条件查询。在没有指定操作符的情况下，会使用=作为操作符。

当前支持的操作符号：

exact / iexact 等于
contains / icontains 包含
gt / gte 大于 / 大于等于
lt / lte 小于 / 小于等于
startswith / istartswith 以...起始
endswith / iendswith 以...结束
in
isnull

后面以 i 开头的表示：大小写不敏感

# exact

Filter / Exclude / Condition expr 的默认值

qs.Filter("name", "slene") // WHERE name = 'slene'
qs.Filter("name__exact", "slene") // WHERE name = 'slene'
// 使用 = 匹配，大小写是否敏感取决于数据表使用的 collation
qs.Filter("profile_id", nil) // WHERE profile_id IS NULL

# iexact

qs.Filter("name__iexact", "slene")
// WHERE name LIKE 'slene'
// 大小写不敏感，匹配任意 'Slene' 'sLENE'

# contains

qs.Filter("name__contains", "slene")
// WHERE name LIKE BINARY '%slene%'
// 大小写敏感, 匹配包含 slene 的字符

# icontains

qs.Filter("name__icontains", "slene")
// WHERE name LIKE '%slene%'
// 大小写不敏感, 匹配任意 'im Slene', 'im sLENE'

# in

qs.Filter("age__in", 17, 18, 19, 20)
// WHERE age IN (17, 18, 19, 20)


ids:=[]int{17,18,19,20}
qs.Filter("age__in", ids)
// WHERE age IN (17, 18, 19, 20)

// 同上效果

# gt / gte

qs.Filter("profile__age__gt", 17)
// WHERE profile.age > 17

qs.Filter("profile__age__gte", 18)
// WHERE profile.age >= 18

# lt / lte

qs.Filter("profile__age__lt", 17)
// WHERE profile.age < 17

qs.Filter("profile__age__lte", 18)
// WHERE profile.age <= 18

# startswith

qs.Filter("name__startswith", "slene")
// WHERE name LIKE BINARY 'slene%'
// 大小写敏感, 匹配以 'slene' 起始的字符串

# istartswith

qs.Filter("name__istartswith", "slene")
// WHERE name LIKE 'slene%'
// 大小写不敏感, 匹配任意以 'slene', 'Slene' 起始的字符串

# endswith

qs.Filter("name__endswith", "slene")
// WHERE name LIKE BINARY '%slene'
// 大小写敏感, 匹配以 'slene' 结束的字符串

# iendswith

qs.Filter("name__iendswithi", "slene")
// WHERE name LIKE '%slene'
// 大小写不敏感, 匹配任意以 'slene', 'Slene' 结束的字符串

# isnull

qs.Filter("profile__isnull", true)
qs.Filter("profile_id__isnull", true)
// WHERE profile_id IS NULL

qs.Filter("profile__isnull", false)
// WHERE profile_id IS NOT NULL

# 中间方法

# Filter

Filter(string, ...interface{}) QuerySeter

多次调用Filter方法，会使用AND将它们连起来。

qs.Filter("profile__isnull", true).Filter("name", "slene")
// WHERE profile_id IS NULL AND name = 'slene'

# FilterRaw

FilterRaw(string, string) QuerySeter

该方法会直接把输入当做是一个查询条件，因此如果输入有错误，那么拼接得来的 SQL 则无法运行。Beego 本身并不会执行任何的检查。

例如：

qs.FilterRaw("user_id IN (SELECT id FROM profile WHERE age>=18)")
//sql-> WHERE user_id IN (SELECT id FROM profile WHERE age>=18)

# Exclude

Exclude(string, ...interface{}) QuerySeter

准确来说，Exclude表达的是NOT的语义：

qs.Filter("profile__age__in", 18, 20).Exclude("profile__lt", 1000)
// WHERE profile.age IN (18, 20) AND NOT profile_id < 1000

# SetCond

SetCond(*Condition) QuerySeter

设置查询条件：

cond := orm.NewCondition()
cond1 := cond.And("profile__isnull", false).AndNot("status__in", 1).Or("profile__age__gt", 2000)
//sql-> WHERE T0.`profile_id` IS NOT NULL AND NOT T0.`Status` IN (?) OR T1.`age` >  2000
num, err := qs.SetCond(cond1).Count()

Condition中使用的表达式，可以参考查询表达式

# GetCond

GetCond() *Condition

获得查询条件。例如：

 cond := orm.NewCondition()
 cond = cond.And("profile__isnull", false).AndNot("status__in", 1)
 qs = qs.SetCond(cond)
 cond = qs.GetCond()
 cond := cond.Or("profile__age__gt", 2000)
 //sql-> WHERE T0.`profile_id` IS NOT NULL AND NOT T0.`Status` IN (?) OR T1.`age` >  2000
 num, err := qs.SetCond(cond).Count()

# Limit

Limit(limit interface{}, args ...interface{}) QuerySeter

该方法第二个参数args实际上只是表达偏移量。也就是说：

如果你只传了limit，例如说 10，那么相当于LIMIT 10
如果你同时传了args 为 2，那么相当于 LIMIT 10 OFFSET 2，或者说LIMIT 2, 10

var DefaultRowsLimit = 1000 // ORM 默认的 limit 值为 1000

// 默认情况下 select 查询的最大行数为 1000
// LIMIT 1000

qs.Limit(10)
// LIMIT 10

qs.Limit(10, 20)
// LIMIT 10 OFFSET 20 注意跟 SQL 反过来的

qs.Limit(-1)
// no limit

qs.Limit(-1, 100)
// LIMIT 18446744073709551615 OFFSET 100
// 18446744073709551615 是 1<<64 - 1 用来指定无 limit 限制 但有 offset 偏移的情况

如果你没有调用该方法，或者调用了该方法，但是传入了一个负数，Beego 会使用默认的值，例如 1000。

# Offset

Offset(offset interface{}) QuerySeter

设置偏移量，等同于Limit方法的第二个参数。

# GroupBy

GroupBy(exprs ...string) QuerySeter

设置分组，参数是列名。

# OrderBy

OrderBy(exprs ...string) QuerySeter

设置排序，使用的是一种特殊的表达：

如果传入的是列名，那么代表的是按照列名 ASC 排序；
如果传入的列名前面有一个负号，那么代表的是按照列名 DESC 排序；

例如：

// ORDER BY STATUS DESC
qs.OrderBy("-status")
// ORDER BY ID ASC, STATUS DESC
qs.OrderBy("id", "-status")

同样地，也可以使用查询表达式，例如：

qs.OrderBy("id", "-profile__age")
// ORDER BY id ASC, profile.age DESC

qs.OrderBy("-profile__age", "profile")
// ORDER BY profile.age DESC, profile_id ASC

# ForceIndex

qs.ForceIndex(`idx_name1`,`idx_name2`)

强制使用某个索引。你需要确认自己使用的数据库支持该特性，并且确认该特性在数据库上的语义。

参数是索引的名字。

# UseIndex

UseIndex(indexes ...string) QuerySeter

使用某个索引。你需要确认自己使用的数据库支持该特性，并且确认该特性在数据库上的语义。比如说在一些数据库上，该特性是“建议使用某个索引”，但是数据库在真实执行查询的时候，完全可能不使用这里指定的索引。

参数是索引的名字。

# IgnoreIndex

IgnoreIndex(indexes ...string) QuerySeter

忽略某个索引。你需要确认自己使用的数据库支持该特性，并且确认该特性在数据库上的语义。比如说在一些数据库上，该特性是“建议不使用某个索引”，但是数据库在真实执行查询的时候，完全可能使用这里指定的索引。

参数是索引的名字。

# RelatedSel

RelatedSel(params ...interface{}) QuerySeter

加载关联表的数据。如果没有传入参数，那么 Beego 加载所有关联表的数据。而如果传入了参数，那么只会加载特定的关联表数据。

在加载的时候，如果对应的字段是可以为 NULL 的，那么会使用 LEFT JOIN，否则使用 JOIN。

例如：

// 使用 LEFT JOIN 加载 user 里面的所有关联表数据
qs.RelatedSel().One(&user)
// 使用 LEFT JOIN 只加载 user 里面 profile 的数据
qs.RelatedSel("profile").One(&user)
user.Profile.Age = 32

默认情况下直接调用 RelatedSel 将进行最大DefaultRelsDepth层的关系查询

# Distinct

Distinct() QuerySeter

为查询加上 DISTINCT 关键字

# ForUpdate

ForUpdate() QuerySeter

为查询加上 FOR UPDATE 片段。

# PrepareInsert

PrepareInsert() (Inserter, error)

用于一次 prepare 多次 insert 插入，以提高批量插入的速度。

var users []*User
...
qs := o.QueryTable("user")
i, _ := qs.PrepareInsert()
for _, user := range users {
	id, err := i.Insert(user)
	if err == nil {
		...
	}
}
// PREPARE INSERT INTO user (`name`, ...) VALUES (?, ...)
// EXECUTE INSERT INTO user (`name`, ...) VALUES ("slene", ...)
// EXECUTE ...
// ...
i.Close() // 别忘记关闭 statement

# Aggregate

Aggregate(s string) QuerySeter

指定聚合函数。例如：

type result struct {
  DeptName string
  Total    int
}
var res []result
o.QueryTable("dept_info").Aggregate("dept_name,sum(salary) as total").GroupBy("dept_name").All(&res)

# 终结方法

# Count

Count() (int64, error)

执行查询并且返回结果集的大小。

# Exist

Exist() bool

判断查询是否返回数据。等效于Count() 返回大于 0 的值。

# Update

Update(values Params) (int64, error)

依据当前查询条件，进行批量更新操作。

num, err := o.QueryTable("user").Filter("name", "slene").Update(orm.Params{
	"name": "astaxie",
})
fmt.Printf("Affected Num: %s, %s", num, err)
// SET name = "astaixe" WHERE name = "slene"

原子操作增加字段值

// 假设 user struct 里有一个 nums int 字段
num, err := o.QueryTable("user").Update(orm.Params{
	"nums": orm.ColValue(orm.ColAdd, 100),
})
// SET nums = nums + 100

orm.ColValue 支持以下操作

ColAdd      // 加
ColMinus    // 减
ColMultiply // 乘
ColExcept   // 除

# Delete

Delete() (int64, error)

删除数据，返回被删除的数据行数。

# All

All(container interface{}, cols ...string) (int64, error)

返回对应的结果集对象。参数支持 *[]Type 和 *[]*Type 两种形式的切片

var users []*User
num, err := o.QueryTable("user").Filter("name", "slene").All(&users)
fmt.Printf("Returned Rows Num: %s, %s", num, err)

All / Values / ValuesList / ValuesFlat 受到 Limit 的限制，默认最大行数为 1000

可以指定返回的字段：

type Post struct {
	Id      int
	Title   string
	Content string
	Status  int
}

// 只返回 Id 和 Title
var posts []Post
o.QueryTable("post").Filter("Status", 1).All(&posts, "Id", "Title")

对象的其他字段值将会是对应类型的默认值。

# One

One(container interface{}, cols ...string) error

尝试返回单条记录：

var user User
err := o.QueryTable("user").Filter("name", "slene").One(&user)
if err == orm.ErrMultiRows {
	// 多条的时候报错
	fmt.Printf("Returned Multi Rows Not One")
}
if err == orm.ErrNoRows {
	// 没有找到记录
	fmt.Printf("Not row found")
}

# Values

Values(results *[]Params, exprs ...string) (int64, error)

返回结果集的 key => value 值

key 为模型里的字段名, value 是interface{}类型,例如，如果你要将 value 赋值给 struct 中的某字段，需要根据结构体对应字段类型使用断言 (opens new window)获取真实值。:Name : m["Name"].(string)

var maps []orm.Params
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["Name"])
	}
}

TODO: 暂不支持级联查询 RelatedSel 直接返回 Values

第二个参数可以是列名，也可以是查询表达式：

var maps []orm.Params
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["Name"], m["Profile"], m["Profile__Age"])
		// map 中的数据都是展开的，没有复杂的嵌套
	}
}

# ValuesList

ValuesList(results *[]ParamsList, exprs ...string) (int64, error)

顾名思义，返回的结果集以切片存储，其排列与模型中定义的字段顺序一致，每个元素值是 string 类型。

var lists []orm.ParamsList
num, err := o.QueryTable("user").ValuesList(&lists)
if err == nil {
	fmt.Printf("Result Nums: %d\n", num)
	for _, row := range lists {
		fmt.Println(row)
	}
}

当然也可以指定查询表达式返回指定的字段：

var lists []orm.ParamsList
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("Name: %s, Age: %s\m", row[0], row[1])
	}
}

# ValuesFlat

ValuesFlat(result *ParamsList, expr string) (int64, error)

只返回特定的字段的值，将结果集展开到单个切片里。

var list orm.ParamsList
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, ", "))
}

# RowsToMap 和 RowsToStruct

这两个方法都没有实现。

← QueryBuilder 构造复杂查询原生查询 →