Azure AI 검색 쿼리용 Apache Gremlin용 Azure Cosmos DB의 인덱스 데이터(미리 보기)

메모

Azure AI 검색 Azure 포털, REST API 및 Azure SDK 통해 사용할 수 있습니다. 또한 엔터프라이즈 콘텐츠를 Microsoft Foundry 포털의 에이전트에 대해 재사용 가능한 사용 권한 인식 기술 자료로 변환하는 관리되는 기술 계층인 Foundry IQ를 뒷받침합니다.

중요

기능, 기능 또는 표시된 속성(미리 보기)은 서비스 수준 계약에 포함되지 않으며 프로덕션 워크로드에는 권장되지 않으며 일반적으로 사용 가능해지기 전에 변경되거나 제한될 수 있습니다. Azure AI 검색 미리 보기 용어는 독립 실행형 기능이든 일반 공급 기능의 일부이든 관계없이 모든 미리 보기 기능에 적용됩니다.

중요

이러한 기능과 기능은 다른 Microsoft 서비스 및 타사 서비스에 대한 연결을 지원합니다. 이러한 서비스의 사용은 해당 약관의 적용을 받으며 Azure 규정 준수 경계 외부의 데이터 처리 또는 스토리지뿐만 아니라 Azure 규정 준수 경계로 데이터가 유입될 수 있습니다.

데이터가 조직의 규정 준수 및 지리적 경계와 관련된 의미를 벗어나는지 여부와 적절한 권한, 경계 및 승인이 프로비전되는지를 관리하는 것은 사용자의 책임입니다.

특정 사용 사례의 컨텍스트에서 빌드한 애플리케이션을 신중하게 검토하고 테스트하고 모든 적절한 결정 및 사용자 지정을 수행할 책임이 있습니다. 여기에는 메타프롬프트, 콘텐츠 필터 또는 기타 안전 시스템과 같은 책임 있는 AI 완화를 구현하고 애플리케이션이 적절한 품질, 안정성, 보안 및 신뢰성 표준을 충족하도록 보장하는 것이 포함됩니다. 자세한 내용은 Azure AI 검색 투명성 정보를 참고하세요.

Apache Gremlin용 Azure Cosmos DB 인덱서(미리 보기)는 Apache Gremlin용 Azure Cosmos DB에서 콘텐츠를 가져와 Azure AI 검색에서 검색할 수 있도록 합니다.

이 문서에서는 Cosmos DB와 관련된 정보를 사용하여 인덱서 만들기 를 보완합니다. REST API를 사용하여 데이터 원본 만들기, 인덱스 만들기, 인덱서 만들기 등 모든 인덱서에 공통적인 세 부분으로 구성된 워크플로를 보여 줍니다. 데이터 추출은 인덱서 만들기 요청을 제출할 때 발생합니다.

용어는 혼동될 수 있으므로 Azure Cosmos DB 인덱싱 및 Azure AI 검색 인덱싱 서로 다른 작업입니다. Azure AI 검색 인덱싱은 검색 서비스에서 검색 인덱스를 만들고 로드합니다.

필수 구성 요소

데이터 원본 정의

데이터 원본 정의는 데이터의 변경 내용을 식별하기 위해 인덱싱할 데이터, 자격 증명 및 정책을 지정합니다. 데이터 원본은 여러 인덱서에서 사용할 수 있도록 독립적인 리소스로 정의됩니다.

