使用批量执行工具库在 Azure Cosmos DB for Gremlin 中批量引入数据
适用对象：
Gremlin
图形数据库通常需要批量引入数据才能刷新整个图形或更新图形的一部分。 Azure Cosmos DB 是一个分布式数据库，也是 Azure Cosmos DB for Gremlin 的主干，它可在负载分布良好时达到最佳性能。 Azure Cosmos DB 中的批量执行工具库旨在利用 Azure Cosmos DB 的这一独特功能并提供最佳性能。 有关详细信息，请参阅 .NET SDK 中的批量支持简介。
本教程说明了如何使用 Azure Cosmos DB 的批量执行工具库将图形对象导入 Azure Cosmos DB for Gremlin 容器并对其进行更新。 在此过程中，可使用该库以编程方式创建顶点和边对象，然后为每个网络请求插入多个对象。
请使用批量执行工具库在本地创建和验证对象，而不是向数据库发送 Gremlin 查询；发送查询会评估命令，然后一次执行一个命令。 在此库初始化图形对象后，你可将这些图形对象按顺序发送到数据库服务。
通过使用此方法，可将数据引入速度提高 100 倍，这使它成为执行初始数据迁移或定期数据移动操作的理想方法。
批量执行工具库现在有以下几种类型。
.NET
先决条件
在开始之前，请确保具有以下各项：
包含 Azure 开发工作负荷的 Visual Studio 2019。 一开始可以使用免费的 Visual Studio 2019 Community Edition。
Azure 订阅。 如果还没有订阅，可以创建 Azure 帐户。
或者，可以创建一个免费的 Azure Cosmos DB 帐户，而无需订阅 Azure。
包含不受限集合的 Azure Cosmos DB for Gremlin 数据库。 若要开始使用，请转至 .NET 中的 Azure Cosmos DB for Gremlin。
Git。 若要开始使用，请转至 git 下载页。
克隆
若要使用此示例，请运行以下命令：
git clone https://github.com/Azure-Samples/azure-cosmos-graph-bulk-executor.git
若要获取示例，请转到 .\azure-cosmos-graph-bulk-executor\dotnet\src\。
示例
IGraphBulkExecutor graphBulkExecutor = new GraphBulkExecutor("MyConnectionString", "myDatabase", "myContainer");
List<IGremlinElement> gremlinElements = new List<IGremlinElement>();
gremlinElements.AddRange(Program.GenerateVertices(Program.documentsToInsert));
gremlinElements.AddRange(Program.GenerateEdges(Program.documentsToInsert));
BulkOperationResponse bulkOperationResponse = await graphBulkExecutor.BulkImportAsync(
gremlinElements: gremlinElements,
enableUpsert: true);
执行
按下表所述修改参数：
| 参数 | 描述 |
|---|---|
ConnectionString |
你的服务连接字符串（将会显示在 Azure Cosmos DB for Gremlin 帐户的“密钥”部分中）。 格式为 AccountEndpoint=https://<account-name>.documents.azure.cn:443/;AccountKey=<account-key>;。 |
DatabaseName，ContainerName |
目标数据库和容器的名称。 |
DocumentsToInsert |
要生成的文档数量（仅与综合数据相关）。 |
PartitionKey |
确保在数据引入期间为每个文档指定分区键。 |
NumberOfRUs |
仅当容器尚不存在且需要在执行期间创建时才相关。 |
Java
示例用法
以下示例应用程序说明了如何使用 GraphBulkExecutor 包。 示例直接使用 domain 对象注释或 POJO 对象（普通的旧 Java 对象）。 建议尝试这两种方法，以确定哪种方法更能满足你的实现和性能需求。
克隆
若要使用示例，请运行以下命令：
git clone https://github.com/Azure-Samples/azure-cosmos-graph-bulk-executor.git
若要获取示例，请转到 .\azure-cosmos-graph-bulk-executor\java\。
先决条件
若要运行此示例，需要具备以下软件：
- OpenJDK 11
- Maven
- 一个配置为使用 Gremlin API 的 Azure Cosmos DB 帐户
示例
private static void executeWithPOJO(Stream<GremlinVertex> vertices,
Stream<GremlinEdge> edges,
boolean createDocs) {
results.transitionState("Configure Database");
UploadWithBulkLoader loader = new UploadWithBulkLoader();
results.transitionState("Write Documents");
loader.uploadDocuments(vertices, edges, createDocs);
}
配置
若要运行示例，请参考以下配置，并根据需要进行修改。
/resources/application.properties 文件定义了配置 Azure Cosmos DB 所需的数据。 下表描述了所需的值：
| 属性 | 说明 |
|---|---|
sample.sql.host |
Azure Cosmos DB 提供的值。 确保使用的是 .NET SDK URI，它位于 Azure Cosmos DB 帐户的“概述”部分。 |
sample.sql.key |
可以从 Azure Cosmos DB 帐户的“密钥”部分中获取主密钥或辅助密钥。 |
sample.sql.database.name |
Azure Cosmos DB 帐户中要对其运行该示例的数据库的名称。 如果找不到该数据库，示例代码会创建一个。 |
sample.sql.container.name |
数据库中要对其运行该示例的容器的名称。 如果找不到该容器，示例代码会创建一个。 |
sample.sql.partition.path |
如果需要创建容器，请使用此值定义 partitionKey 路径。 |
sample.sql.allow.throughput |
容器将更新为使用此处定义的吞吐量值。 如果正在研究可满足性能需求的各种吞吐量选项，请确保在研究完成后重置容器的吞吐量。 为容器保持预配较高的吞吐量会产生相关成本。 |
执行
根据环境修改配置后，运行以下命令：
mvn clean package
为了提高安全性，还可将 pom.xml 文件中的 skipIntegrationTests 值更改为 false 来运行集成测试。
成功运行单元测试后，可以运行示例代码：
java -jar target/azure-cosmos-graph-bulk-executor-1.0-jar-with-dependencies.jar -v 1000 -e 10 -d
如果运行上述命令，则会小批量（1,000 个顶点和大约 5,000 条边）执行示例。 使用以下部分中的命令行参数来调整正在运行的卷以及要运行的示例版本。
命令行参数
运行此示例时有几个命令行参数可用，如下表所述：
| 参数 | 说明 |
|---|---|
--vertexCount（-v） |
告知应用程序要生成多少个人员顶点。 |
--edgeMax（-e） |
告知应用程序要为每个顶点最多生成多少条边。 生成器会从 1 到你提供的值中随机选择一个数字。 |
--domainSample（-d） |
告知应用程序使用人员和关系域结构而不是 GraphBulkExecutors、GremlinVertex 和 GremlinEdge POJO 来运行示例。 |
--createDocuments（-c） |
告知应用程序使用 create 操作。 如果该参数不存在，应用程序默认使用 upsert 操作。 |
详细示例信息
人员顶点
person 类是一个简单的域对象，它已通过多个注释进行修饰，以帮助转换为 GremlinVertex 类，如下表所述：
| 类注释 | 说明 |
|---|---|
GremlinVertex |
使用可选的 label 参数来定义使用此类创建的所有顶点。 |
GremlinId |
用于定义将哪个字段用作 ID 值。 虽然 person 类中的字段名称是 ID，但它不是必需的。 |
GremlinProperty |
在 email 字段中用来更改存储在数据库中的属性的名称。 |
GremlinPartitionKey |
用于定义类中的哪个字段包含分区键。 你提供的字段名称应与容器中分区路径定义的值匹配。 |
GremlinIgnore |
用于从写入数据库的属性中排除 isSpecial 字段。 |
RelationshipEdge 类
RelationshipEdge 类是一个通用的域对象。 通过使用字段级标签注释，可以创建边类型的动态集合，如下表所示：
| 类注释 | 说明 |
|---|---|
GremlinEdge |
类中的 GremlinEdge 修饰用于定义指定分区键的字段名称。 创建边文档时，分配的值来自源顶点信息。 |
GremlinEdgeVertex |
定义两个 GremlinEdgeVertex 实例，边的每一端（源和目标）各一个。 本示例使用 GremlinEdgeVertexInfo 作为字段的数据类型。 需要使用 GremlinEdgeVertex 类提供的信息才能在数据库中正确创建边。 另一种做法是使用通过 GremlinVertex 注释修饰的类作为顶点的数据类型。 |
GremlinLabel |
示例边使用字段来定义 label 值。 它允许定义各种标签，因为它使用相同的基域类。 |
输出说明
控制台使用描述示例运行时间的 JSON 字符串来完成其运行。 该 JSON 字符串包含以下信息：
| JSON 字符串 | 说明 |
|---|---|
| startTime | System.nanoTime()，进程的启动时间。 |
| endTime | 进程结束时的 System.nanoTime()。 |
| durationInNanoSeconds | endTime 和 startTime 值之间的差值。 |
| durationInMinutes | 转换为分钟数的 durationInNanoSeconds 值。 durationInMinutes 值表示为浮点数，而不是时间值。 例如，值 2.5 表示 2 分 30 秒。 |
| vertexCount | 生成的顶点数量，应与传递给命令行执行的值匹配。 |
| edgeCount | 生成的边数量，它不是静态值，而是使用随机性元素生成的。 |
| exception | 仅在尝试运行时引发异常的情况下才填充。 |
状态数组
状态数组提供执行中每个步骤花费的时间的见解。 下表描述了这些步骤：
| 执行步骤 | 说明 |
|---|---|
| 生成示例顶点 | 构建请求的人员对象数量所需的时间。 |
| 生成示例边 | 构建关系对象所需的时间。 |
| 配置数据库 | 配置数据库所需的时间，由 application.properties 中提供的值决定。 |
| 写入文档 | 将文档写入数据库所需的时间。 |
每个状态都包含以下值：
| 状态值 | 说明 |
|---|---|
stateName |
报告的状态的名称。 |
startTime |
状态开始时的 System.nanoTime() 值。 |
endTime |
状态结束时的 System.nanoTime() 值。 |
durationInNanoSeconds |
endTime 和 startTime 值之间的差值。 |
durationInMinutes |
转换为分钟数的 durationInNanoSeconds 值。 durationInMinutes 值表示为浮点数，而不是时间值。 例如，值 2.5 表示 2 分 30 秒。 |
后续步骤
- 有关此命名空间中定义的类和方法的详细信息，请查看 BulkExecutor Java 开源文档。
- 请参阅使用 .NET SDK 将数据批量导入 Azure Cosmos DB SQL API 帐户一文。 此批量模式文档是 .NET V3 SDK 的一部分。