文档菜单
文档首页
/
语言
/
PHP
/
Laravel MongoDB

查询构建器

本页内容

  • 概述
  • 开始之前
  • 检索匹配文档
  • Where 方法示例
  • 逻辑条件操作
  • 范围和类型检查
  • 文本模式匹配示例
  • 检索不同值
  • 聚合
  • 按常见字段值分组结果示例
  • 结果数量示例
  • 字段最大值示例
  • 字段最小值示例
  • 字段平均值示例
  • 字段求和示例
  • 聚合匹配结果示例
  • 设置查询级选项
  • 修改查询结果
  • 排序结果示例
  • 跳过指定数量结果示例
  • 显示结果中字段的子集和数组值示例
  • 分页结果示例
  • 使用 MongoDB 操作检索数据
  • 包含字段示例
  • 包含所有字段示例
  • 匹配数组大小示例
  • 匹配数据类型示例
  • 匹配通过模运算得到的值示例
  • 匹配正则表达式
  • 运行MongoDB查询API操作示例
  • 匹配数组元素示例
  • 指定游标超时示例
  • 使用地理空间操作匹配位置
  • 接近位置示例
  • 在区域内示例
  • 与几何图形相交示例
  • 附近匹配的邻近数据示例
  • 使用MongoDB写入操作写入数据
  • 更新文档示例
  • 递增数值示例
  • 递减数值示例
  • 添加数组元素示例
  • 移除数组元素示例
  • 移除字段示例

概述

在本指南中，您可以学习如何使用Laravel查询构建器的Laravel集成扩展来处理MongoDB数据库。查询构建器允许您使用单一语法和流畅的接口来编写针对任何支持的数据库的查询。

注意

Laravel集成扩展了Laravel查询构建器和Eloquent ORM，它们可以执行类似的数据库操作。要了解更多关于使用Eloquent模型检索文档的信息，请参阅读取操作.

Laravel提供了一个门面来访问查询构建器类DB，它允许您执行数据库操作。门面作为类的静态接口，使语法更简洁，避免运行时错误，并提高可测试性。

Laravel集成提供了DB方法的table()，用于访问集合。通过链式方法指定命令和任何约束。然后，在最后链式调用get()方法来运行方法和检索结果。如果要检索第一个匹配的结果，请使用first()方法而不是get()方法。从Laravel MongoDB v5.0开始，查询构建器将结果作为stdClass对象返回。

以下示例显示了查询构建器调用的语法

DB::table('<collection name>')
    // chain methods by using the "->" object operator
    ->get();

提示

设置数据库连接

在使用DB::table()方法之前，请确保您已指定MongoDB为应用程序的默认数据库连接。有关设置数据库连接的说明，请参阅快速入门中的配置您的MongoDB连接步骤。

如果MongoDB不是应用程序的默认数据库，您可以使用DB::connection()方法指定MongoDB连接。将连接名称传递给connection()方法，如下面的代码所示

$connection = DB::connection('mongodb');

本指南提供了以下类型查询构建器操作的示例：

  • 检索匹配文档

  • 设置查询级选项

  • 修改查询结果

  • 使用 MongoDB 操作检索数据

  • 使用MongoDB写入操作写入数据

在开始之前

要运行本指南中的代码示例，请完成快速入门教程，配置Web应用程序，将样本数据集加载到您的MongoDB部署中，并从控制器方法中运行示例代码。要查看预期的代码输出作为JSON文档，请使用快速入门中可选的将结果以JSON文档形式查看步骤中显示的toJson()方法。

要使用查询构建器执行读取和写入操作，导入Illuminate\Support\Facades\DB外观并编写查询。

检索匹配的文档

本节包含以下操作符类别中读取操作的查询构建器示例

Where方法示例

以下示例展示了如何使用where()查询构建方法从包含imdb.rating字段值为 exactly 9.3的movies集合中检索文档。点击查看输出按钮查看查询返回的结果

$result = DB::connection('mongodb')
    ->table('movies')
    ->where('imdb.rating', 9.3)
    ->get();
