附註
Foundry IQ(Azure AI 搜尋服務)提供直接的索引與查詢 API,並搭配高階知識來源與知識庫 API 用於受控檢索。 使用 Azure 入口網站、REST API 或 Azure SDK 來設定這些功能,或將代理連線到 Microsoft Foundry 入口網站 中的知識庫。
Azure SQL 索引器會將內容從 Azure SQL Database 或 Azure SQL 受控執行個體 匯入到 Foundry IQ(Azure AI 搜尋服務)索引中。
本文以 Azure SQL 的特定資訊補充建立索引子。 它會使用 Azure 入口網站 和 REST API 來示範所有索引器通用的三部分工作流程:建立數據源、建立索引、建立索引器。 提交建立索引子要求時會擷取資料。
本文也提供下列項目:
描述 Azure SQL 索引子所支援的變更偵測原則,以便設定累加式索引編制。
常見問題集 (FAQ) 一節,針對功能相容性問題提供解答。
附註
索引子無法進行即時資料同步處理。 最多每隔五分鐘,索引子可以重新索引您的資料表。 如果資料更新必須盡快反映在索引中,建議您直接推送更新的資料列。
必要條件
具有公用端點的 Azure SQL 資料庫 或 SQL 受控實例。
單一資料表或檢視。
如果您的數據很大,或者如果您需要使用 SQL 的原生變更偵測功能進行累加式索引編製,請使用數據表來反映搜尋索引中新的、已變更和已刪除的數據列。
若您須合併多個資料表的資料,請使用檢視。 大型檢視不適用於 SQL 索引子。 一個解決方法是建立一個專門用於匯入 Foundry IQ 索引的新表格。 如果您選擇使用檢視,您可以使用高水位線進行變更偵測,但必須使用用於刪除偵測的因應措施。
主鍵必須是單一值。 在數據表上,它也必須是非叢集,才能進行完整的SQL整合式變更追蹤。
讀取權限。 Foundry IQ 支援 SQL Server 驗證,使用者名稱與密碼會在 連接字串 中提供。 或者,您可以 設定受控識別,並使用 Azure 角色 搭配 SQL Server 參與者 或 SQL DB 參與者 角色的成員資格。
若要完成本文中的範例,您需要 Azure 入口網站 或 REST 用戶端。 如果您使用的是 Azure 入口網站,請確定已在 Azure SQL 防火牆中啟用所有公用網路的存取權,且用戶端可透過輸入規則加以存取。 針對在本機執行的 REST 用戶端,設定 SQL Server 防火牆以允許來自裝置 IP 位址的輸入存取。 建立 Azure SQL 索引器的其他方法包括 Azure SDK。
嘗試使用範例數據
使用這些指示,在 Azure SQL 資料庫 中建立和載入數據表以供測試之用。
從 GitHub 下載 hotels-azure-sql.sql,在 Azure SQL Database 上建立一個包含範例飯店資料集子集的資料表。
登入 Azure 入口網站 並建立 Azure SQL 資料庫和資料庫伺服器。 請考慮同時設定 SQL Server 驗證和Microsoft Entra ID 驗證。 如果您沒有在 Azure 上設定角色的許可權,您可以使用 SQL 驗證作為因應措施。
將伺服器防火牆設定為來自本機裝置的所有輸入要求。
在您的 Azure SQL 資料庫上,選取 [查詢編輯器][預覽], 然後選取 [ 新增查詢]。
貼上 ,然後執行建立 hotels 數據表的 T-SQL 腳本。 非叢集主鍵是 SQL 整合式變更追蹤的需求。
CREATE TABLE tbl_hotels ( Id TINYINT PRIMARY KEY NONCLUSTERED, Modified DateTime NULL DEFAULT CURRENT_TIMESTAMP, IsDeleted TINYINT, HotelName VARCHAR(40), Category VARCHAR(20), City VARCHAR(30), State VARCHAR(4), Description VARCHAR(500) );貼入 ,然後執行插入記錄的 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 IsDeleted from zero to a one, and then re-run the indexer.');執行查詢以確認上傳。
SELECT Description FROM tbl_hotels;您應該會看到類似下列螢幕快照的結果。
[描述] 欄位提供最詳細的內容。 你應該將此欄位鎖定為全文搜尋及可選的向量化選項。
現在您已有資料庫數據表,您可以使用 Azure 入口網站、REST 用戶端或 Azure SDK 來編制數據索引。
提示
您可以在 Azure-Samples/SQL-AI-samples 上找到另一個提供範例內容和程式代碼的資源。
設定索引器管線
在此步驟中,指定數據源、索引和索引器。
請確定您的 SQL 資料庫處於作用中狀態,而不會因為閑置而暫停。 在 Azure 入口網站中,流覽至資料庫伺服器頁面,並確認資料庫狀態為 在線。 您可以在任何數據表上執行查詢,以啟動資料庫。
請確定您有符合索引子和變更偵測需求的資料表或檢視。
首先,您只能從單一數據表或檢視提取。 我們建議數據表,因為它們支援 SQL 整合式變更追蹤原則,可偵測新的、更新和已刪除的數據列。 高水位線標記原則不支援資料列刪除,而且難以實作。
其次,主鍵必須是單一值(不支持複合索引鍵)和非叢集。
切換至 Foundry IQ 服務並建立資料來源。 在 [搜尋管理>數據源] 底下,選取 [新增數據源]:
- 針對數據源類型,選擇 [Azure SQL Database]。
- 在 Foundry IQ 上為資料來源物件提供名稱。
- 使用下拉式清單來選取訂用帳戶、帳戶類型、伺服器、資料庫、數據表或檢視表、架構和數據表名稱。
- 針對變更追蹤,我們建議 使用 SQL 整合式變更追蹤原則。
- 若要進行驗證,建議您使用 受控識別進行連線。 您的 Foundry IQ 服務必須在資料庫上擁有 SQL Server Contributor 或 SQL DB Contributor 角色成員資格。
- 選取 [建立 ] 以建立數據源。
使用 匯入精靈 建立索引和索引器。
在 概觀 頁面上,選取 匯入資料。
選取您剛建立的資料來源。
略過新增 AI 擴充的步驟。
為索引命名,將索引鍵設定為表格中的主鍵,將所有欄位標記為可擷取和可搜尋,並選擇性地為短字串或數值新增可篩選和可排序。
命名索引器並完成向導以建立必要的物件。
檢查索引子狀態
若要監視索引器狀態和執行歷程記錄,請檢查 Azure 入口網站 中的索引器執行歷程記錄,或傳送取得索引器狀態 REST API 要求
執行歷程記錄包含最多 50 個最近完成的執行,以顛倒的時序排序,因此最後的執行最先出現。
為新增、變更和刪除的資料列編製索引
如果您的 SQL 資料庫支援變更追蹤,則搜尋索引子可以在後續索引子執行時,僅挑選全新和更新的內容。
若要啟用累加式索引編製,請在資料來源定義中設定 "dataChangeDetectionPolicy" 屬性。 這個屬性會告知索引器於您的資料表或檢視中使用了哪種變更追蹤機制。
Azure SQL 索引器有兩種變更偵測策略:
"SqlIntegratedChangeTrackingPolicy" (僅適用於資料表)
“HighWaterMarkChangeDetectionPolicy” (適用於檢視)
SQL 整合式變更追蹤原則
建議您使用 "SqlIntegratedChangeTrackingPolicy",因其具備效率和識別已刪除資料列的能力。
資料庫需求:
- Azure SQL Database 或 SQL 受控實例。 如果您使用 Azure VM,則為 SQL Server 2016 或更新版本。
- 資料庫必須 啟用變更追蹤
- 僅限資料表 (沒有檢視)。
- 無法叢集數據表。 若要符合此需求,請卸除叢集索引,並將其重新建立為非叢集索引。 此因應措施通常會降低效能。 在專用於索引器處理的第二個數據表中複製內容,可能是一個有用的緩和措施。
- 數據表不能是空的。 如果你用 TRUNCATE TABLE 清除列,重設索引器並重執行不會移除對應的搜尋文件。 若要移除孤立的搜尋文件,您必須使用刪除動作編製索引。
- 主鍵不能是複合鍵(包含一個以上的欄)。
- 如果您想要刪除偵測,主索引鍵必須是非叢集。
變更偵測原則會新增至資料來源定義。 若要使用此原則,請在 Azure 入口網站中編輯數據源定義,或使用 REST 來更新您的數據源,如下所示:
POST https://myservice.search.windows.net/datasources?api-version=2026-10-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]
附註
我們強烈建議針對上限標記資料行使用 rowversion 資料類型。 如果使用任何其他資料類型,便無法保證變更追蹤會擷取與索引子查詢同時執行的交易中發生的所有變更。 在具備唯讀複本的設定中使用 rowversion 時,您必須指向主要複本上的索引子。 只有主要複本可用於資料同步處理案例。
變更偵測原則會新增至資料來源定義。 若要使用此原則,請以下列方式建立或更新您的資料來源:
POST https://myservice.search.windows.net/datasources?api-version=2026-10-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]"
}
}
附註
如果來源資料表的高水位標記欄位沒有索引,SQL 索引器所使用的查詢可能會逾時。特別是當資料表包含許多資料列時,ORDER BY [High Water Mark Column] 子句需要有索引才能有效率地執行。
convertHighWaterMarkToRowVersion
若您針對高水位標記資料行使用 rowversion 資料類型,請考慮在索引器設定中設定 convertHighWaterMarkToRowVersion 屬性。 若您將此屬性設定為 true,則會導致下列行為:
針對索引子 SQL 查詢中的上限標準資料行,使用 rowversion 資料類型。 使用正確的資料類型可改善索引子查詢效能。
在索引子查詢執行之前,從 rowversion 值減一。 具有一對多聯結的檢視可能包含具有重複 rowversion 值的資料列。 減一可確保索引子查詢不會遺漏這些資料列。
要啟用此屬性,請在建立或更新索引器時新增以下 parameters 屬性:
{
"parameters": {
"configuration": {
"convertHighWaterMarkToRowVersion": true
}
}
}
queryTimeout
如果您遇到逾時錯誤,請將 queryTimeout 索引子組態設定設為高於預設逾時 (5 分鐘) 的值。 例如,要將逾時設定為 10 分鐘,建立或更新索引器時可新增以下 parameters 屬性:
{
"parameters": {
"configuration": {
"queryTimeout": "00:10:00"
}
}
}
disableOrderByHighWaterMarkColumn
您也可以停用 ORDER BY [High Water Mark Column] 子句。 然而,此操作不建議,因為若索引器執行因錯誤中斷,索引器必須重新處理所有列(即使索引器在中斷時已處理幾乎所有列)。
要停用該 ORDER BY 子句,請在建立或更新索引器時新增以下 parameters 屬性:
{
"parameters": {
"configuration": {
"disableOrderByHighWaterMarkColumn": true
}
}
}
虛刪除資料行刪除偵測原則
當從來源資料表中刪除資料列時,您應該也想刪除在搜尋索引內的那些資料列。 若您使用 SQL 整合變更追蹤原則,就能幫您處理這件工作。 但是,上限標準變更追蹤原則無法幫助您刪除資料列。 怎麼辦?
如果這些列被物理移除,Foundry IQ 就無法推斷那些已不存在的紀錄是否存在。 不過,您可以使用「虛刪除」技術,以邏輯方式刪除資料列,而不需從資料表加以移除。 在資料表或檢視中新增資料行,並使用該資料行將資料列標記為已刪除。
使用軟刪除技術時,請在建立或更新資料來源時新增以下 dataDeletionDetectionPolicy 屬性:
{
"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"。 如果您有 BIT 資料行,且其中的已刪除資料列標記為布林值 true,則請使用字串常值 "True" 或 "true",大小寫並不重要。
若要從 Azure 入口網站設定虛刪除原則,請勿在虛刪除標記值前後加上引號。 欄位內容已瞭解為字串,並會自動轉譯為 JSON 字串。 在先前的範例中,只要在 Azure 入口網站 的欄位中輸入 1或 Truetrue 。
FAQ
問:我可以索引 Always Encrypted 欄位嗎?
否,Foundry IQ 索引器目前不支援 Always Encrypted 欄位。
問:我可以使用 Azure SQL 索引器處理在 Azure 的 IaaS VM 上執行的 SQL 資料庫嗎?
是。 不過,您需要允許您的 Foundry IQ 服務連接到您的資料庫。 如需更多資訊,請參閱〈設定從 Foundry IQ 索引器到 Azure VM 上的 SQL Server 連線〉。
問:我可以將 Azure SQL 索引器搭配本地部署的 SQL 資料庫一起使用嗎?
不直接。 我們不建議或不支援直接連線,因為這樣做需要您開啟資料庫以接收網際網路流量。 客戶需要使用像是 Azure Data Factory 的橋接器技術,才能成功執行此案例。 如需更多資訊,請參閱使用 Azure Data Factory 將資料推送至 Foundry IQ 索引。
問:我可以在 容錯移轉叢集 中使用次要複本作為資料來源嗎?
要看情況而定。 針對完整編製索引的資料表或檢視,您可以使用次要複本。
針對增量索引,Foundry IQ 支援兩種變更偵測策略:SQL 整合變更追蹤與高水位標記。
在唯讀複本中,SQL 資料庫不支援整合變更追蹤。 因此,您必須使用高水位標(High Water Mark)保單。
我們的標準建議是,針對上限標記資料行使用 rowversion 資料類型。 不過,使用 rowversion 會依賴唯讀複本上不支援的 MIN_ACTIVE_ROWVERSION 函式。 因此,如果您使用 rowversion,就必須將索引子指向主要複本。
如果您嘗試在唯讀複本上使用 rowversion,您會收到下列錯誤:
「次要 (唯讀) 可用性複本不支援使用 rowversion 資料行來追蹤變更。 更新資料來源,並指定連線到主要可用性複本。 目前資料庫的 'Updateability' 屬性為 'READ_ONLY'」。
問:我可以使用替代的非 rowversion 欄位來追蹤高水位變更嗎?
我們不建議使用。 僅允許使用 rowversion 進行可靠的資料同步處理。 不過,根據您的應用程式邏輯而定,如果符合下列情況,則它可能是安全的:
您可以確保索引器執行時,正在索引的資料表上沒有未完成的交易(例如,所有資料表更新都會依照排程以批次形式進行,且 Foundry IQ 索引器的排程設定為避免與資料表更新排程重疊)。
您會定期進行完整的重新編製索引,以挑選出任何遺失的資料列。