本教學示範如何在 Azure Cosmos DB Java V4 SDK 中執行批量操作。 此版本的 SDK 包含 Bulk Executor 程式庫。 如果您使用的是較舊版本的 Java SDK,請遷移至最新版本。 目前推薦用於 Java 批次支援的解決方案是 Azure Cosmos DB Java V4 SDK。
目前,只有 Azure Cosmos DB for NoSQL 和 API for Gremlin 帳戶才支援大量執行工具程式庫。 若要了解如何使用 Gremlin 的 API 使用大量執行器 .NET 函式庫,請參閱在 Azure Cosmos DB for Gremlin 中執行大量操作。
Tip
Agent Kit 協助程式設計代理程式依據建議的最佳實務,快速且有效地使用 Azure Cosmos DB。 開始時,請執行:
npx skills add AzureCosmosDB/cosmosdb-agent-kit
欲了解更多,請參閱 Azure Cosmos DB Agent Kit。
Prerequisites
如果您沒有 Azure 訂用帳戶,請在開始前建立免費帳戶。 或者,您也可以使用 Azure Cosmos DB 模擬器 來搭配
https://localhost:8081端點。 驗證請求中會提供主鍵。-
在 Ubuntu 上,執行
apt-get install default-jdk來安裝 JDK。務必設定 JAVA_HOME 環境變數,以指向 JDK 安裝所在的資料夾。
-
- 在 Ubuntu 上,您可以執行
apt-get install maven來安裝 Maven。
- 在 Ubuntu 上,您可以執行
使用 JAVA 快速入門文章的建立資料庫帳戶一節所述的步驟,建立 Azure Cosmos DB for NoSQL 帳戶。
複製範例應用程式
從 GitHub 下載 Java V4 SDK 的範例儲存庫。 這些範例應用程式會執行 CRUD 作業,並在 Azure Cosmos DB 上執行其他常見作業。 若要複製儲存庫,請開啟命令提示字元,前往您想要複製應用程式的目錄,然後執行以下指令:
git clone https://github.com/Azure-Samples/azure-cosmos-java-sql-api-samples
複製的存放庫會包含 SampleBulkQuickStartAsync.java 資料夾中的範例 azure-cosmos-java-sql-api-samples/src/main/java/com/azure/cosmos/examples/bulk/async。 該應用程式會產生文件並執行大量建立、更新、替換及刪除 Azure Cosmos DB 中的項目。 以下章節將檢視範例應用程式中的程式碼。
在 Azure Cosmos DB 中大量執行
- 以引數形式讀取 Azure Cosmos DB 的連接字串,並指派給 /
examples/common/AccountSettings.java檔案中定義的變數。 必須設定這些環境變數
ACCOUNT_HOST=your account hostname;ACCOUNT_KEY=your account primary key
若要執行大量範例,請指定其主要類別:
com.azure.cosmos.examples.bulk.async.SampleBulkQuickStartAsync
-
CosmosAsyncClient物件會使用下列陳述式進行初始化:
client = new CosmosClientBuilder()
.endpoint(AccountSettings.HOST)
.credential(new DefaultAzureCredentialBuilder().build())
.preferredRegions(preferredRegions)
.contentResponseOnWriteEnabled(true)
.consistencyLevel(ConsistencyLevel.SESSION).buildAsyncClient();
- 此範例會建立異步資料庫和容器。 接著會建立多個文件,而這些文件將用於執行批量操作。 此項目會將上述文件新增至
Flux<Family>回應式串流物件:
Family andersenFamilyItem = Families.getAndersenFamilyItem();
Family wakefieldFamilyItem = Families.getWakefieldFamilyItem();
Family johnsonFamilyItem = Families.getJohnsonFamilyItem();
Family smithFamilyItem = Families.getSmithFamilyItem();
// Setup family items to create
Flux<Family> families = Flux.just(andersenFamilyItem, wakefieldFamilyItem, johnsonFamilyItem, smithFamilyItem);
- 此範例包含批量建立、更新或插入、取代和刪除的方法。 在每個方法中,我們會將 BulkWriter
Flux<Family>流中的文件族群對應到CosmosBulkOperations中的多個方法呼叫。 這些作業會新增至另一個回應式串流物件Flux<CosmosItemOperation>。 然後,串流會傳遞至executeBulkOperations我們在開頭時建立的非同步container方法,並大量執行作業。 請參閱下列大量建立方法作為範例:
private void bulkCreateItems(Flux<Family> families) {
Flux<CosmosItemOperation> cosmosItemOperations = families.map(
family -> CosmosBulkOperations.getCreateItemOperation(family, new PartitionKey(family.getLastName())));
container.executeBulkOperations(cosmosItemOperations).blockLast();
}
-
BulkWriter.java與範例應用程式同目錄中的類別示範如何處理批量執行期間發生的速率限制(429)與逾時(408)錯誤,以及如何重試這些操作。 以下方法也示範如何實作本地與全域吞吐量控制。
private void bulkUpsertItemsWithBulkWriterAbstraction() {
Family andersenFamilyItem = Families.getAndersenFamilyItem();
Family wakefieldFamilyItem = Families.getWakefieldFamilyItem();
CosmosItemOperation wakeFieldItemOperation = CosmosBulkOperations.getUpsertItemOperation(wakefieldFamilyItem, new PartitionKey(wakefieldFamilyItem.getLastName()));
CosmosItemOperation andersonItemOperation = CosmosBulkOperations.getUpsertItemOperation(andersenFamilyItem, new PartitionKey(andersenFamilyItem.getLastName()));
BulkWriter bulkWriter = new BulkWriter(container);
bulkWriter.scheduleWrites(andersonItemOperation);
bulkWriter.scheduleWrites(wakeFieldItemOperation);
bulkWriter.execute().subscribe();
}
private void bulkUpsertItemsWithBulkWriterAbstractionAndLocalThroughPutControl() {
ThroughputControlGroupConfig groupConfig =
new ThroughputControlGroupConfigBuilder()
.setGroupName("group1")
.setTargetThroughput(200)
.build();
container.enableLocalThroughputControlGroup(groupConfig);
Family andersenFamilyItem = Families.getAndersenFamilyItem();
Family wakefieldFamilyItem = Families.getWakefieldFamilyItem();
CosmosItemOperation wakeFieldItemOperation = CosmosBulkOperations.getUpsertItemOperation(wakefieldFamilyItem, new PartitionKey(wakefieldFamilyItem.getLastName()));
CosmosItemOperation andersonItemOperation = CosmosBulkOperations.getUpsertItemOperation(andersenFamilyItem, new PartitionKey(andersenFamilyItem.getLastName()));
BulkWriter bulkWriter = new BulkWriter(container);
bulkWriter.scheduleWrites(andersonItemOperation);
bulkWriter.scheduleWrites(wakeFieldItemOperation);
bulkWriter.execute().subscribe();
}
private void bulkCreateItemsWithBulkWriterAbstractionAndGlobalThroughputControl() {
String controlContainerId = "throughputControlContainer";
CosmosAsyncContainer controlContainer = database.getContainer(controlContainerId);
database.createContainerIfNotExists(controlContainer.getId(), "/groupId").block();
ThroughputControlGroupConfig groupConfig =
new ThroughputControlGroupConfigBuilder()
.setGroupName("group-" + UUID.randomUUID())
.setTargetThroughput(200)
.build();
GlobalThroughputControlConfig globalControlConfig = this.client.createGlobalThroughputControlConfigBuilder(this.database.getId(), controlContainerId)
.setControlItemRenewInterval(Duration.ofSeconds(5))
.setControlItemExpireInterval(Duration.ofSeconds(20))
.build();
container.enableGlobalThroughputControlGroup(groupConfig, globalControlConfig);
CosmosItemRequestOptions requestOptions = new CosmosItemRequestOptions();
requestOptions.setThroughputControlGroupName(groupConfig.getGroupName());
Family andersenFamilyItem = Families.getAndersenFamilyItem();
Family wakefieldFamilyItem = Families.getWakefieldFamilyItem();
CosmosItemOperation andersonItemOperation = CosmosBulkOperations.getCreateItemOperation(andersenFamilyItem, new PartitionKey(andersenFamilyItem.getLastName()));
CosmosItemOperation wakeFieldItemOperation = CosmosBulkOperations.getCreateItemOperation(wakefieldFamilyItem, new PartitionKey(wakefieldFamilyItem.getLastName()));
BulkWriter bulkWriter = new BulkWriter(container);
bulkWriter.scheduleWrites(andersonItemOperation);
bulkWriter.scheduleWrites(wakeFieldItemOperation);
bulkWriter.execute().subscribe();
}
- 範例也包含批次建立方法,示範如何新增回應處理並設定執行選項:
private void bulkCreateItemsWithResponseProcessing(Flux<Family> families) {
Flux<CosmosItemOperation> cosmosItemOperations = families.map(
family -> CosmosBulkOperations.getCreateItemOperation(family, new PartitionKey(family.getLastName())));
container.executeBulkOperations(cosmosItemOperations).flatMap(cosmosBulkOperationResponse -> {
CosmosBulkItemResponse cosmosBulkItemResponse = cosmosBulkOperationResponse.getResponse();
CosmosItemOperation cosmosItemOperation = cosmosBulkOperationResponse.getOperation();
if (cosmosBulkOperationResponse.getException() != null) {
logger.error("Bulk operation failed", cosmosBulkOperationResponse.getException());
} else if (cosmosBulkItemResponse == null ||
!cosmosBulkOperationResponse.getResponse().isSuccessStatusCode()) {
logger.error(
"The operation for Item ID: [{}] Item PartitionKey Value: [{}] did not complete " +
"successfully with " + "a" + " {} response code.",
cosmosItemOperation.<Family>getItem().getId(),
cosmosItemOperation.<Family>getItem().getLastName(),
cosmosBulkItemResponse != null ? cosmosBulkItemResponse.getStatusCode() : "n/a");
} else {
logger.info(
"Item ID: [{}] Item PartitionKey Value: [{}]",
cosmosItemOperation.<Family>getItem().getId(),
cosmosItemOperation.<Family>getItem().getLastName());
logger.info("Status Code: {}", cosmosBulkItemResponse.getStatusCode());
logger.info("Request Charge: {}", cosmosBulkItemResponse.getRequestCharge());
}
if (cosmosBulkItemResponse == null) {
return Mono.error(new IllegalStateException("No response retrieved."));
} else {
return Mono.just(cosmosBulkItemResponse);
}
}).blockLast();
}
private void bulkCreateItemsWithExecutionOptions(Flux<Family> families) {
CosmosBulkExecutionOptions bulkExecutionOptions = new CosmosBulkExecutionOptions();
// The default value for maxMicroBatchConcurrency is 1.
// By increasing it, it means more concurrent requests will be allowed to be sent to the server, which leads to increased RU usage.
//
// Before you increase the value, please examine the RU usage of your container - whether it has been saturated or not.
// When the RU has already been under saturation, increasing the concurrency will not help the situation,
// rather it may cause more 429 and request timeout.
bulkExecutionOptions.setMaxMicroBatchConcurrency(2);
Flux<CosmosItemOperation> cosmosItemOperations = families.map(family -> CosmosBulkOperations.getCreateItemOperation(family, new PartitionKey(family.getLastName())));
container.executeBulkOperations(cosmosItemOperations, bulkExecutionOptions).blockLast();
}
大規模資料擷取策略
對於大規模資料擷取,吞吐量 控制與重試政策是 避免節流的主要手段——而非僅靠批次大小或並發性。 只專注於批次大小與並發性,而不處理吞吐量限制與重試問題,無法可靠地防止大規模出現 429(速率限制)回應。
選擇導入方式
| 劇本 | 建議方法 |
|---|---|
| 跨多台機器進行大規模分散式擷取 | Apache Spark 連接器 |
| 單機資料匯入,需細緻控制 | 具吞吐量控制的 Java SDK 批量執行器 |
對於大規模擷取,Apache Spark 連接器是首選。 它能處理分散式運算、自動重試與退避,以及跨工作節點的負載平衡,無需手動調整並行或批次大小。
具吞吐量控制的 Java SDK 批量執行器
如果您的情境需要直接使用 Java SDK,azure-cosmos-distributed-bulk-sample 提供一個用於生產規模資料擷取的參考實作。 它示範了以下關鍵設定:
- 自動調整微批次大小:範例會動態調整每個實體分割區的批次大小,從 1 到 100 份文件,以達到吞吐量飽和,同時保持節流可控。
- 可設定重試次數:預設為每批次 20 次重試。 請根據您對短暫故障及下游延遲需求的容忍度進行調整。
- 每台機器的同時處理批次:預設為 8 個同時處理批次。 建議的範圍是擷取機器上可用 CPU 核心的 25–100%。
Tip
先從預設開始,並監控 429(速率限制)回應的發生率。 減少並行批次數量,或在發生過度節流時新增吞吐量控制。
共用容器的吞吐量控制
如果多個工作負載共用同一容器,請使用 吞吐量控制群組 限制大量擷取所消耗的 RU/s,並防止其導致其他工作負載飢餓:
備註
吞吐量控制需要最低受支援的 Azure Cosmos DB Java SDK v4 版本。 吞吐量控制 API 也已標註為 @Beta,並可能會變更。 在使用以下範例之前,請在 吞吐量控制文件 中確認目前版本需求與 API 狀態。
ThroughputControlGroupConfig groupConfig =
new ThroughputControlGroupConfigBuilder()
.groupName("bulkIngestionGroup")
.targetThroughputThreshold(0.75) // limit ingestion to 75% of provisioned throughput
.defaultControlGroup(true)
.build();
container.enableLocalThroughputControlGroup(groupConfig);
若要在多台擷取機器間協調吞吐量限制,請改用 全域吞吐量控制 。
參考實作
| Sample | Description |
|---|---|
| Azure-cosmos-distributed-bulk-sample | 端對端分散式擷取,具備工作追蹤、可重新啟動批次、自動調整的微批次大小,以及可設定的重試與並發設定。 |
| ThroughputControlQuickstartAsync.java | 本地吞吐量控制、透過元資料容器共享 RU 限制的全域吞吐量控制,以及基於優先權的節流。 |
效能秘訣
在使用 Bulk Executor 程式庫時,請考慮以下幾點以提升效能:
為達到最佳效能,請從位於與 Azure Cosmos DB 帳戶寫入區域相同區域的 Azure VM 中執行應用程式。
為達成更高的吞吐量:
- 將 JVM 堆積大小設定得足夠大,以避免處理大量文件時的記憶體問題。 建議堆大小:
max(3 GB, 3 * sizeof(all documents passed to bulk import API in one batch))。 - 批量作業有預處理階段,因此處理大型文件集時可獲得更高的吞吐量。 例如,透過批量匯入 10 次、每次 1,000,000 份文件匯入,匯入 10,000,000 份文件,比起每次執行 100,000 份文件執行 100 次更有效率。
- 將 JVM 堆積大小設定得足夠大,以避免處理大量文件時的記憶體問題。 建議堆大小:
在單一虛擬機器內實例化整個應用程式的單一
CosmosAsyncClient物件,該虛擬機器對應於特定的 Azure Cosmos DB 容器。單一的批量操作 API 執行會消耗用戶端機器的大量 CPU 與網路 I/O,因為內部會產生多個任務。 避免在您的應用程式程序中產生多個同時執行的任務,其中每個任務都會執行大量作業 API 呼叫。 如果單一虛擬機器上的單一批量操作 API 呼叫無法消耗整個容器的吞吐量(若容器吞吐量 > 為 100 萬 RU/s),請建立獨立虛擬機器以同時執行大量操作 API 呼叫。