Azure Database for MySQL フレキシブルサーバーからのデータのインデックス作成

[アーティクル]
03/08/2024

重要

MySQL のサポートは、現在、追加の使用条件の下でパブリックプレビュー段階にあります。コンテンツにインデックスを作成するには、プレビュー REST API (2020-06-30-preview 以降) を使用してください。現時点でポータルによるサポートはありません。

この記事では、インデクサーを構成する方法について説明します。これにより、Azure Database for MySQL からコンテンツをインポートし、Azure AI Search でその検索ができるようになります。インデクサーへの入力は、1 つのテーブルまたはビュー内の行です。出力は、検索可能なコンテンツが個々のフィールドに格納される検索インデックスです。

「インデクサーの作成」について補足するこの記事では、Azure Database for MySQL フレキシブルサーバーからのインデックス作成に固有の情報を扱います。 REST API を使用して、すべてのインデクサーに共通する 3 部構成のワークフロー (データソースの作成、インデックスの作成、インデクサーの作成) を示します。データ抽出は、インデクサーの作成要求を送信したときに発生します。

高ウォーターマークと論理的な削除を含めるように構成すると、インデクサーは MySQL データベースのすべての変更、アップロード、および削除を実行します。これらの変更は検索インデックスに反映されます。データ抽出は、インデクサーの作成要求を送信したときに発生します。

前提条件

プレビューに登録して、シナリオのフィードバックを提供します。フォームの送信後、この機能に自動的にアクセスできます。
Azure Database for MySQL フレキシブルサーバーとサンプルデータ。データはテーブルまたはビューに存在する必要があります。主キーが必要です。ビューを使用している場合は、高基準値列が必要です。
読み取りアクセス許可。 "フルアクセス" の接続文字列には、コンテンツへのアクセス権を付与するキーが含まれますが、Azure ロールを使用している場合は、検索サービスのマネージド ID に MySQL に対する [閲覧者] アクセス許可があることを確認してください。
データソース、インデックス、インデクサーを作成するための REST クライアント。

Azure SDK for .NET を使用することもできます。インデクサーの作成にポータルは使用できませんが、作成後にインデクサーとデータソースを管理できます。

プレビューの制限事項

現在、日付またはタイムスタンプがすべての行で統一されている場合、変更の追跡と削除の検出は機能しません。この制限は、プレビューの更新プログラムで解決される既知の問題です。この問題が解決されるまでは、MySQL インデクサーにスキルセットを追加しないでください。

プレビューでは geometry 型と BLOB がサポートされていません。

前述のように、ポータルでのインデクサーの作成はサポートされていませんが、MySQL インデクサーとデータソースが存在していれば、ポータルで管理できます。たとえば、定義を編集し、インデクサーのリセット、実行、スケジュール設定を行うことができます。

データソースを定義する

データソース定義では、インデックスを付けるデータ、資格情報、データの変更を識別するためのポリシーを指定します。データソースは、複数のインデクサーから使用できるように、独立したリソースとして定義します。

[データソースの作成または更新]の定義を指定します。データソースの作成時には、プレビュー REST API バージョン (2020-06-30-Preview 以降) を必ず使用してください。

{   
    "name" : "hotel-mysql-ds",
    "description" : "[Description of MySQL data source]",
    "type" : "mysql",
    "credentials" : { 
        "connectionString" : 
            "Server=[MySQLServerName].MySQL.database.azure.com; Port=3306; Database=[DatabaseName]; Uid=[UserName]; Pwd=[Password]; SslMode=Preferred;" 
    },
    "container" : { 
        "name" : "[TableName]" 
    },
    "dataChangeDetectionPolicy" : { 
        "@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
        "highWaterMarkColumnName": "[HighWaterMarkColumn]"
    }
}

重要なポイント:

type を "mysql" に設定します (必須)。
credentials を ADO.NET の接続文字列に設定します。接続文字列は、 Azure portal の MySQL の [接続文字列] ページで確認できます。
container をテーブルの名前に設定します。
データが変化しやすいので、以降の実行で新規および更新された項目だけをインデクサーで取得する場合は、dataChangeDetectionPolicy を設定します。
ソース項目が削除されたら検索インデックスから検索ドキュメントを削除する場合は、dataDeletionDetectionPolicy を設定します。

インデックスを作成する

インデックスの作成または更新では、インデックススキーマを指定します:

{
    "name" : "hotels-mysql-ix",
    "fields": [
        { "name": "ID", "type": "Edm.String", "key": true, "searchable": false },
        { "name": "HotelName", "type": "Edm.String", "searchable": true, "filterable": false },
        { "name": "Category", "type": "Edm.String", "searchable": false, "filterable": true, "sortable": true  },
        { "name": "City", "type": "Edm.String", "searchable": false, "filterable": true, "sortable": true },
        { "name": "Description", "type": "Edm.String", "searchable": false, "filterable": false, "sortable": false  }     
    ]
}

ソーステーブルの主キーがドキュメントキー (この場合は "ID") と一致する場合、インデクサーは主キーをドキュメントキーとしてインポートします。

マッピングデータ型

次の表は、MySQL データベースを Azure AI Search において相当するものにマップしたものです。詳細については、「サポートされるデータ型 (Azure AI Search)」を参照してください。

Note

プレビューでは geometry 型と BLOB がサポートされていません。

MySQL のデータ型	Azure AI Search のフィールドの型
`bool`, `boolean`	Edm.Boolean、Edm.String
`tinyint`、`smallint`、`mediumint`、`int`、`integer`、`year`	Edm.Int32、Edm.Int64、Edm.String
`bigint`	Edm.Int64、Edm.String
`float`、`double`、`real`	Edm.Double、Edm.String
`date`、`datetime`、`timestamp`	Edm.DateTimeOffset、Edm.String
`char`, `varchar`, `tinytext`, `mediumtext`, `text`, `longtext`, `enum`, `set`, `time`	Edm.String
unsigned numerical data、serial、decimal、dec、bit、blob、binary、geometry	該当なし

MySQL インデクサーを構成して実行する

インデックスとデータソースを作成したら、インデクサーを作成できます。インデクサーの構成では、実行時の動作を制御する入力、パラメーター、プロパティを指定します。

名前を指定し、データソースとターゲットインデックスを参照することで、インデクサーを作成または更新します。

{
    "name" : "hotels-mysql-idxr",
    "dataSourceName" : "hotels-mysql-ds",
    "targetIndexName" : "hotels-mysql-ix",
    "disabled": null,
    "schedule": null,
    "parameters": {
        "batchSize": null,
        "maxFailedItems": null,
        "maxFailedItemsPerBatch": null,
        "base64EncodeKeys": null,
        "configuration": { }
        },
    "fieldMappings" : [ ],
    "encryptionKey": null
}

重要なポイント:

フィールドの名前または種類に違いがある、または検索インデックスで複数のソースフィールドのバージョンが必要な場合、フィールドマッピングを定義します。
インデクサーは、作成されると自動的に実行されます。これは、disabled を true に設定することで防ぐことができます。インデクサーの実行を制御するには、インデクサーをオンデマンドで実行するか、スケジュールを設定します。

インデクサーの状態を確認する

インデクサーの実行を監視するために、インデクサーの状態の取得要求を送信します。

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

応答には、状態と処理された項目の数が含まれます。次の例のように表示されます。

