Zbiorcze pozyskiwanie danych w usłudze Azure Cosmos DB for Gremlin przy użyciu biblioteki funkcji wykonawczej zbiorczej

  • Artykuł

DOTYCZY: Gremlin

Bazy danych programu Graph często wymagają zbiorczego pozyskiwania danych, aby odświeżyć cały graf lub zaktualizować jego część. Usługa Azure Cosmos DB, rozproszona baza danych i szkielet usługi Azure Cosmos DB dla języka Gremlin, ma działać najlepiej, gdy obciążenia są dobrze rozproszone. Biblioteki funkcji wykonawczej zbiorczej w usłudze Azure Cosmos DB zostały zaprojektowane w celu wykorzystania tej unikatowej możliwości usługi Azure Cosmos DB i zapewnienia optymalnej wydajności. Aby uzyskać więcej informacji, zobacz Wprowadzenie do obsługi zbiorczej w zestawie SDK platformy .NET.

Z tego samouczka dowiesz się, jak używać biblioteki funkcji wykonawczej usługi Azure Cosmos DB do importowania i aktualizowania obiektów grafu do kontenera usługi Azure Cosmos DB for Gremlin. W trakcie tego procesu biblioteka służy do programowego tworzenia obiektów wierzchołków i krawędzi , a następnie wstawiania wielu obiektów na żądanie sieciowe.

Zamiast wysyłać zapytania języka Gremlin do bazy danych, gdzie polecenia są oceniane, a następnie wykonywane pojedynczo, należy użyć biblioteki funkcji wykonawczej zbiorczej, aby utworzyć i zweryfikować obiekty lokalnie. Po zainicjowaniu obiektów grafu biblioteka umożliwia sekwencyjną wysyłanie ich do usługi bazy danych.

Korzystając z tej metody, można zwiększyć szybkość pozyskiwania danych aż do setek razy, co sprawia, że jest to idealny sposób wykonywania początkowych migracji danych lub okresowych operacji przenoszenia danych.

Biblioteka funkcji wykonawczej zbiorczej jest teraz dostępna w następujących odmianach.

.NET

Wymagania wstępne

Przed rozpoczęciem upewnij się, że masz następujące elementy:

Clone

Aby użyć tego przykładu, uruchom następujące polecenie:

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

Aby uzyskać przykład, przejdź do strony .\azure-cosmos-graph-bulk-executor\dotnet\src\.

Przykład


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

Wykonaj polecenie

Zmodyfikuj parametry zgodnie z opisem w poniższej tabeli:

Parametr Opis
ConnectionString Parametry połączenia usługi, które znajdziesz w sekcji Klucze konta usługi Azure Cosmos DB dla języka Gremlin. Jest on sformatowany jako AccountEndpoint=https://<account-name>.documents.azure.com:443/;AccountKey=<account-key>;.
DatabaseName, ContainerName Nazwy docelowej bazy danych i kontenera.
DocumentsToInsert Liczba dokumentów do wygenerowania (dotyczy tylko danych syntetycznych).
PartitionKey Gwarantuje, że klucz partycji jest określony z każdym dokumentem podczas pozyskiwania danych.
NumberOfRUs Ma zastosowanie tylko wtedy, gdy kontener jeszcze nie istnieje i należy go utworzyć podczas wykonywania.

Pobierz pełną przykładową aplikację na platformie .NET.

Java

Przykładowe zastosowanie

Poniższa przykładowa aplikacja ilustruje sposób używania pakietu GraphBulkExecutor. Przykłady używają adnotacji obiektu domeny lub obiektów POJO (zwykłego starego obiektu Java) bezpośrednio. Zalecamy wypróbowanie obu metod w celu określenia, który lepiej spełnia wymagania dotyczące implementacji i wydajności.

Clone

Aby użyć przykładu, uruchom następujące polecenie:

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

Aby uzyskać przykład, przejdź do strony .\azure-cosmos-graph-bulk-executor\java\.

Wymagania wstępne

Aby uruchomić ten przykład, musisz mieć następujące oprogramowanie:

  • OpenJDK 11
  • Maven
  • Konto usługi Azure Cosmos DB skonfigurowane do korzystania z interfejsu API języka Gremlin

