查询构建器

查询构建器使用 PDO 参数绑定来保护你的应用程序免受 SQL 注入攻击。无需清理作为绑定传递的字符串。

数据库查询构建器提供了一个方便、流畅的接口，用于创建和运行数据库查询。它可用于在你的应用程序中执行大多数数据库操作，并适用于所有支持的数据库系统。

原生 SQL 示例

有时，使用纯 SQL 执行查询会更有意义，你可以通过 Db::select 方法来完成此操作。

php

Db::select('select * from sometable where name = :name', ['name' => 'Charles']);

请参阅有关运行原始 SQL 查询的文章以获取更多信息.

检索结果

要开始一个流畅查询，请在 Db 门面上使用 table 方法。table 方法返回给定表的流畅查询构建器实例，允许你将更多约束链式添加到查询中，然后最终获取结果。在此示例中，get 将返回表中的所有记录。

php

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

类似于原始查询，get 方法返回一个 array 结果集，其中每个结果都是 PHP stdClass 对象的一个实例。你可以通过将列作为对象的属性来访问每个列的值。

php

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

如果您只需要从数据库表中检索单行数据，您可以使用 first 方法。此方法将返回一个 stdClass 对象。

php

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

echo $user->name;

提取值

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

php

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

如果你想检索一个包含单个列值的数组，你可以使用 pluck 方法。在这个例子中，我们将检索一个角色标题数组。

php

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

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

您还可以为返回的数组指定一个自定义键列。

php

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

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

The result from pluck will return Collection object to behaves like an array. Use the all() method to convert it to a PHP array, for example, pluck('name')->all().

分块结果

如果你需要处理数千条数据库记录，考虑使用 chunk 方法。此方法每次检索一小“块”结果，并将每块数据送入一个 Closure 进行处理。此方法对于编写处理数千条记录的控制台命令非常有用。例如，让我们每次以 100 条记录为数据块，处理整个 users 表。

php

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

你可以通过从 Closure 返回 false 来阻止后续块的处理。

php

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

    return false;
});

如果您在分块处理结果时更新数据库记录，您的分块结果可能会以意想不到的方式发生变化。因此，在分块处理时更新记录，最好始终使用 chunkById 方法。此方法将根据记录的主键自动对结果进行分页。

php

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

在分块回调中更新或删除记录时，对主键或外键的任何更改都可能影响分块查询。这可能会导致记录未被包含在分块结果中。

聚合函数

查询构建器还提供了多种聚合方法，例如 count, max, min, avg, 和 sum. 你可以在构建查询后调用这些方法中的任何一个：

php

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

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

当然，您可以将这些方法与其他子句结合，以构建您的查询：

php

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

与其使用 count 方法来判断是否存在与查询的约束条件匹配的记录，您可以使用 exists 和 doesntExist 方法：

php

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

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

查询语句

在某些情况下，您可能并非总是希望从数据库表中选择所有列。使用 select 方法，您可以为查询指定一个自定义的 select 子句。

php

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

distinct 方法允许你强制查询返回唯一结果。

php

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

如果您已经有一个查询构建器实例并且希望添加一个列到其现有的 select 子句中，您可以使用 addSelect 方法：

php

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

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

原始表达式

有时您可能需要在查询中使用原始表达式。要创建原始表达式，您可以使用 Db::raw 方法。

php

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

另一种用途可能是将列和/或字符串拼接在一起。

php

Db::raw("(first_name, ' ', last_name) as full_name");

原始语句将作为字符串注入到查询中，因此您应该格外小心，以免造成 SQL 注入漏洞。

原始方法

除了使用 Db::raw，您也可以使用以下方法将原始表达式插入到查询的各个部分中。

这 selectRaw 方法可以用于替代 addSelect(Db::raw(...))。该方法接受一个可选的绑定数组作为其第二个参数：

php

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

whereRaw 和 orWhereRaw 方法可用于向你的查询中注入一个原始 where 子句。这些方法接受一个可选的绑定数组作为它们的第二个参数：

php

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

havingRaw 和 orHavingRaw 方法可以用于将原始字符串设置为 having 子句的值。这些方法接受一个可选的绑定数组作为它们的第二个参数：

