查询构造器

5.6

8.x 7.x 6.x 5.8 5.7 5.6 5.5 5.4 5.3 5.2 5.1

Laravel 5.6 中文文档 /

本文档最新版为 8.x，旧版本可能放弃维护，推荐阅读最新版！

数据库: 查询构造器

简介
获取结果
- 分块结果
- 聚合
查询
原生表达式
Joins
Unions
Where 语句
Ordering, Grouping, Limit, & Offset
条件语句
插入
更新
- 更新 JSON
- 自增与自减
Deletes
悲观锁

简介

Laravel 的数据库查询构造器为创建和运行数据库查询提供了一个方便的接口。它能用来执行应用程序中的大部分数据库操作，且可在所有支持的数据库系统上运行。

Laravel 的查询构造器使用 PDO 参数绑定来保护您的应用程序免受 SQL 注入攻击。因此没有必要清理作为绑定传递的字符串。

获取结果

从数据表中获取所有行

你可以 DB facade 上使用 table 方法来开始查询。该 table 方法为给定的表返回一个查询构造器实例，允许你在查询上链式调用更多的约束，最后使用 get 方法获取结果：

<?php

namespace App\Http\Controllers;

use Illuminate\Support\Facades\DB;
use App\Http\Controllers\Controller;

class UserController extends Controller
{
    /**
     * 显示所有应用程序用户的列表
     *
     * @return Response
     */
    public function index()
    {
        $users = DB::table('users')->get();

        return view('user.index', ['users' => $users]);
    }
}

该 get 方法返回一个包含 Illuminate\Support\Collection 的结果，其中每个结果都是 PHP StdClass 对象的一个实例。你可以访问字段作为对象的属性来访问每列的值：

foreach ($users as $user) {
    echo $user->name;
}

从数据表中获取单行或列

如果你只需要从数据表中检索一行数据，你可以使用 first 方法。该方法返回一个 StdClass 对象：

$user = DB::table('users')->where('name', 'John')->first();

echo $user->name;

如果你甚至不需要整行数据，可以使用 value 方法从记录中获取单个值。该方法将直接返回字段的值：

$email = DB::table('users')->where('name', 'John')->value('email');

获取一列的值

如果你想获取包含单列值的集合，你可以使用 pluck 方法。在下面的例子中，我们将获取角色表中标题的集合：

$titles = DB::table('roles')->pluck('title');

foreach ($titles as $title) {
    echo $title;
}

你也可以在返回的集合中指定字段的自定义键值：

$roles = DB::table('roles')->pluck('title', 'name');

foreach ($roles as $name => $title) {
    echo $title;
}

分块结果

如果你需要处理数千条数据库记录，可以考虑使用 chunk 方法。该方法每次只取出一小块结果，并将取出的结果传递给 闭包 处理。这对于编写数千条记录的 Artisan 命令而言是非常有用的。例如，一次处理 users 表中的 100 条记录：

DB::table('users')->orderBy('id')->chunk(100, function ($users) {
    foreach ($users as $user) {
        //
    }
});

你可以从 闭包 中返回 false 来阻止进一步的分块结果：

DB::table('users')->orderBy('id')->chunk(100, function ($users) {
    // Process the records...

    return false;
});

聚合

查询构造器还提供了各种聚合方法，例如 count， max， min， avg，和 sum。你可以在查询后调用任何方法：

$users = DB::table('users')->count();

$price = DB::table('orders')->max('price');

当然。你也可以将这些方法和其他语句结合起来：

$price = DB::table('orders')
                ->where('finalized', 1)
                ->avg('price');

确定记录是否存在

不要使用 count 方法来确定是否存在与查询相匹配的记录，应该使用 exists 和 doesntExist 方法：

return DB::table('orders')->where('finalized', 1)->exists();

return DB::table('orders')->where('finalized', 1)->doesntExist();

Selects

指定一个 Select 语句

当然你可能并不总是希望从数据库表中获取所有列。使用 select 方法，你可以自定义一个 select 语句来查询指定的字段:

$users = DB::table('users')->select('name', 'email as user_email')->get();

distinct允许你强制让查询返回不重复的结果：