{
    "status":"running",
    "lastResult": {
        "status":"success",
        "errorMessage":null,
        "startTime":"2024-02-21T00:23:24.957Z",
        "endTime":"2024-02-21T00:36:47.752Z",
        "errors":[],
        "itemsProcessed":1599501,
        "itemsFailed":0,
        "initialTrackingState":null,
        "finalTrackingState":null
    },
    "executionHistory":
    [
        {
            "status":"success",
            "errorMessage":null,
            "startTime":"2024-02-21T00:23:24.957Z",
            "endTime":"2024-02-21T00:36:47.752Z",
            "errors":[],
            "itemsProcessed":1599501,
            "itemsFailed":0,
            "initialTrackingState":null,
            "finalTrackingState":null
        },
        ... earlier history items
    ]
}

実行履歴には、最近完了した実行 50 件が含まれます。時系列の逆の順に並べられるため、最後の実行が最初に表示されます。

新規および変更された行のインデックス作成

インデクサーで検索インデックスが完全に設定されたら、以降のインデクサーで、データベース内の新規および変更された行だけのインデックスを増分的に作成することができます。

増分インデックス作成を有効にするには、データソース定義で dataChangeDetectionPolicy プロパティを設定します。このプロパティで、データに対して使用する変更追跡メカニズムをインデクサーに指示します。

Azure Database for MySQL のインデクサー場合、サポートされているポリシーは HighWaterMarkChangeDetectionPolicy のみです。

インデクサーの変更検出ポリシーは、行のバージョン、または行が最後に更新された日時を取得する "高基準値" 列があることを前提としてします。多くの場合、これは高基準値列の要件を満たすために十分な細分性がある DATE、DATETIME、または TIMESTAMP 列です。

MySQL データベースで、高基準値列は次の要件を満たす必要があります。

すべてのデータ挿入で、その列の値を指定する必要があります。
項目を更新すると、列の値も変更されます。
この列の値は挿入または更新のたびに増加します。
次の WHERE 句および ORDER BY 句のあるクエリを効率的に実行できます。WHERE [High Water Mark Column] > [Current High Water Mark Value] ORDER BY [High Water Mark Column]

次の例は、変更検出ポリシーを含むデータソース定義を示しています。

{
    "name" : "[Data source name]",
    "type" : "mysql",
    "credentials" : { "connectionString" : "[connection string]" },
    "container" : { "name" : "[table or view name]" },
    "dataChangeDetectionPolicy" : {
        "@odata.type" : "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
        "highWaterMarkColumnName" : "[last_updated column name]"
    }
}

重要

ビューを使用している場合は、インデクサーデータソースで高基準値ポリシーを設定する必要があります。

ソーステーブルの高基準列にインデックスがない場合、MySQL インデクサーが使用するクエリはタイムアウトになる可能性があります。具体的には、多くの行が含まれるテーブルに対してクエリを効率的に実行するには、ORDER BY [High Water Mark Column] 句にはインデックスが必要です。

削除された行のインデックス作成

テーブルまたはビューから行が削除されると、通常、検索インデックスからも同様にそれらの行を削除する必要があります。ただし、行がテーブルから物理的に削除されている場合、存在しなくなったレコードの存在をインデクサーで推論することはできません。解決策は、"論理的な削除" 手法を使用して、行をテーブルから削除せずに論理的に削除することです。このテクニックでは、列をテーブルまたはビューに追加し、その列を使用して行を削除済みとしてマークします。

削除状態を示す列があれば、削除状態が true に設定されている検索ドキュメントを削除するようにインデクサーを構成できます。この動作をサポートする構成プロパティは、次のようにデータソース定義で指定されたデータ削除検出ポリシーです。

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

softDeleteMarkerValue は文字列である必要があります。たとえば、削除された行が値 1 でマークされている整数列がある場合は、"1" を使用します。削除された行が BIT 列でブール型の true 値でマークされている場合は、文字列リテラル True または true を使用します (大文字/小文字は区別されません)。

次のステップ

これでインデクサーの実行、状態の監視、インデクサーの実行のスケジュール設定を行うことができます。次の記事は、Azure MySQL からコンテンツをプルするインデクサーに適用されます。

Azure Database for MySQL フレキシブル サーバーからのデータのインデックス作成