[
   { "title": "Cosmos",
     "year": 1980,
     "runtime": 60,
     "imdb": {
       "rating": 9.3,
       "votes": 17174,
       "id": 81846
     },
     "plot": "Astronomer Carl Sagan leads us on an engaging guided tour of the various elements and cosmological theories of the universe.",
     ...
   },
   { "title": "The Shawshank Redemption",
     "year": 1994,
     "runtime": 142,
     "imdb": {
       "rating": 9.3,
       "votes": 1521105,
       "id": 111161
     },
     "plot": "Two imprisoned men bond over a number of years, finding solace and eventual redemption through acts of common decency.",
     ...
   },
   { "title": "The Real Miyagi",
     "year": 2015,
     "runtime": 90,
     "imdb": {
       "rating": 9.3,
       "votes": 41,
       "id": 2313306
     },
     "plot": "The life of the greatest karate master of a generation.",
      ...
   }
]

逻辑条件操作

本节中的示例展示了您可以使用以下查询构建语法执行以下逻辑条件操作

逻辑或示例

以下示例展示了如何使用orWhere()查询构建方法将movies集合中_id字段的值是ObjectId('573a1398f29313caabce9682')或title字段的值是"Back to the Future"的文档检索出来

$result = DB::connection('mongodb')
    ->table('movies')
    ->where('id', new ObjectId('573a1398f29313caabce9682'))
    ->orWhere('title', 'Back to the Future')
    ->get();

注意

您可以在查询中使用id别名来表示MongoDB文档中的_id字段，如前面的代码所示。当您使用查询构建器运行查找操作时，Laravel集成会自动在_id和id字段名之间进行转换。在查询结果中，_id字段以id的形式呈现。这提供了与Laravel更好的一致性，因为框架默认假设每个记录都有一个名为id的主键。

由于这种行为，您不能在文档中有两个不同的id和_id字段。

逻辑与示例

以下示例展示了如何将where()查询构建方法链式调用，以检索符合以下条件的movies集合中的文档：imdb评分大于8.5且年份小于1940

$result = DB::connection('mongodb')
    ->table('movies')
    ->where('imdb.rating', '>', 8.5)
    ->where('year', '<', 1940)
    ->get();

提示

为了与Laravel兼容，Laravel MongoDB v5.1支持箭头（->）和点（.）表示法来访问查询过滤器中的嵌套字段。前面的示例使用点表示法查询嵌套的imdb.rating字段，这是推荐的语法。

逻辑非示例

以下示例展示了如何调用whereNot()查询构建方法，以检索符合以下条件的movies集合中的文档：不包含imdb评分大于2的文档。这相当于匹配所有imdb评分小于或等于2的文档。

$result = DB::connection('mongodb')
    ->table('movies')
    ->whereNot('imdb.rating', '>', 2)
    ->get();

嵌套逻辑运算符组示例

以下示例展示了如何将where()查询构建方法链起来以检索符合以下两个条件的movies集合中的文档。此示例将闭包作为where()查询构建方法的第一个参数传递，以分组逻辑或组

  • imdb.rating的值大于8.5

  • year的值是1986或1996

$result = DB::connection('mongodb')
    ->table('movies')
    ->where('imdb.rating', '>', 8.5)
    ->where(function (Builder $query) {
        return $query
            ->where('year', 1986)
            ->orWhere('year', 1996);
    })->get();

范围和类型检查

本节中的示例展示了您可以使用以下范围查询和类型检查操作来匹配值的查询构建器语法

数值范围示例

以下示例展示了如何使用whereBetween()查询构建方法从movies集合中检索包含imdb.rating值在9到9.5之间的文档

$result = DB::connection('mongodb')
    ->table('movies')
    ->whereBetween('imdb.rating', [9, 9.5])
    ->get();
[
   { "title" "The Godfather", "imdb": { "rating": 9.2, "votes": 1038358, "id": 68646 }, ... },
   { "title": "Hollywood", "imdb": { "rating": 9.1, "votes": 511,"id": 80230 }, ... },
   { "title": "Cosmos", "imdb": { "rating": 9.3, "votes": 17174, "id": 81846 }, ... },
   ...
]

空值或缺失值示例

以下示例展示了如何使用whereNull()查询构建器方法从movies集合中检索缺少runtime值或字段的文档

$result = DB::connection('mongodb')
    ->table('movies')
    ->whereNull('runtime')
    ->get();

集合中一个或多个值示例

以下示例展示了如何使用whereIn()查询构建器方法从movies集合中检索与指定集合中至少一个title值匹配的文档

