Indizieren von Daten aus Azure SQL in Azure KI-Suche

In diesem Artikel erfahren Sie, wie Sie einen Indexer konfigurieren, der Inhalte aus der Azure SQL-Datenbank oder aus verwalteten Azure SQL-Instanzen importiert und in Azure KI-Suche durchsuchbar macht.

Dieser Artikel ergänzt den Artikel Erstellen von Indexern mit spezifischen Informationen für Azure SQL. Er verwendet die REST-APIs, um einen dreiteiligen Workflow zu veranschaulichen, der allen Indexern gemeinsam ist: Erstellen einer Datenquelle, Erstellen eines Indexes und Erstellen eines Indexers.

Dieser Artikel enthält auch Folgendes:

• Eine Beschreibung der vom Azure SQL-Indexer unterstützten Änderungserkennungsrichtlinien, damit Sie inkrementelle Indizierung einrichten können.

• Ein Abschnitt mit häufig gestellten Fragen (FAQs) mit Antworten auf Fragen zur Featurekompatibilität.

Voraussetzungen

• Eine Azure SQL-Datenbank mit Daten in einer einzelnen Tabelle oder Ansicht oder einer verwalteten SQL-Instanz mit einem öffentlichen Endpunkt.

  Verwenden Sie eine Tabelle, wenn Sie über große Datenmengen verfügen oder wenn Sie inkrementelle Indizierung mithilfe der nativen Änderungserkennungsfunktionen von SQL benötigen.

  Verwenden Sie eine Ansicht, wenn Sie Daten aus mehreren Tabellen konsolidieren müssen. Große Ansichten sind für SQL-Indexer nicht ideal. Eine Problemumgehung besteht darin, eine neue Tabelle nur für die Erfassung in den Azure KI-Suche-Index zu erstellen. Sie können die integrierte SQL-Änderungsnachverfolgung verwenden, die einfacher implementiert werden kann als der obere Grenzwert.

• Leseberechtigungen. Azure KI-Suche unterstützt die SQL Server-Authentifizierung, bei der Benutzername und Kennwort in der Verbindungszeichenfolge angegeben werden. Alternativ können Sie eine verwaltete Identität einrichten und Azure-Rollen verwenden.

Um die Beispiele in diesem Artikel durchzuarbeiten, benötigen Sie einen REST-Client.

Andere Ansätze zum Erstellen eines Azure SQL-Indexers umfassen Azure-SDKs oder den Importdaten-Assistenten im Azure-Portal. Wenn Sie das Azure-Portal verwenden, stellen Sie sicher, dass der Zugriff auf alle öffentlichen Netzwerke in der Azure SQL-Firewall aktiviert ist und dass der Zugriff des Clients über eine Regel für eingehenden Datenverkehr erfolgt.

Definieren der Datenquelle

Die Datenquellendefinition gibt die zu indizierenden Daten, die Anmeldeinformationen und die Richtlinien für die Identifizierung von Datenänderungen an. Eine Datenquelle wird als unabhängige Ressource definiert, sodass sie von mehreren Indexern verwendet werden kann.

1. Erstellen Sie eine Datenquelle, oder erstellen oder aktualisieren Sie eine Datenquelle, um ihre Definition festzulegen:

    POST https://myservice.search.windows.net/datasources?api-version=2024-07-01
    Content-Type: application/json
    api-key: admin-key
   
    {
        "name" : "myazuresqldatasource",
        "description" : "A database for testing Azure AI Search indexes.",
        "type" : "azuresql",
        "credentials" : { "connectionString" : "Server=tcp:<your server>.database.windows.net,1433;Database=<your database>;User ID=<your user name>;Password=<your password>;Trusted_Connection=False;Encrypt=True;Connection Timeout=30;" },
        "container" : { 
            "name" : "name of the table or view that you want to index",
            "query" : null (not supported in the Azure SQL indexer)
            },
        "dataChangeDetectionPolicy": null,
        "dataDeletionDetectionPolicy": null,
        "encryptionKey": null,
        "identity": null
    }
   

2. Geben Sie einen eindeutigen Namen für die Datenquelle an, der den Namenskonventionen von Azure KI-Suche entspricht.

3. Legen Sie "type" auf "azuresql" fest (erforderlich).