php

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

该 orderByRaw 方法可用于将一个原始字符串设置为 order by 子句的值:

php

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

groupByRaw 方法可用于将原始字符串设为 group by 子句的值：

php

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

连接

查询构建器也可用于编写连接语句。要执行基本的 SQL“内连接”，您可以使用查询构建器实例上的 join 方法。传递给 join 方法的第一个参数是您需要连接到的表的名称，而其余参数则指定连接的列约束。当然，如您所见，您可以在单个查询中连接到多个表。

php

$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方法。leftJoin和rightJoin方法具有与join方法相同的签名。

php

$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 方法并指定您希望进行交叉连接的表名。交叉连接会在第一个表和连接的表之间生成笛卡尔积。

php

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

高级连接语句

你还可以指定更高级的 join 子句。首先，传入一个 Closure 作为 join 方法的第二个参数。该 Closure 将会收到一个 JoinClause 对象，它允许你对 join 子句指定约束。

php

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

如果你希望在连接上使用 "where" 样式子句，你可以在连接上使用 where 和 orWhere 方法。这些方法不是比较两列，而是会将列与一个值进行比较。

php

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

子查询连接

您可以使用 joinSub, leftJoinSub, 和 rightJoinSub 方法将查询与子查询连接起来. 这些方法都接收三个参数: 子查询, 其表别名, 以及一个定义相关列的闭包:

php

$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 ($join) {
        $join->on('users.id', '=', 'latest_posts.user_id');
    })->get();

联合体

查询构建器还提供了一种快速方法来“联合”两个查询。例如，你可以创建一个初始查询，然后使用 union 方法将其与第二个查询联合。

php

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

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

unionAll 方法也可用，并具有与 union 相同的方法签名。

WHERE 子句

为查询添加 where 子句，请在查询构建器实例上使用 where 方法。对 where 最基本的调用需要三个参数。第一个参数是列的名称。第二个参数是一个运算符，它可以是数据库支持的任何运算符。第三个参数是用于对照列进行评估的值。

例如，这里有一个查询，用于验证 "votes" 列的值等于 100。

php

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

为了方便，如果您只想验证某一列等于给定值，您可以将该值直接作为第二个参数传递给 where 方法。

php

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

在编写 where 子句时，您可以使用多种其他运算符，例如，大于 >，不等于 <> 和 like。

php

$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 约束串联起来, 以及向查询添加 or 子句. orWhere 方法接受与 where 方法相同的参数:

php

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

您还可以将 or 作为前缀添加到以下任何 where 语句方法中，以使条件成为 "或" 条件 - 例如，orWhereBetween、orWhereIn 等。
:::

搜索语句

searchWhere 和 orSearchWhere 方法可用于对列值执行搜索查询。该方法将使用搜索词（第一个参数）和搜索列（第二个参数），通过不区分大小写的 like 查询添加到查询中。

php

$pages = Db::table('posts')
    ->searchWhere('foo bar', ['title', 'content'])
    ->get();

上述示例将生成以下 SQL，其中每个列和值都已对其应用了 lower()：

sql

select * from users where
    (title like '%foo%' and title like '%bar%') or
    (content like '%foo%' and content like '%bar%')

默认情况下，搜索词中的每个词都将被搜索，但是，你可以通过提供一个模式（第三个参数）来修改此行为，并支持以下模式。

所有：结果必须包含所有词语 (默认)
任意：结果可包含任意词
精确：结果必须包含该精确短语

php

$query->searchWhere('foo bar', ['title', 'content'], 'exact');

上述 exact 搜索示例将生成以下 SQL：

sql

select * from users where (title like '%foo bar%' or content like '%foo bar%')

复合 WHERE 子句

有时你可能需要创建更高级的 where 子句，例如 "where exists" 或嵌套参数分组。Laravel 查询构建器也可以处理这些情况。首先，让我们看一个在括号内对约束进行分组的例子：

php

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

如你所见，将 Closure 传递给 orWhere 方法会指示查询构建器开始一个约束组。该 Closure 将接收到一个查询构建器实例，你可以使用它来设置应包含在括号组中的约束。上述示例将生成以下 SQL：

