Azure SQL Database에서 데이터 인덱싱

이 문서에서는 Azure SQL Database 또는 Azure SQL 관리되는 인스턴스에서 콘텐츠를 가져오고 Azure AI Search에서 검색할 수 있도록 하는 인덱서를 구성하는 방법에 대해 알아봅니다.

이 문서는 Azure SQL과 관련된 정보로 인덱서 만들기를 보완합니다. Azure Portal과 REST API를 사용하여 모든 인덱서에 공통적인 3단계 워크플로(데이터 원본 만들기, 인덱스 만들기, 인덱서 만들기)를 보여 줍니다. 인덱서 만들기 요청을 제출하면 데이터 추출이 발생합니다.

이 문서에서는 다음과 같은 내용도 제공합니다.

• 증분 인덱싱을 설정하는 데 도움이 되는 Azure SQL 인덱서에서 지원하는 변경 감지 정책에 대한 설명

• 기능 호환성에 대한 질문과 대답에 대한 FAQ(질문과 대답) 섹션

필수 구성 요소

• Azure SQL 데이터베이스 또는 공용 엔드포인트가 있는 SQL 관리 인스턴스

• 단일 테이블 또는 뷰입니다.

  데이터가 크거나 SQL의 기본 변경 검색 기능(SQL 통합 변경 내용 추적)을 사용하여 증분 인덱싱이 필요한 경우 검색 인덱스의 새 행, 변경 및 삭제된 행을 반영하려면 테이블을 사용합니다.

  여러 테이블의 데이터를 통합해야 하는 경우 뷰를 사용합니다. 대형 뷰는 SQL 인덱서에 적합하지 않습니다. 해결 방법은 Azure AI Search 인덱스로 수집할 새 테이블을 만드는 것입니다. 보기로 이동하도록 선택한 경우 변경 검색에 높은 워터 마크 를 사용할 수 있지만 삭제 검색에 대한 해결 방법을 사용해야 합니다.

• 기본 키는 단일 값이어야 합니다. 테이블에서 전체 SQL 통합 변경 내용 추적을 위해 클러스터되지 않아야 합니다.

• 읽기 권한. Azure AI Search는 연결 문자열에 사용자 이름과 암호가 제공되는 SQL Server 인증을 지원합니다. 또는 관리 ID를 설정하고SQL Server 기여자 또는 SQL DB 기여자 역할의 멤버 자격으로 Azure 역할을 사용할 수 있습니다.

이 문서의 예를 진행하려면 Azure Portal이나 REST 클라이언트가 필요합니다. Azure Portal을 사용하는 경우 Azure SQL 방화벽에 모든 공용 네트워크에 대한 액세스가 서 사용하도록 설정되어 있고 클라이언트가 인바운드 규칙을 통해 액세스할 수 있는지 확인합니다. 로컬로 실행되는 REST 클라이언트의 경우, 디바이스 IP 주소에서 인바운드 액세스를 허용하도록 SQL Server 방화벽을 구성합니다. Azure SQL 인덱서를 만드는 다른 방법으로는 Azure SDK가 있습니다.

샘플 데이터 사용해 보기

테스트 목적으로 Azure SQL Database에 테이블을 만들고 로드하려면 다음 지침을 따릅니다.

1. GitHub에서 hotels-azure-sql.sql을 다운로드하여 샘플 호텔 데이터 세트의 하위 집합을 포함하는 Azure SQL Database에 테이블을 만듭니다.

2. Azure Portal에 로그인하고 Azure SQL Database와 데이터베이스 서버를 만듭니다. SQL Server 인증과 Microsoft Entra ID 인증을 모두 구성하는 것이 좋습니다. Azure에서 역할을 구성할 수 있는 권한이 없는 경우 해결 방법으로 SQL 인증을 사용할 수 있습니다.

3. 로컬 디바이스에서 들어오는 모든 요청에 대해 서버 방화벽을 구성합니다.

