Массовое прием данных в Azure Cosmos DB для Gremlin с помощью библиотеки массового исполнителя

  • Статья

Область применения: Гремлин

Для массового обновления всего графа или части графа в базе данных часто требуется массовый прием данных. Azure Cosmos DB, распределенная база данных и магистраль Azure Cosmos DB для Gremlin, предназначена для оптимального выполнения при хорошо распределенных нагрузках. Библиотеки исполнителя массовых операций в Azure Cosmos DB используют эту уникальную возможность Azure Cosmos DB для обеспечения оптимальной производительности. Дополнительные сведения см. в записи блога Introducing bulk support in the .NET SDK (Введение в поддержку массовых операций SDK для .NET).

В этом руководстве описано, как использовать библиотеку массового исполнителя Azure Cosmos DB для импорта и обновления объектов графа в контейнер Azure Cosmos DB для 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 для 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
  • учетная запись базы данных Cosmos Azure, настроенная для использования API Gremlin.

Пример

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. Необходимые значения описаны в следующей таблице.

Свойство Description
sample.sql.host Значение, предоставленное Azure Cosmos DB. Убедитесь, что вы используете URI пакета SDK для .NET, который можно найти в разделе Обзор учетной записи 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

Чтобы обеспечить дополнительную безопасность, можно также запустить тесты интеграции, изменив значение skipIntegrationTests в файле pom.xml на false.

После успешного выполнения модульных тестов можно запустить пример кода:

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

Представленная выше команда выполняет пример с небольшим пакетом данных (1000 вершин и примерно 5000 ребер). Аргументы командной строки, представленные в следующих разделах, позволяют настроить выполняемые тома и версию примера.

Аргументы командной строки

При выполнении этого примера доступны несколько аргументов командной строки, которые описаны в следующей таблице:

Аргумент Description
--vertexCount (-v) Сообщает приложению, сколько вершин person необходимо создать.
--edgeMax (-e) Сообщает приложению, какое максимальное число ребер необходимо создать для каждой вершины. Генератор случайным образом выбирает число от 1 до указанного вами значения.
--domainSample (-d) Сообщает приложению, что нужно выполнить примера со структурами person и relationship вместо объектов POJO GraphBulkExecutors, GremlinVertex и GremlinEdge.
--createDocuments (-c) Указывает приложению, что нужно использовать операции create. Если этот аргумент не указан, приложение по умолчанию использует операции upsert.

Подробные сведения о примере

Вершина person

Класс person — это простой объект предметной области, дополненный несколькими заметками для преобразования в класс GremlinVertex, как описано в следующей таблице:

Заметка к классу Description
GremlinVertex Использует необязательный параметр label для определения всех вершин, создаваемых с помощью этого класса.
GremlinId Используется для определения поля, которое будет использоваться в качестве значения ID. Несмотря на то, что имя поля класса Person является идентификатором, оно не требуется.
GremlinProperty Используется в поле email для изменения имени свойства при хранении в базе данных.
GremlinPartitionKey Используется для определения поля класса, которое содержит ключ секции. Указанное здесь имя поля должно соответствовать значению, определенному путем секции в контейнере.
GremlinIgnore Используется для исключения поля isSpecial из свойства, записываемого в базу данных.

Класс RelationshipEdge

Класс RelationshipEdge представляет собой гибкий объект домена. С помощью заметок на уровне поля вы можете создать динамическую коллекцию типов ребер, как показано в следующей таблице.

Заметка к классу Description
GremlinEdge Дополнение GremlinEdge в классе определяет имя поля для указанного ключа секции. При создании пограничного документа назначается значение, созданное на основе исходных сведений о вершинах.
GremlinEdgeVertex Определяются два экземпляра GremlinEdgeVertex: по одному для каждой стороны ребра (начальное и конечное положения). В нашем примере представлен тип данных поля GremlinEdgeVertexInfo. Сведения, предоставляемые классом GremlinEdgeVertex, необходимы для правильного создания ребра в базе данных. Другим вариантом было бы иметь тип данных вершин как класс с аннотациями GremlinVertex.
GremlinLabel Этот пример ребра использует поле для определения значения label. Он позволяет определять различные метки, так как использует один и тот же базовый класс домена.

Описание выходных данных

Завершая выполнение, консоль возвращает строку в формате JSON, которая описывает времена выполнения примера. Строка JSON содержит следующие сведения.

Строка JSON Description
startTime Время System.nanoTime() начала процесса.
endTime Значение System.nanoTime() при завершении процесса.
durationInNanoSeconds Разница между значениями endTime и startTime.
durationInMinutes Значение durationInNanoSeconds, преобразованное в минуты. Значение durationInMinutes представляется в формате числа с плавающей точкой, а не значения времени. Например, значение "2,5" здесь обозначает 2 минуты и 30 секунд.
vertexCount Объем сгенерированных вершин, который должен совпадать с тем значением, которое мы передали в процесс выполнения командной строки.
edgeCount Объем сгенерированных ребер, который задается не строго, а с некоторым элементом случайности.
отрисовки Заполняется только в том случае, если при попытке выполнения возникает исключение.

Массив состояний

Массив состояний дает представление о том, сколько времени занимает выполнение каждого шага. Они описаны в следующей таблице.

Шаг выполнения Description
Сборка примеров вершин Время, необходимое для создания запрошенного объема объектов person.
Сборка примеров ребер Время, необходимое для создания объектов relationship.
Настройка базы данных Время, необходимое для настройки базы данных с учетом значений, предоставленных в application.properties.
Запись документов Время, необходимое на запись документов в базу данных.

Каждое состояние содержит следующие значения.

Значение состояния Description
stateName Имя сообщаемого состояния.
startTime Значение System.nanoTime() в начале состояния.
endTime Значение System.nanoTime() после завершения состояния.
durationInNanoSeconds Разница между значениями endTime и startTime.
durationInMinutes Значение durationInNanoSeconds, преобразованное в минуты. Значение durationInMinutes представляется в формате числа с плавающей точкой, а не значения времени. Например, значение "2,5" здесь обозначает 2 минуты и 30 секунд.

Следующие шаги