Azure AI 검색의 쿼리를 위해 Azure Cosmos DB for NoSQL에서 데이터 인덱싱

아티클
11/23/2024

이 문서에서는 Azure Cosmos DB for NoSQL에서 콘텐츠를 가져오고 Azure AI Search에서 검색할 수 있게 해 주는 인덱서를 구성하는 방법을 알아봅니다.

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

용어가 혼동될 수 있으므로 Azure Cosmos DB 인덱싱과 Azure AI 검색 인덱싱은 서로 다른 작업임에 유의해야 합니다. Azure AI 검색의 인덱싱은 검색 서비스에서 검색 인덱스를 만들고 로드합니다.

필수 조건

Azure Cosmos DB 계정, 데이터베이스, 컨테이너 및 항목. 대기 시간을 줄이고 대역폭 요금이 부과되지 않도록 하려면 Azure AI Search와 Azure Cosmos DB 모두에 동일한 지역을 사용합니다.
일관성 있음으로 설정된 Azure Cosmos DB 컬렉션의 자동 인덱싱 정책. 이것은 기본 구성입니다. 지연 인덱싱은 권장되지 않으며 데이터가 누락될 수 있습니다.
읽기 권한. "모든 액세스" 연결 문자열 콘텐츠에 대한 액세스 권한을 부여하는 키가 포함되어 있지만 ID(Microsoft Entra ID)를 사용하는 경우 검색 서비스 관리 ID에 Cosmos DB 계정 읽기 권한자 역할과 Cosmos DB 기본 제공 데이터 판독기 역할이 모두 할당되어 있는지 확인합니다.

이 문서의 예제를 진행하려면 Azure Portal 또는 REST 클라이언트가 필요합니다. Azure Portal을 사용하는 경우 모든 공용 네트워크에 대한 액세스가 사용하도록 설정되어 있는지 확인합니다. Cosmos DB 인덱서 만들기에 대한 다른 방법은 Azure SDK를 포함합니다.

샘플 데이터 사용해 보기

다음 지침을 사용하여 테스트 목적으로 Cosmos DB에서 컨테이너 및 데이터베이스를 만듭니다.

GitHub에서 HotelsData_toCosmosDB.JSON 다운로드하여 샘플 호텔 데이터 집합의 하위 집합이 포함된 컨테이너를 Cosmos DB에 만듭니다.
Azure Portal에 로그인하고 Cosmos DB에서 계정, 데이터베이스 및 컨테이너 를 만듭니다.

Cosmos DB에서 새 컨테이너에 대한 데이터 탐색기를 선택하고 다음 값을 제공합니다.

속성	값
데이터베이스	새로 만들기
데이터베이스 ID	hotelsdb
컨테이너 간에 처리량 공유	선택하지 마세요.
컨테이너 ID	hotels
파티션 키	/HotelId
컨테이너 처리량(자동 크기 조정)	Autoscale
컨테이너 최대 RU/s	1000

데이터 탐색기에서 hotelsdb 및 *hotels"를 확장한 다음 항목을 선택합니다.
항목 업로드를 선택한 다음 GitHub에서 다운로드한 HotelsData_toCosmosDB.JSON 파일을 선택합니다.
항목을 마우스 오른쪽 단추로 클릭하고 새 SQL 쿼리를 선택합니다. 기본 쿼리는 .입니다 SELECT * FROM c.
쿼리 실행을 선택하여 쿼리 를 실행하고 결과를 봅니다. 호텔 문서는 50개여야 합니다.

이제 컨테이너가 있으므로 Azure Portal, REST 클라이언트 또는 Azure SDK를 사용하여 데이터를 인덱싱할 수 있습니다.

설명 필드는 가장 자세한 내용을 제공합니다. 전체 텍스트 검색 및 선택적 벡터 쿼리에 대해 이 필드를 대상으로 지정해야 합니다.

Azure Portal 사용

데이터 가져오기 마법사 또는 데이터 가져오기 및 벡터화 마법사를 사용하여 SQL 데이터베이스 테이블 또는 뷰에서 인덱싱을 자동화할 수 있습니다. 데이터 원본 구성은 두 마법사 모두에 대해 유사합니다.

마법사 시작.
데이터에 연결 시 데이터 원본 형식이 Azure Cosmos DB 또는 NoSQL 계정인지 선택하거나 확인합니다.

