查询构造器

13.x

13.x 12.x 11.x 10.x 9.x 8.5 8.x 7.x 6.x 5.8 5.7 5.6 5.5 5.4 5.3 5.2 5.1

Laravel 13 中文文档 /

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

数据库：查询构建器

简介
运行数据库查询
Select 语句
原始表达式
联接
并集
基本 Where 子句
高级 Where 子句
排序、分组、条数限制和偏移量
条件子句
插入语句
- 插入或更新
更新语句
- 更新 JSON 列
- 自增与自减
删除语句
悲观锁
可复用的查询组件
调试

简介

Laravel 的数据库查询构建器提供了便捷的链式接口，用于创建和运行数据库查询。它可以执行应用中的大多数数据库操作，并且兼容 Laravel 支持的所有数据库系统。

Laravel 查询构建器使用 PDO 参数绑定来保护应用免受 SQL 注入攻击。作为查询绑定传给查询构建器的字符串，无需额外清理或过滤。

[!WARNING]
PDO 不支持绑定列名。因此，切勿让用户输入决定查询中引用的列名，包括「order by」子句中的列名。

运行数据库查询

从表中获取所有行

你可以使用 DB 门面的 table 方法开始查询。该方法会为指定表返回一个查询构建器实例，你可以链式添加更多约束，最后通过 get 方法获取查询结果：

<?php

namespace App\Http\Controllers;

use Illuminate\Support\Facades\DB;
use Illuminate\View\View;

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

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

get 方法返回包含查询结果的 Illuminate\Support\Collection 实例，其中每项结果都是 PHP stdClass 对象。你可以通过对象上与列同名的属性访问各列的值：

use Illuminate\Support\Facades\DB;

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

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

[!NOTE]
Laravel 集合提供了多种强大的数据映射和归约方法。更多信息请参阅集合文档。

从表中获取单行或单列

如果只需从数据库表中获取一行，可以使用 DB 门面的 first 方法。该方法会返回单个 stdClass 对象：

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

return $user->email;

如果希望获取单行，并在找不到匹配行时抛出 Illuminate\Database\RecordNotFoundException 异常，可以使用 firstOrFail 方法。如果未捕获 RecordNotFoundException，系统会自动向客户端返回 404 HTTP 响应：

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

如果不需要整行，可以使用 value 方法从记录中提取单个值。该方法会直接返回指定列的值：

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

要根据 id 列的值获取单行，请使用 find 方法：

$user = DB::table('users')->find(3);

获取单列值的列表

如果希望获取包含单列值的 Illuminate\Support\Collection 实例，可以使用 pluck 方法。下面的示例会获取用户 title 列的值集合：

use Illuminate\Support\Facades\DB;

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

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

你可以向 pluck 方法传入第二个参数，指定结果集合以哪一列的值作为键：

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

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

分块处理结果

如果需要处理数千条数据库记录，可以考虑使用 DB 门面的 chunk 方法。该方法每次获取一小块结果，并将其传给闭包处理。例如，下面会以每块 100 条记录的方式读取整个 users 表：

use Illuminate\Support\Collection;
use Illuminate\Support\Facades\DB;

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

在闭包中返回 false，即可停止处理后续分块：

DB::table('users')->orderBy('id')->chunk(100, function (Collection $users) {
    // 处理记录……

    return false;
});

如果在分块处理过程中更新数据库记录，分块结果可能发生意外变化。如果打算在分块处理时更新已获取的记录，最好改用 chunkById 方法。该方法会根据记录的主键自动对结果分页：

DB::table('users')->where('active', false)
    ->chunkById(100, function (Collection $users) {
        foreach ($users as $user) {
            DB::table('users')
                ->where('id', $user->id)
                ->update(['active' => true]);
        }
    });

由于 chunkById 和 lazyById 方法会向查询添加自己的「where」条件，通常应将你自己的条件放入闭包中进行逻辑分组：

DB::table('users')->where(function ($query) {
    $query->where('credits', 1)->orWhere('credits', 2);
})->chunkById(100, function (Collection $users) {
    foreach ($users as $user) {
        DB::table('users')
            ->where('id', $user->id)
            ->update(['credits' => 3]);
    }
});

[!WARNING]
在分块回调中更新或删除记录时，修改主键或外键可能影响分块查询，导致某些记录未被包含在分块结果中。

惰性流式处理结果

lazy 方法与 chunk 方法类似，都会分块执行查询。但 lazy() 不会将每个分块传给回调，而是返回一个 LazyCollection，让你可以像处理单个数据流一样处理结果：

use Illuminate\Support\Facades\DB;

DB::table('users')->orderBy('id')->lazy()->each(function (object $user) {
    // ...
});

同样，如果打算在遍历已获取的记录时更新它们，最好改用 lazyById 或 lazyByIdDesc 方法。这些方法会根据记录的主键自动对结果分页：

