Penyerapan massal di Azure Cosmos DB Gremlin API menggunakan BulkExecutor

  • Artikel
  • 6 menit untuk membaca

BERLAKU UNTUK: Gremlin API

Database grafik sering memiliki kasus penggunaan untuk melakukan penyerapan massal untuk merefresh seluruh grafik atau memperbarui sebagiannya. Cosmos DB, yang merupakan database terdistribusi dan tulang punggung Azure Cosmos DB - Gremlin API, dimaksudkan untuk melakukan jika beban didistribusikan dengan baik. Pustaka BulkExecutor di Cosmos DB yang dirancang untuk mengeksploitasi kemampuan unik Cosmos DB ini dan memberikan performa terbaik, lihat di sini.

Tutorial ini memberikan instruksi tentang menggunakan pustaka pelaksana massal Azure Cosmos DB untuk mengimpor dan memperbarui objek grafik ke dalam kontainer Azure Cosmos DB Gremlin API. Proses ini digunakan untuk membuat objek Vertex dan Edge secara terprogram untuk kemudian menyisipkan beberapa objek tersebut per permintaan jaringan.

Alih-alih mengirim kueri GREMLIN ke database, di mana perintah dievaluasi dan kemudian dieksekusi satu per satu, menggunakan pustaka BulkExecutor akan mengharuskan untuk membuat dan memvalidasi objek secara lokal. Setelah menginisialisasi, objek grafik, perpustakaan memungkinkan Anda untuk mengirim objek grafik ke layanan database secara berurutan. Dengan menggunakan metode ini, kecepatan konsumsi data dapat ditingkatkan hingga 100x, yang menjadikannya metode ideal untuk migrasi data awal atau operasi pergerakan data berkala.

Sekarang tersedia dalam flavor berikut:

.NET

Prasyarat

Kloning

Untuk menjalankan sampel ini, jalankan perintah git clone di bawah ini:

git clone https://github.com/Azure-Samples/azure-cosmos-graph-bulk-executor.git

Sampel tersedia di jalur .\azure-cosmos-graph-bulk-executor\dotnet\src\

Sampel


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);

Jalankan

Modifikasi parameter berikut sebagai:

Parameter Deskripsi
ConnectionString Ini adalah titik akhir .NET SDK Anda yang ditemukan di bagian Gambaran umum akun database Azure Cosmos DB Gremlin API Anda. Ini memiliki format https://your-graph-database-account.documents.azure.com:443/
DatabaseName, ContainerName Parameter ini adalah database target dan nama kontainer.
DocumentsToInsert Jumlah dokumen yang akan dihasilkan (hanya relevan untuk menghasilkan data sintetis)
PartitionKey Untuk memastikan kunci partisi ditentukan bersama dengan setiap dokumen saat penyerapan.
NumberOfRUs Hanya relevan jika kontainer tidak ada dan perlu dibuat sebagai bagian dari eksekusi

Unduh aplikasi sampel lengkap di .NET dari sini.

JAVA

Penggunaan sampel

Aplikasi sampel disediakan untuk mengilustrasikan cara menggunakan paket GraphBulkExecutor. Sampel tersedia untuk menggunakan anotasi objek Domain atau menggunakan objek POJO secara langsung. Disarankan, untuk mencoba kedua pendekatan, untuk menentukan mana yang lebih memenuhi tuntutan implementasi dan performa Anda.

Kloning

Untuk menjalankan sampel, jalankan perintah git clone di bawah ini:

git clone https://github.com/Azure-Samples/azure-cosmos-graph-bulk-executor.git

Sampel tersedia di .\azure-cosmos-graph-bulk-executor\java\

Prasyarat

Untuk menjalankan sampel ini, Anda harus memiliki perangkat lunak berikut:

  • OpenJDK 11
  • Maven
  • Akun Azure Cosmos DB yang dikonfigurasi untuk menggunakan Gremlin API

Sampel

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);
    }

