使用大量執行工具程式庫在 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 查詢傳送至資料庫，命令會逐一受到評估繼而執行，您使用大量執行程式文件庫時，將必須在本機建立及驗證物件。 程式庫初始化圖表物件之後，可讓您以循序方式將圖表物件傳送至資料庫服務。

藉由此方法，您可以增加資料擷取速度達百倍之多，這讓其成為執行初始資料移轉或定期資料移動作業的理想方式。

大量執行程式文件庫現在隨附於下列各種類型。

.NET

必要條件

開始之前，請先確定您具備下列條件：

複製

若要使用此範例，請執行以下命令：

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.com:443/;AccountKey=<account-key>;。
DatabaseName, ContainerName 目標資料庫和容器的名稱。
DocumentsToInsert 要產生的文件數目 (只與綜合資料相關)。
PartitionKey 確保資料擷取期間，每個文件都會指定資料分割索引鍵。
NumberOfRUs 只有在容器尚未存在，且在執行期間建立時才相關。

下載 .NET 中的完整範例應用程式。

Java

範例用法

下列範例應用程式說明如何使用 GraphBulkExecutor 套件。 這些範例會使用領域物件註釋或直接使用 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) 要求應用程式使用 Person 或 Relationship 網域結構來執行範例，而不是使用 GraphBulkExecutors、GremlinVertex 和 GremlinEdge POJOs。
--createDocuments (-c) 要求應用程式使用 create 建立作業。 如果引數不存在，應用程式預設為使用 upsert 作業。

詳細的範例資訊

人員頂點

人員類別是一個簡單的領域物件，已使用數個注釋裝飾，以協助轉換至 GremlinVertex 類別，如下表所述：

類別注釋 描述
GremlinVertex 使用選擇性 label 參數來定義您使用這個類別建立的所有頂點。
GremlinId 用來定義將用作 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 只有當您嘗試執行時擲回例外狀況，才會填入。

狀態陣列

狀態陣列提供每個步驟所花費時間長度的深入解析。 下表說明這些步驟：

執行步驟 描述
建置範例頂點 產生所要求人員物件量所需的時間量。
建置範例邊緣 產生 Relationship 物件所需的時間量。
設定資料庫 根據 application.properties 中提供的值，設定資料庫所花費的時間量。
撰寫文件 將文件寫入資料庫所花費的時間量。

每個狀態都包含下列值：

狀態值 描述
stateName 所報告狀態的名稱。
startTime 狀態啟動時的 System.nanoTime() 值。
endTime 狀態完成時的 System.nanoTime() 值。
durationInNanoSeconds endTime 和 startTime 值之間的差異。
durationInMinutes durationInNanoSeconds 值，轉換成分鐘數。 durationInMinutes 值會以浮點數表示，而不是時間值。 例如，值 2.5 表示 2 分 30 秒。

下一步