데이터 원본 이름은 Azure AI Search의 데이터 원본 연결 개체를 나타냅니다. 벡터 마법사를 사용하는 경우 마법사 워크플로의 끝에 지정된 사용자 지정 접두사를 사용하여 데이터 원본 이름이 자동으로 생성됩니다.
데이터베이스 이름 및 컬렉션을 지정합니다. 쿼리는 선택 사항입니다. 계층적 데이터가 있고 특정 조각을 가져오려는 경우에 유용합니다.
인증 방법(관리 ID 또는 기본 제공 API 키)을 지정합니다. 관리 ID 연결을 지정하지 않으면 포털에서 키를 사용합니다.

관리 ID를 사용하도록 Azure AI Search를 구성하고 Cosmos DB 계정 읽기 권한자 및 Cosmos DB 기본 제공 데이터 판독기 권한을 ID에 부여하는 역할 할당을 만드는 경우 인덱서는 Microsoft Entra ID 및 역할을 사용하여 Cosmos DB에 연결할 수 있습니다.
데이터 가져오기 및 벡터화 마법사의 경우 변경 및 삭제 추적 옵션을 지정할 수 있습니다.

변경 검색 은 기본적으로 필드(타임스탬프)를 통해 _ts 지원됩니다. 샘플 데이터로 Try에 설명된 방법을 사용하여 콘텐츠를 업로드하면 컬렉션이 필드로 _ts 만들어집니다.

삭제 검색 을 수행하려면 컬렉션에 일시 삭제 플래그로 사용할 수 있는 기존 최상위 필드가 있어야 합니다. 부울 필드여야 합니다(IsDeleted로 이름을 지정할 수 있음). 일시 삭제 값으로 지정 true 합니다. 검색 인덱스에서 검색 가능하고 필터링 가능한 IsDeleted 집합이라는 해당 검색 필드를 추가합니다.
나머지 단계를 계속 진행하여 마법사를 완료합니다.
- 빠른 시작: 데이터 가져오기 마법사
- 빠른 시작: 데이터 가져오기 및 벡터화 마법사

REST API 사용

이 섹션에서는 데이터 원본, 인덱스 및 인덱터를 만드는 REST API 호출을 보여 줍니다.

데이터 원본 정의

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

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

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

"type"을 "cosmosdb"(필수)으로 설정합니다. 이전 Search API 버전 2017-11-11을 사용하는 경우 "type"의 구문은 "documentdb"입니다. 그렇지 않으면 2019-05-06 이상에서는 "cosmosdb"를 사용합니다.
"credentials"를 연결 문자열로 설정합니다. 다음 섹션에서는 지원되는 형식에 대해 설명합니다.
"container"를 컬렉션으로 설정합니다. "name" 속성은 필요이며 인덱싱할 데이터베이스 컬렉션의 ID를 지정합니다. "query" 속성은 선택 사항입니다. 이를 사용하여 Azure AI Search가 인덱싱할 수 있는 평면 스키마로 추상 JSON 문서를 평면화합니다.
데이터가 휘발성이고 후속 실행 시 인덱서에서 새 항목과 업데이트된 항목만 선택하도록 하려면 "dataChangeDetectionPolicy"를 설정합니다.
원본 항목이 삭제될 때 검색 인덱스에서 검색 문서를 제거하려면 "dataDeletionDetectionPolicy"를 설정합니다.

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

인덱서는 다음 연결을 사용하여 컬렉션에 연결할 수 있습니다.

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

모든 권한 연결 문자열
`{ "connectionString" : "AccountEndpoint=https://<Cosmos DB account name>.documents.azure.com;AccountKey=<Cosmos DB auth key>;Database=<Cosmos DB database id>`" }`
왼쪽 탐색 창에서 키를 선택하여 Azure Portal의 Azure Cosmos DB 계정 페이지에서 연결 문자열을 가져올 수 있습니다. 키 외에도 전체 연결 문자열을 선택해야 합니다.

관리 ID 연결 문자열

관리 ID 연결 문자열
`{ "connectionString" : "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.DocumentDB/databaseAccounts/<your cosmos db account name>/;(ApiKind=[api-kind];)/(IdentityAuthType=[identity-auth-type])" }`
이 연결 문자열에는 계정 키가 필요하지 않지만 관리 ID를 사용하여 연결할 수 있는 검색 서비스가 있어야 합니다. SQL API를 대상으로 하는 연결의 경우 연결 문자열에서 `ApiKind`를 생략할 수 있습니다. `ApiKind`, `IdentityAuthType`에 대한 자세한 내용은 관리 ID를 사용하여 Azure Cosmos DB 데이터베이스에 대한 인덱서 연결 설정을 참조하세요.