sql

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

存在语句

whereExists 方法允许您编写 where exist SQL 子句。whereExists 方法接受一个 Closure 参数，该参数将接收一个查询构建器实例，允许您定义应放置在 "exists" 子句中的查询：

php

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

上述查询将生成以下 SQL：

sql

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

JSON `WHERE` 语句

October CMS 也支持在支持 JSON 字段类型的数据库上查询 JSON 字段类型。要查询 JSON 字段，使用 -> 操作符。

php

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

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

你可以使用 whereJsonContains 查询 JSON 数组 (在 SQLite 上不支持)。

php

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

MySQL 和 PostgreSQL 支持 whereJsonContains 使用多个值。

php

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

您可以使用 whereJsonLength 来根据 JSON 数组的长度进行查询。

php

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

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

条件子句

有时你可能希望将子句应用于查询，仅当其他条件为真时。例如，你可能只想在传入请求中存在给定输入值时，才应用 where 语句。你可以通过使用 when 方法来实现此目的：

php

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

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

when 方法仅在第一个参数为 true 时执行给定的闭包。如果第一个参数为 false，则闭包将不会被执行。

您可以将另一个闭包作为第三个参数传递给 when 方法。如果第一个参数评估为假，则此闭包将执行。为了说明此功能如何使用，我们将使用它来配置查询的默认排序：

php

$sortBy = null;

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

排序, 分组, 限制

排序

orderBy 方法允许你根据指定列对查询结果进行排序。 orderBy 方法的第一个参数应该是你希望排序的列，而第二个参数控制排序方向，可以是 asc 或 desc。

php

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

latest 和 oldest 方法可以方便地根据日期对结果进行排序。默认情况下，结果将根据 created_at 列进行排序。或者，您也可以传入希望排序的列名。

php

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

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

php

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

分组

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

php

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

你可以向 groupBy 方法传递多个参数来根据多个列进行分组。

php

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

对于更高级的 having 语句，您可能希望使用 havingRaw 方法。

限制与偏移

为了限制查询返回的结果数量，或跳过查询中给定数量的结果 (OFFSET)，您可以使用 skip 和 take 方法。

php

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

插入

查询构建器也提供了一个 insert 方法，用于向数据库表中插入记录。该 insert 方法接受一个包含要插入的列名和值的数组：

php

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

你甚至可以通过一次调用 insert 将多条记录插入表中，通过传入一个数组的数组。每个数组代表一个要插入表中的行：

php

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

自增长 ID

如果表有自增 ID，请使用 insertGetId 方法插入一条记录，然后获取该 ID：

php

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

当使用 PostgreSQL 数据库驱动时，insertGetId 方法期望自增列名为 id。如果你想从不同的“序列”中检索 ID，你可以将序列名作为第二个参数传递给 insertGetId 方法。

更新

除了向数据库插入记录之外，查询构建器还可以使用 update 方法更新现有记录。update 方法与 insert 方法类似，接受一个包含列和值对的数组，其中包含要更新的列。你可以使用 where 子句来约束 update 查询。

php

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

更新或插入

有时你可能希望更新数据库中已有的记录，或者在没有匹配记录时创建它。在这种情况下，可以使用 updateOrInsert 方法。updateOrInsert 方法接受两个参数：一个用于查找记录的条件数组，以及一个包含要更新列的列与值对数组。

updateOrInsert 方法将首先尝试使用第一个参数的列和值对来定位匹配的数据库记录。如果记录存在，它将使用第二个参数中的值进行更新。如果找不到该记录，将插入一个新记录，其中包含两个参数合并后的属性。

php

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

更新或插入

upsert 方法将插入不存在的行，并使用新值更新已存在的行。该方法的第一个参数包含要插入或更新的值，而第二个参数列出了在关联表中唯一标识记录的列。该方法的第三个也是最后一个参数是一个列数组，如果数据库中已存在匹配的记录，则应更新这些列。

php

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

除 SQL Server 外的所有数据库都要求 upsert 方法的第二个参数中的列具有“主键”或“唯一”索引。

更新 JSON 列

当更新 JSON 列时，应使用 -> 语法来访问 JSON 对象中相应的键。此操作在 MySQL 5.7+ 和 PostgreSQL 9.5+ 上受支持：