4. Legen Sie „credentials“ auf eine Verbindungszeichenfolge fest:

   • Sie können diese Verbindungszeichenfolge mit vollständigem Zugriff aus dem Azure-Portal abrufen. Verwenden Sie die ADO.NET connection string-Option. Legen Sie einen Benutzernamen und ein Kennwort fest.

   • Alternativ können Sie eine Verbindungszeichenfolge für verwaltete Identitäten ohne Datenbankgeheimnisse angeben. Verwenden Sie dazu das folgende Format: Initial Catalog|Database=<your database name>;ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.Sql/servers/<your SQL Server name>/;Connection Timeout=connection timeout length;.

   Weitere Informationen finden Sie unter Herstellen einer Verbindung mit dem Azure SQL Datenbankindexer mithilfe einer verwalteten Identität.

Hinzufügen von Suchfeldern zu einem Index

Fügen Sie in einem Suchindex Felder hinzu, die den Feldern in der SQL-Datenbank entsprechen. Achten Sie darauf, dass das Suchindexschema mit dem Quellschema kompatibel ist und über äquivalente Datentypen verfügt.

1. Erstellen oder aktualisieren Sie einen Index, um Suchfelder zu definieren, in denen Daten gespeichert werden:

   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": "id",
           "type": "Edm.String",
           "key": true,
           "searchable": false
       }, 
       {
           "name": "description",
           "type": "Edm.String",
           "filterable": false,
           "searchable": true,
           "sortable": false,
           "facetable": false,
           "suggestions": true
       }
     ]
   }
   

2. Erstellen Sie ein Dokumentschlüsselfeld ("key": true), das jedes Suchdokument eindeutig identifiziert. Dies ist das einzige Feld, das in einem Suchindex erforderlich ist. In der Regel wird der Primärschlüssel der Tabelle dem Indexschlüsselfeld zugeordnet. Der Dokumentschlüssel muss eindeutig und nicht NULL sein. In Quelldaten können die Werte numerisch sein. In einem Suchindex ist ein Schlüssel aber immer eine Zeichenfolge.

3. Erstellen Sie weitere Felder, um mehr durchsuchbare Inhalte hinzuzufügen. Weitere Informationen finden Sie unter Erstellen eines Index.

Zuordnen von Datentypen

Konfigurieren und Ausführen des Azure SQL-Indexers

Nach der Erstellung von Index und Datenquelle können Sie den Indexer erstellen. Die Indexerkonfiguration gibt die Eingaben, Parameter und Eigenschaften an, die das Laufzeitverhalten steuern.

1. Erstellen oder aktualisieren Sie den Indexer, indem Sie ihm einen Namen geben und einen Verweis auf die Datenquelle und den Zielindex hinzufügen:

   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-sqldb-indexer]",
       "dataSourceName" : "[my-sqldb-ds]",
       "targetIndexName" : "[my-search-index]",
       "disabled": null,
       "schedule": null,
       "parameters": {
           "batchSize": null,
           "maxFailedItems": 0,
           "maxFailedItemsPerBatch": 0,
           "base64EncodeKeys": false,
           "configuration": {
               "queryTimeout": "00:04:00",
               "convertHighWaterMarkToRowVersion": false,
               "disableOrderByHighWaterMarkColumn": false
           }
       },
       "fieldMappings": [],
       "encryptionKey": null
   }
   

2. Unter „Parametern“ sind im Abschnitt „Konfiguration“ Azure SQL-spezifische Parameter aufgeführt:

   • Das Standardabfragetimeout für die SQL-Abfrageausführung beträgt 5 Minuten; dieser Wert kann überschrieben werden.

   • „convertHighWaterMarkToRowVersion“ ist für die Richtlinie zur Erkennung von Änderungen am oberen Grenzwert optimiert. Änderungserkennungsrichtlinien werden in der Datenquelle festgelegt. Wenn Sie die native Änderungserkennungsrichtlinie verwenden, hat dieser Parameter keine Auswirkung.

   • „disableOrderByHighWaterMarkColumn“ bewirkt, dass bei der SQL-Abfrage, die von der Richtlinie zum Erkennen von Änderungen mit oberem Grenzwert verwendet wird, die ORDER BY-Klausel weggelassen wird. Wenn Sie die native Änderungserkennungsrichtlinie verwenden, hat dieser Parameter keine Auswirkung.

3. Geben Sie Feldzuordnungen an, wenn es Unterschiede beim Feldnamen oder -typ gibt, oder wenn Sie mehrere Versionen eines Quellfelds im Suchindex benötigen.

4. Weitere Informationen zu anderen Eigenschaften finden Sie unter Erstellen von Indexern in Azure Cognitive Search.

