Important
この機能は ベータ版です。 ワークスペース管理者は、[ プレビュー] ページからこの機能へのアクセスを制御できます。 Manage Azure Databricks プレビューを参照してください。
フルテキスト検索インデックスを使用すると、マネージド Delta Lake または Iceberg テーブルの 1 つ以上のテキスト列の検索が高速化されます。 インデックスは、部分文字列の一致と単語の一致をサポートします。
search または isearch 関数を使用してテーブルにクエリを実行する場合、Azure Databricksはインデックスを使用して、一致する行が含まれていないことが保証されているファイルをスキップします。 これにより、スキャンされるデータの量が大幅に削減されます(特に選択的検索の場合)。
Important
ベータ リリース中に作成されたインデックスは、以降のリリースとの互換性は保証されません。 この機能がパブリック プレビューに達したら、既存のインデックスを削除し、新しいインデックスを作成する必要があります。
Requirements
フルテキスト検索インデックスには、コンピューティング、ベース テーブルとスキーマのアクセス許可、およびベース テーブルの構成に関する要件があります。
Compute
フルテキスト検索インデックスは、Azure Databricks Runtime 18.2 以降でのみ使用でき、ワークスペース設定でこのベータ機能を有効にする必要があります。 Manage Azure Databricks プレビューを参照してください。
Permissions
検索インデックスを作成するには:
- 検索インデックスで参照されるテーブルに対する
MODIFY権限が必要です。 - 親スキーマに対する
CREATE TABLE権限が必要です。 MANAGE 権限を持つスキーマ所有者またはユーザーは、スキーマに対するCREATE TABLE権限を付与できます。
テーブル構成
フルテキスト検索インデックスを作成する前に、ベース テーブルが次のすべてを満たす必要があります。
- ベース テーブルと同じカタログとスキーマにインデックスを作成する必要があります。
- テーブルは、マネージド Delta Lake テーブルまたはマネージド Iceberg テーブルです。
- 行の追跡が有効になっている (
delta.enableRowTracking = true)。 Azure Databricksの行追跡を参照してください。 - インデックス付き列の種類は、
STRING、VARIANT、STRUCT、またはARRAYです。STRING列では、UTF8_BINARY照合順序が使用されます。 -
STRUCT列には、ネストの深さにかかわらず、少なくとも 1 つのSTRING、VARIANT、またはARRAYのリーフ フィールドが含まれます。他のリーフ フィールドは無視されます。 - このテーブルでは、OpenSharing、簡易複製、属性ベースのアクセス制御、行レベルのセキュリティ ポリシー、列マスクなど、制限の一覧の機能は使用されません。 制限事項を参照してください。
Delta Lake テーブルと Iceberg テーブルの両方に適用されるテーブル プロトコルの要件については、 Delta Lake の機能の互換性とプロトコルに関する記事を参照してください。
フルテキスト検索インデックスを作成する
1 つのテーブルに最大 4 つのインデックスを作成でき、それぞれ異なる列に作成できます。
CREATE SEARCH INDEXを使用して、1 つ以上のテキスト列にインデックスを作成します。 次の例では、既存のログ テーブルの 2 つのテキスト列にインデックスを作成します。
CREATE SEARCH INDEX log_idx
ON logs (message, error_detail);
完全な構文は次のとおりです。
CREATE SEARCH INDEX [IF NOT EXISTS] index_name
ON table_name ( column_name [, column_name ...] )
[OPTIONS ( option_key = option_value [, ... ] )]
index_name はスキーマ内で一意である必要があり、既存のテーブル名と一致することはできません。
テキストのトークン化方法を制御するには、「 オプション」を参照してください。
警告
CREATE SEARCH INDEX
REFRESH INDEX実行中に失敗した場合は、REFRESH INDEXを実行して部分的な障害から復旧します。
オプション
OPTIONS句は、次のキーを受け入れます。
| Key | 価値観 | デフォルト | Description |
|---|---|---|---|
tokenizer |
ngram、split |
ngram |
インデックス作成のためにテキストをトークン化する方法。 ユース ケースのトークナイザーの選択を参照してください。 |
ngram_size |
[3, 10] 内の整数 |
5 |
生成された n グラムの長さ。
tokenizer = 'ngram'の場合にのみ有効です。 |
min_token_length |
整数 >= 1 |
3 |
保持するトークンの最小長。 これより短いトークンは、インデックス作成中に削除されます。
tokenizer = 'split'の場合にのみ有効です。 |
無効なオプション エラーの詳細については、「 SEARCH_INDEX_INVALID_PARAMETERSエラー状態」を参照してください。
ユース ケースのトークナイザーを選択する
検索インデックスには、ユース ケースに応じて、次の 2 つのトークナイザー オプションを使用できます。
| トークナイザー | 利用シーン | Description |
|---|---|---|
ngram |
部分文字列マッチング。 | テキストを重複する n グラムの長さの ngram_sizeに分割します。 |
split |
単語全体の包含チェック。 | テキストを単語トークンに分割します。 トークンは Unicode 文字 (\p{L}) と結合記号 (\p{M}) の実行です。その他の文字は区切り記号です。 |
n-gram のサイズを 4 として n-gram インデックスを作成する方法;
CREATE SEARCH INDEX log_ngram_idx
ON logs (message)
OPTIONS (tokenizer = 'ngram', ngram_size = 4);
トークンの最小長が 2 の split インデックスを作成するには:
CREATE SEARCH INDEX log_word_idx
ON logs (message)
OPTIONS (tokenizer = 'split', min_token_length = 2);
search と isearch を使用してデータをクエリします
Azure Databricksには、検索パターンが 1 つ以上のテキスト ターゲットに存在するかどうかをテストする 2 つの SQL 関数があります。
-
search: 大文字小文字を区別する。 -
isearch: 大文字小文字を区別しない。
大文字と小文字を区別する必要性に応じて、search または isearch を選択してください。 インデックス付き列がフルテキスト検索インデックスでカバーされている場合、Azure Databricksはインデックスを使用して、一致する行が含まれていないファイルをスキップします。 検索インデックスは結果に影響しません。
インデックスは、テーブルのファイルのごく一部に検索パターンが表示される場合に、クエリを最も高速化します。
search( target [, target ... ] , 'pattern' [, mode => 'substring' | 'word' ] )
isearch( target [, target ... ] , 'pattern' [, mode => 'substring' | 'word' ] )
論争
search と isearch は次の引数を受け取ります。
-
targetは、インデックス作成で許可されるのと同じ型STRING、VARIANT、STRUCT、またはARRAYである必要があります。 ターゲットの重複が削除されます。 -
patternは null 以外の文字列リテラルである必要があります。 -
modeは、各patterntarget一致する方法を指定します。-
substring(既定値):patternは、各target内の部分文字列として照合されます。 -
word:patternは、splitトークナイザーと同じルールを使用して単語トークンに分割されます。 順序に関係なく、pattern内のすべての単語が少なくとも 1 つのターゲットに表示される場合、関数は true を返します。 ユース ケースのトークナイザーの選択を参照してください。
-
返品
search
isearchは、3 つの値を持つロジックを持つBOOLEAN値を返します。
-
true少なくとも 1 つの null 以外のターゲットが一致する場合。 -
nullnull 以外のターゲットが一致せず、少なくとも 1 つのターゲットがnull場合。 -
falseすべてのターゲットが null ではなく、どれも一致しない場合。
例示
次の例は、一般的な search クエリと isearch クエリを示しています。
-- Case-insensitive substring search across one column.
SELECT * FROM logs
WHERE isearch(message, 'connection refused');
-- Case-sensitive substring search across multiple columns.
SELECT * FROM logs
WHERE search(message, error_detail, '550e8400-e29b-41d4-a716-446655440000');
-- Word search: matches rows containing all three words, in any order.
SELECT * FROM audit_logs
WHERE search(message, 'user admin login', mode => 'word');
インデックスの管理
Important
フルテキスト検索インデックスは、ベース テーブルが変更されたときに自動的に更新されません。 「インデックスを更新する」を参照してください。
Azure Databricksは、インデックスの鮮度に関係なく、クエリの正確性を維持します。 テーブルにインデックスのないデータが含まれている場合、クエリは既存のインデックスを使用してインデックス付きレコードへのアクセスを高速化し、インデックスのないレコードのテーブル スキャンを使用します。
フルテキスト検索インデックスを管理するには、次の操作を使用します。
インデックスを記述または表示する
インデックスに関する情報を表示するには:
DESCRIBE INDEX log_idx;
インデックスを更新する
フルテキスト検索インデックスは、ベース テーブルが変更されたときに自動的に更新されません。
インデックスを更新するには、新しい行のエントリを追加します。
REFRESH INDEX log_idx;
REFRESH INDEX は増分型の追記専用操作です。 新しいデータのインデックスが作成されますが、削除された行のエントリは削除されません。
インデックスを更新するには、新しい行のエントリを追加し、削除された行のエントリを削除する両方で、 REFRESH INDEX ... FULLを使用します。
REFRESH INDEX log_idx FULL;
完全更新では、増分更新よりも多くのコンピューティング リソースが必要です。 時間の経過と同時に、増分更新によって古いエントリが蓄積され、インデックスのサイズが増加し、パフォーマンスに悪影響が及びます。
インデックスを削除する
インデックスを削除するには、次のコマンドを実行します。
DROP INDEX log_idx;
インデックスが見つからない場合にエラーが発生しないようにするには、次の値を使用します。
DROP INDEX IF EXISTS log_idx;
Note
ベース テーブルを削除すると、フルテキスト検索インデックスも削除されます。
制限事項
フルテキスト検索インデックスには、次の制限があります。
- ベース テーブルのインデックス付き列の名前を変更したり、そのデータ型を変更したりすることはできません。
- OpenSharing を含むテーブルはサポートされていません。 インデックスの作成後にベース テーブルを OpenSharing ソースまたはターゲットとして追加した場合、Azure Databricksは検索インデックスを無視します。
- 簡易クローンを含むテーブルはサポートされていません。 インデックスの作成後に基本テーブルを浅い複製ソースとして追加した場合、Azure Databricksは検索インデックスを無視します。
- 属性ベースのアクセス制御、列マスク、または行レベルのセキュリティ ポリシーを持つテーブルはサポートされていません。 これらのコントロールのいずれかを検索インデックスを持つテーブルに追加した場合、Azure Databricksは検索インデックスを無視します。 属性ベースのアクセス制御 (ABAC) のコア概念を参照してください。
