대량 실행기 라이브러리를 사용하여 Azure Cosmos DB for Gremlin에서 데이터 대량 수집

  • 아티클

적용 대상: Gremlin

그래프 데이터베이스에서 전체 그래프를 새로 고치거나 그래프 일부를 업데이트하려면 데이터를 대량으로 수집해야 하는 경우가 많습니다. Azure Cosmos DB for Gremlin의 분산 데이터베이스이자 백본인 Azure Cosmos DB는 부하가 잘 분산되어 있으면 최상으로 수행합니다. Azure Cosmos DB의 대량 실행기 라이브러리는 Azure Cosmos DB의 이 고유한 기능을 익스플로잇하고 최적의 성능을 제공하도록 설계되었습니다. 자세한 내용은 .NET SDK에서 대량 지원 소개를 참조하세요.

이 자습서에서는 Azure Cosmos DB 대량 실행기 라이브러리를 사용하여 그래프 개체를 Azure Cosmos DB for Gremlin 컨테이너로 가져오고 업데이트하는 방법을 알아봅니다. 이 프로세스 중에는 라이브러리를 사용하여 프로그래매틱으로 꼭짓점과 에지 개체를 만든 다음, 네트워크 요청당 개체 여러 개를 삽입합니다.

명령을 평가한 다음, 한 번에 하나씩 실행하는 Gremlin 쿼리를 데이터베이스로 보내는 대신 대량 실행기 라이브러리를 사용하여 개체를 로컬로 만들고 유효성을 검사합니다. 라이브러리가 그래프 개체를 초기화한 후에 이를 사용하여 그래프 개체를 순차적으로 데이터베이스 서비스에 보낼 수 있습니다.

이 방법을 사용하면 데이터 수집 속도를 100배까지 향상시킬 수 있으므로 초기 데이터 마이그레이션이나 정기적인 데이터 이동 작업을 수행하는 데 적합한 방법입니다.

이제 대량 실행기 라이브러리는 다음과 같은 종류로 제공됩니다.

.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 서비스 연결 문자열은 Gremlin용 Azure Cosmos DB 계정의 키 섹션에서 찾을 수 있습니다. 형식은 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에서 제공하는 값입니다. Azure Cosmos DB 계정의 개요 섹션에서 찾을 수 있는 .NET SDK URI를 사용하고 있는지 확인합니다.
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) GraphBulkExecutors, GremlinVertex 및 GremlinEdge POJO 대신 사람 및 관계 도메인 구조를 사용하여 샘플을 실행하도록 애플리케이션에게 지시합니다.
--createDocuments(-c) create 연산을 사용하도록 애플리케이션에게 지시합니다. 인수가 없으면 애플리케이션은 기본적으로 upsert 연산을 사용합니다.

자세한 샘플 정보

사람 꼭짓점

사람 클래스는 다음 표의 설명대로 GremlinVertex 클래스로 변환하는 데 도움이 되는 여러 주석으로 데코레이팅된 간단한 도메인 개체입니다.

클래스 주석 설명
GremlinVertex 선택적 label 매개 변수를 사용하여 이 클래스로 만드는 모든 꼭짓점을 정의합니다.
GremlinId ID 값으로 사용할 필드를 정의하는 데 사용됩니다. 사람 클래스의 필드 이름은 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 실행을 시도할 때 예외가 발생한 경우에만 채워집니다.

상태 배열

상태 배열은 실행 내에서 각 단계의 소요 시간을 파악할 수 있습니다. 이 단계는 다음 표에 설명되어 있습니다.

실행 단계 설명
빌드 샘플 꼭짓점 요청된 사람 개체 볼륨을 생성하는 데 걸리는 시간입니다.
빌드 샘플 에지 관계 개체를 생성하는 데 걸리는 시간입니다.
데이터베이스 구성 application.properties에 제공된 값에 따라 데이터베이스를 구성하는 데 걸리는 시간입니다.
문서 작성 문서를 데이터베이스에 작성하는 데 걸리는 시간입니다.

각 상태에는 다음 값이 포함됩니다.

상태 값 설명
stateName 보고되는 상태의 이름입니다.
startTime 상태가 시작된 System.nanoTime() 값입니다.
endTime 상태가 완료된 System.nanoTime() 값입니다.
durationInNanoSeconds endTime 및 startTime 값 간의 차이입니다.
durationInMinutes 분으로 변환된 durationInNanoSeconds 값입니다. durationInMinutes 값은 시간 값이 아닌 부동 소수로 표시됩니다. 예를 들어 2.5 값은 2분 30초를 나타냅니다.

다음 단계