什么是查询构建器
Laravel 的查询构建器提供了一套流式接口来构建并执行数据库查询。从DB 门面的 table() 方法开始，链式组合出查询。
use Illuminate\Support\Facades\DB;
$users = DB::table('users')->get();
查询构建器可在 Laravel 支持的所有数据库（MySQL、MariaDB、PostgreSQL、SQLite、SQL Server）上运行，切换数据库时代码不变。
与 Eloquent 的选择
| 场景 | 推荐 |
|---|---|
| 需要模型与关联 | Eloquent |
| 复杂聚合或报表 | 查询构建器 |
| 追求性能的大量数据处理 | 查询构建器 |
| 对已有表的简单操作 | 查询构建器 |
| 迁移 / Seeder 中的处理 | 查询构建器 |
读取数据
取全部
$users = DB::table('users')->get();
foreach ($users as $user) {
echo $user->name;
}
get() 返回 Illuminate\Support\Collection。每条记录是 stdClass 对象。
取单条
// 第一条（无则 null）
$user = DB::table('users')->where('name', '山田太郎')->first();
// 无则抛异常（自动 404）
$user = DB::table('users')->where('name', '山田太郎')->firstOrFail();
// 只取某列的值
$email = DB::table('users')->where('name', '山田太郎')->value('email');
// 按 ID 查
$user = DB::table('users')->find(3);
抽取某列
$emails = DB::table('users')->pluck('email');
$emailByName = DB::table('users')->pluck('email', 'name');
大量数据分块处理
use Illuminate\Support\Collection;
// 每 100 条处理一次
DB::table('users')->orderBy('id')->chunk(100, function (Collection $users) {
foreach ($users as $user) {
// 处理...
}
});
// 边处理边更新请用 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()。chunk() 可能出现记录偏移。流式处理（LazyCollection）
DB::table('users')->orderBy('id')->lazy()->each(function (object $user) {
// 一次处理一条
});
聚合
$count = DB::table('users')->count();
$maxAge = DB::table('users')->max('age');
$minAge = DB::table('users')->min('age');
$avgAge = DB::table('users')->avg('age');
$total = DB::table('orders')->sum('amount');
$avgPremium = DB::table('orders')
->where('plan', 'premium')
->avg('amount');
是否存在
if (DB::table('orders')->where('finalized', 1)->exists()) {
// 存在
}
if (DB::table('orders')->where('finalized', 1)->doesntExist()) {
// 不存在
}
SELECT 子句
$users = DB::table('users')
->select('name', 'email as user_email')
->get();
$users = DB::table('users')->distinct()->get();
$query = DB::table('users')->select('name');
$users = $query->addSelect('age')->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', '山田%')->get();
// 多条件（AND）
$users = DB::table('users')
->where('status', 'active')
->where('age', '>', 20)
->get();
// OR
$users = DB::table('users')
->where('votes', '>', 100)
->orWhere('name', '山田太郎')
->get();
条件分组
use Illuminate\Database\Query\Builder;
$users = DB::table('users')
->where('active', true)
->where(function (Builder $query) {
$query->where('role', 'admin')
->orWhere('role', 'moderator');
})
->get();
// WHERE active = 1 AND (role = 'admin' OR role = 'moderator')
whereIn / whereBetween / whereNull
$users = DB::table('users')
->whereIn('id', [1, 2, 3])
->get();
$users = DB::table('users')
->whereNotIn('id', [1, 2, 3])
->get();
$users = DB::table('users')
->whereBetween('age', [20, 40])
->get();
$users = DB::table('users')->whereNull('deleted_at')->get();
$users = DB::table('users')->whereNotNull('email_verified_at')->get();
whereLike
// 默认忽略大小写
$users = DB::table('users')
->whereLike('name', '%山田%')
->get();
$users = DB::table('users')
->whereLike('name', '%Yamada%', caseSensitive: true)
->get();
whereAny / whereAll
$users = DB::table('users')
->where('active', true)
->whereAny(['name', 'email', 'bio'], 'like', '%Laravel%')
->get();
$posts = DB::table('posts')
->whereAll(['title', 'content'], 'like', '%Laravel%')
->get();
whereNullSafeEquals
whereNullSafeEquals / orWhereNullSafeEquals 将两个 NULL 也视为相等（对应 MySQL <=>、PostgreSQL IS NOT DISTINCT FROM）。
$lastLoginIp = $request->input('last_login_ip');
$users = DB::table('users')
->whereNullSafeEquals('last_login_ip', $lastLoginIp)
->get();
where('column', null) 会变成 WHERE column IS NULL，而 whereNullSafeEquals('column', $value) 无论 $value 是否为 null 都能一致工作，尤其适用于用户输入可能为 null 的场景。JOIN
$users = DB::table('users')
->join('orders', 'users.id', '=', 'orders.user_id')
->select('users.name', 'orders.amount')
->get();
$users = DB::table('users')
->leftJoin('orders', 'users.id', '=', 'orders.user_id')
->get();
$users = DB::table('users')
->join('contacts', 'users.id', '=', 'contacts.user_id')
->join('orders', 'users.id', '=', 'orders.user_id')
->select('users.*', 'contacts.phone', 'orders.amount')
->get();
子查询 JOIN
$latestOrders = DB::table('orders')
->select('user_id', DB::raw('MAX(created_at) as last_order_at'))
->groupBy('user_id');
$users = DB::table('users')
->joinSub($latestOrders, 'latest_orders', function ($join) {
$join->on('users.id', '=', 'latest_orders.user_id');
})
->get();
排序 / 分组 / 限制
$users = DB::table('users')
->orderBy('name', 'asc')
->get();
$users = DB::table('users')
->orderBy('last_name')
->orderBy('first_name', 'desc')
->get();
$users = DB::table('users')->inRandomOrder()->get();
$orders = DB::table('orders')
->select('status', DB::raw('COUNT(*) as count'))
->groupBy('status')
->get();
$orders = DB::table('orders')
->select('user_id', DB::raw('SUM(amount) as total'))
->groupBy('user_id')
->having('total', '>', 10000)
->get();
$users = DB::table('users')
->skip(10)
->take(5)
->get();
子查询
$activeUsers = DB::table('users')->select('id')->where('is_active', 1);
$comments = DB::table('comments')
->whereIn('user_id', $activeUsers)
->get();
$users = DB::table('users')
->select('name')
->selectSub(function ($query) {
$query->from('orders')
->selectRaw('COUNT(*)')
->whereColumn('orders.user_id', 'users.id');
}, 'order_count')
->get();
向量相似度检索
对保存了嵌入向量的列，可以使用whereVectorSimilarTo 只检索与指定向量相近的记录。向量列需要在迁移中定义为 vector 类型（迁移中的向量列）。
use Illuminate\Support\Facades\DB;
$embedding = [0.12, -0.34, 0.56];
$documents = DB::table('documents')
->whereVectorSimilarTo('embedding', $embedding, minSimilarity: 0.4)
->limit(10)
->get();
whereVectorSimilarTo 会按相似度从高到低排序。如果不需要指定最小相似度，只想显式地按距离排序，可以使用 orderByVectorDistance。想在返回的列中包含距离时，可以通过 selectVectorDistance 指定别名。
$documents = DB::table('documents')
->select('id', 'title')
->selectVectorDistance('embedding', $embedding, as: 'distance')
->orderByVectorDistance('embedding', $embedding)
->limit(10)
->get();
pgvector 扩展。
Raw 表达式
Raw 表达式会作为 SQL 字符串直接拼入。若直接传入用户输入会导致 SQL 注入。请务必使用绑定。
$users = DB::table('users')
->select(DB::raw('count(*) as user_count, status'))
->groupBy('status')
->get();
$orders = DB::table('orders')
->selectRaw('price * ? as price_with_tax', [1.10])
->get();
$orders = DB::table('orders')
->whereRaw('price > IF(state = "JP", ?, 100)', [500])
->get();
$orders = DB::table('orders')
->select('department', DB::raw('SUM(amount) as total'))
->groupBy('department')
->havingRaw('SUM(amount) > ?', [100000])
->get();
$orders = DB::table('orders')
->orderByRaw('updated_at - created_at DESC')
->get();
INSERT / UPDATE / DELETE
INSERT
DB::table('users')->insert([
'email' => '[email protected]',
'name' => '山田太郎',
]);
DB::table('users')->insert([
['email' => '[email protected]', 'name' => '山田太郎'],
['email' => '[email protected]', 'name' => '铃木花子'],
]);
$id = DB::table('users')->insertGetId([
'email' => '[email protected]',
'name' => '佐藤次郎',
]);
UPSERT
DB::table('users')->upsert(
[
['email' => '[email protected]', 'name' => '山田太郎', 'votes' => 5],
['email' => '[email protected]', 'name' => '铃木花子', 'votes' => 10],
],
uniqueBy: ['email'],
update: ['name', 'votes']
);
UPDATE
$affected = DB::table('users')
->where('id', 1)
->update(['name' => '山田一郎', 'updated_at' => now()]);
DB::table('users')->where('id', 1)->increment('votes');
DB::table('users')->where('id', 1)->increment('votes', 5);
DB::table('users')->where('id', 1)->decrement('votes');
DB::table('users')->where('id', 1)->decrement('balance', 100);
DELETE
$deleted = DB::table('users')->where('status', 'inactive')->delete();
DB::table('users')->truncate();
按条件构建查询（when）
$status = request('status');
$sortBy = request('sort', 'name');
$users = DB::table('users')
->when($status, function ($query, $status) {
$query->where('status', $status);
})
->when($sortBy === 'email', function ($query) {
$query->orderBy('email');
}, function ($query) {
$query->orderBy('name');
})
->get();
调试
$sql = DB::table('users')->where('active', true)->toSql();
// "select * from `users` where `active` = ?"
$bindings = DB::table('users')->where('active', true)->getBindings();
// 输出后继续执行
DB::table('users')->where('active', true)->dump();
// 输出后终止
DB::table('users')->where('active', true)->dd();
dd() 只用于调试，生产环境请勿使用。使用 toSql() 与 getBindings() 更安全。小结
常用方法一览
常用方法一览
| 方法 | 说明 |
|---|---|
get() | 取全部（Collection） |
first() | 取第一条 |
find($id) | 按 ID 取 |
value($column) | 取某字段的值 |
pluck($column) | 取字段列表 |
count() | 数量 |
sum($col) | 求和 |
avg($col) | 平均 |
max($col) | 最大 |
min($col) | 最小 |
exists() | 是否存在 |
insert([...]) | 插入 |
update([...]) | 更新 |
delete() | 删除 |
chunk($n, fn) | 分块处理 |
when($cond, fn) | 条件构建 |
toSql() | 查看生成 SQL |
查询构建器 vs Eloquent
查询构建器 vs Eloquent
查询构建器比 Eloquent 更底层，返回
stdClass 而非模型实例。
若不需要关联或模型事件（Observer），构建器更简单也更快。