Untuk menjalankan sampel, lihat konfigurasi sebagai berikut dan ubah sesuai kebutuhan:

Konfigurasi

File /resources/application.properties menentukan data yang diperlukan untuk mengonfigurasi Cosmos DB, nilai yang diperlukan adalah:

  • sample.sql.host: Ini adalah nilai yang disediakan oleh Azure Cosmos DB. Pastikan Anda menggunakan ".NET SDK URI", yang dapat ditemukan di bagian Gambaran Umum Akun Cosmos DB.
  • sample.sql.key: Anda bisa mendapatkan kunci primer atau sekunder dari bagian Kunci akun Cosmos DB.
  • sample.sql.database.name: Nama database dalam akun Cosmos DB untuk menjalankan sampel. Jika database tidak ditemukan, kode sampel akan membuatnya.
  • sample.sql.container.name: Nama kontainer dalam database untuk menjalankan sampel. Jika kontainer tidak ditemukan, kode sampel akan membuatnya.
  • sample.sql.partition.path: Jika kontainer perlu dibuat, nilai ini akan digunakan untuk menentukan jalur partitionKey.
  • sample.sql.allow.throughput: Kontainer akan diperbarui untuk menggunakan nilai throughput yang ditentukan di sini. Jika Anda menjelajahi opsi throughput yang berbeda untuk memenuhi tuntutan performa, pastikan untuk mengatur ulang throughput pada kontainer setelah selesai dengan eksplorasi Anda. Ada biaya yang terkait dengan meninggalkan kontainer yang disediakan dengan throughput yang lebih tinggi.

Jalankan

Setelah konfigurasi dimodifikasi sesuai lingkungan Anda, jalankan perintah :

mvn clean package

Untuk keamanan tambahan, Anda juga dapat menjalankan pengujian integrasi dengan mengubah nilai "skipIntegrationTests" di pom.xml menjadi false.

Dengan asumsi pengujian Unit berhasil dijalankan. Anda dapat menjalankan baris perintah untuk menjalankan kode sampel:

java -jar target/azure-cosmos-graph-bulk-executor-1.0-jar-with-dependencies.jar -v 1000 -e 10 -d

Menjalankan perintah di atas akan menjalankan sampel dengan batch kecil (1k Simpul dan sekitar 5k Tepi). Gunakan argumen baris perintah berikut untuk mengubah volume yang dijalankan dan versi sampel mana yang akan dijalankan.

Argumen baris perintah

Ada beberapa argumen baris perintah yang tersedia saat menjalankan sampel ini, yang dirinci sebagai:

  • --vertexCount (-v): Memberi tahu aplikasi berapa banyak simpul orang yang akan dihasilkan.
  • --edgeMax (-e): Memberi tahu aplikasi berapa jumlah maksimum tepi yang dihasilkan untuk setiap Simpul. Generator akan secara acak memilih angka antara 1 dan nilai yang disediakan di sini.
  • --domainSample (-d): Memberi tahu aplikasi untuk menjalankan sampel menggunakan struktur domain Orang dan Hubungan alih-alih POJO GraphBulkExecutors GremlinVertex dan GremlinEdge.
  • --createDocuments (-c): Memberi tahu aplikasi untuk menggunakan operasi buat. Jika tidak ada, aplikasi akan default menggunakan operasi upsert.

Detail tentang sampel

Simpul Orang

Kelas Orang adalah objek domain yang cukup sederhana yang telah dihiasi dengan beberapa anotasi untuk membantu transformasi ke kelas GremlinVertex. Klaimnya sebagai berikut:

  • GremlinVertex: Perhatikan cara kami menggunakan parameter "label" opsional untuk menentukan semua Simpul yang dibuat menggunakan kelas ini.
  • GremlinId: Digunakan untuk menentukan bidang mana yang akan digunakan sebagai nilai ID. Meskipun nama bidang pada kelas Orang adalah ID, itu tidak diperlukan.
  • GremlinProperty: Sedang digunakan pada bidang email untuk mengubah nama properti saat disimpan dalam database.
  • GremlinPartitionKey: Sedang digunakan untuk menentukan bidang mana pada kelas yang berisi kunci partisi. Nama bidang yang disediakan di sini harus cocok dengan nilai yang ditentukan oleh jalur partisi pada kontainer.
  • GremlinIgnore: Sedang digunakan untuk mengecualikan bidang isSpecial dari properti yang ditulis ke database.