$result = DB::table('movies')
    ->whereIn('title', ['Toy Story', 'Shrek 2', 'Johnny English'])
    ->get();
[
   { "title": "Toy Story", "year": 1995, "runtime": 81, ... },
   { "title": "Johnny English", "year": 2003, "runtime": 87, ... },
   { "title": "Shrek 2", "year" 2004, "runtime": 93, ... },
   ...
]

匹配日期示例

以下示例展示了如何使用 where() 查询构建器方法从 movies 集合中检索具有指定 released 值（即 2010 年 1 月 15 日）的文档，该值由一个 Carbon 对象指定。

$result = DB::connection('mongodb')
    ->table('movies')
    ->where('released', Carbon::create(2010, 1, 15))
    ->get();

注意

日期查询筛选器和结果类型

从 Laravel MongoDB v5.0 开始，作为查询筛选器传递的 Carbon 对象被转换为 UTCDateTime BSON 值，如前述代码所示。

在查询结果中，MongoDB 中的 UTCDateTime BSON 值作为 Carbon 对象返回。Laravel 集成在执行此转换时应用默认时区。

如果您想将日期作为字符串而不是 Carbon 对象表示在查询筛选器中，请使用 whereDate() 查询构建器方法。以下示例从 movies 集合中检索具有 released 值（即 2010 年 1 月 15 日）的文档，并指定日期为字符串。

$result = DB::connection('mongodb')
    ->table('movies')
    ->whereDate('released', '2010-1-15')
    ->get();

文本模式匹配示例

以下示例展示了如何使用 like 查询操作符和 where() 查询构建器方法通过指定的文本模式从 movies 集合中检索文档。

文本模式可以包含与以下通配符字符混合的文本

  • % 匹配零个或多个字符

  • _ 匹配单个字符

$result = DB::table('movies')
    ->where('title', 'like', '%spider_man%')
    ->get();
[
   { "title": "Kiss of the Spider Woman", ... },
   { "title": "Spider-Man", ... },
   { "title": "Spider-Man 2", ...},
   ...
]

whereLike() 和 whereNotLike() 方法

以下方法提供与使用 like 查询运算符匹配模式相同的功能

  • whereLike()：匹配指定的模式。默认情况下，此方法执行不区分大小写的匹配。您可以通过将 true 作为方法的最后一个参数传递来启用大小写敏感。

  • whereNotLike()：匹配字段值不包含指定字符串模式的文档。

以下示例显示了如何使用 whereLike() 方法来匹配标题字段值匹配模式 'Start%' 的文档，并启用大小写敏感。

$result = DB::connection('mongodb')
    ->table('movies')
    ->whereLike('title', 'Start%', true)
    ->get();
[
   { "title": "Start-Up", ... },
   { "title": "Start the Revolution Without Me", ... },
   ...
]

检索不同值

以下示例显示了如何使用 distinct() 查询构建器方法检索 movies 集合中所有不同年份字段的值。

$result = DB::table('movies')
    ->distinct('year')->get();

聚合

本节中的示例展示了您可以使用查询构建器语法来执行 聚合 操作。聚合是从一组查询结果数据中计算值的操作。您可以使用聚合来计算并返回以下信息

按常用字段值分组的示例

以下示例展示了如何使用 groupBy() 查询构建器方法根据 runtime 字段的共享值检索文档数据。此示例将以下操作链式调用以匹配来自 movies 集合的文档，这些文档包含值为 G 的 rated 值，并且对于每个不同的 runtime 值，包含一部电影的 title 字段。

  • 使用 where() 方法仅匹配包含值为 "G" 的 rated 字段的文档

  • 使用 groupBy() 方法按 runtime 字段的唯一值分组数据，并将 _id 字段分配给该值

  • 使用 orderBy() 方法按 runtime 字段对组进行排序

  • 通过在 get() 方法中指定它，从分组结果的最后一个文档中返回 title 数据

提示

groupBy() 方法调用 MongoDB 的 $group 聚合运算符和 $last 累加器运算符。有关这些运算符的更多信息，请参阅服务器手册中的 $group (aggregation)。

$result = DB::table('movies')
   ->where('rated', 'G')
   ->groupBy('runtime')
   ->orderBy('runtime', 'asc')
   ->get(['title']);