Przykład

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

Konfigurowanie

Aby uruchomić przykład, zapoznaj się z następującą konfiguracją i zmodyfikuj ją zgodnie z potrzebami.

Plik /resources/application.properties definiuje dane wymagane do skonfigurowania usługi Azure Cosmos DB. Wymagane wartości opisano w poniższej tabeli:

Właściwość Opis
sample.sql.host Wartość dostarczana przez usługę Azure Cosmos DB. Upewnij się, że używasz identyfikatora URI zestawu .NET SDK, który znajdziesz w sekcji Przegląd konta usługi Azure Cosmos DB.
sample.sql.key Klucz podstawowy lub pomocniczy można uzyskać z sekcji Klucze konta usługi Azure Cosmos DB.
sample.sql.database.name Nazwa bazy danych na koncie usługi Azure Cosmos DB do uruchomienia przykładu. Jeśli baza danych nie zostanie znaleziona, przykładowy kod go utworzy.
sample.sql.container.name Nazwa kontenera w bazie danych do uruchomienia przykładu. Jeśli kontener nie zostanie znaleziony, zostanie utworzony przykładowy kod.
sample.sql.partition.path Jeśli musisz utworzyć kontener, użyj tej wartości, aby zdefiniować ścieżkę partitionKey .
sample.sql.allow.throughput Kontener zostanie zaktualizowany w celu użycia wartości przepływności zdefiniowanej tutaj. Jeśli eksplorujesz różne opcje przepływności, aby spełnić wymagania dotyczące wydajności, pamiętaj o zresetowaniu przepływności w kontenerze po zakończeniu eksploracji. Istnieją koszty związane z pozostawieniem kontenera aprowizowanego z wyższą przepływnością.

Wykonaj polecenie

Po zmodyfikowaniu konfiguracji zgodnie ze środowiskiem uruchom następujące polecenie:

mvn clean package

W celu zwiększenia bezpieczeństwa można również uruchomić testy integracji, zmieniając skipIntegrationTests wartość w pliku pom.xml na false.

Po pomyślnym uruchomieniu testów jednostkowych możesz uruchomić przykładowy kod:

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

Uruchomienie poprzedniego polecenia wykonuje przykład z małą partią (1000 wierzchołków i około 5000 krawędzi). Użyj argumentów wiersza polecenia w poniższych sekcjach, aby dostosować woluminy, które są uruchamiane i która przykładowa wersja ma zostać uruchomiona.

Argumenty wiersza polecenia

Podczas uruchamiania tego przykładu dostępnych jest kilka argumentów wiersza polecenia, zgodnie z opisem w poniższej tabeli:

Argument Opis
--vertexCount (-v) Informuje aplikację o liczbą wierzchołków do wygenerowania.
--edgeMax (-e) Informuje aplikację o maksymalnej liczbie krawędzi do wygenerowania dla każdego wierzchołka. Generator losowo wybiera liczbę z zakresu od 1 do podanej wartości.
--domainSample (-d) Informuje aplikację o uruchomieniu przykładu przy użyciu struktur domeny osoby i relacji zamiast GraphBulkExecutorsobiektów , GremlinVertexi GremlinEdge POJOs.
--createDocuments (-c) Informuje aplikację o użyciu create operacji. Jeśli argument nie jest obecny, aplikacja domyślnie używa upsert operacji.

Szczegółowe informacje o przykładach

Wierzchołek osoby

Klasa person to prosty obiekt domeny, który został ozdobiony kilkoma adnotacjami, aby ułatwić przekształcenie w GremlinVertex klasę, zgodnie z opisem w poniższej tabeli:

Adnotacja klasy Opis
GremlinVertex Używa opcjonalnego label parametru do zdefiniowania wszystkich wierzchołków tworzonych przy użyciu tej klasy.
GremlinId Służy do definiowania, które pole będzie używane jako ID wartość. Nazwa pola w klasie person ma identyfikator, ale nie jest wymagana.
GremlinProperty Użyto w email polu, aby zmienić nazwę właściwości, gdy jest ona przechowywana w bazie danych.
GremlinPartitionKey Służy do definiowania, które pole w klasie zawiera klucz partycji. Podana nazwa pola powinna być zgodna z wartością zdefiniowaną przez ścieżkę partycji w kontenerze.
GremlinIgnore Służy do wykluczania isSpecial pola z właściwości zapisywanej w bazie danych.

Klasa RelationshipEdge

Klasa RelationshipEdge jest wszechstronnym obiektem domeny. Za pomocą adnotacji etykiety na poziomie pola można utworzyć dynamiczną kolekcję typów krawędzi, jak pokazano w poniższej tabeli:

Adnotacja klasy Opis
GremlinEdge Dekoracja GremlinEdge w klasie definiuje nazwę pola dla określonego klucza partycji. Podczas tworzenia dokumentu brzegowego przypisana wartość pochodzi z informacji o wierzchołku źródłowym.
GremlinEdgeVertex Definiowane GremlinEdgeVertex są dwa wystąpienia obiektu , po jednym dla każdej strony krawędzi (źródło i lokalizacja docelowa). Nasz przykład zawiera typ danych pola jako GremlinEdgeVertexInfo. Informacje dostarczone przez klasę GremlinEdgeVertex są wymagane do poprawnego utworzenia krawędzi w bazie danych. Inną opcją jest posiadanie typu danych wierzchołków jako klasy, która została ozdobiona GremlinVertex adnotacjami.
GremlinLabel Przykładowa krawędź używa pola do zdefiniowania label wartości. Umożliwia zdefiniowanie różnych etykiet, ponieważ używa tej samej klasy domeny podstawowej.

Objaśnione dane wyjściowe

Konsola kończy uruchamianie za pomocą ciągu JSON opisującego czasy wykonywania przykładu. Ciąg JSON zawiera następujące informacje:

Ciąg JSON Opis
startTime Czas System.nanoTime() rozpoczęcia procesu.
endTime Po System.nanoTime() zakończeniu procesu.
durationInNanoSeconds Różnica między wartościami endTime i startTime .
durationInMinutes Wartość durationInNanoSeconds , przekonwertowana na minuty. Wartość durationInMinutes jest reprezentowana jako liczba zmiennoprzecinkowa, a nie wartość czasu. Na przykład wartość 2,5 reprezentuje 2 minuty i 30 sekund.
vertexCount Ilość wygenerowanych wierzchołków, która powinna być zgodna z wartością przekazywaną do wykonywania wiersza polecenia.
edgeCount Ilość wygenerowanych krawędzi, która nie jest statyczna i jest tworzona z elementem losowości.
Wyjątek Wypełniane tylko wtedy, gdy podczas próby uruchomienia zostanie zgłoszony wyjątek.

Tablica States

Tablica states zawiera szczegółowe informacje o tym, jak długo trwa każdy krok w ramach wykonywania. Kroki opisano w poniższej tabeli:

Krok wykonywania Opis
Tworzenie przykładowych wierzchołków Czas potrzebny na utworzenie szkieletu żądanej liczby obiektów osób.
Tworzenie przykładowych krawędzi Czas potrzebny na utworzenie szkieletu obiektów relacji.
Konfigurowanie bazy danych Czas potrzebny na skonfigurowanie bazy danych na podstawie wartości podanych w pliku application.properties.
Pisanie dokumentów Czas potrzebny na zapisanie dokumentów w bazie danych.

Każdy stan zawiera następujące wartości:

Wartość stanu Opis
stateName Nazwa zgłaszanego stanu.
startTime Wartość System.nanoTime() po uruchomieniu stanu.
endTime System.nanoTime() Wartość po zakończeniu stanu.
durationInNanoSeconds Różnica między wartościami endTime i startTime .
durationInMinutes Wartość durationInNanoSeconds , przekonwertowana na minuty. Wartość durationInMinutes jest reprezentowana jako liczba zmiennoprzecinkowa, a nie wartość czasu. Na przykład wartość 2,5 reprezentuje 2 minuty i 30 sekund.

Następne kroki