$users = DB::table('users')->distinct()->get();

如果你已有一个查询构造器实例，并且希望在现有的 select 语句中加入一个字段，则可以 addSelect 方法：

$query = DB::table('users')->select('name');

$users = $query->addSelect('age')->get();

原生表达式

有时候你可能需要在查询中使用原生表达式。创建一个原生表达式，你可以使用 DB::raw 方法：

$users = DB::table('users')
                     ->select(DB::raw('count(*) as user_count, status'))
                     ->where('status', '<>', 1)
                     ->groupBy('status')
                     ->get();

{note} 原生表达式将会被当做字符串注入到查询中，因此你应该小心使用，避免创建 SQL 注入漏洞。

原生方法

可以使用以下的方法代替 DB::raw 将原生表达式插入查询的各个部分。

`selectRaw`

selectRaw 方法可以用来代替 select(DB::raw(...))。这个方法的第二个参数接受一个可选的绑定参数数组：

$orders = DB::table('orders')
                ->selectRaw('price * ? as price_with_tax', [1.0825])
                ->get();

`whereRaw / orWhereRaw`

可以使用 whereRaw 和 orWhereRaw 方法将原生的 where 注入到你的查询中。这些方法接受一个可选的绑定数组作为他们的第二个参数：

$orders = DB::table('orders')
                ->whereRaw('price > IF(state = "TX", ?, 100)', [200])
                ->get();

`havingRaw / orHavingRaw`

havingRaw 和 orHavingRaw 方法可用于将原生字符串设置为 having 语句的值：

$orders = DB::table('orders')
                ->select('department', DB::raw('SUM(price) as total_sales'))
                ->groupBy('department')
                ->havingRaw('SUM(price) > 2500')
                ->get();

`orderByRaw`

orderByRaw 方法可用于将原生字符串设置为 order by 子句的值：

$orders = DB::table('orders')
                ->orderByRaw('updated_at - created_at DESC')
                ->get();

Joins

Inner Join 语句

查询构造器也可编写 join 语句。若要执行基本的「内链接」，你可以在查询构造器实例上使用 join 方法。传递给 join 方法的第一个参数是你需要连接的表的名称，而其它参数则用来指定连接的字段约束。你还可以在单个查询中连接多个数据表：

$users = DB::table('users')
            ->join('contacts', 'users.id', '=', 'contacts.user_id')
            ->join('orders', 'users.id', '=', 'orders.user_id')
            ->select('users.*', 'contacts.phone', 'orders.price')
            ->get();

Left Join 语句

如果你想使用「左连接」代替「内连接」，使用 leftJoin 方法。 leftJoin 方法与 join 方法用法相同：

$users = DB::table('users')
            ->leftJoin('posts', 'users.id', '=', 'posts.user_id')
            ->get();

Cross Join 语句

使用 crossJoin 方法和你想要交叉连接的表名来做「交叉连接」。交叉连接在第一个表和连接之间生成笛卡尔积：

$users = DB::table('sizes')
            ->crossJoin('colours')
            ->get();

高级 Join 语句

你可以指定更高级的 join 语句。比如传递一个 闭包 作为 join 方法的第二个参数。此 闭包 接收一个 JoinClause 对象，从而在其中指定 join 语句中指定约束：

DB::table('users')
        ->join('contacts', function ($join) {
            $join->on('users.id', '=', 'contacts.user_id')->orOn(...);
        })
        ->get();

如果你想要在连接上使用「where」风格的语句，可以在连接上使用 where 和 orWhere 方法。这些方法会将列和值进行比较而不是列和列进行比较：

DB::table('users')
        ->join('contacts', function ($join) {
            $join->on('users.id', '=', 'contacts.user_id')
                 ->where('contacts.user_id', '>', 5);
        })
        ->get();

Unions

查询构造器还提供了将两个查询「联合」起来的快捷方式。比如，你可以先创建一个查询，然后使用 union 方法将其和第二个查询进行联合：

$first = DB::table('users')
            ->whereNull('first_name');

$users = DB::table('users')
            ->whereNull('last_name')
            ->union($first)
            ->get();

