使用游标访问数据

Overview

在本指南中，您可以了解如何使用 Rust 驱动程序通过游标访问读取操作或聚合返回的数据。 游标是一种机制，可让您迭代多个文档，同时在给定时间仅在内存中保存其中的子集。

驱动程序提供Cursor类型以从游标检索文档。 例如，当您运行可以返回多个文档的查找操作时，驱动程序会返回一个Cursor实例，您可以从该实例访问匹配的文档。

Cursor运行读操作或聚合后，返回的实例包含该操作的批处理结果。当您遍历游标时，服务器会返回更多单独的结果。 如果在到达一批处理结果的末尾后还有更多匹配文档，则Cursor实例将获取下一批处理文档，直到返回所有结果。

本指南包括以下部分：

• 示例的样本数据显示了游标示例使用的样本数据

• 单独检索文档描述了如何使用迭代或流一次访问一个结果

• 以数组形式检索文档描述了如何通过收集返回的游标结果，以单个大量形式访问权限所有结果

• 检索原始文档批处理描述了如何使用原始批处理游标API进行零拷贝文档处理并直接访问权限BSON数据

• 指定游标行为描述了如何配置方法返回的游标

• 附加信息提供了本指南中提到的类型和方法的资源和 API 文档链接

示例样本数据

本指南中的示例使用存储在结构体中的以下数据：

let docs = vec! [
    Fruit { 
        name: "strawberry".to_string(), 
        color: "red".to_string() 
    },
    Fruit { 
        name: "banana".to_string(), 
        color: "yellow".to_string() 
    },
    Fruit { 
        name: "pomegranate".to_string(), 
        color: "red".to_string() 
    },
    Fruit { 
        name: "pineapple".to_string(), 
        color: "yellow".to_string() 
    }
];

分别检索文档

该驱动程序提供以下访问模式来遍历Cursor实例返回的文档：

• 内置模式：前进游标，然后检索并反序列化当前文档

• 流实现模式：迭代游标并调用Stream提供的方法来进程单个或多个文档

以下部分将更详细地描述这些访问模式和相应的方法。

let mut cursor = my_coll.find(doc! { "color": "red" }).await?;
while cursor.advance().await? {
    println!("{:?}", cursor.deserialize_current()?);
}

Fruit { name: "strawberry", color: "red" }
Fruit { name: "pomegranate", color: "red" }

let mut cursor = my_coll.find(doc! { "color": "red" }).await?;
println!("Output from next() iteration:");
while let Some(doc) = cursor.next().await {
    println!("{:?}", doc?);
}
println!();
let mut cursor = my_coll.find(doc! { "color": "yellow" }).await?;
println!("Output from try_next() iteration:");
while let Some(doc) = cursor.try_next().await? {
    println!("{:?}", doc);
}

Output from next() iteration:
Fruit { name: "strawberry", color: "red" }
Fruit { name: "pomegranate", color: "red" }
Output from try_next() iteration:
Fruit { name: "banana", color: "yellow" }
Fruit { name: "pineapple", color: "yellow" }

以数组形式检索文档

由于Cursor类型实现了Stream特征，因此您可以将游标的结果收集到数组中。

您可以使用以下方法以数组形式检索文档：

• collect()：将游标的结果收集为Vec<Result<T>>类型

• try_collect()：将游标的结果收集为Result<Vec<T>>类型

let cursor = my_coll.find(doc! { "color": "red" }).await?;
println!("Output from collect():");
let v: Vec<Result<Fruit>> = cursor.collect().await;
println!("{:?}", v);
println!();
let cursor = my_coll.find(doc! { "color": "yellow" }).await?;
println!("Output from try_collect():");
let v: Vec<Fruit> = cursor.try_collect().await?;
println!("{:?}", v);

Output from collect():
[Ok(Fruit { name: "strawberry", color: "red" }), Ok(Fruit { name: "pomegranate", color: "red" })]
Output from try_collect():
[Fruit { name: "banana", color: "yellow" }, Fruit { name: "pineapple", color: "yellow" }]

使用原始批处理游标

您可以对游标返回操作（例如 find()）调用 batch() 方法，以返回 RawBatchCursor。这允许您迭代服务器返回的原始BSON文档批处理，而不是单个反序列化值。当您需要直接访问权限服务器响应批处理时，此模块提供了一种高性能的文档进程方法。对具有高吞吐量的性能敏感游标应用程序使用原始批处理模式。

let mut cursor = my_coll.find(doc! { "color": "red" }).batch().await?;
while let Some(batch) = cursor.next().await {
    let batch = batch?;
    let doc_slices = batch.doc_slices()?;
    let count = doc_slices.into_iter().count();
    println!("Processing batch with {} documents", count);
    for doc_result in batch.doc_slices()? {
        let doc = doc_result?;
        if let mongodb::bson::RawBsonRef::Document(raw_doc) = doc {
            println!("Raw document size: {} bytes", raw_doc.as_bytes().len());
        }
    }
}

Processing batch with 4 documents
Raw document size: 58 bytes
Raw document size: 59 bytes
Raw document size: 58 bytes
Raw document size: 59 bytes

指定游标行为

要修改操作返回的游标，请将选项构建器方法链接到返回Cursor实例的方法。 示例，您可以将与游标相关的选项构建器方法链接到find()方法。

下表描述了与游标相关的选项，您可以通过调用相应的构建器方法来设立这些选项：

以下代码演示如何通过将选项构建器方法链接到find()方法来指定游标相关设置：

let mut cursor = my_coll.find(doc! { "color": "red" })
    .batch_size(5)
    .cursor_type(CursorType::Tailable)
    .no_cursor_timeout(true)
    .await?;

更多信息

要了解有关本指南中操作的更多信息，请参阅以下文档：

• 查找文档指南

• 指定查询指南

要了解有关 Rust 类型和 BSON 之间转换的更多信息，请参阅数据建模和序列化指南。