Ein Indexer wird automatisch ausgeführt, wenn er erstellt wird. Sie können dies verhindern, indem Sie „disabled“ (Deaktiviert) auf „true“ festlegen. Um die Ausführung des Indexers zu steuern, führen Sie einen Indexer nach Bedarf aus, oder legen Sie für ihn einen Zeitplan fest.

Überprüfen des Indexerstatus

Um den Indexerstatus und den Ausführungsverlauf zu überwachen, senden Sie eine Anforderung zum Abrufen des Indexerstatus:

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

Die Antwort enthält den Status und die Anzahl der verarbeiteten Elemente. Sie sollte in etwa wie das folgende Beispiel aussehen:

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

Der Ausführungsverlauf enthält bis zu 50 der zuletzt abgeschlossenen Ausführungen. Diese sind in umgekehrter chronologischer Reihenfolge sortiert, sodass die neueste Ausführung als Erstes aufgelistet wird.

Indizieren neuer, geänderter und gelöschter Zeilen

Wenn Ihre SQL-Datenbank die Änderungsnachverfolgung unterstützt, kann sich ein Suchindexer bei nachfolgenden Indexerausführungen auf neue und aktualisierte Inhalte beschränken.

Um die inkrementelle Indizierung zu aktivieren, legen Sie die Eigenschaft „dataChangeDetectionPolicy“ in Ihrer Datenquellendefinition fest. Diese Eigenschaft teilt dem Indexer mit, welcher Mechanismus für die Änderungsnachverfolgung für Ihre Tabelle oder Sicht verwendet wird.

Für Azure SQL-Indexer gibt es zwei Richtlinien zur Erkennung von Änderungen:

• „SqlIntegratedChangeTrackingPolicy“ (nur für Tabellen)

• „HighWaterMarkChangeDetectionPolicy“ (für Tabellen und Sichten)

Richtlinie für die integrierte SQL-Änderungsnachverfolgung

Aus Effizienzgründen sowie aufgrund der Möglichkeit, gelöschte Zeilen zu erkennen, wird die Verwendung von „SqlIntegratedChangeTrackingPolicy“ empfohlen.

Datenbankanforderungen:

• SQL Server 2012 SP3 und höher bei Verwendung von SQL Server auf Azure-VMs
• Azure SQL-Datenbank oder SQL Managed Instance
• Nur Tabellen (keine Sichten)
• In der Datenbank: Aktivierte Änderungsnachverfolgung für die Tabelle
• Kein zusammengesetzter Primärschlüssel (Primärschlüssel mit mehr als einer Spalte) für die Tabelle
• Keine gruppierten Indizes für Tabellen. Als Problemumgehung sollte jeder gruppierte Index gelöscht und als nicht gruppierter Index neu erstellt werden. Allerdings kann die Leistung an der Quelle im Vergleich zu einem gruppierten Index beeinträchtigt werden.

Richtlinien zur Änderungserkennung werden Datenquellendefinitionen hinzugefügt. Um diese Richtlinie zu verwenden, erstellen oder aktualisieren Sie die Datenquelle wie folgt:

POST https://myservice.search.windows.net/datasources?api-version=2024-07-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"
    }

Geben Sie bei Verwendung einer Richtlinie für die integrierte SQL-Änderungsnachverfolgung keine separate Richtlinie zur Erkennung von Datenlöschungen an. Die Richtlinie für die integrierte SQL-Änderungsnachverfolgung unterstützt die Identifizierung gelöschter Zeilen. Damit die gelöschten Zeilen automatisch erkannt werden, muss der Dokumentschlüssel im Suchindex allerdings mit dem Primärschlüssel in der SQL-Tabelle übereinstimmen.

Richtlinie zum Erkennen von Änderungen mit oberem Grenzwert

Diese Richtlinie zur Erkennung von Änderungen basiert auf einer Spalte mit oberem Grenzwert in Ihrer Tabelle oder Sicht, in der die Version oder der Zeitpunkt der letzten Aktualisierung einer Zeile erfasst wird. Bei Verwendung einer Sicht müssen Sie eine Richtlinie mit oberem Grenzwert einsetzen.

Die Spalte mit dem oberen Grenzwert muss die folgenden Anforderungen erfüllen:

• Alle Einfügungen geben einen Wert für die Spalte an.
• Alle Updates für ein Element ändern auch den Wert der Spalte.
• Der Wert dieser Spalte wird bei jeder Einfügung oder Aktualisierung erhöht.
• Abfragen mit den folgenden WHERE- und ORDER BY-Klauseln können effizient ausgeführt werden: WHERE [High Water Mark Column] > [Current High Water Mark Value] ORDER BY [High Water Mark Column]

