Udostępnij za pośrednictwem

Zbiorcze pozyskiwanie danych w usłudze Azure Cosmos DB dla języka Gremlin przy użyciu biblioteki funkcji wykonawczej zbiorczej

  • Artykuł

DOTYCZY: Gremlin

Grafowe bazy danych 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 funkcji usługi Azure Cosmos DB i zapewnienia optymalnej wydajności. Aby uzyskać więcej informacji, zobacz Wprowadzenie obsługi zbiorczej w zestawie SDK platformy .NET.

Z tego samouczka dowiesz się, jak używać biblioteki funkcji wykonawczej operacji zbiorczych usługi Azure Cosmos DB do importowania i aktualizowania obiektów grafu do kontenera usługi Azure Cosmos DB dla języka Gremlin. Podczas 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 do utworzenia i zweryfikowania obiektów 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 nawet sto razy, co sprawia, że jest to idealny sposób przeprowadzania początkowych migracji danych lub okresowych operacji przenoszenia danych.

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

.NET

Wymagania wstępne

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

Klonowanie

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

Wykonywanie

Zmodyfikuj parametry zgodnie z opisem w poniższej tabeli:

Parametr Opis
ConnectionString Twoja usługa parametry połączenia, która znajduje się 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życia pakietu GraphBulkExecutor. Przykłady używają adnotacji obiektów domeny lub obiektów POJO (zwykły stary obiekt Java) bezpośrednio. Zalecamy wypróbowanie obu metod, aby określić, który z nich lepiej spełnia wymagania dotyczące implementacji i wydajności.

Klonowanie

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

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

Aby pobrać 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 zostały opisane w poniższej tabeli:

Właściwości 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 pobrać 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, przykładowy kod go utworzy.
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 w tym miejscu. Jeśli eksplorujesz różne opcje przepływności, aby spełnić wymagania dotyczące wydajności, pamiętaj, aby zresetować przepływność w kontenerze po zakończeniu eksploracji. Istnieją koszty związane z pozostawieniem kontenera aprowizowanego z wyższą przepływnością.

Wykonywanie

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 powyższego 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 osób 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 POJO.
--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 jest prostym obiektem 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 pola, które będzie używane jako ID wartość. Nazwa pola w klasie person jest identyfikatorem, ale nie jest wymagana.
GremlinProperty Pole służy email do zmiany nazwy właściwości, gdy jest ona przechowywana w bazie danych.
GremlinPartitionKey Służy do definiowania pola w klasie zawierającego 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, po jednym dla każdej strony krawędzi (źródło i miejsce docelowe). 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ą byłoby 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 podstawowej klasy domeny.

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 Stanów

Tablica stanów zapewnia wgląd w czas wykonywania każdego kroku. Kroki zostały opisane 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 System.nanoTime() Wartość 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