빠른 시작: Python용 Apache Gremlin 클라이언트 라이브러리용 Azure Cosmos DB

2025-07-23
적용 대상: ✅ Apache Gremlin

Python용 Azure Cosmos DB for Apache Gremlin 클라이언트 라이브러리를 시작하여 구조화되지 않은 데이터를 저장, 관리 및 쿼리합니다. 이 가이드의 단계에 따라 새 계정을 만들고, Python 클라이언트 라이브러리를 설치하고, 계정에 연결하고, 일반적인 작업을 수행하고, 최종 샘플 데이터를 쿼리합니다.

라이브러리 소스 코드 | 패키지(PyPi)

필수 구성 요소

Azure 구독
- Azure 구독이 없는 경우, 시작하기 전에 무료 계정을 만드십시오.

Azure Cloud Shell에서 최신 버전의 Azure CLI입니다.
- CLI 참조 명령을 로컬로 실행하려면 명령을 사용하여 Azure CLI에 로그인합니다 az login .

Python 3.12 이상

설치

먼저 이 가이드에 대한 계정 및 개발 환경을 설정합니다. 이 섹션에서는 계정을 만들고 자격 증명을 얻은 다음 개발 환경을 준비하는 프로세스를 안내합니다.

계정 만들기

먼저 Apache Gremlin 계정에 대한 API를 만듭니다. 계정이 만들어지면 데이터베이스 및 그래프 리소스를 만듭니다.

Azure CLI
Azure Portal

대상 리소스 그룹이 아직 없는 경우 이 명령을 사용하여 az group create 구독에 새 리소스 그룹을 만듭니다.
```
az group create \
    --name "<resource-group-name>" \
    --___location "<___location>"
```

명령을 az cosmosdb create 사용하여 기본 설정으로 새 Azure Cosmos DB for Apache Gremlin 계정을 만듭니다.

az cosmosdb create \
    --resource-group "<resource-group-name>" \
    --name "<account-name>" \
    --locations "regionName=<___location>" \
    --capabilities "EnableGremlin"

새 데이터베이스를 az cosmosdb gremlin database create을(를) 사용하여 cosmicworks으로 만드십시오.

az cosmosdb gremlin database create \
    --resource-group "<resource-group-name>" \
    --account-name "<account-name>" \
    --name "cosmicworks"

명령을 az cosmosdb gremlin graph create 사용하여 이름이 지정된 새 그래프를 만듭니다 products.

az cosmosdb gremlin graph create \
    --resource-group "<resource-group-name>" \
    --account-name "<account-name>" \
    --database-name "cosmicworks" \
    --name "products" \
    --partition-key-path "/category"