4. Azure SQL Database에서 쿼리 편집기(미리 보기)를 선택한 다음 새 쿼리를 선택합니다.

5. T-SQL 스크립트를 붙여넣은 다음 실행하여 호텔 테이블을 만듭니다. 비클러스터형 기본 키는 SQL 통합 변경 내용 추적을 위한 요구 사항입니다.

   CREATE TABLE tbl_hotels
    (
        Id TINYINT PRIMARY KEY NONCLUSTERED,
        Modified DateTime NULL DEFAULT '0000-00-00 00:00:00',
        IsDeleted TINYINT,
        HotelName VARCHAR(40),
        Category VARCHAR(20),
        City VARCHAR(30),
        State VARCHAR(4),
        Description VARCHAR(500)
    );
   

6. T-SQL 스크립트를 붙여넣은 다음 레코드를 삽입합니다.

    -- Insert rows
    INSERT INTO tbl_hotels (Id, Modified, IsDeleted, HotelName, Category, City, State, Description) VALUES (1, CURRENT_TIMESTAMP, 0,  'Stay-Kay City Hotel', 'Boutique', 'New York', 'NY', 'This classic hotel is fully-refurbished and ideally located on the main commercial artery of the city in the heart of New York. A few minutes away is Times Square and the historic centre of the city, as well as other places of interest that make New York one of Americas most attractive and cosmopolitan cities.');
    INSERT INTO tbl_hotels (Id, Modified, IsDeleted, HotelName, Category, City, State, Description) VALUES (10, CURRENT_TIMESTAMP, 0, 'Countryside Hotel', 'Extended-Stay', 'Durham', 'NC', 'Save up to 50% off traditional hotels. Free WiFi, great location near downtown, full kitchen, washer & dryer, 24\/7 support, bowling alley, fitness center and more.');
    INSERT INTO tbl_hotels (Id, Modified, IsDeleted, HotelName, Category, City, State, Description) VALUES (11, CURRENT_TIMESTAMP, 0, 'Royal Cottage Resort', 'Extended-Stay', 'Bothell', 'WA', 'Your home away from home. Brand new fully equipped premium rooms, fast WiFi, full kitchen, washer & dryer, fitness center. Inner courtyard includes water features and outdoor seating. All units include fireplaces and small outdoor balconies. Pets accepted.');
    INSERT INTO tbl_hotels (Id, Modified, IsDeleted, HotelName, Category, City, State, Description) VALUES (12, CURRENT_TIMESTAMP, 0, 'Winter Panorama Resort', 'Resort and Spa', 'Wilsonville', 'OR', 'Plenty of great skiing, outdoor ice skating, sleigh rides, tubing and snow biking. Yoga, group exercise classes and outdoor hockey are available year-round, plus numerous options for shopping as well as great spa services. Newly-renovated with large rooms, free 24-hr airport shuttle & a new restaurant. Rooms\/suites offer mini-fridges & 49-inch HDTVs.');
    INSERT INTO tbl_hotels (Id, Modified, IsDeleted, HotelName, Category, City, State, Description) VALUES (13, CURRENT_TIMESTAMP, 0, 'Luxury Lion Resort', 'Luxury', 'St. Louis', 'MO', 'Unmatched Luxury. Visit our downtown hotel to indulge in luxury accommodations. Moments from the stadium and transportation hubs, we feature the best in convenience and comfort.');
    INSERT INTO tbl_hotels (Id, Modified, IsDeleted, HotelName, Category, City, State, Description) VALUES (14, CURRENT_TIMESTAMP, 0, 'Twin Vortex Hotel', 'Luxury', 'Dallas', 'TX', 'New experience in the making. Be the first to experience the luxury of the Twin Vortex. Reserve one of our newly-renovated guest rooms today.');
    INSERT INTO tbl_hotels (Id, Modified, IsDeleted, HotelName, Category, City, State, Description) VALUES (15, CURRENT_TIMESTAMP, 0, 'By the Market Hotel', 'Budget', 'New York', 'NY', 'Book now and Save up to 30%. Central location. Walking distance from the Empire State Building & Times Square, in the Chelsea neighborhood. Brand new rooms. Impeccable service.');
    INSERT INTO tbl_hotels (Id, Modified, IsDeleted, HotelName, Category, City, State, Description) VALUES (16, CURRENT_TIMESTAMP, 0, 'Double Sanctuary Resort', 'Resort and Spa', 'Seattle', 'WA', '5 Star Luxury Hotel - Biggest Rooms in the city. #1 Hotel in the area listed by Traveler magazine. Free WiFi, Flexible check in\/out, Fitness Center & espresso in room.');
    INSERT INTO tbl_hotels (Id, Modified, IsDeleted, HotelName, Category, City, State, Description) VALUES (17, CURRENT_TIMESTAMP, 0, 'City Skyline Antiquity Hotel', 'Boutique', 'New York', 'NY', 'In vogue since 1888, the Antiquity Hotel takes you back to bygone era. From the crystal chandeliers that adorn the Green Room, to the arched ceilings of the Grand Hall, the elegance of old New York beckons. Elevate Your Experience. Upgrade to a premiere city skyline view for less, where old world charm combines with dramatic views of the city, local cathedral and midtown.');
    INSERT INTO tbl_hotels (Id, Modified, IsDeleted, HotelName, Category, City, State, Description) VALUES (18, CURRENT_TIMESTAMP, 0, 'Ocean Water Resort & Spa', 'Luxury', 'Tampa', 'FL', 'New Luxury Hotel for the vacation of a lifetime. Bay views from every room, location near the pier, rooftop pool, waterfront dining & more.');
    INSERT INTO tbl_hotels (Id, Modified, IsDeleted, HotelName, Category, City, State, Description) VALUES (19, CURRENT_TIMESTAMP, 0, 'Economy Universe Motel', 'Budget', 'Redmond', 'WA', 'Local, family-run hotel in bustling downtown Redmond. We are a pet-friendly establishment, near expansive Marymoor park, haven to pet owners, joggers, and sports enthusiasts. Close to the highway and just a short drive away from major cities.');
    INSERT INTO tbl_hotels (Id, Modified, IsDeleted, HotelName, Category, City, State, Description) VALUES (20, CURRENT_TIMESTAMP, 0, 'Delete Me Hotel', 'Unknown', 'Nowhere', 'XX', 'Test-case row for change detection and delete detection . For change detection, modify any value, and then re-run the indexer. For soft-delete, change IsDelete from zero to a one, and then re-run the indexer.');
   
   