php

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

递增 / 递减

查询构建器也提供了便捷方法，用于递增或递减给定列的值。这仅仅是一个捷径，与手动编写 update 语句相比，它提供了一个更具表达性和简洁的接口。

这两种方法都接受至少一个参数：要修改的列。可以选择性地传递第二个参数，以控制列应增加/减少的量。

php

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

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

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

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

您还可以在操作期间指定要更新的附加列：

php

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

删除

查询构建器也可以用于通过 delete 方法从表中删除记录。

php

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

您可以在调用 delete 方法之前通过添加 where 子句来约束 delete 语句。

php

Db::table('users')->where('votes', `<`, 100)->delete();

如果您希望截断整个表，这将移除所有行并将自增 ID 重置为零，您可以使用 truncate 方法。

php

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

悲观锁定

查询构建器也包含一些函数，可帮助你在 select 语句上执行 "悲观锁定"。若要使用 "共享锁" 运行语句，你可以在查询上使用 sharedLock 方法。共享锁会阻止所选行被修改，直到你的事务提交。

php

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

或者，你可以使用 lockForUpdate 方法. “for update”锁防止行被修改或被另一个共享锁选中.

php

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

缓存查询

您可以使用缓存服务轻松缓存查询结果。只需在准备查询时链式调用 remember 或 rememberForever 方法即可。

php

$users = Db::table('users')->remember(10)->get();

在此示例中，查询结果将被缓存十分钟。在结果被缓存期间，查询不会针对数据库运行，并且结果将从为您的应用程序指定的默认缓存驱动器加载。

调试

您可以在构建查询时使用 dd 或 dump 方法来转储查询绑定和 SQL。dd 方法将显示调试信息，然后停止执行请求。dump 方法将显示调试信息，但允许请求继续执行：

php

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

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

另请参阅

Laravel 查询构建器

查询构建器

查询构建器使用 PDO 参数绑定来保护你的应用程序免受 SQL 注入攻击。无需清理作为绑定传递的字符串。

原生 SQL 示例

有时，使用纯 SQL 执行查询会更有意义，你可以通过 Db::select 方法来完成此操作。

php

Db::select('select * from sometable where name = :name', ['name' => 'Charles']);

请参阅有关运行原始 SQL 查询的文章以获取更多信息.

检索结果

php

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

php

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

如果您只需要从数据库表中检索单行数据，您可以使用 first 方法。此方法将返回一个 stdClass 对象。

php

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

echo $user->name;

提取值

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

php

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

如果你想检索一个包含单个列值的数组，你可以使用 pluck 方法。在这个例子中，我们将检索一个角色标题数组。

php

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

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

您还可以为返回的数组指定一个自定义键列。

php

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

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

The result from pluck will return Collection object to behaves like an array. Use the all() method to convert it to a PHP array, for example, pluck('name')->all().

分块结果

php

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

你可以通过从 Closure 返回 false 来阻止后续块的处理。

php

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

    return false;
});

php

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

在分块回调中更新或删除记录时，对主键或外键的任何更改都可能影响分块查询。这可能会导致记录未被包含在分块结果中。

聚合函数

查询构建器还提供了多种聚合方法，例如 count, max, min, avg, 和 sum. 你可以在构建查询后调用这些方法中的任何一个：

php

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

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

当然，您可以将这些方法与其他子句结合，以构建您的查询：

php

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

与其使用 count 方法来判断是否存在与查询的约束条件匹配的记录，您可以使用 exists 和 doesntExist 方法：

php

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

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

查询语句

在某些情况下，您可能并非总是希望从数据库表中选择所有列。使用 select 方法，您可以为查询指定一个自定义的 select 子句。

php

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

distinct 方法允许你强制查询返回唯一结果。

php

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

如果您已经有一个查询构建器实例并且希望添加一个列到其现有的 select 子句中，您可以使用 addSelect 方法：

php

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

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

原始表达式

有时您可能需要在查询中使用原始表达式。要创建原始表达式，您可以使用 Db::raw 方法。

php

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

另一种用途可能是将列和/或字符串拼接在一起。