이 호출의 경우 미리 보기 REST API 버전을 지정하여 Apache Gremlin에 대한 Azure Cosmos DB 통해 연결하는 데이터 원본을 만듭니다. 2021-04-01-preview 이상을 사용할 수 있습니다. 최신 미리 보기 REST API를 사용하는 것이 좋습니다.

  1. 데이터 원본을 만들거나 업데이트 하여 해당 정의를 설정합니다.

     POST https://[service name].search.windows.net/datasources?api-version=2026-08-01-preview
 Content-Type: application/json
 api-key: [Search service admin key]
 {
   "name": "[my-cosmosdb-gremlin-ds]",
   "type": "cosmosdb",
   "credentials": {
     "connectionString": "AccountEndpoint=https://[cosmos-account-name].documents.azure.com;AccountKey=[cosmos-account-key];Database=[cosmos-database-name];ApiKind=Gremlin;"
   },
   "container": {
     "name": "[cosmos-db-collection]",
     "query": "g.V()"
   },
   "dataChangeDetectionPolicy": {
     "@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
     "highWaterMarkColumnName": "_ts"
   },
   "dataDeletionDetectionPolicy": null,
   "encryptionKey": null,
   "identity": null
 }

  2. "type"을 (필수)로 "cosmosdb" 설정합니다.

  3. "자격 증명"을 연결 문자열로 설정합니다. 다음 섹션에서는 지원되는 형식에 대해 설명합니다.

  4. "container"를 컬렉션으로 설정합니다. "name" 속성이 필요하며 그래프의 ID를 지정합니다.

    "query" 속성은 선택 사항입니다. 기본적으로 Apache Gremlin용 Azure Cosmos DB Azure AI 검색 인덱서는 그래프의 모든 꼭짓점을 인덱스 문서로 만듭니다. 가장자리는 무시됩니다. 쿼리 기본값은 .입니다 g.V(). 가장자리만 인덱싱하도록 쿼리를 설정할 수도 있습니다. 에지를 인덱싱하려면 쿼리 g.E()를 .로 설정합니다.

  5. 데이터가 휘발성이고 인덱서가 후속 실행 시 새 항목과 업데이트된 항목만 선택하도록 하려면 "dataChangeDetectionPolicy"를 설정합니다. 증분 진행은 기본적으로 사용하도록 설정되며 _ts를 상위 워터마크 열로 사용합니다.

  6. 원본 항목이 삭제될 때 검색 인덱스에서 검색 문서를 제거하려면 "dataDeletionDetectionPolicy"를 설정합니다.

지원되는 자격 증명 및 연결 문자열

인덱서는 다음 연결을 사용하여 컬렉션에 연결할 수 있습니다. Azure Cosmos DB for Apache Gremlin을 대상으로 하는 연결의 경우, 연결 문자열에 "ApiKind"를 반드시 포함해야 합니다.

엔드포인트 URL에서 포트 번호를 사용하지 않습니다. 포트 번호를 포함하면 연결이 실패합니다.

전체 액세스 연결 문자열
{ "connectionString" : "AccountEndpoint=https://<Cosmos DB account name>.documents.azure.com;AccountKey=<Cosmos DB auth key>;Database=<Cosmos DB database id>;ApiKind=Gremlin" }
왼쪽 창에서 Keys를 선택하여 Azure 포털의 Azure Cosmos DB 계정 페이지에서 연결 문자열 가져올 수 있습니다. 전체 연결 문자열(연결 문자열)을 선택하고 키만 선택하지 않도록 하세요.
관리되는 ID 연결 문자열
{ "connectionString" : "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.DocumentDB/databaseAccounts/<your cosmos db account name>/;(ApiKind=[api-kind];)" }
이 연결 문자열 계정 키가 필요하지는 않지만 이전에 관리 ID를 사용하여 연결하도록 검색 서비스를 구성하고 및 Cosmos DB 계정 읽기 권한자 역할 권한을 부여하는 역할 할당을 만들었어야 합니다. 자세한 내용은 관리 ID를 사용하여 Azure Cosmos DB 데이터베이스에 대한 인덱서 연결 설정을 참조하세요.

인덱스에 검색 필드 추가

