运行数据库命令

本页内容

概述

执行命令
响应
命令示例
附加信息
API文档

概述

在本指南中，您可以了解如何使用MongoDB PHP库来运行数据库命令。您可以使用数据库命令执行各种管理性和诊断任务，例如获取服务器统计信息、初始化副本集或运行聚合管道。

重要

优先使用库方法而非数据库命令

库为许多数据库命令提供了包装方法。我们建议在可能的情况下使用这些方法而不是直接执行数据库命令。

要执行管理任务，请使用MongoDB Shell 而不是MongoDB PHP库。Shell提供了可能在库中不可用的辅助方法。

如果库或Shell中没有可用的辅助方法，您可以使用db.runCommand() Shell方法或库的 MongoDB\Database::command() 方法，该方法在本指南中有所描述。

执行命令

要运行数据库命令，您必须在命令文档中指定命令和任何相关参数，然后将命令文档传递给 MongoDB\Database::command() 方法。许多数据库命令返回多个结果文档，因此 command() 方法返回一个您可以迭代的 MongoDB\Driver\Cursor 对象。

以下代码展示了如何使用 command() 方法在MongoDB\Database 实例上运行 hello 命令，该命令返回有关服务器的信息

$database = $client->selectDatabase('myDB');
$cursor = $database->command(['hello' => 1]);

要查找数据库命令和相应参数的完整列表，请参阅附加信息部分。

注意

读偏好

command() 方法不会继承您可能在代码的其他地方设置的读偏好。默认情况下，command() 使用 primary 读偏好。

您可以通过在选项参数中设置一个来为命令执行设置读偏好，如下面的代码所示

$readPref = new MongoDB\Driver\ReadPreference('primaryPreferred');
$cursor = $database->command(
    ['hello' => 1], 
    ['readPreference' => $readPref]
);

在PHP 扩展 API 文档中了解有关 ReadPreference 类的更多信息。

要了解更多关于读取偏好选项的信息，请参阅MongoDB服务器手册中的读取偏好。

响应

方法command()返回一个包含给定命令数据库响应的Cursor对象。每个数据库命令执行不同的功能，因此响应内容可能不同。

对于返回单个结果文档的命令，该结果作为游标中的第一个也是唯一的文档可用。对于返回多个结果文档的命令，库将原始命令响应中的游标封装转换为可迭代的游标，该封装包括游标ID和第一批结果。

在运行命令之前，了解命令的响应格式，以便您的应用程序可以遍历多个结果或从游标中提取第一个也是唯一的文档。请参阅本指南的附加信息部分，以找到数据库命令完整列表的链接。

原始命令响应包含以下字段

字段	描述
<command result>	特定于数据库命令的字段。例如，`count`命令返回`n`字段。
`ok`	命令是否成功（`1`）或失败（`0`）。如果`ok`字段为`0`，库将抛出CommandException异常。
`operationTime`	操作的逻辑时间。MongoDB使用逻辑时间来排序操作。要了解更多关于这个概念的信息，请参阅我们关于全局逻辑时钟的博客文章。
`$clusterTime`	一个包含签名集群时间的文档。集群时间是一种用于操作排序的逻辑时间。

命令示例

以下示例使用command()方法运行dbStats命令，以检索accounts数据库的存储统计信息。

$database = $client->accounts;
$command = ['dbStats' => 1];
// dbStats returns a single document
$cursor = $database->command($command);
// Print the first document in the cursor
echo json_encode($cursor->toArray()[0]), PHP_EOL;

此命令的输出包括数据库中集合的信息，并描述了跨集合存储的数据量和大小。

{"db":"accounts","collections":2,"views":0,"objects":5,"avgObjSize":22,"dataSize":110,
"storageSize":40960,"totalFreeStorageSize":0,"numExtents":0,"indexes":2,"indexSize":40960,
"indexFreeStorageSize":0,"fileSize":0,"nsSizeMB":0,"ok":1}