php

Db::raw("(first_name, ' ', last_name) as full_name");

原始语句将作为字符串注入到查询中，因此您应该格外小心，以免造成 SQL 注入漏洞。

原始方法

除了使用 Db::raw，您也可以使用以下方法将原始表达式插入到查询的各个部分中。

这 selectRaw 方法可以用于替代 addSelect(Db::raw(...))。该方法接受一个可选的绑定数组作为其第二个参数：

php

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

whereRaw 和 orWhereRaw 方法可用于向你的查询中注入一个原始 where 子句。这些方法接受一个可选的绑定数组作为它们的第二个参数：

php

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

havingRaw 和 orHavingRaw 方法可以用于将原始字符串设置为 having 子句的值。这些方法接受一个可选的绑定数组作为它们的第二个参数：

php

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

该 orderByRaw 方法可用于将一个原始字符串设置为 order by 子句的值:

php

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

groupByRaw 方法可用于将原始字符串设为 group by 子句的值：

php

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

连接

php

$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方法。leftJoin和rightJoin方法具有与join方法相同的签名。

php

$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 方法并指定您希望进行交叉连接的表名。交叉连接会在第一个表和连接的表之间生成笛卡尔积。

php

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

高级连接语句

php

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

如果你希望在连接上使用 "where" 样式子句，你可以在连接上使用 where 和 orWhere 方法。这些方法不是比较两列，而是会将列与一个值进行比较。

php

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

子查询连接

您可以使用 joinSub, leftJoinSub, 和 rightJoinSub 方法将查询与子查询连接起来. 这些方法都接收三个参数: 子查询, 其表别名, 以及一个定义相关列的闭包:

php

$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 ($join) {
        $join->on('users.id', '=', 'latest_posts.user_id');
    })->get();

联合体

查询构建器还提供了一种快速方法来“联合”两个查询。例如，你可以创建一个初始查询，然后使用 union 方法将其与第二个查询联合。

php

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

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

unionAll 方法也可用，并具有与 union 相同的方法签名。

WHERE 子句

例如，这里有一个查询，用于验证 "votes" 列的值等于 100。

php

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

为了方便，如果您只想验证某一列等于给定值，您可以将该值直接作为第二个参数传递给 where 方法。

php

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

在编写 where 子句时，您可以使用多种其他运算符，例如，大于 >，不等于 <> 和 like。

php

$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 约束串联起来, 以及向查询添加 or 子句. orWhere 方法接受与 where 方法相同的参数:

php

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

您还可以将 or 作为前缀添加到以下任何 where 语句方法中，以使条件成为 "或" 条件 - 例如，orWhereBetween、orWhereIn 等。
:::

搜索语句

php

$pages = Db::table('posts')
    ->searchWhere('foo bar', ['title', 'content'])
    ->get();

上述示例将生成以下 SQL，其中每个列和值都已对其应用了 lower()：

sql

select * from users where
    (title like '%foo%' and title like '%bar%') or
    (content like '%foo%' and content like '%bar%')

默认情况下，搜索词中的每个词都将被搜索，但是，你可以通过提供一个模式（第三个参数）来修改此行为，并支持以下模式。

所有：结果必须包含所有词语 (默认)
任意：结果可包含任意词
精确：结果必须包含该精确短语

php

$query->searchWhere('foo bar', ['title', 'content'], 'exact');

上述 exact 搜索示例将生成以下 SQL：

sql

select * from users where (title like '%foo bar%' or content like '%foo bar%')

复合 WHERE 子句

php

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

sql

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

存在语句

php

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

上述查询将生成以下 SQL：

sql

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

JSON `WHERE` 语句

October CMS 也支持在支持 JSON 字段类型的数据库上查询 JSON 字段类型。要查询 JSON 字段，使用 -> 操作符。

php

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

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

你可以使用 whereJsonContains 查询 JSON 数组 (在 SQLite 上不支持)。

php

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

MySQL 和 PostgreSQL 支持 whereJsonContains 使用多个值。

php

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

您可以使用 whereJsonLength 来根据 JSON 数组的长度进行查询。

php

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

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

条件子句

php

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

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