Tepi Hubungan

RelationshipEdge adalah objek domain yang cukup serbaguna. Menggunakan anotasi label tingkat bidang memungkinkan kumpulan dinamis jenis tepi dibuat. Anotasi berikut diwakili dalam contoh tepi domain ini:

  • GremlinEdge: Dekorasi GremlinEdge pada kelas, menentukan nama bidang untuk kunci partisi yang ditentukan. Nilai yang ditetapkan, saat dokumen tepi dibuat, akan berasal dari informasi puncak sumber.
  • GremlinEdgeVertex: Perhatikan bahwa ada dua instans GremlinEdgeVertex yang ditentukan. Satu untuk setiap sisi tepi (Sumber dan Tujuan). Sampel kami memiliki jenis data bidang sebagai GremlinEdgeVertexInfo. Informasi yang diberikan oleh kelas GremlinEdgeVertex diperlukan agar tepi dibuat dengan benar dalam database. Opsi lain adalah memiliki jenis data simpul menjadi kelas yang telah dihiasi dengan anotasi GremlinVertex.
  • GremlinLabel: Tepi sampel menggunakan bidang untuk menentukan nilai label. Ini memungkinkan label yang berbeda untuk didefinisikan saat masih menggunakan kelas domain dasar yang sama.

Output Dijelaskan

Konsol akan menyelesaikan eksekusinya dengan string json yang menjelaskan durasi sampel. String json berisi informasi berikut.

  • startTime: System.nanoTime() saat proses dimulai.
  • endtime: System.nanoTime() saat proses selesai.
  • durationInNanoSeconds: Perbedaan antara endTime dan startTime.
  • durationInMinutes: DurationInNanoSeconds dikonversi menjadi menit. Penting untuk dicatat bahwa durationInMinutes dinyatakan sebagai angka float, bukan nilai waktu. Misalnya, nilai 2,5 adalah 2 menit dan 30 detik.
  • vertexCount: Volume simpul yang dihasilkan yang harus cocok dengan nilai yang diteruskan ke eksekusi baris perintah.
  • edgeCount: Volume tepi yang dihasilkan yang tidak statis dan dibangun dengan elemen keacakan.
  • pengecualian: Hanya diisi saat ada pengecualian yang dilemparkan saat mencoba menjalankan.

Array Status

Array status memberikan wawasan tentang berapa lama setiap langkah dalam eksekusi berlangsung. Langkah-langkah yang terjadi adalah:

  • Buat sampel simpul: Waktu yang diperlukan untuk membuat volume objek Orang yang diminta.
  • Buat tepi sampel: Waktu yang diperlukan untuk membuat objek Hubungan.
  • Konfigurasi Database: Jumlah waktu yang diperlukan untuk mengonfigurasi database berdasarkan nilai yang disediakan dalam application.properties.
  • Tulis Dokumen: Total waktu yang diperlukan untuk menulis dokumen ke database.

Setiap status akan berisi nilai berikut:

  • stateName: Nama status yang sedang dilaporkan.
  • startTime: System.nanoTime() saat status dimulai.
  • endtime: System.nanoTime() saat status selesai.
  • durationInNanoSeconds: Perbedaan antara endTime dan startTime.
  • durationInMinutes: DurationInNanoSeconds dikonversi menjadi menit. Penting untuk dicatat bahwa durationInMinutes dinyatakan sebagai angka float, bukan nilai waktu. misalnya, nilai 2,5 adalah 2 menit dan 30 detik.

Langkah berikutnya