运行数据库命令

Overview

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

重要

首选驱动程序方法而非数据库命令

驱动程序为许多数据库命令提供了包装器方法。如果可能，我们建议使用这些方法，而不是执行数据库命令。

要执行管理任务，请使用MongoDB Shell而不是Ruby驱动程序。Shell提供了驱动程序中可能不可用的辅助工具。

如果驱动程序或shell中没有可用的辅助工具，则可以使用 db.runCommand() shell方法或驱动程序的 command 和 cursor_command 方法，如本指南中所述。

样本数据

本指南中的示例使用Atlas示例数据集中的 sample_restaurants数据库。要从Ruby应用程序访问权限此数据库，请创建一个连接到Atlas 集群的Mongo::Client对象，并将以下值分配给 database 变量：

database = client.use('sample_restaurants').database

要学习如何创建免费的MongoDB Atlas 集群并加载示例数据集，请参阅MongoDB 入门指南。

使用 `command` 方法

要运行数据库命令，请在 Mongo::Database 实例上调用 command 方法，并将要运行的操作名称作为参数传递。

以下示例调用 command 方法来运行hello 命令，该命令会返回有关服务器的信息：

database.command(hello: 1)

提示

要查看数据库命令及其相应参数的完整列表，请参阅MongoDB Server手册中的数据库命令。

`command` 响应

command 方法返回 Mongo::Operation::Result，其中包含数据库对给定命令的响应。

您可以使用以下方法访问权限原始命令响应文档的字段：

方法	说明
`acknowledged?`	如果服务器确认该命令，则返回 `true`，否则返回 `false`。
`inspect`	返回命令响应的格式化字符串表示形式。
`ok?`	如果命令成功，则返回 `true`，否则返回 `false`。如果 `ok?` 方法返回 `false`，则驱动程序将引发 `Mongo::Error::OperationFailure`。
`cluster_time`	返回服务器响应中报告的集群时间。集群时间是用于对操作进行排序的逻辑时间。此字段仅适用于在副本集或分片集群上运行的命令。
`operation_time`	返回操作执行的逻辑时间。

有关 Result对象可用方法的完整列表，请参阅API文档。

提示

要学习；了解有关逻辑时间的更多信息，请参阅有关逻辑时钟的维基百科条目。

以下示例运行 dbStats 命令来检索sample_restaurants数据库的存储统计信息，然后使用 inspect 方法打印命令结果：

puts database.command({dbStats: 1}).first

此命令的输出包括数据库中存储的数据的信息，如以下代码所示：

{"db"=>"sample_restaurants", "collections"=>4, "views"=>0, "objects"=>18767, "avgObjSize"=>596.1911866574306,"dataSize"=>11188720, "storageSize"=>7528448, "totalFreeStorageSize"=>0, "numExtents"=>0, "indexes"=>6,"indexSize"=>1519616, "indexFreeStorageSize"=>0, "fileSize"=>0,"nsSizeMB"=>0, "ok"=>1}

使用 `cursor_command` 方法

一些数据库命令会在游标中返回其结果。要运行这些命令，请在 Mongo::Database 实例上调用 cursor_command 方法。此方法返回一个 Mongo::Cursor 对象，当您对其进行迭代时，该对象会从服务器检索其他批处理结果。如果命令响应不包含游标，驱动程序会引发 Mongo::Error::InvalidCursorOperation 错误。

以下示例使用 cursor_command 方法运行 listCollections 命令，并打印 sample_restaurants 数据库中每个集合的名称和类型：

cursor = database.cursor_command(listCollections: 1, nameOnly: true)cursor.each do |doc|  puts docend

{"name"=>"restaurants", "type"=>"collection"}{"name"=>"neighborhoods", "type"=>"collection"}

命令选项

您可以将以下选项传递给 command 和 cursor_command 方法：

选项	方法	说明
`:read`	`command`, `cursor_command`	用于该命令的读取偏好（read preference）。`cursor_command` 方法也对后续 `getMore` 命令使用此读取偏好（read preference）。默认情况下，这两种方法都使用 `primary` 读取偏好（read preference）。
`:session`	`command`, `cursor_command`	用于该命令的会话。如果您没有为 `cursor_command` 方法指定会话，驱动程序将创建一个隐式会话，该会话在游标的生命周期内持续有效。
`:timeout_ms`	`command`, `cursor_command`	操作超时时间（以毫秒为单位）。该值必须是非负整数。`0` 的值表示没有超时。如果您不设置此选项，该方法将从数据库或客户端继承超时设置。
`:batch_size`	`cursor_command`	在 `getMore` 命令上发送的 `batchSize` 值。
`:max_time_ms`	`cursor_command`	在 `getMore` 命令上发送的 `maxTimeMS` 值。要为初始命令设置时间限制，请在命令文档中包含 `maxTimeMS` 字段。
`:comment`	`cursor_command`	附加到 `getMore` 命令的注释。
`:cursor_type`	`cursor_command`	游标类型，可以是 `:tailable` 或 `:tailable_await`。此值必须与命令文档中设置的标志相匹配。
`:timeout_mode`	`cursor_command`	超时模式，可以是 `:cursor_lifetime` 或 `:iteration`。

设置读取偏好

command 和 cursor_command 方法不会继承 Database 实例上的读取偏好（read preference）。

您可以通过将 :read 选项传递给 command 方法来为命令执行设置读取偏好（read preference），如下面的代码所示：

database.command({hello: 1}, read: {mode: :secondary})

提示

要学习；了解有关读取偏好（read preference）选项的更多信息，请参阅MongoDB Server手册中的读取偏好。

运行数据库命令

Overview

样本数据

使用 command 方法

command 响应

使用 cursor_command 方法

命令选项

设置读取偏好

更多信息

API 文档

使用 `command` 方法

`command` 响应

使用 `cursor_command` 方法