{ "connectionString" : "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.DocumentDB/databaseAccounts/<your cosmos db account name>/;(ApiKind=[api-kind];)/(IdentityAuthType=[identity-auth-type])" }

이 연결 문자열에는 계정 키가 필요하지 않지만 관리 ID를 사용하여 연결할 수 있는 검색 서비스가 있어야 합니다. SQL API를 대상으로 하는 연결의 경우 연결 문자열에서 ApiKind를 생략할 수 있습니다. ApiKind, IdentityAuthType에 대한 자세한 내용은 관리 ID를 사용하여 Azure Cosmos DB 데이터베이스에 대한 인덱서 연결 설정을 참조하세요.

쿼리를 사용하여 인덱싱된 데이터 형성

"container" 아래의 "query" 속성에서 SQL 쿼리를 지정하여 중첩된 속성 또는 배열을 평면화하고, JSON 속성을 투영하고, 인덱싱할 데이터를 필터링할 수 있습니다.

예제 문서:

    {
        "userId": 10001,
        "contact": {
            "firstName": "andy",
            "lastName": "hoh"
        },
        "company": "microsoft",
        "tags": ["azure", "cosmosdb", "search"]
    }

필터 쿼리:

SELECT * FROM c WHERE c.company = "microsoft" and c._ts >= @HighWaterMark ORDER BY c._ts

평면화 쿼리:

SELECT c.id, c.userId, c.contact.firstName, c.contact.lastName, c.company, c._ts FROM c WHERE c._ts >= @HighWaterMark ORDER BY c._ts

프로젝션 쿼리:

SELECT VALUE { "id":c.id, "Name":c.contact.firstName, "Company":c.company, "_ts":c._ts } FROM c WHERE c._ts >= @HighWaterMark ORDER BY c._ts

배열 평면화 쿼리:

SELECT c.id, c.userId, tag, c._ts FROM c JOIN tag IN c.tags WHERE c._ts >= @HighWaterMark ORDER BY c._ts

지원되지 않는 쿼리(DISTINCT 및 GROUP BY)

DISTINCT 키워드 또는 GROUP BY 절을 사용하는 쿼리는 지원되지 않습니다. Azure AI Search는 SQL 쿼리 페이지 매김을 사용하여 쿼리 결과를 완전히 열거합니다. DISTINCT 키워드 또는 GROUP BY 절은 결과를 매길 때 사용되는 연속 토큰과 호환되지 않습니다.

지원되지 않는 쿼리 예제:

SELECT DISTINCT c.id, c.userId, c._ts FROM c WHERE c._ts >= @HighWaterMark ORDER BY c._ts

SELECT DISTINCT VALUE c.name FROM c ORDER BY c.name

SELECT TOP 4 COUNT(1) AS foodGroupCount, f.foodGroup FROM Food f GROUP BY f.foodGroup

Azure Cosmos DB에 ORDER BY 절을 사용하여 DISTINCT 키워드로 SQL 쿼리 페이지 매김을 지원하기 위한 해결 방법이 있지만 Azure AI Search와 호환되지 않습니다. Azure AI Search에는 JSON 개체가 필요하지만 쿼리는 단일 JSON 값을 반환합니다.

-- The following query returns a single JSON value and isn't supported by Azure AI Search
SELECT DISTINCT VALUE c.name FROM c ORDER BY c.name

인덱스에 검색 필드 추가

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

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

POST https://[service name].search.windows.net/indexes?api-version=2024-07-01
Content-Type: application/json
api-key: [Search service admin key]
{
    "name": "mysearchindex",
    "fields": [{
        "name": "rid",
        "type": "Edm.String",
        "key": true,
        "searchable": false
    }, 
    {
        "name": "description",
        "type": "Edm.String",
        "filterable": false,
        "searchable": true,
        "sortable": false,
        "facetable": false,
        "suggestions": true
    }
  ]
}

문서 키 필드("key": true)를 만듭니다. 분할된 컬렉션의 경우 기본 문서 키는 Azure Cosmos DB _rid 속성입니다. 필드 이름은 밑줄 문자로 시작할 수 없으므로 Azure AI Search에서 자동으로 이 이름을 rid로 바꿉니다. 또한 Azure Cosmos DB _rid 값은 Azure AI Search 키에 잘못된 문자를 포함합니다. 따라서 _rid 값은 Base64로 인코딩됩니다.
더 많은 검색 가능한 콘텐츠를 위해 더 많은 필드를 만듭니다. 자세한 내용은 인덱스 만들기를 참조하세요.