검색 인덱스에서 원본 JSON 문서 또는 사용자 지정 쿼리 프로젝션의 출력을 허용하는 필드를 추가합니다. 검색 인덱스 스키마가 그래프와 호환되는지 확인합니다. Azure Cosmos DB 콘텐츠의 경우 검색 인덱스 스키마는 데이터 원본의 Azure Cosmos DB 항목 일치해야 합니다.

  1. 인덱스를 만들거나 업데이트하여 데이터를 저장하는 검색 필드를 정의합니다.

     POST https://[service name].search.windows.net/indexes?api-version=2026-08-01-preview
 Content-Type: application/json
 api-key: [Search service admin key]
 {
    "name": "mysearchindex",
    "fields": [
     {
         "name": "rid",
         "type": "Edm.String",
         "facetable": false,
         "filterable": false,
         "key": true,
         "retrievable": true,
         "searchable": true,
         "sortable": false,
         "analyzer": "standard.lucene",
         "indexAnalyzer": null,
         "searchAnalyzer": null,
         "synonymMaps": [],
         "fields": []
     }, {
         "name": "label",
         "type": "Edm.String",
         "searchable": true,
         "filterable": false,
         "retrievable": true,
         "sortable": false,
         "facetable": false,
         "key": false,
         "indexAnalyzer": null,
         "searchAnalyzer": null,
         "analyzer": "standard.lucene",
         "synonymMaps": []
    }]
  }

  2. 문서 키 필드("키": true)를 만듭니다. 분할된 컬렉션의 경우 기본 문서 키는 Azure Cosmos DB _rid 속성으로, 필드 이름은 밑줄 문자로 시작할 수 없으므로 Azure AI 검색 자동으로 rid 이름을 바꿉니다. 또한 Azure Cosmos DB _rid 값에는 Azure AI 검색 키에 유효하지 않은 문자가 포함됩니다. 이러한 이유로 값은 _rid Base64로 인코딩됩니다.

  3. 검색 가능한 콘텐츠에 대한 추가 필드를 만듭니다. 자세한 내용은 인덱스 만들기 를 참조하세요.

데이터 형식 매핑

