Indexer des données provenant d’Azure SQL Database

Dans cet article, découvrez comment configurer un indexeur qui importe du contenu à partir d’Azure SQL Database ou d’une instance gérée Azure SQL et le rend consultable dans Recherche Azure AI.

Cet article vient en complément de l’article Créer un indexeur avec des informations spécifiques sur l’indexation à partir d’Azure SQL. Il utilise le portail Azure et des API REST pour montrer un workflow en trois parties commun à tous les indexeurs : créer une source de données, créer un index, créer un indexeur. L’extraction de données se produit quand vous envoyez la demande de création d’un indexeur.

Cet article fournit également ce qui suit :

• Description des stratégies de détection des modifications prises en charge par l’indexeur Azure SQL pour configurer l’indexation incrémentielle.

• Section Forum aux questions (FAQ) pour obtenir des réponses aux questions relatives à la compatibilité des fonctionnalités.

Prérequis

• Une base de données Azure SQL ou une instance managée SQL avec un point de terminaison public.

• Une seule table ou vue.

  Utilisez une table si vos données sont volumineuses ou si vous avez besoin d’une indexation incrémentielle à l’aide des fonctionnalités de détection des modifications natives de SQL (suivi intégré des modifications SQL) pour refléter les lignes nouvelles, modifiées et supprimées dans l’index de recherche.

  Utilisez une vue si vous devez consolider les données de plusieurs tables. Les vues volumineuses ne sont pas idéales pour l’indexeur SQL. Une solution de contournement consiste à créer une table réservée à l’ingestion dans votre index Recherche Azure AI. Si vous choisissez d’utiliser une vue, vous pouvez utiliser High Water Mark pour la détection des modifications, mais vous devez utiliser une solution de contournement pour la détection de suppression.

• La clé primaire doit être à valeur unique. Sur une table, elle doit également être non clusterisée pour le suivi completement intégré au SQL des modifications.

• Autorisations de lecture. Recherche Azure AI prend en charge l’authentification SQL Server, où le nom d’utilisateur et le mot de passe sont fournis dans la chaîne de connexion. Vous pouvez également configurer une identité managée et utiliser des rôles Azure avec l’appartenance aux rôles Contributeur SQL Server ou Contributeur SQL DB .

Pour utiliser les exemples de cet article, vous avez besoin du portail Azure ou d’un client REST. Si vous utilisez le portail Azure, assurez-vous que l’accès à tous les réseaux publics est activé dans le pare-feu Azure SQL, et que le client dispose d’un accès via une règle de trafic entrant. Pour un client REST qui s’exécute localement, configurez le pare-feu SQL Server pour autoriser l’accès entrant depuis l’adresse IP de votre appareil. Les Kits de développement logiciel (SDK) Azure font partie des autres approches pour créer un indexeur Azure SQL.

Essayer avec des exemples de données

Utilisez ces instructions pour créer et charger une table dans Azure SQL Database à des fins de test.

1. Téléchargez hotels-azure-sql.sql depuis GitHub pour créer une table sur Azure SQL Database qui contient un sous-ensemble de l’exemple de jeu de données d’hôtels.

2. Connectez-vous au portail Azure et créez une base de données Azure SQL et un serveur de base de données. Envisagez de configurer à la fois l’authentification SQL Server et l’authentification Microsoft Entra ID. Si vous n’avez pas les autorisations nécessaires pour configurer des rôles sur Azure, vous pouvez utiliser l’authentification SQL comme solution de contournement.

3. Configurez le pare-feu du serveur pour toutes les requêtes entrantes depuis votre appareil local.

4. Dans votre base de données Azure SQL, sélectionnez Éditeur de requête (préversion), puis Nouvelle requête.

5. Collez puis exécutez le script T-SQL qui crée la table hotels. Une clé primaire non cluster est requise pour le suivi des modifications intégré 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. Collez puis exécutez le script T-SQL qui insère des enregistrements.

    -- 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. Exécutez une requête pour vérifier le chargement.

   SELECT Description FROM tbl_hotels;
   

   Vous devez voir des résultats similaires à la capture d’écran suivante.

   