{tip} unionAll 方法也是可用的，并且和 union 方法用法相同。

Where 语句

简单的 Where 语句

使用查询构建器上的 where 方法可以添加 where 子句到查询中。调用 where 最基本的方式需要传递三个参数，第一个参数是列名，第二个参数是任意一个数据库系统支持的运算符，第三个参数是该列要比较的值。

例如，下面是一个要验证「votes」字段的值等于 100 的查询：

$users = DB::table('users')->where('votes', '=', 100)->get();

为了方便，如果你只是简单比较列值和给定数值是否相等，可以将数值直接作为 where 方法的第二个参数：

$users = DB::table('users')->where('votes', 100)->get();

当然你还可以使用其他运算符来编写 where 子句：

$users = DB::table('users')
                ->where('votes', '>=', 100)
                ->get();

$users = DB::table('users')
                ->where('votes', '<>', 100)
                ->get();

$users = DB::table('users')
                ->where('name', 'like', 'T%')
                ->get();

还可以传递数组到 where 函数中：

$users = DB::table('users')->where([
    ['status', '=', '1'],
    ['subscribed', '<>', '1'],
])->get();

Or 语句

你可以一起链式调用 where，也可以在查询中添加 or 语句。 orWhere 方法接受与 where 方法相同的参数：

$users = DB::table('users')
                    ->where('votes', '>', 100)
                    ->orWhere('name', 'John')
                    ->get();

其他 Where 语句

whereBetween

whereBetween 方法验证字段的值位于两个值之间：

$users = DB::table('users')
                    ->whereBetween('votes', [1, 100])->get();

whereNotBetween

whereNotBetween 方法验证字段的值位于两个值之外：

$users = DB::table('users')
                    ->whereNotBetween('votes', [1, 100])
                    ->get();

whereIn / whereNotIn

whereIn 方法验证字段的值在指定的数组内：

$users = DB::table('users')
                    ->whereIn('id', [1, 2, 3])
                    ->get();

whereNotIn 方法验证字段的值不在指定的数组内：

$users = DB::table('users')
                    ->whereNotIn('id', [1, 2, 3])
                    ->get();

whereNull / whereNotNull

whereNull 方法验证字段的值为 NULL：

$users = DB::table('users')
                    ->whereNull('updated_at')
                    ->get();

whereNotNull 方法验证字段的值不为 NULL：

$users = DB::table('users')
                    ->whereNotNull('updated_at')
                    ->get();

whereDate / whereMonth / whereDay / whereYear / whereTime

whereDate 方法用于比较字段的值和日期：

$users = DB::table('users')
                ->whereDate('created_at', '2016-12-31')
                ->get();

whereMonth 方法用于比较字段的值与一年的特定月份：

$users = DB::table('users')
                ->whereMonth('created_at', '12')
                ->get();

whereDay 方法用于比较字段的值与一个月的特定日期：

$users = DB::table('users')
                ->whereDay('created_at', '31')
                ->get();

whereYear 方法用于比较字段的值与特定年份：

$users = DB::table('users')
                ->whereYear('created_at', '2016')
                ->get();

whereTime 用于将字段的值与特定的时间进行比较：

$users = DB::table('users')
                ->whereTime('created_at', '=', '11:20')
                ->get();

whereColumn

whereColumn 方法用于验证两个字段是否相等：

$users = DB::table('users')
                ->whereColumn('first_name', 'last_name')
                ->get();

还可以将比较运算符传递给该方法：

$users = DB::table('users')
                ->whereColumn('updated_at', '>', 'created_at')
                ->get();

还可以传递多条件数组到 whereColumn 方法，这些条件通过 and 运算符连接：

$users = DB::table('users')
                ->whereColumn([
                    ['first_name', '=', 'last_name'],
                    ['updated_at', '>', 'created_at']
                ])->get();

参数分组

有时候你需要创建更高级的 where 子句，例如「where exists」或者嵌套的参数分组。 Laravel 的查询构造器也能够处理这些。下面，让我们看一个在括号中进行分组约束的例子：