데이터 형식 매핑

JSON 데이터 형식	Azure AI Search 필드 형식
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 for NoSQL 인덱서 구성 및 실행

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

이름을 지정하고 데이터 원본 및 대상 인덱스를 참조하여 인덱서를 만들거나 업데이트합니다.

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

필드 이름 또는 형식이 다르거나 검색 인덱스에서 여러 버전의 원본 필드가 필요한 경우 필드 매핑을 지정합니다.
다른 속성에 대한 자세한 내용은 인덱서 만들기를 참조하세요.

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

인덱서 상태 확인

인덱서 상태 및 실행 기록을 모니터링하려면 Azure Portal에서 인덱서 실행 기록을 확인하거나 인덱서 상태 REST APIrequest 가져오기를 보냅니다.

포털
REST (영문)

검색 서비스 페이지에서 검색 관리>인덱서를 엽니다.
구성 및 실행 기록에 액세스할 인덱서 선택
세부 정보, 경고 및 오류를 보려면 특정 인덱서 작업을 선택합니다.

GET https://myservice.search.windows.net/indexers/myindexer/status?api-version=2024-07-01
  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에서 제공하는 _ts(타임스탬프) 속성을 사용하는 HighWaterMarkChangeDetectionPolicy입니다.

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

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

참고 항목

Azure Cosmos DB의 필드에 null 값을 할당하면 AI Search 인덱서가 null과(와) 누락된 필드 값을 구분할 수 없습니다. 따라서 인덱스 필드가 비어 있으면 데이터베이스에서 특별히 수정한 경우에도 null 값으로 대체되지 않습니다.

증분 인덱싱 및 사용자 지정 쿼리

문서 검색을 위한 사용자 지정 쿼리를 사용하는 경우 쿼리가 _ts 열을 기준으로 결과를 정렬하는지 확인합니다. 그러면 Azure AI Search에서 사용하는 정기적 검사점이 오류가 있는 경우 증분 진행률을 제공할 수 있습니다.

경우에 따라 쿼리에 ORDER BY [collection alias]._ts 절이 포함되더라도 Azure AI Search는 _ts 기준으로 쿼리를 정렬하는지 유추하지 않을 수 있습니다. assumeOrderByHighWaterMarkColumn 구성 속성을 설정하여 결과가 정렬되도록 Azure AI Search에 알릴 수 있습니다.

이 힌트를 지정하려면 다음과 같이 인덱서 정의를 만들거나 업데이트합니다.

{
    ... other indexer definition properties
    "parameters" : {
        "configuration" : { "assumeOrderByHighWaterMarkColumn" : true } }
}

삭제된 문서 인덱싱

컬렉션에서 행이 삭제된 경우 일반적으로 검색 인덱스에서도 해당 행을 삭제하려고 할 것입니다. 데이터 삭제 감지 정책의 목적은 변경된 데이터 항목을 효율적으로 식별하는 것입니다. 현재 지원되는 유일한 정책은 다음과 같이 데이터 원본 정의에 지정된 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"
}

사용자 지정 쿼리를 사용하는 경우 softDeleteColumnName에서 참조하는 속성이 쿼리에서 프로젝션되는지 확인합니다.

softDeleteColumnName은 인덱스의 최상위 필드여야 합니다. 복합 데이터 형식 softDeleteColumnName 내에서 중첩된 필드를 지원되지 않으므로 사용합니다.

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

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

{
    "name": "[my-cosmosdb-ds]",
    "type": "cosmosdb",
    "credentials": {
        "connectionString": "AccountEndpoint=https://[cosmos-account-name].documents.azure.com;AccountKey=[cosmos-account-key];Database=[cosmos-database-name]"
    },
    "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"
    }
}

.NET 사용

SQL API 프로토콜을 통해 액세스하는 데이터의 경우 .NET SDK를 사용하여 인덱서로 자동화할 수 있습니다. 개념, 워크플로 및 요구 사항을 알아보려면 이전 REST API 섹션을 검토하는 것이 좋습니다. 그런 후, 다음 .NET API 참조 설명서를 참조하여 관리되는 코드에서 JSON 인덱서를 구현할 수 있습니다.

다음 단계

이제 인덱서를 실행하거나, 상태를 모니터링하거나 인덱서 실행을 예약하는 방법을 제어할 수 있습니다. 다음 문서는 Azure Cosmos DB에서 콘텐츠를 가져오는 인덱서에 적용됩니다.

다음을 통해 공유