Richtlinien zur Änderungserkennung werden Datenquellendefinitionen hinzugefügt. Um diese Richtlinie zu verwenden, erstellen oder aktualisieren Sie die Datenquelle wie folgt:

POST https://myservice.search.windows.net/datasources?api-version=2024-07-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

Wenn Sie für die Spalte mit dem oberen Grenzwert den Datentyp rowversion verwenden, empfiehlt es sich gegebenenfalls, in der Indexerkonfiguration die Eigenschaft convertHighWaterMarkToRowVersion festzulegen. Wenn Sie diese Eigenschaft auf „true“ festlegen, hat dies folgende Auswirkungen:

• Für die Spalte mit dem oberen Grenzwert wird der Datentyp „rowversion“ für die SQL-Abfrage des Indexers verwendet. Die Verwendung des richtigen Datentyps verbessert die Abfrageleistung des Indexers.

• Vor dem Ausführen der Indexerabfrage wird vom rowversion-Wert die Zahl 1 subtrahiert. Sichten mit 1:n-Joins können Zeilen mit doppelten rowversion-Werten enthalten. Durch Subtraktion von eins wird sichergestellt, dass die Indexerabfrage diese Zeilen nicht übergeht.

Erstellen oder aktualisieren Sie den Indexer mit der folgenden Konfiguration, um diese Eigenschaft zu aktivieren:

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

queryTimeout

Sollten Timeoutfehler auftreten, legen Sie die Indexer-Konfigurationseinstellung queryTimeout auf einen höheren Wert als das Standardtimeout von fünf Minuten fest. Um das Timeout z.B. auf 10 Minuten festzulegen, erstellen oder aktualisieren Sie den Indexer mit der folgenden Konfiguration:

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

disableOrderByHighWaterMarkColumn

Sie können auch die Klausel ORDER BY [High Water Mark Column] deaktivieren. Dies wird jedoch nicht empfohlen, da der Indexer im Fall einer fehlerbedingten Unterbrechung der Indexerausführung alle Zeilen erneut verarbeiten muss, wenn er später ausgeführt wird, auch wenn zum Zeitpunkt der Unterbrechung bereits nahezu alle Zeilen verarbeitet wurden. Zum Deaktivieren der Klausel ORDER BY verwenden Sie die Einstellung disableOrderByHighWaterMarkColumn in der Indexer-Definition:

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

Richtlinie zum Erkennen von Löschungen anhand der Spalte „Vorläufig löschen“

Wenn Zeilen aus der Quelltabelle gelöscht werden, sollten Sie diese Zeilen auch aus dem Suchindex löschen. Wenn Sie die Richtlinie für die integrierte SQL-Änderungsnachverfolgung verwenden, müssen Sie sich nicht darum kümmern, weil es automatisch geschieht. Die Richtlinie zum Erkennen von Änderungen mit oberem Grenzwert hilft Ihnen allerdings nicht beim Löschen von Zeilen. Vorgehensweise

Wenn Zeilen physisch aus der Tabelle entfernt werden, gibt es in Azure KI-Suche keine Möglichkeit, das Vorhandensein von Datensätzen, die nicht mehr vorhanden sind, abzuleiten. Mit der Methode des „vorläufigen Löschens“ können Sie jedoch Zeilen logisch löschen, ohne sie aus der Tabelle zu entfernen. Fügen Sie dazu der Tabelle eine Spalte hinzu, um Zeilen unter Verwendung dieser Spalte anzuzeigen und als gelöscht zu markieren.

Wenn Sie die Methode des "vorläufigen Löschens" verwenden, können Sie die Richtlinie zum Erkennen von Löschungen anhand der "Vorläufig löschen"-Spalte wie folgt beim Erstellen oder Aktualisieren der Datenquelle angeben:

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

softDeleteMarkerValue muss eine Zeichenfolge in der JSON-Darstellung Ihrer Datenquelle sein. Verwenden Sie die Zeichenfolgendarstellung Ihres tatsächlichen Werts. Wenn Sie z.B. über eine „integer“-Spalte verfügen, in der gelöschte Zeilen durch den Wert 1 gekennzeichnet sind, verwenden Sie "1". Wenn Sie über eine BIT-Spalte verfügen, in der gelöschte Zeilen durch den booleschen Wert TRUE gekennzeichnet sind, verwenden Sie das Zeichenfolgenliteral "True" oder "true" (die Groß- und Kleinschreibung spielt keine Rolle).