when 方法仅在第一个参数为 true 时执行给定的闭包。如果第一个参数为 false，则闭包将不会被执行。

php

$sortBy = null;

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

排序, 分组, 限制

排序

php

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

latest 和 oldest 方法可以方便地根据日期对结果进行排序。默认情况下，结果将根据 created_at 列进行排序。或者，您也可以传入希望排序的列名。

php

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

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

php

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

分组

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

php

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

你可以向 groupBy 方法传递多个参数来根据多个列进行分组。

php

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

对于更高级的 having 语句，您可能希望使用 havingRaw 方法。

限制与偏移

为了限制查询返回的结果数量，或跳过查询中给定数量的结果 (OFFSET)，您可以使用 skip 和 take 方法。

php

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

插入

查询构建器也提供了一个 insert 方法，用于向数据库表中插入记录。该 insert 方法接受一个包含要插入的列名和值的数组：

php

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

你甚至可以通过一次调用 insert 将多条记录插入表中，通过传入一个数组的数组。每个数组代表一个要插入表中的行：

php

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

自增长 ID

如果表有自增 ID，请使用 insertGetId 方法插入一条记录，然后获取该 ID：

php

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

当使用 PostgreSQL 数据库驱动时，insertGetId 方法期望自增列名为 id。如果你想从不同的“序列”中检索 ID，你可以将序列名作为第二个参数传递给 insertGetId 方法。

更新

php

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

更新或插入

php

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

更新或插入

php

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

除 SQL Server 外的所有数据库都要求 upsert 方法的第二个参数中的列具有“主键”或“唯一”索引。

更新 JSON 列

当更新 JSON 列时，应使用 -> 语法来访问 JSON 对象中相应的键。此操作在 MySQL 5.7+ 和 PostgreSQL 9.5+ 上受支持：

php

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

递增 / 递减

这两种方法都接受至少一个参数：要修改的列。可以选择性地传递第二个参数，以控制列应增加/减少的量。

php

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

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

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

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

您还可以在操作期间指定要更新的附加列：

php

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

删除

查询构建器也可以用于通过 delete 方法从表中删除记录。

php

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

您可以在调用 delete 方法之前通过添加 where 子句来约束 delete 语句。

php

Db::table('users')->where('votes', `<`, 100)->delete();

如果您希望截断整个表，这将移除所有行并将自增 ID 重置为零，您可以使用 truncate 方法。

php

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

悲观锁定

php

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

或者，你可以使用 lockForUpdate 方法. “for update”锁防止行被修改或被另一个共享锁选中.

php

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

缓存查询

您可以使用缓存服务轻松缓存查询结果。只需在准备查询时链式调用 remember 或 rememberForever 方法即可。

php

$users = Db::table('users')->remember(10)->get();

在此示例中，查询结果将被缓存十分钟。在结果被缓存期间，查询不会针对数据库运行，并且结果将从为您的应用程序指定的默认缓存驱动器加载。

调试

php

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

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

另请参阅

Laravel 查询构建器

文档导航

查询构建器

原生 SQL 示例

检索结果

提取值

分块结果

聚合函数

查询语句

原始表达式

原始方法

连接

高级连接语句

子查询连接

联合体

WHERE 子句

或语句

更多 WHERE 语句

搜索语句

复合 WHERE 子句

存在语句

JSON WHERE 语句

条件子句

排序, 分组, 限制

排序

分组

限制与偏移

插入

自增长 ID

更新

更新或插入

更新或插入

更新 JSON 列

递增 / 递减

删除

悲观锁定

缓存查询

调试

另请参阅

查询构建器

原生 SQL 示例

检索结果

提取值

分块结果

聚合函数

查询语句

原始表达式

原始方法

连接

高级连接语句

子查询连接

联合体

WHERE 子句

或语句

更多 WHERE 语句

搜索语句

复合 WHERE 子句

存在语句

JSON WHERE 语句

条件子句

排序, 分组, 限制

排序

分组

限制与偏移

插入

自增长 ID

更新

更新或插入

更新或插入

更新 JSON 列

递增 / 递减

删除

悲观锁定

缓存查询

调试

另请参阅

JSON `WHERE` 语句

JSON `WHERE` 语句