DB::table('users')
            ->where('name', '=', 'John')
            ->orWhere(function ($query) {
                $query->where('votes', '>', 100)
                      ->where('title', '<>', 'Admin');
            })
            ->get();

正如你所看到的，传递 闭包 到 orWhere 方法构造查询构建器来开始一个约束分组。该 闭包 接受一个查询构造器实例，上述语句等价于下面的 SQL：

select * from users where name = 'John' or (votes > 100 and title <> 'Admin')

Where Exists 语句

whereExists 方法允许你编写 where exists SQL 语句。该 whereExists 方法接受一个 Closure 参数，该闭包获取一个查询构建器实例从而允许你定义放置在 "exists" 字句中查询：

DB::table('users')
            ->whereExists(function ($query) {
                $query->select(DB::raw(1))
                      ->from('orders')
                      ->whereRaw('orders.user_id = users.id');
            })
            ->get();

上述查询等价于下面的 SQL 语句：

select * from users
where exists (
    select 1 from orders where orders.user_id = users.id
)

JSON Where 语句

Laravel 也支持查询 JSON 类型的字段（仅在对 JSON 类型支持的数据库上）。目前，本特性仅支持 MySQL 5.7+ 和 Postgres数据库。使用 -> 操作符查询 JSON 数据：

$users = DB::table('users')
                ->where('options->language', 'en')
                ->get();

$users = DB::table('users')
                ->where('preferences->dining->meal', 'salad')
                ->get();

Ordering, Grouping, Limit, & Offset

orderBy

orderBy 方法允许你通过给定字段对结果集进行排序。 orderBy 的第一个参数应该是你希望排序的字段，第二个参数控制排序的方向，可以是 asc 或 desc：

$users = DB::table('users')
                ->orderBy('name', 'desc')
                ->get();

latest / oldest

latest 和 oldest 方法允许你通过日期对结果进行排序。默认情况下，结果集根据 created_at 列进行排序。或者，你可以按照你想要排序的字段作为字段名传入：

$user = DB::table('users')
                ->latest()
                ->first();

inRandomOrder

inRandomOrder 方法可以将查询结果随机排序。例如，你可以使用这个方法获取一个随机用户：

$randomUser = DB::table('users')
                ->inRandomOrder()
                ->first();

groupBy / having

groupBy 和 having 方法对查询结果进行分组。 having 方法的用法与 where 方法类似：

$users = DB::table('users')
                ->groupBy('account_id')
                ->having('account_id', '>', 100)
                ->get();

可以将多个参数传递给 groupBy 方法，按多个字段进行分组：

$users = DB::table('users')
                ->groupBy('first_name', 'status')
                ->having('account_id', '>', 100)
                ->get();

关于 having 更高级的用法，请查看 havingRaw 方法。

skip / take

想要限定查询返回的结果集的数目，或者在查询中跳过给定数目的结果，可以使用 skip 和 take 方法：

$users = DB::table('users')->skip(10)->take(5)->get();

或者，你也可以使用 limit 和 offset 方法：

$users = DB::table('users')
                ->offset(10)
                ->limit(5)
                ->get();

条件语句

有时你可能想要子句只适用于某个情况为真时才执行查询。例如，你可能只想给定值在请求中存在的情况下才应用 where 语句。你可以通过使用 when 方法：

$role = $request->input('role');

$users = DB::table('users')
                ->when($role, function ($query) use ($role) {
                    return $query->where('role_id', $role);
                })
                ->get();

when 方法只有在第一个参数为 true 的时候才执行给定闭包。如果第一个参数为 false，那么这个闭包将不会被执行。

你可以传递另一个闭包作为 when 方法的第三个参数。该闭包会在第一个参数为 false 的情况下执行。为了演示这个特性如何使用，我们来配置一个查询的默认排序：

$sortBy = null;

$users = DB::table('users')
                ->when($sortBy, function ($query) use ($sortBy) {
                    return $query->orderBy($sortBy);
                }, function ($query) {
                    return $query->orderBy('name');
                })
                ->get();

插入

查询构造器还提供了 insert 方法用于插入记录到数据库中。 insert 方法接收数组形式的字段名和字段值进行插入操作：