7. 업로드를 확인하기 위해 쿼리를 실행합니다.

   SELECT Description FROM tbl_hotels;
   

   다음 스크린샷과 비슷한 결과가 표시되어야 합니다.

   

설명 필드는 가장 자세한 콘텐츠를 제공합니다. 전체 텍스트 검색과 선택적 벡터화를 위해서는 이 필드를 대상으로 삼아야 합니다.

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

인덱서 파이프라인 설정

이 단계에서는 데이터 원본, 인덱스 및 인덱서가 지정됩니다.

인덱서 상태 확인

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

GET https://myservice.search.windows.net/indexers/myindexer/status?api-version=2025-09-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개의 가장 최근에 완료된 실행이 포함되며, 가장 최근의 실행이 먼저 나오도록 시간 역순으로 정렬됩니다.

새 행, 변경된 행 및 삭제된 행 인덱싱

SQL 데이터베이스에서 변경 내용 추적을 지원하는 경우 검색 인덱서는 후속 인덱서 실행에서 새 콘텐츠와 업데이트된 콘텐츠만 선택할 수 있습니다.

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

Azure SQL 인덱서의 경우 두 가지 변경 감지 정책이 있습니다.

• "SqlIntegratedChangeTrackingPolicy"(테이블에만 적용됨)

• "HighWaterMarkChangeDetectionPolicy"(뷰에 적용)

SQL 통합 변경 내용 추적 정책