[
  ...
  {
    "_id": { "runtime": 64 },
    "runtime": 64,
    "title": "Stitch! The Movie"
  },
  {
     "_id": { "runtime": 67 },
     "runtime": 67,
     "title": "Bartok the Magnificent"
   },
   {
     "_id": { "runtime":68 },
     "runtime": 68,
     "title": "Mickey's Twice Upon a Christmas"
   },
   ...
]

结果数量示例

以下示例展示了如何使用count()查询构建方法来返回包含在movies集合中的文档数量

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

字段最大值示例

以下示例展示了如何使用max()查询构建方法来返回整个movies集合中runtime字段的最高数值

$result = DB::table('movies')
    ->max('runtime');

字段最小值示例

以下示例展示了如何使用min()查询构建方法来返回整个movies集合中year字段的最小数值

$result = DB::table('movies')
    ->min('year');

字段平均值示例

以下示例展示了如何使用avg()查询构建方法来返回整个movies集合中imdb.rating值的数值平均值。

$result = DB::table('movies')
    ->avg('imdb.rating');

字段求和示例

以下示例展示了如何使用sum()查询构建方法来返回整个movies集合中imdb.votes值的数值总和。

$result = DB::table('movies')
    ->sum('imdb.votes');

聚合匹配结果示例

以下示例展示了如何从匹配查询的结果中聚合数据。该查询匹配所有2000年之后的电影，并使用avg()方法计算这些匹配项的imdb.rating的平均值。

$result = DB::table('movies')
    ->where('year', '>', 2000)
    ->avg('imdb.rating');

设置查询级别选项

您可以通过在查询构建器上设置选项来修改Laravel集成执行操作的方式。您可以通过将选项数组传递给options()查询构建器方法来指定查询选项。

以下代码演示了如何将注释附加到查询

$result = DB::connection('mongodb')
    ->table('movies')
    ->where('year', 2000)
    ->options(['comment' => 'hello'])
    ->get();

查询构建器接受您可以在MongoDB PHP库中的find()方法中设置的相同选项。一些修改查询结果的选项，如skip、sort和limit，可以直接作为查询构建器方法设置，并在本指南的修改查询结果部分中描述。我们建议您使用这些方法而不是将它们作为选项传递。

修改查询结果

本节包括以下函数的查询构建器示例，这些函数可以修改查询结果的顺序和格式

订单结果示例

以下示例展示了如何使用 orderBy() 查询构建方法，根据 title 字段中指定的过滤器，按照 imdb.rating 值降序排列匹配的结果。

$result = DB::table('movies')
    ->where('title', 'like', 'back to the future%')
    ->orderBy('imdb.rating', 'desc')
    ->get();
[
  { "title": "Back to the Future", "imdb": { "rating":8.5,"votes":636511,"id":88763 }, ... },
  { "title": "Back to the Future Part II", "imdb": { "rating":7.8,"votes":292539,"id":96874 }, ... },
  { "title": "Back to the Future Part III", "imdb": {"rating":7.4,"votes":242390,"id":99088 }, ... },
  ...
]

省略指定数量结果示例

以下示例展示了如何使用 skip() 查询构建方法，省略与 title 字段中指定的过滤器匹配的前四个结果，并按 year 值升序排序。

$result = DB::table('movies')
    ->where('title', 'like', 'star trek%')
    ->orderBy('year', 'asc')
    ->skip(4)
    ->get();

在结果中显示字段的子集和数组值示例

以下示例展示了如何使用 project() 查询构建方法，匹配包含 imdb.rating 值高于 8.5 的文档，并仅返回以下字段值

  • 电影标题 title

  • 如果存在，则返回 cast 数组字段的第二到第四个值

  • 文档 _id 字段，这是自动包含的

$result = DB::table('movies')
    ->where('imdb.rating', '>', 8.5)
    ->project([
        'title' => 1,
        'cast' => ['$slice' => [1, 3]],
    ])
    ->get();
[
  {
    "_id": { ... },
    "title": "City Lights"
    "cast": [
      "Florence Lee",
      "Harry Myers",
      "Al Ernest Garcia"
    ],
  },
  {
    "_id": { ... },
    "title": "Modern Times",
    "cast": [
      "Paulette Goddard",
      "Henry Bergman",
      "Tiny Sandford"
    ]
  },
  {
    "_id": { ... },
    "title": "Casablanca"
    "cast": [
      "Ingrid Bergman",
      "Paul Henreid",
      "Claude Rains"
    ],
  },
  ...
]