Wenn Sie eine Richtlinie für das vorläufige Löschen über das Azure-Portal einrichten, fügen Sie keine Anführungszeichen um den Markerwert für das vorläufige Löschen hinzu. Der Feldinhalt wird bereits als Zeichenfolge verstanden und automatisch in eine JSON-Zeichenfolge übersetzt. Geben Sie in den oben gezeigten Beispielen einfach 1, True oder true in das Feld des Portals ein.

Häufig gestellte Fragen

F: Kann ich Always Encrypted-Spalten indizieren?

Nein, Always Encrypted-Spalten werden derzeit nicht von Azure KI-Suche-Indexern unterstützt.

F: Kann ich Azure SQL-Indexer mit SQL-Datenbanken verwenden, die auf IaaS-VMs in Azure ausgeführt werden?

Ja. Sie müssen jedoch die Verbindung des Suchdiensts mit der Datenbank ermöglichen. Weitere Informationen finden Sie im Artikel Konfigurieren einer Verbindung eines Azure KI-Suche-Indexern mit SQL Server auf einer Azure-VM.

F: Kann ich Azure SQL-Indexer mit SQL-Datenbanken verwenden, die lokal ausgeführt werden?

Nicht direkt. Weder empfehlen noch unterstützen wir eine direkte Verbindung, da Sie die Datenbanken dann für den Internetdatenverkehr öffnen müssten. Kunden waren bei diesem Szenario mit Brückentechnologien wie Azure Data Factory erfolgreich. Weitere Informationen finden Sie unter Push-Übertragung von Daten in den Azure KI-Suche-Index mithilfe von Azure Data Factory.

F: Kann ich ein sekundäres Replikat in einem Failovercluster als Datenquelle verwenden?

Das ist unterschiedlich. Für die vollständige Indizierung einer Tabelle oder Sicht können Sie ein sekundäres Replikat verwenden.

Für eine inkrementelle Indizierung unterstützt Azure KI-Suche zwei Richtlinien zur Erkennung von Änderungen: integrierte SQL-Änderungsnachverfolgung und oberer Grenzwert.

Bei schreibgeschützten Replikaten wird die integrierte Änderungsnachverfolgung von SQL-Datenbank nicht unterstützt. Aus diesem Grund müssen Sie die Richtlinie mit oberem Grenzwert verwenden.

Unsere Standardempfehlung ist den Datentyp „rowversion“ für die Spalte mit dem oberen Grenzwert zu verwenden. Allerdings muss für „rowversion“ die Funktion MIN_ACTIVE_ROWVERSION verwendet werden, die für schreibgeschützte Replikate nicht unterstützt wird. Aus diesem Grund muss der Indexer auf ein primäres Replikat verwiesen werden, wenn Sie „rowversion“ verwenden.

Wenn Sie versuchen, „rowversion“ bei einem schreibgeschützten Replikat zu verwenden, wird die folgende Fehlermeldung angezeigt:

„Die Verwendung einer rowversion-Spalte für die Änderungsnachverfolgung wird für sekundäre (schreibgeschützte) Verfügbarkeitsreplikate nicht unterstützt. Aktualisieren Sie die Datenquelle, und geben Sie eine Verbindung zum primären Verfügbarkeitsreplikat an. Die Datenbankeigenschaft „Updateability“ ist derzeit auf READ_ONLY festgelegt.“

F: Kann ich eine alternative Spalte mit einem anderen Typ als „rowversion“ für die Änderungsnachverfolgung mit oberem Grenzwert verwenden?

Dies ist nicht empfehlenswert. Nur rowversion ermöglicht eine zuverlässige Datensynchronisierung. Je nach Anwendungslogik kann es jedoch möglicherweise in folgendem Fall machbar sein:

• Sie können sicherstellen, dass bei der Ausführung des Indexers keine ausstehenden Transaktionen für die Tabelle vorhanden sind, die indiziert wird (z. B. alle Tabellenaktualisierungen werden als ein Batch nach einem Zeitplan ausgeführt, und der Zeitplan des Azure KI-Suche-Indexers ist so festgelegt, dass er sich nicht mit dem Zeitplan der Tabellenaktualisierung überschneidet).

• Sie führen in regelmäßigen Abständen eine vollständige erneute Indizierung aus, damit alle fehlenden Zeilen übernommen werden.