Le champ Description fournit le contenu le plus détaillé. Vous devez cibler ce champ pour la recherche en texte intégral et la vectorisation facultative.

Maintenant que vous disposez d’une table de base de données, vous pouvez utiliser le portail Azure, le client REST ou un Kit de développement logiciel (SDK) Azure pour indexer vos données.

Configurer le pipeline d’indexeur

Dans cette étape, spécifiez la source de données, l’index et l’indexeur.

Vérifier l’état de l’indexeur

Pour surveiller l'état de l'indexeur et l'historique d'exécution, vérifiez l'historique d'exécution de l'indexeur dans le portail Azure ou envoyez une Requête d'API REST Obtenir l'état de l'indexeur

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
        ]
    }

L’historique d’exécution contient jusqu’à 50 exécutions les plus récentes, classées par ordre antichronologique, la dernière exécution apparaissant en premier.

Indexation de lignes nouvelles, modifiées et supprimées

Si votre base de données SQL prend en charge le suivi des modifications, un indexeur de recherche peut récupérer uniquement le contenu nouveau et mis à jour lors des exécutions ultérieures de l’indexeur.

Pour activer l’indexation incrémentielle, définissez la propriété « dataChangeDetectionPolicy » dans la définition de votre source de données. Cette propriété indique à l’indexeur quel mécanisme de suivi des modifications est utilisé sur votre table ou vue.

Pour les indexeurs Azure SQL, il existe deux stratégies de détection des modifications :

• « SqlIntegratedChangeTrackingPolicy » (s’applique aux tables uniquement)

• « HighWaterMarkChangeDetectionPolicy » (fonctionne pour les vues)

Stratégie de suivi des modifications intégrée SQL

Nous vous recommandons d’utiliser « SqlIntegratedChangeTrackingPolicy » pour son efficacité et sa capacité à identifier les lignes supprimées.

Configuration requise pour la base de données :

• Azure SQL Database ou SQL Managed Instance. SQL Server 2016 ou version ultérieure si vous utilisez une machine virtuelle Azure.
• La base de données doit avoir activé le suivi des modifications
• Tables uniquement (pas de vues).
• Les tables ne peuvent pas être en cluster. Pour répondre à cette exigence, supprimez l’index cluster et recréez-le en tant qu’index non cluster. Cette solution de contournement dégrade souvent les performances. La duplication de contenu dans une deuxième table dédiée au traitement de l’indexeur peut être une atténuation utile.
• Les tables ne peuvent pas être vides. Si vous utilisez TRUNCATE TABLE pour effacer les lignes, une réinitialisation et une réexécution de l’indexeur ne supprimeront pas les documents de recherche correspondants. Pour supprimer des documents de recherche orphelins, vous devez les indexer avec une action de suppression.
• La clé primaire ne peut pas être une clé composée (contenant plusieurs colonnes).
• La clé primaire doit être non clusterisée si vous souhaitez la détection de suppression.

Les stratégies de détection des modifications sont ajoutées aux définitions de la source de données. Pour utiliser cette stratégie, modifiez la définition de source de données dans le portail Azure ou utilisez REST pour mettre à jour votre source de données comme suit :

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"
        }
    }

Lorsque vous utilisez la stratégie de suivi intégré des modifications SQL, ne spécifiez pas de stratégie de détection de suppression de données distincte. La stratégie de suivi intégré des modifications SQL offre une prise en charge intégrée de l’identification des lignes supprimées. Toutefois, pour que les lignes supprimées soient détectées automatiquement, la clé de document dans votre index de recherche doit être identique à la clé primaire de la table SQL, et la clé primaire doit être non cluster.

Stratégie de détection des changements de limite supérieure