结果分页示例

以下示例演示了如何使用 paginate() 查询构建器方法将整个 movie 集合划分为 15 个文档的离散结果集。示例还包括一个排序顺序，按 imdb.votes 字段降序排列结果，并仅包括结果中的特定字段。

$resultsPerPage = 15;
$projectionFields = ['title', 'runtime', 'imdb.rating'];
$result = DB::table('movies')
    ->orderBy('imdb.votes', 'desc')
    ->paginate($resultsPerPage, $projectionFields);

要了解更多有关分页的信息，请参阅 Laravel 文档中的 分页查询构建器结果。

使用 MongoDB 操作检索数据

本节包含查询构建器示例，展示了如何使用以下 MongoDB 特定查询操作

包含字段示例

以下示例展示了如何使用exists()查询构建器方法来匹配包含字段random_review的文档

$result = DB::table('movies')
    ->exists('random_review', true);

要了解更多关于此查询操作符的信息，请参阅服务器手册中的$exists

包含所有字段示例

以下示例展示了如何使用all查询操作符与where()查询构建器方法匹配包含所有指定字段的文档

$result = DB::table('movies')
    ->where('movies', 'all', ['title', 'rated', 'imdb.rating'])
    ->get();

要了解更多关于此查询操作符的信息，请参阅服务器手册中的$all

匹配数组大小示例

以下示例展示了如何使用size查询操作符与where()查询构建器方法匹配包含一个恰好有五个元素的directors字段的文档

$result = DB::table('movies')
    ->where('directors', 'size', 5)
    ->get();

要了解更多关于此查询操作符的信息，请参阅服务器手册中的$size

匹配数据类型示例

以下示例展示了如何使用带有 where() 查询构建器方法的 type 查询操作符来匹配包含 4 值的文档，该值对应于数组数据类型，在 released 字段中。

$result = DB::table('movies')
    ->where('released', 'type', 4)
    ->get();

有关类型代码和查询操作符的更多信息，请参阅服务器手册中的 $type。

使用取模运算符匹配计算值的示例

以下示例展示了如何使用带有 where() 查询构建器方法的 mod 查询操作符，通过表达式 year % 2 == 0 来匹配 year 字段的偶数值。

$result = DB::table('movies')
    ->where('year', 'mod', [2, 0])
    ->get();

有关此查询操作符的更多信息，请参阅服务器手册中的 $mod。

匹配正则表达式

以下示例展示了如何使用 REGEX 查询运算符和 where() 查询构建方法来匹配包含符合指定正则表达式的 title 字段的文档

$result = DB::connection('mongodb')
    ->table('movies')
    ->where('title', 'REGEX', new Regex('^the lord of .*', 'i'))
    ->get();

要了解更多关于 MongoDB 中的正则表达式查询的信息，请参阅服务器手册中的 $regex。

运行 MongoDB 查询 API 操作示例

以下示例展示了如何使用 whereRaw() 查询构建方法来运行使用 MongoDB 查询 API 语法编写的查询操作

$result = DB::table('movies')
    ->whereRaw([
        'imdb.votes' => ['$gte' => 1000 ],
        '$or' => [
            ['imdb.rating' => ['$gt' => 7]],
            ['directors' => ['$in' => [ 'Yasujiro Ozu', 'Sofia Coppola', 'Federico Fellini' ]]],
        ],
    ])->get();

以下代码展示了等效的 MongoDB 查询 API 语法

db.movies.find({
  "imdb.votes": { $gte: 1000 },
  $or: [{
    imdb.rating: { $gt: 7 },
    directors: { $in: [ "Yasujiro Ozu", "Sofia Coppola", "Federico Fellini" ] }
}]});

要了解更多关于 MongoDB 查询 API 的信息，请参阅服务器手册中的 MongoDB 查询 API。

匹配数组元素示例

以下示例展示了如何使用where()查询构建方法将elemMatch查询操作符传递给查询，以匹配包含至少一个指定查询条件匹配的数组元素的文档。

$result = DB::table('movies')
    ->where('writers', 'elemMatch', ['$in' => ['Maya Forbes', 'Eric Roth']])
    ->get();

要了解更多关于MongoDB中正则表达式查询的信息，请参阅服务器手册中的$elemMatch操作符。