효율적이고 삭제된 행을 식별할 수 있는 "SqlIntegratedChangeTrackingPolicy"를 사용하는 것이 좋습니다.

데이터베이스 요구 사항:

• Azure SQL Database 또는 SQL Managed Instance. Azure VM을 사용하는 경우 SQL Server 2016 이상
• 데이터베이스에 변경 내용 추적을 사용하도록 설정해야 합니다.
• 테이블만(보기 없음)
• 테이블을 클러스터할 수 없습니다. 이 요구 사항을 충족하려면 클러스터형 인덱스 삭제 및 비클러스터형 인덱스로 다시 만듭니다. 이 해결 방법은 성능이 저하되는 경우가 많습니다. 인덱서 처리 전용인 두 번째 테이블에서 콘텐츠를 복제하면 유용한 완화 방법이 될 수 있습니다.
• 테이블은 비워 둘 수 없습니다. TRUNCATE TABLE을 사용하여 행을 지우는 경우 인덱서를 다시 설정하고 다시 실행해도 해당 검색 문서가 제거되지 않습니다. 분리된 검색 문서를 제거하려면 삭제 작업으로 문서를 인덱싱해야 합니다.
• 기본 키는 복합 키(둘 이상의 열 포함)일 수 없습니다.
• 삭제 검색을 원하는 경우 기본 키는 비클러스터형이어야 합니다.

변경 감지 정책은 데이터 원본 정의에 추가됩니다. 이 정책을 사용하려면 Azure Portal에서 데이터 원본 정의를 편집하거나 REST를 사용하여 다음과 같이 데이터 원본을 업데이트합니다.

POST https://myservice.search.windows.net/datasources?api-version=2025-09-01
Content-Type: application/json
api-key: admin-key
    {
        "name" : "myazuresqldatasource",
        "type" : "azuresql",
        "credentials" : { "connectionString" : "connection string" },
        "container" : { "name" : "table name" },
        "dataChangeDetectionPolicy" : {
            "@odata.type" : "#Microsoft.Azure.Search.SqlIntegratedChangeTrackingPolicy"
        }
    }

SQL 통합 변경 내용 추적 정책을 사용하는 경우 별도의 데이터 삭제 감지 정책을 지정하지 마세요. SQL 통합 변경 내용 추적 정책은 삭제된 행을 식별하는 지원 기능을 기본 제공합니다. 그러나 삭제된 행이 자동으로 검색되려면 검색 인덱스의 문서 키가 SQL 테이블의 기본 키와 동일해야 하며 기본 키는 비클러스터형이어야 합니다.

상위 워터마크 변경 감지 정책

이 변경 감지 정책은 행이 마지막으로 업데이트된 버전 또는 시간을 캡처하는 테이블 또는 뷰의 “상위 워터 마크” 열을 사용합니다. 뷰를 사용하는 경우 상위 워터 마크 정책을 사용해야 합니다.

상위 워터 마크 열은 다음 요구 사항을 충족해야 합니다.

• 모든 삽입 시 열의 값을 지정합니다.
• 항목에 대한 모든 업데이트는 열의 값도 변경합니다.
• 삽입 또는 업데이트할 때마다 이 열의 값이 증가합니다.
• 다음 WHERE 및 ORDER BY 절이 포함된 쿼리를 효율적으로 실행할 수 있습니다. WHERE [High Water Mark Column] > [Current High Water Mark Value] ORDER BY [High Water Mark Column]

변경 감지 정책은 데이터 원본 정의에 추가됩니다. 이 정책을 사용하려면 다음과 같이 데이터 원본을 만들거나 업데이트합니다.

POST https://myservice.search.windows.net/datasources?api-version=2025-09-01
Content-Type: application/json
api-key: admin-key
    {
        "name" : "myazuresqldatasource",
        "type" : "azuresql",
        "credentials" : { "connectionString" : "connection string" },
        "container" : { "name" : "table or view name" },
        "dataChangeDetectionPolicy" : {
            "@odata.type" : "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
            "highWaterMarkColumnName" : "[a rowversion or last_updated column name]"
        }
    }