Cette stratégie de détection des modifications s’appuie sur une colonne « Limite supérieure » de votre table ou vue qui capture la version ou l’heure pour laquelle une ligne a été mise à jour. Si vous utilisez une vue, vous devez vous servir d’une stratégie de limite supérieure.

La colonne de limite supérieure doit remplir les conditions suivantes :

• Toutes les insertions spécifient une valeur pour la colonne.
• Toutes les mises à jour d'un élément modifient également la valeur de la colonne.
• La valeur de cette colonne augmente à chaque insertion ou mise à jour.
• Les requêtes utilisant les clauses WHERE et ORDER BY suivantes peuvent être exécutées efficacement : WHERE [High Water Mark Column] > [Current High Water Mark Value] ORDER BY [High Water Mark Column]

Les stratégies de détection des modifications sont ajoutées aux définitions de la source de données. Pour utiliser cette stratégie, créez ou mettez à jour votre source de données comme suit :

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]"
        }
    }

convertHighWaterMarkToRowVersion

Si vous utilisez un type de données rowversion pour la colonne de limite supérieure, envisagez de définir la propriété convertHighWaterMarkToRowVersion dans le configuration de l’indexeur. L’affectation de la valeur true à cette propriété entraîne les comportements suivants :

• Utilisez le type de données rowversion pour la colonne de limite supérieure dans la requête SQL de l’indexeur. L’utilisation du type de données correct améliore le niveau de performance de requête de l’indexeur.

• Soustrayez un de la valeur rowversion avant l’exécution de la requête de l’indexeur. Les vues avec des jointures une-à-plusieurs risquent de contenir des lignes avec des valeurs rowversion en double. Soustraire un garantit que la requête de l’indexeur n’ignore pas ces lignes.

Pour activer cette propriété, créez ou mettez à jour l’indexeur avec la configuration suivante :

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

queryTimeout

Si vous rencontrez des erreurs de temporisation, utilisez le paramètre de configuration d’indexeur queryTimeout pour une valeur d’expiration plus élevée que les 5 minutes par défaut. Par exemple, pour fixer un délai d’expiration de 10 minutes, créez ou mettez à jour l’indexeur avec la configuration suivante :

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

disableOrderByHighWaterMarkColumn

Vous pouvez également désactiver la clause ORDER BY [High Water Mark Column]. Toutefois, cette action est déconseillée parce que si l’exécution de l’indexeur est interrompue par une erreur, l’indexeur doit retraiter toutes les lignes s’il s’exécute par la suite, même s’il avait déjà traité la quasi-totalité des lignes au moment de l’interruption. Pour désactiver la clause ORDER BY, utilisez le paramètre disableOrderByHighWaterMarkColumn dans la définition de l’indexeur :

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

Stratégie de détection de suppression réversible de colonnes

Lorsque des lignes sont supprimées de la table source, vous devez également supprimer ces lignes de l'index de recherche. Si vous utilisez la stratégie de suivi intégré des modifications SQL, cette opération est prise en charge à votre place. Mais la stratégie de suivi des modifications de limite supérieure ne vous est d’aucune aide pour les lignes supprimées. Que faire, alors ?

Si des lignes sont physiquement supprimées de la table, la Recherche Azure AI n’a aucun moyen de déduire la présence d’enregistrements qui n’existent plus. Toutefois, vous pouvez utiliser la technique de la « suppression réversible » pour supprimer des lignes logiquement sans les supprimer de la table. Ajoutez une colonne à votre table ou votre vue et marquez les lignes comme supprimées à l’aide de cette colonne.

Lorsque vous utilisez la technique de suppression réversible, vous pouvez spécifier cette stratégie réversible comme suit lors de la création ou de la mise à jour de la source de données :

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