DB::table('users')->where('active', false)
    ->lazyById()->each(function (object $user) {
        DB::table('users')
            ->where('id', $user->id)
            ->update(['active' => true]);
    });

[!WARNING]
在遍历过程中更新或删除记录时，修改主键或外键可能影响分块查询，导致某些记录未被包含在结果中。

聚合

查询构建器还提供了多种获取聚合值的方法，例如 count、max、min、avg 和 sum。你可以在构建查询后调用这些方法：

use Illuminate\Support\Facades\DB;

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

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

你也可以将这些方法与其他子句结合，进一步控制聚合值的计算方式：

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

判断记录是否存在

要判断是否存在符合查询约束的记录，可以使用 exists 和 doesntExist 方法，无需使用 count：

if (DB::table('orders')->where('finalized', 1)->exists()) {
    // ...
}

if (DB::table('orders')->where('finalized', 1)->doesntExist()) {
    // ...
}

Select 语句

指定 Select 子句

你可能并不总是需要选择数据库表中的所有列。使用 select 方法，可以为查询指定自定义的「select」子句：

use Illuminate\Support\Facades\DB;

$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();

[!WARNING]
原始语句会以字符串的形式直接插入查询，因此务必谨慎，避免引入 SQL 注入漏洞。

原始表达式方法

除了 DB::raw，还可以使用以下方法将原始表达式插入查询的不同部分。请记住，Laravel 无法保证使用原始表达式的查询不受 SQL 注入攻击。

`selectRaw`