하이 워터 마크를 행 버전으로 변환

상위 워터 마크 열에 rowversion 데이터 형식을 사용하는 경우 인덱서 구성에 convertHighWaterMarkToRowVersion 속성을 설정하는 것이 좋습니다. 이 속성을 true로 설정하면 다음과 같은 동작이 발생합니다.

• 인덱서 SQL 쿼리의 상위 워터 마크 열에는 rowversion 데이터 형식을 사용합니다. 올바른 데이터 형식을 사용하면 인덱서 쿼리 성능이 향상됩니다.

• 인덱서 쿼리를 실행하기 전에 rowversion 값에서 1을 뺍니다. 일대다 조인을 사용하는 뷰에는 rowversion 값이 중복되는 행이 있을 수 있습니다. 1을 빼면 인덱서 쿼리에서 이러한 행을 누락하지 않습니다.

이 속성을 사용하도록 설정하려면 다음 구성을 사용하여 인덱서를 만들거나 업데이트합니다.

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

queryTimeout

시간 초과 오류가 발생하는 경우 queryTimeout 인덱서 구성 설정을 기본값(5분)보다 높은 값으로 설정합니다. 예를 들어 제한 시간을 10분으로 설정하려면 다음 구성을 사용하여 인덱서를 만들거나 업데이트합니다.

    {
      ... other indexer definition properties
     "parameters" : {
            "configuration" : { "queryTimeout" : "00:10:00" } }
    }

하이 워터 마크 열 기준 정렬 비활성화 (disableOrderByHighWaterMarkColumn)

ORDER BY [High Water Mark Column] 절을 사용하지 않도록 설정할 수도 있습니다. 그러나 인덱서 실행이 오류로 인해 중단된 경우 해당 시점에 거의 모든 행을 처리했더라도 나중에 실행될 때 모든 행을 다시 처리해야 하므로 이는 권장되지 않습니다. ORDER BY 절을 사용하지 않도록 설정하려면 인덱서 정의에서 disableOrderByHighWaterMarkColumn 설정을 사용합니다.

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

일시 삭제 열 삭제 감지 정책

원본 테이블에서 행이 삭제된 경우 검색 인덱스에서도 해당 행을 삭제할 수 있습니다. SQL 통합 변경 내용 추적 정책을 사용하는 경우 이 작업이 자동으로 수행됩니다. 그러나 상위 워터 마크 변경 내용 추적 정책은 삭제된 행을 지원하지 않습니다. 그렇다면 어떻게 해야 할까요?

행이 테이블에서 실제로 제거된 경우 Azure AI Search에서 더 이상 존재하지 않는 레코드의 현재 상태를 유추할 방법이 없습니다. 그러나 "일시 삭제" 기술을 사용하여 테이블에서 제거하지 않고 논리적으로 행을 삭제할 수 있습니다. 테이블 또는 뷰에 열을 추가하고 이 열을 사용하여 행을 삭제된 것으로 표시합니다.

일시 삭제 기술을 사용하는 경우 데이터 원본을 만들거나 업데이트할 때 다음과 같이 일시 삭제 정책을 지정할 수 있습니다.

    {
        …,
        "dataDeletionDetectionPolicy" : {
           "@odata.type" : "#Microsoft.Azure.Search.SoftDeleteColumnDeletionDetectionPolicy",
           "softDeleteColumnName" : "[a column name]",
           "softDeleteMarkerValue" : "[the value that indicates that a row is deleted]"
        }
    }

softDeleteMarkerValue는 데이터 원본에서 JSON 형식으로 표현된 문자열이어야 합니다. 실제 값의 문자열 표현을 사용합니다. 예를 들어 삭제된 행이 값 1로 표시된 정수 열이 있는 경우 "1"을 사용합니다. 삭제된 행이 부울 true 값으로 표시된 BIT 열이 있는 경우 문자열 리터럴 "True" 또는 "true"를 사용합니다. 대소문자는 상관 없습니다.