指定游标超时示例

以下示例展示了如何使用timeout()方法来指定等待游标操作完成的最大持续时间。

$result = DB::table('movies')
    ->timeout(2) // value in seconds
    ->where('year', 2001)
    ->get();

注意

此设置将maxTimeMS值指定为秒而不是毫秒。要了解更多关于maxTimeMS值的信息，请参阅PHP库文档中的MongoDBCollection::find()。

使用地理空间操作匹配位置

本节中的示例展示了可以使用查询构建器语法执行地理空间查询，以检索以下类型的位置。

重要

要在MongoDB中执行GeoJSON查询，必须在集合上创建2d或2dsphere索引。要了解如何创建地理空间索引，请参阅Schema Builder指南中的创建地理空间索引部分。

要了解更多关于MongoDB支持的GeoJSON对象的信息，请参阅服务器手册中的GeoJSON Objects。

靠近位置示例

以下示例展示了如何使用 near 查询运算符和 where() 查询构建方法来匹配包含与 GeoJSON 点对象最多 50 米距离的位置的文档

$results = DB::table('theaters')
    ->where('location.geo', 'near', [
        '$geometry' => [
            'type' => 'Point',
            'coordinates' => [
                -86.6423,
                33.6054,
            ],
        ],
        '$maxDistance' => 50,
    ])->get();

要了解更多关于此运算符的信息，请参阅服务器手册中的 $near 运算符。

在区域内的示例

以下示例展示了如何使用 geoWithin 查询运算符和 where() 查询构建方法来匹配包含在指定 Polygon GeoJSON 对象边界内的位置的文档

$results = DB::table('theaters')
    ->where('location.geo', 'geoWithin', [
        '$geometry' => [
            'type' => 'Polygon',
            'coordinates' => [
                [
                    [-72, 40],
                    [-74, 41],
                    [-72, 39],
                    [-72, 40],
                ],
            ],
        ],
    ])->get();

与几何相交的示例

以下示例展示了如何使用 geoIntersects 查询运算符和 where() 查询构建方法来匹配包含与指定的 LineString GeoJSON 对象相交位置的文档

$results = DB::table('theaters')
    ->where('location.geo', 'geoIntersects', [
        '$geometry' => [
            'type' => 'LineString',
            'coordinates' => [
                [-73.600525, 40.74416],
                [-72.600525, 40.74416],
            ],
        ],
    ])->get();

附近匹配的邻近数据示例

以下示例展示了如何使用 geoNear 聚合运算符和 raw() 查询构建方法来执行一个聚合操作，该操作返回诸如每个匹配项的邻近信息等元数据

$results = DB::table('theaters')->raw(
    function (Collection $collection) {
        return $collection->aggregate([
            [
                '$geoNear' => [
                    'near' => [
                        'type' => 'Point',
                        'coordinates' => [-118.34, 34.10],
                    ],
                    'distanceField' => 'dist.calculated',
                    'maxDistance' => 500,
                    'includeLocs' => 'dist.location',
                    'spherical' => true,
                ],
            ],
        ]);
    },
)->toArray();

要了解更多关于此聚合运算符的信息，请参阅服务器手册中的 $geoNear 运算符。

使用 MongoDB 写入操作写入数据

本节包括查询构建示例，展示了如何使用以下 MongoDB 特定的写入操作

更新或插入文档示例

从v4.7版本开始，您可以使用以下查询构建器方法之一执行upsert操作：

  • upsert()：当您使用此方法时，您可以执行 批量upsert，在一次操作中更改或插入多个文档。

  • update()：当您使用此方法时，您必须指定 upsert 选项来更新所有匹配查询筛选器的文档，或者在没有匹配文档的情况下插入一个文档。仅在v4.6及更早版本中支持此upsert方法。

upsert方法

upsert(array $values, array|string $uniqueBy, array|null $update) 查询构建器方法接受以下参数

  • $values：要更新或插入的文档的字段和值的数组。

  • $uniqueBy：用于唯一标识第一个数组参数中文档的字段列表。

  • $update：可选的字段列表，如果存在匹配的文档则更新。如果您省略此参数，Laravel集成将更新所有字段。