softDeleteMarkerValue doit être une chaîne dans la représentation au format chaîne de votre source de données. Utilisez la représentation sous forme de chaîne de votre valeur réelle. Par exemple, si vous avez une colonne d’entiers dans laquelle les lignes supprimées sont marquées avec la valeur 1, utilisez "1". Si vous avez une colonne BIT dans laquelle les lignes supprimées sont marquées avec la valeur booléenne True, utilisez le littéral de chaîne "True" ou "true", la casse ne comptant pas.

Si vous configurez une stratégie de suppression réversible à partir du portail Azure, n’ajoutez pas de guillemets autour de la valeur du marqueur de suppression réversible. Le contenu du champ est déjà interprété comme une chaîne et est automatiquement converti en chaîne JSON. Dans les exemples précédents, tapez simplement 1, True ou true dans le champ du Portail Microsoft Azure.

Questions fréquentes (FAQ)

Q : Puis-je indexer les colonnes Always Encrypted ?

Non, les colonnes Always Encrypted ne sont pas prises en charge par les indexeurs Recherche Azure AI actuellement.

Q. : Puis-je utiliser l’indexeur SQL Azure avec des bases de données SQL exécutées sur des machines virtuelles IaaS dans Azure ?

Oui. Toutefois, vous devez autoriser votre service de recherche à se connecter à votre base de données. Pour plus d’informations, consultez l’article Configurer une connexion d’un indexeur de Recherche Azure AI à SQL Server sur une machine virtuelle Azure.

Q. : Puis-je utiliser l’indexeur Azure SQL avec des bases de données SQL exécutées localement ?

Pas directement. La connexion directe n’est pas prise en charge, ni recommandée, car elle vous oblige à ouvrir vos bases de données au trafic Internet. Les clients ont réussi à l’aide de technologies de pont telles qu’Azure Data Factory. Pour plus d’informations, consultez Envoyer des données à un index Recherche Azure AI à l’aide d’Azure Data Factory.

Q : Puis-je utiliser un réplica secondaire dans un cluster de basculement comme source de données ?

Cela dépend. Pour l’indexation intégrale d’une table ou d’une vue, vous pouvez utiliser un réplica secondaire.

Pour une indexation incrémentielle, Recherche Azure AI prend en charge deux stratégies de détection des modifications : le suivi de modifications intégré SQL et la définition d’une limite supérieure.

Sur les réplicas en lecture seule, SQL Database ne prend pas en charge le suivi des modifications intégré. Par conséquent, vous devez utiliser la stratégie de limite supérieure.

Nous vous recommandons d’utiliser le type de données rowversion pour la colonne dédiée à la limite supérieure. Toutefois, l’utilisation de rowversion repose sur la fonction MIN_ACTIVE_ROWVERSION, qui n’est pas prise en charge sur les réplicas en lecture seule. Par conséquent, vous devez pointer l’indexeur sur un réplica principal si vous utilisez rowversion.

Si vous essayez d’utiliser rowversion sur un réplica en lecture seule, vous recevez l’erreur suivante :

« L’utilisation d’une colonne rowversion pour le suivi des modifications n’est pas prise en charge sur les réplicas de disponibilité secondaires (en lecture seule). Mettez à jour la source de données et spécifiez une connexion au réplica de disponibilité principal. La propriété de « capacité de mise à jour » de la base de données actuelle est « READ_ONLY ».

Q : Puis-je utiliser une colonne autre que rowversion pour le suivi des modifications de la limite supérieure ?

Cela n’est pas recommandé. Seule la colonne rowversion permet une synchronisation fiable des données. Toutefois, en fonction de votre logique d’application, vous devriez pouvoir le faire sans problème si :

• Vous pouvez vous assurer que pendant l’exécution de l’indexeur, aucune transaction n’est en attente sur la table en cours d’indexation (par exemple, toutes les mises à jour de la table s’effectuent de manière planifiée par lot, et la planification de l’indexeur Recherche Azure AI est définie de manière à éviter tout chevauchement avec la planification de la mise à jour de la table).

• Vous procédez régulièrement à une réindexation complète pour sélectionner toutes les lignes manquantes.