DB::table('users')->insert(
    ['email' => 'john@example.com', 'votes' => 0]
);

你还可以在 insert 中传入一个嵌套数组向表中插入多条记录。每个数组代表要插入表中的行：

DB::table('users')->insert([
    ['email' => 'taylor@example.com', 'votes' => 0],
    ['email' => 'dayle@example.com', 'votes' => 0]
]);

自增 ID

如果数据表有自增ID，使用 insertGetId 方法来插入记录并返回ID值：

$id = DB::table('users')->insertGetId(
    ['email' => 'john@example.com', 'votes' => 0]
);

{note} 当使用 PostgreSQL 时，insertGetId 方法将默认把 id 作为自动递增字段的名称。若你要从其他「序列」来获取 ID，则可以将字段名称作为第二个参数传递给 insertGetId 方法。

更新

当然，除了插入记录到数据库中，查询构造器也可通过 update 方法更新已有的记录。 update 方法和 insert 方法一样，接受包含要更新的字段及值的数组。你可以通过 where 子句对 update 查询进行约束：

DB::table('users')
            ->where('id', 1)
            ->update(['votes' => 1]);

更新 JSON 字段

更新 JSON 字段时，你可以使用 -> 语法访问 JSON 对象上相应的值，该操作只能用于支持 JSON 字段类型的数据库：

DB::table('users')
            ->where('id', 1)
            ->update(['options->enabled' => true]);

自增与自减

查询构造器还为给定字段的递增或递减提供了方便的方法。此方法提供了一个比手动编写 update 语句更具表达力且更精练的接口。

这两个方法都至少接收一个参数：需要修改的列。第二个参数是可选的，用于控制列递增或递减的量。

DB::table('users')->increment('votes');

DB::table('users')->increment('votes', 5);

DB::table('users')->decrement('votes');

DB::table('users')->decrement('votes', 5);

你也可以在操作过程中指定要更新的字段：

DB::table('users')->increment('votes', 1, ['name' => 'John']);

Deletes

查询构造器也可以使用 delete 方法从数据表中删除记录。在使用 delete 前，可添加 where 子句来约束 delete 语法：

DB::table('users')->delete();

DB::table('users')->where('votes', '>', 100)->delete();

如果你需要清空表，你可以使用 truncate 方法，这将删除所有行，并重置自增 ID 为零：

DB::table('users')->truncate();

悲观锁

查询构造器也包含一些可以帮助你在 select 语法上实现「悲观锁定」的函数。若想在查询中实现一个「共享锁」，你可以使用 sharedLock 方法。共享锁可防止选中的数据列被篡改，直到事务被提交为止：

DB::table('users')->where('votes', '>', 100)->sharedLock()->get();

另外，你也可以使用 lockForUpdate 方法。使用「更新」锁可避免行被其它共享锁修改或选取：

DB::table('users')->where('votes', '>', 100)->lockForUpdate()->get();

本文章首发在网站上。

查询构造器 5.6 8.x 7.x 6.x 5.8 5.7 5.6 5.5 5.4 5.3 5.2 5.1

数据库: 查询构造器

简介

获取结果

从数据表中获取所有行

从数据表中获取单行或列

获取一列的值

分块结果

聚合

确定记录是否存在

Selects

指定一个 Select 语句

原生表达式

原生方法

selectRaw

whereRaw / orWhereRaw

havingRaw / orHavingRaw

orderByRaw

Joins

Inner Join 语句

Left Join 语句

Cross Join 语句

高级 Join 语句

Unions

Where 语句

简单的 Where 语句

Or 语句

其他 Where 语句

参数分组

Where Exists 语句

JSON Where 语句

Ordering, Grouping, Limit, & Offset

orderBy

latest / oldest

inRandomOrder

groupBy / having

skip / take

条件语句

插入

自增 ID

更新

更新 JSON 字段

自增与自减

Deletes

悲观锁

查询构造器

5.6

8.x 7.x 6.x 5.8 5.7 5.6 5.5 5.4 5.3 5.2 5.1

`selectRaw`

`whereRaw / orWhereRaw`

`havingRaw / orHavingRaw`

`orderByRaw`