selectRaw 方法可以替代 addSelect(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();

`groupByRaw`

groupByRaw 方法可以将原始字符串用作 group by 子句：

$orders = DB::table('orders')
    ->select('city', 'state')
    ->groupByRaw('city, state')
    ->get();

联接

内联接子句

查询构建器也可以为查询添加联接子句。要执行基本的「内联接」，可以使用查询构建器实例的 join 方法。第一个参数是要联接的表名，其余参数用于指定联接的列约束。你甚至可以在单个查询中联接多个表：

use Illuminate\Support\Facades\DB;

$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();

左联接与右联接子句

如果要执行「左联接」或「右联接」，可以使用 leftJoin 或 rightJoin 方法。这些方法的签名与 join 相同：

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

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

交叉联接子句

你可以使用 crossJoin 方法执行「交叉联接」。交叉联接会生成第一个表与被联接表之间的笛卡尔积：

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

高级联接子句

你也可以指定更复杂的联接子句。将闭包作为 join 方法的第二个参数传入，闭包会接收一个 Illuminate\Database\Query\JoinClause 实例，让你可以为「join」子句指定约束：

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

如果要在联接中使用「where」子句，可以使用 JoinClause 实例的 where 和 orWhere 方法。这些方法会将列与值进行比较，而不是比较两个列：

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

子查询联接

你可以使用 joinSub、leftJoinSub 和 rightJoinSub 方法将查询与子查询联接。这些方法都接收三个参数：子查询、子查询的表别名，以及定义关联列的闭包。下面的示例会获取用户集合，每条用户记录还包含该用户最近发布的博客文章的 created_at 时间戳：

$latestPosts = DB::table('posts')
    ->select('user_id', DB::raw('MAX(created_at) as last_post_created_at'))
    ->where('is_published', true)
    ->groupBy('user_id');

$users = DB::table('users')
    ->joinSub($latestPosts, 'latest_posts', function (JoinClause $join) {
        $join->on('users.id', '=', 'latest_posts.user_id');
    })->get();

横向联接

[!WARNING]
目前，PostgreSQL、MySQL >= 8.0.14 和 SQL Server 支持横向联接。

你可以使用 joinLateral 和 leftJoinLateral 方法与子查询执行「横向联接」。这些方法都接收两个参数：子查询及其表别名。联接条件应在子查询的 where 子句中指定。横向联接会针对每一行求值，并且可以引用子查询外部的列。

下面的示例会获取用户集合及每个用户最近的三篇博客文章。每个用户在结果集中最多产生三行，每行对应其中一篇文章。联接条件在子查询中通过 whereColumn 子句指定，并引用当前用户行：

$latestPosts = DB::table('posts')
    ->select('id as post_id', 'title as post_title', 'created_at as post_created_at')
    ->whereColumn('user_id', 'users.id')
    ->orderBy('created_at', 'desc')
    ->limit(3);

$users = DB::table('users')
    ->joinLateral($latestPosts, 'latest_posts')
    ->get();

并集

查询构建器还提供了便捷的方法，将两个或多个查询合并为「并集」。例如，你可以先创建一个查询，再使用 union 方法将其与其他查询合并：

use Illuminate\Support\Facades\DB;

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

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

除了 union，查询构建器还提供了 unionAll 方法。使用 unionAll 合并查询时，不会移除重复结果。unionAll 的方法签名与 union 相同。

基本 Where 子句

Where 子句

你可以使用查询构建器的 where 方法添加「where」子句。最基本的调用需要三个参数：第一个是列名，第二个是数据库支持的任意运算符，第三个是要与该列的值进行比较的值。

例如，以下查询会获取 votes 列等于 100 且 age 列大于 35 的用户：

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

为方便使用，如果只需判断列是否 = 给定值，可以将该值作为 where 的第二个参数传入。Laravel 会默认使用 = 运算符：

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

你也可以向 where 方法传入关联数组，快速查询多个列：

$users = DB::table('users')->where([
    'first_name' => 'Jane',
    'last_name' => 'Doe',
])->get();

如前所述，你可以使用数据库系统支持的任何运算符：

$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 函数传入条件数组。数组中的每一项也应是数组，包含通常传给 where 方法的三个参数：

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

[!WARNING]
PDO 不支持绑定列名。因此，切勿让用户输入决定查询中引用的列名，包括「order by」子句中的列名。

[!WARNING]
MySQL 和 MariaDB 在比较字符串与数字时，会自动将字符串转换为整数。非数字字符串会被转换为 0，可能导致意外结果。例如，表中某行的 secret 列为 aaa，执行 User::where('secret', 0) 仍会返回该行。为避免此问题，请在查询前将所有值转换为适当的类型。

Or Where 子句

链式调用查询构建器的 where 方法时，各「where」子句会通过 and 运算符连接。你也可以使用 orWhere 方法，通过 or 运算符连接子句。orWhere 接受的参数与 where 相同：

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

如果需要用括号对「or」条件分组，可以将闭包作为 orWhere 方法的第一个参数传入：

use Illuminate\Database\Query\Builder;

$users = DB::table('users')
    ->where('votes', '>', 100)
    ->orWhere(function (Builder $query) {
        $query->where('name', 'Abigail')
            ->where('votes', '>', 50);
        })
    ->get();

上述示例会生成以下 SQL：

select * from users where votes > 100 or (name = 'Abigail' and votes > 50)

[!WARNING]
应始终对 orWhere 调用进行分组，避免应用全局作用域时出现意外行为。

Where Not 子句

whereNot 和 orWhereNot 方法可以对一组查询约束取反。例如，以下查询会排除正在清仓或价格低于 10 的商品：

$products = DB::table('products')
    ->whereNot(function (Builder $query) {
        $query->where('clearance', true)
            ->orWhere('price', '<', 10);
        })
    ->get();

Where Any / All / None 子句

有时，你可能需要将相同的查询约束应用于多个列。例如，获取指定列中任意一列与给定值 LIKE 匹配的所有记录，可以使用 whereAny 方法：

$users = DB::table('users')
    ->where('active', true)
    ->whereAny([
        'name',
        'email',
        'phone',
    ], 'like', 'Example%')
    ->get();

上述查询会生成以下 SQL：

SELECT *
FROM users
WHERE active = true AND (
    name LIKE 'Example%' OR
    email LIKE 'Example%' OR
    phone LIKE 'Example%'
)

类似地，whereAll 方法可以获取所有指定列都满足给定约束的记录：

$posts = DB::table('posts')
    ->where('published', true)
    ->whereAll([
        'title',
        'content',
    ], 'like', '%Laravel%')
    ->get();

上述查询会生成以下 SQL：

SELECT *
FROM posts
WHERE published = true AND (
    title LIKE '%Laravel%' AND
    content LIKE '%Laravel%'
)

whereNone 方法可以获取所有指定列都不满足给定约束的记录：

$albums = DB::table('albums')
    ->where('published', true)
    ->whereNone([
        'title',
        'lyrics',
        'tags',
    ], 'like', '%explicit%')
    ->get();

上述查询会生成以下 SQL：

SELECT *
FROM albums
WHERE published = true AND NOT (
    title LIKE '%explicit%' OR
    lyrics LIKE '%explicit%' OR
    tags LIKE '%explicit%'
)

JSON Where 子句

对于支持 JSON 列类型的数据库，Laravel 也支持查询 JSON 列。目前包括 MariaDB 10.3+、MySQL 8.0+、PostgreSQL 12.0+、SQL Server 2017+ 和 SQLite 3.39.0+。查询 JSON 列时，请使用 -> 运算符：

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

$users = DB::table('users')
    ->whereIn('preferences->dining->meal', ['pasta', 'salad', 'sandwiches'])
    ->get();

你可以使用 whereJsonContains 和 whereJsonDoesntContain 方法查询 JSON 数组：

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

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

如果应用使用 MariaDB、MySQL 或 PostgreSQL 数据库，可以向 whereJsonContains 和 whereJsonDoesntContain 方法传入值数组：

$users = DB::table('users')
    ->whereJsonContains('options->languages', ['en', 'de'])
    ->get();

$users = DB::table('users')
    ->whereJsonDoesntContain('options->languages', ['en', 'de'])
    ->get();

此外，你可以使用 whereJsonContainsKey 或 whereJsonDoesntContainKey 方法，获取包含或不包含指定 JSON 键的结果：

$users = DB::table('users')
    ->whereJsonContainsKey('preferences->dietary_requirements')
    ->get();

$users = DB::table('users')
    ->whereJsonDoesntContainKey('preferences->dietary_requirements')
    ->get();

最后，你可以使用 whereJsonLength 方法按 JSON 数组的长度进行查询：

$users = DB::table('users')
    ->whereJsonLength('options->languages', 0)
    ->get();

$users = DB::table('users')
    ->whereJsonLength('options->languages', '>', 1)
    ->get();

其他 Where 子句

whereLike / orWhereLike / whereNotLike / orWhereNotLike

whereLike 方法允许你添加「LIKE」子句进行模式匹配。这组方法提供了不依赖具体数据库的字符串匹配方式，并支持切换是否区分大小写。默认情况下，匹配不区分大小写：

$users = DB::table('users')
    ->whereLike('name', '%John%')
    ->get();

你可以通过 caseSensitive 参数启用区分大小写的搜索：

$users = DB::table('users')
    ->whereLike('name', '%John%', caseSensitive: true)
    ->get();

orWhereLike 方法允许你添加带有 LIKE 条件的「or」子句：

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

whereNotLike 方法允许你向查询添加「NOT LIKE」子句：

$users = DB::table('users')
    ->whereNotLike('name', '%John%')
    ->get();

类似地，你可以使用 orWhereNotLike 添加带有 NOT LIKE 条件的「or」子句：

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

[!WARNING]
SQL Server 目前不支持 whereLike 的区分大小写搜索选项。

whereIn / whereNotIn / orWhereIn / orWhereNotIn

whereIn 方法用于判断指定列的值是否包含在给定数组中：

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

whereNotIn 方法用于判断指定列的值是否不在给定数组中：

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

你也可以将查询对象作为 whereIn 方法的第二个参数传入：

$activeUsers = DB::table('users')->select('id')->where('is_active', 1);

$comments = DB::table('comments')
    ->whereIn('user_id', $activeUsers)
    ->get();

上述示例会生成以下 SQL：

select * from comments where user_id in (
    select id
    from users
    where is_active = 1
)

[!WARNING]
如果需要向查询绑定大量整数，可以使用 whereIntegerInRaw 或 whereIntegerNotInRaw 方法，大幅减少内存占用。

whereBetween / orWhereBetween

whereBetween 方法用于判断列的值是否位于两个值之间：

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

whereNotBetween / orWhereNotBetween

whereNotBetween 方法用于判断列的值是否位于两个值所构成的区间之外：

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

whereBetweenColumns / whereNotBetweenColumns / orWhereBetweenColumns / orWhereNotBetweenColumns

whereBetweenColumns 方法用于判断列的值是否位于同一行中另外两列的值之间：

$patients = DB::table('patients')
    ->whereBetweenColumns('weight', ['minimum_allowed_weight', 'maximum_allowed_weight'])
    ->get();

whereNotBetweenColumns 方法用于判断列的值是否位于同一行中另外两列的值所构成的区间之外：

$patients = DB::table('patients')
    ->whereNotBetweenColumns('weight', ['minimum_allowed_weight', 'maximum_allowed_weight'])
    ->get();

whereValueBetween / whereValueNotBetween / orWhereValueBetween / orWhereValueNotBetween

whereValueBetween 方法用于判断给定值是否位于同一行中两个同类型列的值之间：

$products = DB::table('products')
    ->whereValueBetween(100, ['min_price', 'max_price'])
    ->get();

whereValueNotBetween 方法用于判断给定值是否位于同一行中两列的值所构成的区间之外：

$products = DB::table('products')
    ->whereValueNotBetween(100, ['min_price', 'max_price'])
    ->get();

whereNull / whereNotNull / orWhereNull / orWhereNotNull

whereNull 方法用于判断指定列的值是否为 NULL：

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

whereNotNull 方法用于判断列的值是否不为 NULL：

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

whereNullSafeEquals / orWhereNullSafeEquals

whereNullSafeEquals 和 orWhereNullSafeEquals 方法可以将列的值与给定值进行比较，并将两个 NULL 视为相等：

$lastLoginIp = $request->input('last_login_ip');

$users = DB::table('users')
    ->whereNullSafeEquals('last_login_ip', $lastLoginIp)
    ->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:45')
    ->get();

wherePast / whereFuture / whereToday / whereBeforeToday / whereAfterToday

wherePast 和 whereFuture 方法可以判断列的值是否位于过去或未来：

$invoices = DB::table('invoices')
    ->wherePast('due_at')
    ->get();

$invoices = DB::table('invoices')
    ->whereFuture('due_at')
    ->get();

whereNowOrPast 和 whereNowOrFuture 方法可以判断列的值是否位于过去或未来，并将当前日期和时间包含在内：

$invoices = DB::table('invoices')
    ->whereNowOrPast('due_at')
    ->get();

$invoices = DB::table('invoices')
    ->whereNowOrFuture('due_at')
    ->get();

whereToday、whereBeforeToday 和 whereAfterToday 方法分别用于判断列的值是否为今天、早于今天或晚于今天：

$invoices = DB::table('invoices')
    ->whereToday('due_at')
    ->get();

$invoices = DB::table('invoices')
    ->whereBeforeToday('due_at')
    ->get();

$invoices = DB::table('invoices')
    ->whereAfterToday('due_at')
    ->get();

类似地，whereTodayOrBefore 和 whereTodayOrAfter 方法可以判断列的值是否早于或晚于今天，并包含今天：

$invoices = DB::table('invoices')
    ->whereTodayOrBefore('due_at')
    ->get();

$invoices = DB::table('invoices')
    ->whereTodayOrAfter('due_at')
    ->get();

whereColumn / orWhereColumn

whereColumn 方法可以判断两列的值是否相等：

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

你也可以向 whereColumn 方法传入比较运算符：

$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」子句分组，以实现所需的查询逻辑。通常应始终用括号对 orWhere 方法的调用分组，避免意外的查询行为。为此，可以向 where 方法传入闭包：

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

如上所示，向 where 方法传入闭包，就会让查询构建器创建一个约束组。闭包会接收一个查询构建器实例，你可以用它设置括号内的约束。上述示例会生成以下 SQL：

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

[!WARNING]
应始终对 orWhere 调用进行分组，避免应用全局作用域时出现意外行为。

高级 Where 子句

Where Exists 子句

whereExists 方法允许你编写「where exists」SQL 子句。该方法接受一个闭包，闭包会接收查询构建器实例，让你可以定义「exists」子句内部的查询：

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

你也可以向 whereExists 方法传入查询对象来代替闭包：

$orders = DB::table('orders')
    ->select(DB::raw(1))
    ->whereColumn('orders.user_id', 'users.id');

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

上述两个示例都会生成以下 SQL：

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

子查询 Where 子句

有时，你可能需要构建「where」子句，将子查询结果与给定值进行比较。向 where 方法传入闭包和值即可实现。例如，以下查询会获取最近一条「membership」记录属于指定类型的所有用户：

use App\Models\User;
use Illuminate\Database\Query\Builder;

$users = User::where(function (Builder $query) {
    $query->select('type')
        ->from('membership')
        ->whereColumn('membership.user_id', 'users.id')
        ->orderByDesc('membership.start_date')
        ->limit(1);
}, 'Pro')->get();

你也可能需要将某列与子查询结果进行比较。向 where 方法传入列名、运算符和闭包即可实现。例如，以下查询会获取金额低于平均值的所有收入记录：

use App\Models\Income;
use Illuminate\Database\Query\Builder;

$incomes = Income::where('amount', '<', function (Builder $query) {
    $query->selectRaw('avg(i.amount)')->from('incomes as i');
})->get();

全文 Where 子句

[!WARNING]
目前，MariaDB、MySQL 和 PostgreSQL 支持全文 Where 子句。

whereFullText 和 orWhereFullText 方法可以为具有全文索引的列添加全文「where」子句。Laravel 会根据底层数据库系统，将这些方法转换为相应的 SQL。例如，使用 MariaDB 或 MySQL 时，会生成 MATCH AGAINST 子句：

$users = DB::table('users')
    ->whereFullText('bio', 'web developer')
    ->get();

向量相似度子句

[!NOTE]
目前，使用 pgvector 扩展的 PostgreSQL 连接以及 MariaDB 11.7 及更高版本支持向量相似度子句。有关定义向量列和索引的信息，请参阅迁移文档。

whereVectorSimilarTo 方法根据与给定向量的余弦相似度筛选结果，并按相关性排序。minSimilarity 阈值应介于 0.0 和 1.0 之间，其中 1.0 表示完全相同：

$documents = DB::table('documents')
    ->whereVectorSimilarTo('embedding', $queryEmbedding, minSimilarity: 0.4)
    ->limit(10)
    ->get();

如果向量参数传入的是普通字符串，Laravel 会使用 Laravel AI SDK 自动为其生成嵌入向量：

$documents = DB::table('documents')
    ->whereVectorSimilarTo('embedding', 'Best wineries in Napa Valley')
    ->limit(10)
    ->get();

默认情况下，whereVectorSimilarTo 还会按距离对结果排序，相似度最高的结果排在前面。你可以将 order 参数设为 false，禁用此排序：

$documents = DB::table('documents')
    ->whereVectorSimilarTo('embedding', $queryEmbedding, minSimilarity: 0.4, order: false)
    ->orderBy('created_at', 'desc')
    ->limit(10)
    ->get();

如果需要更精细的控制，可以分别使用 selectVectorDistance、whereVectorDistanceLessThan 和 orderByVectorDistance 方法：

$documents = DB::table('documents')
    ->select('*')
    ->selectVectorDistance('embedding', $queryEmbedding, as: 'distance')
    ->whereVectorDistanceLessThan('embedding', $queryEmbedding, maxDistance: 0.3)
    ->orderByVectorDistance('embedding', $queryEmbedding)
    ->limit(10)
    ->get();

使用 PostgreSQL 时，必须先加载 pgvector 扩展，才能创建 vector 列：

Schema::ensureVectorExtensionExists();

排序、分组、条数限制和偏移量

排序

`orderBy` 方法

orderBy 方法可以按指定列对查询结果排序。第一个参数是要排序的列，第二个参数是排序方向，可以是 asc 或 desc：

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

要按多列排序，只需多次调用 orderBy：

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

排序方向是可选的，默认为升序。如果要降序排列，可以指定 orderBy 的第二个参数，或直接使用 orderByDesc：

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

此外，使用 -> 运算符，可以按 JSON 列内部的值对结果排序：

$corporations = DB::table('corporations')
    ->where('country', 'US')
    ->orderBy('location->state')
    ->get();

`latest` 和 `oldest` 方法

latest 和 oldest 方法可以轻松按日期对结果排序。默认按表的 created_at 列排序，你也可以传入要排序的列名：

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

随机排序

inRandomOrder 方法可以随机排列查询结果。例如，下面会随机获取一个用户：

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

移除现有排序

reorder 方法会移除查询中已有的所有「order by」子句：

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

$unorderedUsers = $query->reorder()->get();

调用 reorder 时，你可以传入列名和排序方向，移除已有的所有「order by」子句，并应用全新的排序：

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

$usersOrderedByEmail = $query->reorder('email', 'desc')->get();

为方便使用，你可以通过 reorderDesc 方法将查询结果重新按降序排列：

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

$usersOrderedByEmail = $query->reorderDesc('email')->get();

分组

`groupBy` 和 `having` 方法

groupBy 和 having 方法可以对查询结果进行分组及筛选。having 的方法签名与 where 类似：

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

你可以使用 havingBetween 方法筛选位于指定范围内的结果：

$report = DB::table('orders')
    ->selectRaw('count(id) as number_of_orders, customer_id')
    ->groupBy('customer_id')
    ->havingBetween('number_of_orders', [5, 15])
    ->get();

向 groupBy 方法传入多个参数，即可按多列分组：

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

要构建更复杂的 having 语句，请参阅 havingRaw 方法。

条数限制和偏移量

你可以使用 limit 和 offset 方法，限制查询返回的结果数量，或跳过指定数量的结果：

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

条件子句

有时，你可能希望根据其他条件决定是否应用某些查询子句。例如，仅当传入的 HTTP 请求中存在某个输入值时，才应用 where 语句。可以通过 when 方法实现：

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

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

when 方法仅在第一个参数求值为 true 时执行指定闭包；求值为 false 时则不执行。因此，在上述示例中，只有请求中存在 role 字段且其值求值为 true 时，才会调用传给 when 的闭包。

你可以将另一个闭包作为 when 的第三个参数传入。该闭包仅在第一个参数求值为 false 时执行。下面的示例使用此功能配置查询的默认排序：

$sortByVotes = $request->boolean('sort_by_votes');

$users = DB::table('users')
    ->when($sortByVotes, function (Builder $query, bool $sortByVotes) {
        $query->orderBy('votes');
    }, function (Builder $query) {
        $query->orderBy('name');
    })
    ->get();

插入语句

查询构建器还提供了 insert 方法，用于向数据库表插入记录。该方法接受由列名和值组成的数组：

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

传入二维数组可以一次插入多条记录，每个子数组代表要插入表中的一条记录：

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

insertOrIgnore 方法会忽略插入数据库记录时发生的错误。请注意，该方法会忽略重复记录错误，某些数据库引擎还可能忽略其他类型的错误。例如，insertOrIgnore 会绕过 MySQL 的严格模式：

DB::table('users')->insertOrIgnore([
    ['id' => 1, 'email' => 'sisko@example.com'],
    ['id' => 2, 'email' => 'archer@example.com'],
]);

insertUsing 方法可以通过子查询确定要插入的数据，并将新记录插入表中：

DB::table('pruned_users')->insertUsing([
    'id', 'name', 'email', 'email_verified_at'
], DB::table('users')->select(
    'id', 'name', 'email', 'email_verified_at'
)->where('updated_at', '<=', now()->minus(months: 1)));

自增 ID

如果表具有自增 ID，可以使用 insertGetId 方法插入记录并获取该 ID：

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

[!WARNING]
使用 PostgreSQL 时，insertGetId 方法默认自增列名为 id。如果要从其他「序列」获取 ID，可以将列名作为该方法的第二个参数传入。

插入或更新

upsert 方法会插入不存在的记录，并使用指定的新值更新已有记录。第一个参数是要插入或更新的值，第二个参数列出在表中唯一标识记录的列。第三个也是最后一个参数是列名数组，指定存在匹配记录时应更新哪些列：

DB::table('flights')->upsert(
    [
        ['departure' => 'Oakland', 'destination' => 'San Diego', 'price' => 99],
        ['departure' => 'Chicago', 'destination' => 'New York', 'price' => 150]
    ],
    ['departure', 'destination'],
    ['price']
);

在上述示例中，Laravel 会尝试插入两条记录。如果已存在 departure 和 destination 列值相同的记录，就更新该记录的 price 列。

[!WARNING]
除 SQL Server 外，所有数据库都要求 upsert 第二个参数中的列具有「主键」或「唯一」索引。此外，MariaDB 和 MySQL 数据库驱动会忽略第二个参数，始终通过表的「主键」和「唯一」索引来检测现有记录。

更新语句

除了插入记录，查询构建器还可以通过 update 方法更新已有记录。与 insert 一样，该方法接受由列名和值组成的数组，指定要更新的列，并返回受影响的行数。你可以使用 where 子句限制 update 查询的范围：

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

更新或插入

有时，你可能希望更新已有记录，并在不存在匹配记录时创建记录。这时可以使用 updateOrInsert 方法。该方法接受两个参数：用于查找记录的条件数组，以及指定要更新的列和值的数组。

updateOrInsert 会使用第一个参数中的列和值查找匹配记录。如果记录存在，就使用第二个参数中的值更新它。如果找不到记录，则合并两个参数中的属性，插入一条新记录：

DB::table('users')
    ->updateOrInsert(
        ['email' => 'john@example.com', 'name' => 'John'],
        ['votes' => '2']
    );

你可以向 updateOrInsert 传入闭包，根据匹配记录是否存在，自定义要更新或插入数据库的属性：

DB::table('users')->updateOrInsert(
    ['user_id' => $user_id],
    fn ($exists) => $exists ? [
        'name' => $data['name'],
        'email' => $data['email'],
    ] : [
        'name' => $data['name'],
        'email' => $data['email'],
        'marketable' => true,
    ],
);

更新 JSON 列

更新 JSON 列时，应使用 -> 语法更新 JSON 对象中的对应键。MariaDB 10.3+、MySQL 5.7+ 和 PostgreSQL 9.5+ 支持此操作：

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

自增与自减

查询构建器还提供了便捷的方法，用于增加或减少指定列的值。这两种方法都至少接受一个参数，即要修改的列。你可以传入第二个参数，指定增加或减少的数量：

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']);

此外，你可以通过 incrementEach 和 decrementEach 方法，一次增加或减少多列的值：

DB::table('users')->incrementEach([
    'votes' => 5,
    'balance' => 100,
]);

删除语句

查询构建器的 delete 方法可以删除表中的记录，并返回受影响的行数。你可以在调用该方法前添加「where」子句，限制删除范围：

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

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

悲观锁

查询构建器还提供了一些方法，帮助你在执行 select 语句时使用「悲观锁」。调用 sharedLock 方法可以使用「共享锁」执行查询。共享锁会防止选中的行被修改，直到事务提交：

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

你也可以使用 lockForUpdate 方法。「for update」锁会防止选中的记录被修改，或被其他共享锁选中：

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

虽然并非强制要求，但建议将悲观锁放在事务中使用。这可以确保整个操作完成之前，获取的数据在数据库中不会被修改。如果操作失败，事务会自动回滚所有更改并释放锁：

DB::transaction(function () {
    $sender = DB::table('users')
        ->lockForUpdate()
        ->find(1);

    $receiver = DB::table('users')
        ->lockForUpdate()
        ->find(2);

    if ($sender->balance < 100) {
        throw new RuntimeException('Balance too low.');
    }

    DB::table('users')
        ->where('id', $sender->id)
        ->update([
            'balance' => $sender->balance - 100
        ]);

    DB::table('users')
        ->where('id', $receiver->id)
        ->update([
            'balance' => $receiver->balance + 100
        ]);
});

可复用的查询组件

如果应用中存在重复的查询逻辑，可以使用查询构建器的 tap 和 pipe 方法，将这些逻辑提取为可复用的对象。假设应用中有以下两个查询：

use Illuminate\Database\Query\Builder;
use Illuminate\Support\Facades\DB;

$destination = $request->query('destination');

DB::table('flights')
    ->when($destination, function (Builder $query, string $destination) {
        $query->where('destination', $destination);
    })
    ->orderByDesc('price')
    ->get();

// ...

$destination = $request->query('destination');

DB::table('flights')
    ->when($destination, function (Builder $query, string $destination) {
        $query->where('destination', $destination);
    })
    ->where('user', $request->user()->id)
    ->orderBy('destination')
    ->get();

你可以将两个查询共有的目的地筛选逻辑提取为可复用的对象：

<?php

namespace App\Scopes;

use Illuminate\Database\Query\Builder;

class DestinationFilter
{
    public function __construct(
        private ?string $destination,
    ) {
        //
    }

    public function __invoke(Builder $query): void
    {
        $query->when($this->destination, function (Builder $query) {
            $query->where('destination', $this->destination);
        });
    }
}

然后，使用查询构建器的 tap 方法，将该对象的逻辑应用到查询中：

use App\Scopes\DestinationFilter;
use Illuminate\Database\Query\Builder;
use Illuminate\Support\Facades\DB;

DB::table('flights')
    ->when($destination, function (Builder $query, string $destination) { // [tl! remove]
        $query->where('destination', $destination); // [tl! remove]
    }) // [tl! remove]
    ->tap(new DestinationFilter($destination)) // [tl! add]
    ->orderByDesc('price')
    ->get();

// ...

DB::table('flights')
    ->when($destination, function (Builder $query, string $destination) { // [tl! remove]
        $query->where('destination', $destination); // [tl! remove]
    }) // [tl! remove]
    ->tap(new DestinationFilter($destination)) // [tl! add]
    ->where('user', $request->user()->id)
    ->orderBy('destination')
    ->get();

查询管道

tap 方法始终返回查询构建器。如果希望提取的对象执行查询并返回其他值，可以改用 pipe 方法。

下面的查询对象包含整个应用共用的分页逻辑。DestinationFilter 只为查询添加条件，而 Paginate 对象会执行查询并返回分页器实例：

<?php

namespace App\Scopes;

use Illuminate\Contracts\Pagination\LengthAwarePaginator;
use Illuminate\Database\Query\Builder;

class Paginate
{
    public function __construct(
        private string $sortBy = 'timestamp',
        private string $sortDirection = 'desc',
        private int $perPage = 25,
    ) {
        //
    }

    public function __invoke(Builder $query): LengthAwarePaginator
    {
        return $query->orderBy($this->sortBy, $this->sortDirection)
            ->paginate($this->perPage, pageName: 'p');
    }
}

通过查询构建器的 pipe 方法，就可以使用该对象应用共用的分页逻辑：

$flights = DB::table('flights')
    ->tap(new DestinationFilter($destination))
    ->pipe(new Paginate);

调试

构建查询时，你可以使用 dd 和 dump 方法输出当前查询的绑定值和 SQL。dd 会显示调试信息并停止执行请求；dump 则会显示调试信息，并让请求继续执行：

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

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

你也可以调用查询的 dumpRawSql 和 ddRawSql 方法，输出已正确代入所有绑定参数的完整 SQL：

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

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

本文章首发在 LearnKu.com 网站上。

本译文仅用于学习和交流目的，转载请务必注明文章译者、出处、和本文链接
我们的翻译工作遵照 CC 协议，如果我们的工作有侵犯到您的权益，请及时联系我们。

原文地址：https://learnku.com/docs/laravel/13.x/qu...

译文地址：https://learnku.com/docs/laravel/13.x/qu...

Markdown 文本

从小程序个人账户申请开始，带你一步步进行开发一个微信小程序，直到提交微信控制台上线发布。

你将学到如 RESTFul 设计风格、PostMan 的使用、OAuth 流程，JWT 概念及使用和 API 开发相关的进阶知识。

贡献者：1

查询构造器 13.x 13.x 12.x 11.x 10.x 9.x 8.5 8.x 7.x 6.x 5.8 5.7 5.6 5.5 5.4 5.3 5.2 5.1

数据库：查询构建器

简介

运行数据库查询

从表中获取所有行

从表中获取单行或单列

获取单列值的列表

分块处理结果

惰性流式处理结果

聚合

判断记录是否存在

Select 语句

指定 Select 子句

原始表达式

原始表达式方法

selectRaw

whereRaw / orWhereRaw

havingRaw / orHavingRaw

orderByRaw

groupByRaw

联接

内联接子句

左联接与右联接子句

交叉联接子句

高级联接子句

子查询联接

横向联接

并集

基本 Where 子句

Where 子句

Or Where 子句

Where Not 子句

Where Any / All / None 子句

JSON Where 子句

其他 Where 子句

逻辑分组

高级 Where 子句

Where Exists 子句

子查询 Where 子句

全文 Where 子句

向量相似度子句

排序、分组、条数限制和偏移量

排序

orderBy 方法

latest 和 oldest 方法

随机排序

移除现有排序

分组

groupBy 和 having 方法

条数限制和偏移量

条件子句

插入语句

自增 ID

插入或更新

更新语句

更新或插入

更新 JSON 列

自增与自减

删除语句

悲观锁

可复用的查询组件

查询管道

调试

推荐文章：

社区赞助商

关于 LearnKu

资源推荐

服务提供商

其他信息

请登录

查询构造器

13.x

13.x 12.x 11.x 10.x 9.x 8.5 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`

`groupByRaw`

`orderBy` 方法

`latest` 和 `oldest` 方法

`groupBy` 和 `having` 方法