JSON 데이터 형식 Azure AI 검색 필드 형식
Bool Edm.Boolean, Edm.String
정수와 같은 숫자 Edm.Int32, Edm.Int64, Edm.String
부동 소수점처럼 보이는 숫자 Edm.Double, Edm.String
문자열 Edm.String
["a", "b", "c"]와 같은 기본 형식의 배열 Collection(Edm.String)
날짜와 같은 문자열 Edm.DateTimeOffset, Edm.String
GeoJSON 개체(예: { "type": "Point", "coordinates": [long, lat] } Edm.GeographyPoint
기타 JSON 개체 해당 없음

Azure Cosmos DB 인덱서 구성 및 실행

인덱스 및 데이터 원본이 만들어지면 인덱서 만들 준비가 된 것입니다. 인덱서 구성은 런타임 동작을 제어하는 입력, 매개 변수 및 속성을 지정합니다.

  1. 인덱서에 이름을 지정하고 데이터 원본 및 대상 인덱스 참조를 사용하여 인덱서 만들기 또는 업데이트:

    POST https://[service name].search.windows.net/indexers?api-version=2026-08-01-preview
Content-Type: application/json
api-key: [search service admin key]
{
    "name" : "[my-cosmosdb-indexer]",
    "dataSourceName" : "[my-cosmosdb-gremlin-ds]",
    "targetIndexName" : "[my-search-index]",
    "disabled": null,
    "schedule": null,
    "parameters": {
        "batchSize": null,
        "maxFailedItems": 0,
        "maxFailedItemsPerBatch": 0,
        "base64EncodeKeys": false,
        "configuration": {}
        },
    "fieldMappings": [],
    "encryptionKey": null
}

  2. 필드 이름 또는 형식에 차이가 있거나 검색 인덱스에 여러 버전의 원본 필드가 필요한 경우 필드 매핑을 지정합니다.

  3. 다른 속성에 대한 자세한 내용은 인덱서 만들기 를 참조하세요.

인덱서는 만들 때 자동으로 실행됩니다. "disabled"를 true로 설정하여 이를 방지할 수 있습니다. 인덱서 실행을 제어하려면 요청 시 인덱서를 실행하거나 일정에 따라 실행하십시오.

인덱서 상태 확인

인덱서 상태 및 실행 기록을 모니터링하려면 인덱서 상태 가져오기 요청을 보냅니다.

GET https://myservice.search.windows.net/indexers/myindexer/status?api-version=2026-08-01-preview
  Content-Type: application/json  
  api-key: [admin key]

응답에는 상태 및 처리된 항목 수가 포함됩니다. 다음 예제와 유사하게 표시됩니다.

    {
        "status":"running",
        "lastResult": {
            "status":"success",
            "errorMessage":null,
            "startTime":"2022-02-21T00:23:24.957Z",
            "endTime":"2022-02-21T00:36:47.752Z",
            "errors":[],
            "itemsProcessed":1599501,
            "itemsFailed":0,
            "initialTrackingState":null,
            "finalTrackingState":null
        },
        "executionHistory":
        [
            {
                "status":"success",
                "errorMessage":null,
                "startTime":"2022-02-21T00:23:24.957Z",
                "endTime":"2022-02-21T00:36:47.752Z",
                "errors":[],
                "itemsProcessed":1599501,
                "itemsFailed":0,
                "initialTrackingState":null,
                "finalTrackingState":null
            },
            ... earlier history items
        ]
    }

실행 기록에는 가장 최근에 완료된 실행 중 최대 50개까지 포함되며, 이 실행은 최신 실행이 먼저 수행되도록 역방향 시간순으로 정렬됩니다.

새 문서 및 변경된 문서 인덱싱

인덱서가 검색 인덱스를 완전히 채운 후에는, 이후 인덱서 실행 시 데이터베이스에서 새로 추가되거나 변경된 문서만을 증분 방식으로 인덱싱하도록 설정할 수 있습니다.

증분 인덱싱을 사용하도록 설정하려면 데이터 원본 정의에서 "dataChangeDetectionPolicy" 속성을 설정합니다. 이 속성은 데이터에서 사용되는 변경 내용 추적 메커니즘을 인덱서에 알려줍니다.

Azure Cosmos DB 인덱서의 경우, Azure Cosmos DB에서 제공하는 HighWaterMarkChangeDetectionPolicy (타임스탬프) 속성을 사용하는 정책만 지원됩니다.

다음 예제에서는 변경 검색 정책이 있는 데이터 원본 정의를 보여줍니다.

"dataChangeDetectionPolicy": {
    "@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
    "highWaterMarkColumnName": "_ts"
},

삭제된 문서 인덱싱

그래프 데이터가 삭제되면 검색 인덱스에서 해당 문서를 삭제할 수도 있습니다. 데이터 삭제 검색 정책의 목적은 삭제된 데이터 항목을 효율적으로 식별하고 인덱스에서 전체 문서를 삭제하는 것입니다. 데이터 삭제 검색 정책은 부분 문서 정보를 삭제하기 위한 것이 아닙니다. 현재 지원되는 유일한 정책은 Soft Delete 다음과 같이 데이터 원본 정의에 지정된 정책(삭제는 일종의 플래그로 표시됨)입니다.

"dataDeletionDetectionPolicy": {
    "@odata.type" : "#Microsoft.Azure.Search.SoftDeleteColumnDeletionDetectionPolicy",
    "softDeleteColumnName" : "the property that specifies whether a document was deleted",
    "softDeleteMarkerValue" : "the value that identifies a document as deleted"
}

다음 예제에서는 일시 삭제 정책을 사용하여 데이터 원본을 만듭니다.

POST https://[service name].search.windows.net/datasources?api-version=2026-08-01-preview
Content-Type: application/json
api-key: [Search service admin key]

{
    "name": "[my-cosmosdb-gremlin-ds]",
    "type": "cosmosdb",
    "credentials": {
        "connectionString": "AccountEndpoint=https://[cosmos-account-name].documents.azure.com;AccountKey=[cosmos-account-key];Database=[cosmos-database-name];ApiKind=Gremlin"
    },
    "container": { "name": "[my-cosmos-collection]" },
    "dataChangeDetectionPolicy": {
        "@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
        "highWaterMarkColumnName": "`_ts`"
    },
    "dataDeletionDetectionPolicy": {
        "@odata.type": "#Microsoft.Azure.Search.SoftDeleteColumnDeletionDetectionPolicy",
        "softDeleteColumnName": "isDeleted",
        "softDeleteMarkerValue": "true"
    }
}

삭제 검색 정책을 사용하도록 설정하더라도 인덱스에서 복합(Edm.ComplexType) 필드를 삭제하는 것은 지원되지 않습니다. 이 정책을 사용하려면 Gremlin 데이터베이스의 '활성' 열이 정수, 문자열 또는 부울 형식이어야 합니다.

그래프 데이터를 검색 인덱스 필드로 매핑

Apache Gremlin 인덱서에 대한 Azure Cosmos DB 그래프 데이터의 몇 조각을 자동으로 매핑합니다.

  1. 인덱서는 _rid가 존재하는 경우 이를 인덱스에서 rid 필드에 매핑하고 Base64로 인코딩합니다.

  2. 인덱서는 _id가 있으면 이를 인덱스의 id 필드에 매핑합니다.

  3. Apache Gremlin용 Azure Cosmos DB를 사용하여 Azure Cosmos DB 데이터베이스를 쿼리할 때 각 속성의 JSON 출력에 id 및 value가 있음을 알 수 있습니다. 인덱서는 속성이 있는 경우 속성 value 과 동일한 이름을 가진 검색 인덱스의 필드에 속성의 속성을 자동으로 매핑합니다. 다음 예제에서는 450이 검색 인덱스의 pages 필드에 매핑됩니다.

    {
        "id": "Cookbook",
        "label": "book",
        "type": "vertex",
        "properties": {
          "pages": [
            {
              "id": "48cf6285-a145-42c8-a0aa-d39079277b71",
              "value": "450"
            }
          ]
        }
    }

출력 필드 매핑을 사용하여 쿼리 출력을 인덱스의 필드에 매핑해야 할 수 있습니다. 사용자 지정 쿼리에 복잡한 데이터가 있을 수 있으므로 필드 매핑 대신 출력 필드 매핑 을 사용할 수 있습니다.

예를 들어 쿼리에서 이 출력을 생성한다고 가정해 보겠습니다.

    [
      {
        "vertex": {
          "id": "Cookbook",
          "label": "book",
          "type": "vertex",
          "properties": {
            "pages": [
              {
                "id": "48cf6085-a211-42d8-a8ea-d38642987a71",
                "value": "450"
              }
            ],
          }
        },
        "written_by": [
          {
            "yearStarted": "2017"
          }
        ]
      }
    ]

위의 JSON의 pages 값을 인덱스의 필드에 매핑하려는 경우 인덱서 정의에 다음 totalpages을 추가할 수 있습니다.

    ... // rest of indexer definition 
    "outputFieldMappings": [
        {
          "sourceFieldName": "/document/vertex/pages",
          "targetFieldName": "totalpages"
        }
    ]

출력 필드 매핑이 /document로 시작하며 JSON에 속성 키에 대한 참조가 포함되어 있지 않은 점을 확인하십시오. 그래프 데이터를 수집할 때 인덱서가 각 문서를 /document 노드 아래에 배치하고, 인덱서를 사용하면 pages 배열의 첫 번째 개체를 참조하지 않고도 pages를 간단하게 참조하여 값을 자동으로 인식할 수 있기 때문입니다.

다음 단계

  • Last updated on