Azure Portal에 로그인합니다(https://portal.azure.com).
전역 검색 창에 Azure Cosmos DB를 입력합니다.
서비스 내에서 Azure Cosmos DB를 선택합니다.
Azure Cosmos DB 창에서 만들기를 선택한 다음, 다른 탭 내에서 Apache Gremlin용 Azure Cosmos DB를 선택합니다.

기본 창에서 다음 옵션을 구성한 다음 검토 + 만들기를 선택합니다.

	값
워크로드 유형	학습
구독	Azure 구독 선택
리소스 그룹	새 리소스 그룹을 만들거나 기존 리소스 그룹을 선택합니다.
계정 이름	전역적으로 고유한 이름 입력
가용성 영역	비활성화
위치	구독에 대해 지원되는 Azure 지역 선택

팁

지정하지 않은 옵션은 기본값으로 그대로 둘 수 있습니다. 총 계정 처리량을 초당 1,000개 요청 단위(RU/s)로 제한하거나 무료 계층을 사용하도록 계정을 구성하여 비용을 최소화할 수도 있습니다.

검토 + 만들기 창에서 계정 유효성 검사가 성공적으로 완료될 때까지 기다린 다음 만들기를 선택합니다.
포털이 자동으로 배포 창으로 이동합니다. 배포가 완료되기를 기다립니다.
배포가 완료되면 리소스로 이동을 선택하여 Apache Gremlin 계정의 새로운 API로 이동합니다.
리소스 메뉴에서 데이터 탐색기 옵션을 선택합니다.
데이터 탐색기에서 + 새 그래프를 선택합니다.
그래프 추가 대화 상자에서 다음 옵션을 구성한 다음 확인을 선택합니다.

값

데이터베이스 새로 만들기

데이터베이스 이름 cosmicworks

그래프 이름 products

파티션 키 /category

팁

지정하지 않은 옵션은 기본값으로 그대로 둘 수 있습니다.

	값
데이터베이스	새로 만들기
데이터베이스 이름	`cosmicworks`
그래프 이름	`products`
파티션 키	`/category`

자격 증명 가져오기

이제 최근에 만든 계정에 대한 연결을 만드는 데 사용할 클라이언트 라이브러리의 암호를 가져옵니다.

Azure CLI
Azure Portal

az cosmosdb show를 사용하여 계정의 호스트를 가져오십시오.

az cosmosdb show \
    --resource-group "<resource-group-name>" \
    --name "<account-name>" \
    --query "{host:name}"

이전 명령의 host 출력에서 속성 값을 기록합니다. 이 속성의 값은 이 가이드의 뒷부분에서 라이브러리를 사용하여 계정에 연결하는 데 사용하는 호스트 입니다.

계정의 키를 가져오는 데 사용합니다az cosmosdb keys list.

az cosmosdb keys list \
    --resource-group "<resource-group-name>" \
    --name "<account-name>" \
    --type "keys"

이전 명령의 primaryMasterKey 출력에서 속성 값을 기록합니다. 이 속성의 값은 이 가이드의 뒷부분에서 라이브러리를 사용하여 계정에 연결하는 데 사용하는 키 입니다.

개발 환경 준비

그런 다음 새 프로젝트 및 클라이언트 라이브러리를 사용하여 개발 환경을 구성합니다. 이 단계는 이 가이드의 나머지 단계로 넘어가기 전에 마지막으로 필요한 필수 구성 요소입니다.

빈 폴더에서 시작합니다.
gremlinpython PyPI(Python 패키지 인덱스)에서 패키지를 가져옵니다.
```
pip install gremlinpython
```
app.py 파일을 만듭니다.

개체 모델

	설명
`GremlinClient`	Gremlin 서버에 연결하고 상호 작용하는 데 사용되는 클라이언트를 나타냅니다.
`GraphTraversalSource`	Gremlin 탐색을 구성하고 실행하는 데 사용됩니다

클라이언트 인증

먼저 이 가이드의 앞부분에서 수집한 자격 증명을 사용하여 클라이언트를 인증합니다.

IDE(통합 개발 환경)에서 app.py 파일을 엽니다.
gremlin_python.driver 라이브러리에서 다음 형식을 가져옵니다.
- gremlin_python.driver.client
- gremlin_python.driver.serializer
```
from gremlin_python.driver import client, serializer
```
이 가이드의 앞부분에서 수집된 자격 증명에 대한 문자열 변수를 만듭니다. 변수 hostname 및 primary_key의 이름을 지정하십시오.
```
hostname = "<host>"
primary_key = "<key>"
```

Client 이전 단계에서 만든 자격 증명 및 구성 변수를 사용하여 개체를 만듭니다. 변수 이름을 지정합니다 client.

client = client.Client(
    url=f"wss://{hostname}.gremlin.cosmos.azure.com:443/",
    traversal_source="g",
    username="/dbs/cosmicworks/colls/products",
    password=f"{primary_key}",
    message_serializer=serializer.GraphSONSerializersV2d0()
)

데이터 삽입

다음으로 그래프에 새 꼭짓점 및 에지 데이터를 삽입합니다. 새 데이터를 만들기 전에 기존 데이터의 그래프를 지웁다.

쿼리를 g.V().drop() 실행하여 그래프에서 모든 꼭짓점 및 가장자리를 지웁니다.
```
client.submit("g.V().drop()").all().result()
```

꼭짓점을 추가하는 Gremlin 쿼리를 만듭니다.

insert_vertex_query = (
    "g.addV('product')"
    ".property('id', prop_id)"
    ".property('name', prop_name)"
    ".property('category', prop_category)"
    ".property('quantity', prop_quantity)"
    ".property('price', prop_price)"
    ".property('clearance', prop_clearance)"
)

단일 제품에 대한 꼭짓점을 추가합니다.

client.submit(
    message=insert_vertex_query,
    bindings={
        "prop_id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
        "prop_name": "Yamba Surfboard",
        "prop_category": "gear-surf-surfboards",
        "prop_quantity": 12,
        "prop_price": 850.00,
        "prop_clearance": False,
    },
).all().result()

두 개의 꼭짓점을 추가하여 두 개의 추가 제품을 만듭니다.

client.submit(
    message=insert_vertex_query,
    bindings={
        "prop_id": "bbbbbbbb-1111-2222-3333-cccccccccccc",
        "prop_name": "Montau Turtle Surfboard",
        "prop_category": "gear-surf-surfboards",
        "prop_quantity": 5,
        "prop_price": 600.00,
        "prop_clearance": True,
    },
).all().result()

client.submit(
    message=insert_vertex_query,
    bindings={
        "prop_id": "cccccccc-2222-3333-4444-dddddddddddd",
        "prop_name": "Noosa Surfboard",
        "prop_category": "gear-surf-surfboards",
        "prop_quantity": 31,
        "prop_price": 1100.00,
        "prop_clearance": False,
    },
).all().result()

에지를 추가하는 다른 Gremlin 쿼리를 만듭니다.

insert_edge_query = (
    "g.V([prop_partition_key, prop_source_id])"
    ".addE('replaces')"
    ".to(g.V([prop_partition_key, prop_target_id]))"
)

두 개의 가장자리를 추가합니다.

client.submit(
    message=insert_edge_query,
    bindings={
        "prop_partition_key": "gear-surf-surfboards",
        "prop_source_id": "bbbbbbbb-1111-2222-3333-cccccccccccc",
        "prop_target_id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
    },
).all().result()

client.submit(
    message=insert_edge_query,
    bindings={
        "prop_partition_key": "gear-surf-surfboards",
        "prop_source_id": "bbbbbbbb-1111-2222-3333-cccccccccccc",
        "prop_target_id": "cccccccc-2222-3333-4444-dddddddddddd",
    },
).all().result()

데이터 읽기

그런 다음, 이전에 그래프에 삽입된 데이터를 읽습니다.

고유 식별자 및 파티션 키 값을 사용하여 꼭짓점을 읽는 쿼리를 만듭니다.
```
read_vertex_query = "g.V([prop_partition_key, prop_id])"
```

그런 다음 필요한 매개 변수를 제공하여 꼭짓점을 읽습니다.

matched_item = client.submit(
    message=read_vertex_query,
    bindings={
        "prop_partition_key": "gear-surf-surfboards",
        "prop_id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
    }
).one()

쿼리 데이터

마지막으로, 쿼리를 사용하여 그래프에서 특정 순회 또는 필터와 일치하는 모든 데이터를 찾습니다.

특정 꼭짓점에서 바깥 방향으로 탐색되는 모든 꼭짓점을 찾는 쿼리를 생성합니다.

find_vertices_query = (
    "g.V().hasLabel('product')"
    ".has('category', prop_partition_key)"
    ".has('name', prop_name)"
    ".outE('replaces').inV()"
)

제품을 지정하는 쿼리를 실행합니다 Montau Turtle Surfboard .

find_results = client.submit(
    message=find_vertices_query,
    bindings={
        "prop_partition_key": "gear-surf-surfboards",
        "prop_name": "Montau Turtle Surfboard",
    },
).all().result()

쿼리 결과를 반복합니다.

for result in find_results:
    # Do something here with each result

코드 실행

애플리케이션 디렉터리의 터미널을 사용하여 새로 만든 애플리케이션을 실행합니다.

python app.py

리소스 정리

계정이 더 이상 필요하지 않은 경우 리소스를 삭제하여 Azure 구독에서 계정을 제거합니다.

Azure CLI
Azure Portal

az cosmosdb delete \
    --resource-group "<resource-group-name>" \
    --name "<account-name>"

다음 단계

Apache Gremlin용 Azure Cosmos DB 개요