Azure Portal에서 일시 삭제 정책을 설정하는 경우 일시 삭제 마커 값 주위에 따옴표를 추가하지 마세요. 필드 콘텐츠는 이미 문자열로 이해되어 있으며 자동으로 JSON 문자열로 변환됩니다. 이전 예에서는 Azure Portal 필드에 1, True 또는 true를 입력하기만 하면 됩니다.

FAQ

Q: Always Encrypted 열을 인덱싱할 수 있나요?

아니요, Always Encrypted 열은 현재 Azure AI Search 인덱서에서 지원되지 않습니다.

Q: Azure의 IaaS VM에서 실행되는 SQL 데이터베이스에서 Azure SQL 인덱서를 사용할 수 있습니까?

예. 그러나 검색 서비스에서 데이터베이스에 연결할 수 있도록 허용해야 합니다. 자세한 내용은 Azure VM에서 Azure AI Search 인덱서로부터 SQL Server로의 연결 구성을 참조하세요.

Q: 온-프레미스에서 실행되는 SQL 데이터베이스에서 Azure SQL 인덱서를 사용할 수 있습니까?

직접 끌 수는 없습니다. 직접 연결은 권장되거나 지원되지 않습니다. 이렇게 하려면 데이터베이스를 인터넷 트래픽에 개방해야 하기 때문입니다. 고객은 Azure Data Factory와 같은 브리지 기술을 사용하여 이 시나리오를 성공적으로 수행했습니다. 자세한 내용은 Azure Data Factory를 사용하여 Azure AI Search 인덱스에 데이터 푸시를 참조하세요.

Q: 장애 조치(failover) 클러스터에서 데이터 원본으로 보조 복제본을 사용할 수 있습니까?

경우에 따라 다릅니다. 테이블 또는 뷰의 전체 인덱싱에 대해 보조 복제본을 사용할 수 있습니다.

증분 인덱싱의 경우 Azure AI Search는 SQL 통합 변경 내용 추적 및 상위 워터 마크라는 두 가지 변경 검색 정책을 지원합니다.

읽기 전용 복제본에서 SQL Database는 통합된 변경 내용 추적을 지원하지 않습니다. 따라서 상위 워터 마크 정책을 사용해야 합니다.

상위 워터 마크 열에는 rowversion 데이터 형식을 사용하는 것이 일반적으로 권장됩니다. 그러나 rowversion 사용 시, 읽기 전용 복제본에서는 지원되지 않는 MIN_ACTIVE_ROWVERSION 함수에 의존합니다. 따라서 rowversion를 사용하는 경우 인덱서가 주 복제본을 가리키도록 해야 합니다.

읽기 전용 복제본에서 rowversion을 사용하려고 하면 다음 오류가 발생합니다.

"변경 내용 추적에 rowversion 열을 사용하는 것은 보조(읽기 전용) 가용성 복제본에서 지원되지 않습니다. 데이터 원본을 업데이트하고 기본 가용성 복제본에 대한 연결을 지정합니다. 현재 데이터베이스 '업데이트 가능 여부' 속성은 'READ_ONLY'입니다."

Q: 상위 워터 마크 변경 내용 추적에 대체의 rowversion이 아닌 열을 사용할 수 있습니까?

권장되지 않습니다. 신뢰할 수 있는 데이터 동기화를 위해서는 rowversion만 허용됩니다. 그러나 애플리케이션 논리에 따라 다음과 같은 경우 안전할 수 있습니다.

• 인덱서가 실행될 때 인덱싱되는 테이블에 미해결 트랜잭션이 있는지 확인할 수 있습니다(예를 들어 모든 테이블 업데이트가 일정에 따라 일괄 처리되고 Azure AI Search 인덱서 일정이 테이블 업데이트 일정과 겹치지 않도록 설정됨).

• 모든 누락된 행을 선택하기 위해 전체 다시 인덱싱을 정기적으로 수행합니다.