以下示例展示了如何使用 upsert() 查询构建器方法根据以下说明更新或插入文档

  • 指定一个文档，其中 title 字段的值是 'Inspector Maigret'，recommended 字段的值是 false，而 runtime 字段的值是 128。

  • 指定一个文档，其中 title 字段的值是 'Petit Maman'，recommended 字段的值是 true，而 runtime 字段的值是 72。

  • 指出 title 字段在操作范围内唯一标识文档。

  • 仅更新匹配文档中的 recommended 字段。

$result = DB::table('movies')
    ->upsert(
        [
            ['title' => 'Inspector Maigret', 'recommended' => false, 'runtime' => 128],
            ['title' => 'Petit Maman', 'recommended' => true, 'runtime' => 72],
        ],
        'title',
        'recommended',
    );

upsert() 查询构建器方法返回操作更新的、插入的和修改的文档数量。

注意

upsert() 方法不会触发事件。要从upsert操作触发事件，请使用 createOrFirst() 方法代替。

更新方法

以下示例展示了如何使用 update() 查询构建器方法和 upsert 选项来更新匹配的文档或在不存在的文档中插入具有指定数据的文档。当将 upsert 选项设置为 true 且文档不存在时，该命令将插入数据和在 where() 查询操作中指定的 title 字段和值。

$result = DB::table('movies')
    ->where('title', 'Will Hunting')
    ->update(
        [
            'plot' => 'An autobiographical movie',
            'year' => 1998,
            'writers' => [ 'Will Hunting' ],
        ],
        ['upsert' => true],
    );

update() 查询构建器方法返回操作更新或插入的文档数。

增加数值示例

以下示例展示了如何使用 increment() 查询构建器方法将 3000 添加到匹配文档中 imdb.votes 字段的值。

$result = DB::table('movies')
    ->where('title', 'Field of Dreams')
    ->increment('imdb.votes', 3000);

increment() 查询构建器方法返回操作更新的文档数。

从 Laravel 集成 v4.8 开始，您还可以使用 incrementEach() 查询构建器方法在单个操作中增加多个值。以下示例使用 incrementEach() 方法增加匹配文档中 awards.wins 和 imdb.votes 字段的值。

$result = DB::table('movies')
    ->where('title', 'Lost in Translation')
    ->incrementEach([
        'awards.wins' => 2,
        'imdb.votes' => 1050,
    ]);

注意

如果您将字段传递给 increment() 或 incrementEach() 方法，而该字段在匹配的文档中没有值或不存在，这些方法将初始化指定的字段为增量值。

减少数值示例

以下示例展示了如何使用 decrement() 查询构建器方法从匹配文档的 imdb.rating 字段中减去 0.2

$result = DB::table('movies')
    ->where('title', 'Sharknado')
    ->decrement('imdb.rating', 0.2);

decrement() 查询构建器方法返回操作更新的文档数量。

从 Laravel 集成 v4.8 开始，您还可以使用 decrementEach() 查询构建器方法在一次操作中减少多个值。以下示例使用 decrementEach() 方法减少匹配文档中 metacritic 和 imdb.rating 字段的值。

$result = DB::table('movies')
    ->where('title', 'Dunkirk')
    ->decrementEach([
        'metacritic' => 1,
        'imdb.rating' => 0.4,
    ]);

注意

如果您将字段传递给 decrement() 或 decrementEach() 方法，而该字段没有值或不存在于匹配的文档中，这些方法将初始化指定的字段为减量值。

添加数组元素示例

以下示例展示了如何使用 push() 查询构建器方法将 "Gary Cole" 添加到匹配文档的 cast 数组字段。

$result = DB::table('movies')
    ->where('title', 'Office Space')
    ->push('cast', 'Gary Cole');

push() 查询构建器方法返回操作更新的文档数量。

删除数组元素示例

以下示例展示了如何使用pull()查询构建器方法从与查询匹配的文档中删除genres字段中的"Adventure"值

$result = DB::table('movies')
    ->where('title', 'Iron Man')
    ->pull('genres', 'Adventure');

pull()查询构建器方法返回操作更新的文档数量。

删除字段示例

以下示例展示了如何使用unset()查询构建器方法从与查询匹配的文档中删除tomatoes.viewer字段和值

$result = DB::table('movies')
    ->where('title', 'Final Accord')
    ->unset('tomatoes.viewer');

unset()查询构建器方法返回操作更新的文档数量。

返回

架构构建器

下一步

用户身份验证

本页内容