Azure AI Searchクエリリファレンスガイド

はじめに

この記事では、Azure AI Searchのクエリの使い方について紹介します。

Azure Cognitive Searchとは

Azure AI Search(旧Azure Cognitive Search) は、ストレージ上のファイルなどのデータソースに対して、インデックスを作成し、作成したインデックスによる検索を可能にするサービスです。

インデックスには、ファイルの種類や、ファイルの作成日などのファイルに関するメタデータを格納することができ、 AI Searchを使うと、指定した種類に該当するファイルの絞り込みや、 指定した期間に該当する作成日のファイルの検索などが可能になります。

https://learn.microsoft.com/ja-JP/azure/search/search-what-is-azure-search

クエリパラメータ

Azure AI Searchでは、検索クエリの実行時にクエリパラメータを渡すことで、検索時に挙動を変更することができます。
クエリパラメータは以下のようなものがあります。

• queryType
• searchMode
• search
• searchFields

https://learn.microsoft.com/ja-jp/azure/search/search-query-overview

queryType

queryTypeはクエリのパーサーを設定します。

以下の値が指定できます。

• simplefull : 既定のクエリパーサー、単純なフルテキスト検索に最適

• full : 正規表現、近接検索、あいまい検索、ワイルドカード検索などの高度なクエリに使用する

• semantic : セマンティック検索用に設定

searchMode

Azure AI SearchのsearchModeパラメータは、検索クエリの動作を指定することができます。
searchModeにはanyとallの2つの値を指定することができます。
デフォルトのsearchModeはanyです。

それぞれのモードは以下のような動作を持ちます。

• any

このモードを指定すると、検索クエリに含まれる単語のいずれかが存在するすべてのドキュメントを検索します。

# キーワードのいずれかを含むドキュメントを表示
search='キーワード1 キーワード2'&searchMode=any

• all

このモードを指定すると、検索クエリに含まれるすべての単語が存在するドキュメントを検索します。

# 両方のキーワードを含むドキュメントを表示
search='キーワード1 キーワード2'&searchMode=all

広範に検索する場合はany、厳密な検索を行う際はallを使用します。

search

searchはインデックスを検索するキーワードまたは、ワイルドカード(*)などの演算子を指定します。
インデックスで検索可能に設定したフィールドを対象として、検索を実行します。

# キーワード検索
search=キーワード1

# 複数のキーワードを検索
search=キーワード1 キーワード2

# シングルクォーテーションでキーワード検索 ※検索結果はシングルクォーテーションなしと同じ
search='キーワード1 キーワード2'

• フレーズ検索

引用符 で囲まれた完全に一致する語句です。
キーワード1 キーワード2は、引用符なしでは、キーワード1とキーワード2のいずれかを含むドキュメントが検索されます。
その場合、語句が指定されている場所と順序は関係ありません。
一方、ダブルクオーテーションでキーワードを括った引用符ありの場合では、スペースを含んだ文字列で検索ができます。

# ダブルクォーテーションでフレーズ検索
search="キーワード1 キーワード2"

# ダブルクォーテーションをエスケープしてフレーズ検索
search="\"キーワード1 キーワード2\""

https://learn.microsoft.com/ja-jp/azure/search/query-simple-syntax#keyword-search-on-terms-and-phrases

searchFields

searchFieldsを使うと検索対象を特定のフィールドに設定できます。

$select=metadata_storage_name&searchFields=metadata_storage_name&search=キーワード

フィールド検索 : Fielded search

searchFieldsを使わずに、fieldName:searchExpressionという構文を使用して、指定したフィールドを検索することもできます。

# 言語がjaで、zh-TWでないドキュメントを検索
search=metadata_language:ja NOT zh-TW&queryType=full

# 言語がjaまたは、zh-TWの言語をドキュメントを検索
search=metadata_language:("ja" "zh-TW")&queryType=full

https://learn.microsoft.com/ja-jp/azure/search/query-lucene-syntax#bkmk_fields

あいまい検索 : Fuzzy search

あいまい検索は、検索キーワードに一致していない単語を含めた、類似する単語を検索することができる機能です。
~を指定するとあいまい検索をすることができます。 　

search=キーワード~&queryType=full

https://learn.microsoft.com/ja-jp/azure/search/query-lucene-syntax#bkmk_fuzzy

近接検索 : Proximity search

近接検索は、指定されたキーワードが文書内で指定した距離（単語数）以内にあるドキュメントを検索します。

検索キーワードの末尾にチルダ ~ 記号を挿入し、その後に単語数を挿入します。

# キーワード1からキーワード2の間にある単語数が5以内のドキュメントを検索
search="キーワード1 キーワード2"~5&queryType=full

https://learn.microsoft.com/ja-jp/azure/search/query-lucene-syntax#bkmk_proximity

用語ブースト : Term boosting

用語ブーストはブースト係数という重みを付与して検索し、その用語を含むドキュメントに、それを含まないドキュメントより高い順位を付けて、検索結果の上位に含まれやすくする機能です。

search=ブースト対象用語^3 検索キーワード&queryType=full

用語をブーストするには、 検索する用語の末尾にキャレット^記号を使用します。
ブースト係数が高いほど、用語は他の検索用語に対して高い順位になりやすくなります。
既定のブースト係数は1です。
ブースト係数は正数にする必要がありますが、1未満 (0.20 など) の数字にすることができます。

https://learn.microsoft.com/ja-jp/azure/search/query-lucene-syntax#bkmk_termboost

正規表現検索 : Regular expression search

Azure Cognitive Search では、正規表現はスラッシュ/で囲んだ文字列を正規表現として認識します。

# pdfファイルを正規表現で検索
search=/.*pdf/&queryType=full&searchFields=metadata_storage_name

日本語含むドキュメントは正規表現検索を実行した場合、想定結果が得られなかったという話もしばしばあるらしく、期待した動作にならない可能性があります。

https://learn.microsoft.com/ja-jp/azure/search/query-lucene-syntax#bkmk_regex

https://learn.microsoft.com/ja-jp/azure/search/search-query-lucene-examples#example-5-regex

ワイルドカード検索 : Wild card search

ワイルドカード検索は、特定の文字を代替するシンボル（ワイルドカード）を使用して、一部の文字列が一致するデータを検索する手法です。

以下の2つのワイルドカード文字を使用することができます。

• アスタリスク(*)

ゼロ個以上の任意の文字にマッチします。
例えば、read* は “read”, “reader”, “reading”, “readable” などにマッチします。

• クエスチョンマーク(?)

一個の任意の文字にマッチします。
例えば、read? は “reads”, “ready” などにはマッチしますが、“read” や “reader” にはマッチしません。

Azure AI Searchでは文字列の先頭に*および?を使ったワイルドカード検索はできないため、この場合は、/を使った正規表現で検索する必要があります。

日本語含むドキュメントはワイルドカード検索を実行した場合、想定結果が得られないという話もしばしばあるらしく、期待した動作にならない可能性があります。

# prefix検索
search=test*&queryType=full&searchFields=metadata_storage_name
search=test.pd?&queryType=full&searchFields=metadata_storage_name

# suffix検索 : 正規表現で検索する必要がある
search=/.*pdf/&queryType=full&searchFields=metadata_storage_name

# 挿入辞検索
search=test*pdf&queryType=full&searchFields=metadata_storage_name

https://learn.microsoft.com/ja-jp/azure/search/query-lucene-syntax#bkmk_wildcard

OData（Open Data Protocol）とは

Azure AI Searchでは、クエリを簡単に行い、結果を返すために OData (Open Data Protocol) の一部を採用しています。

OData（Open Data Protocol）は、Microsoft社が策定したREST APIの標準プロトコルです。

Odataではデータにアクセスする際の標準的なクエリオプション: フィルタリング、ページング、ソートオーダー、結果の選択などのクエリオプションを標準化して提供しています。
Odataクエリを使用する場合は先頭に$を指定します。

$select : 結果の選択

select クエリオプションを使用して、検索結果として表示するフィールドを指定することができます。
これにより、必要なデータだけを取得して、余分なデータの取得を避けることができます。

# 単一フィールドを選択
$select=metadata_storage_name

# 複数フィールドを選択
$select=metadata_storage_name,metadata_storage_size

https://learn.microsoft.com/ja-jp/azure/search/search-query-odata-select

$filter : フィルタリング

filterクエリオプションを使用して、検索結果をフィルタリングすることができます。

# 指定サイズ以上のファイルを検索
$filter=metadata_storage_size ge 2160599

# 指定したファイル名と一致するファイルを検索
$filter=metadata_storage_name eq 'test.txt'

# 更新日が指定した範囲期間にあるファイルを検索
$filter=metadata_storage_last_modified ge 2023-08-15T00:00:00Z and metadata_storage_last_modified le 2023-08-16T23:59:59Z

https://learn.microsoft.com/ja-jp/azure/search/search-query-odata-filter

$orderby : ソートオーダー

orderbyクエリオプションを使用して、検索結果を並べ変えることができます。

# 昇順ソート
$orderby=metadata_storage_size

# 降順ソート
$orderby=metadata_storage_size desc

# 複数フィールドのソート
$orderby=metadata_storage_size, metadata_storage_last_modified desc

https://learn.microsoft.com/ja-jp/azure/search/search-query-odata-orderby

$top : ページネーション

topクエリオプションを使用して、検索結果のページネーションを行うことができます。

# 上位3つを検索結果として表示
$top=3

$facets : ファセット

例としてファセットはファイルを種類別にグループ化する機能です。

例として、以下のようなファセットがあります。

ファイルタイプ別のファセット : テキストファイル、PDFファイルなどのファイルの種類に応じて分類 アップロード日時別のファセット : アップロード日時別に分類

facetsクエリを実行する際は、以下のようなクエリを実行します。

# ファイルタイプ別のファセット
$select=metadata_storage_name,metadata_storage_content_type&$facets=["metadata_storage_content_type"]

facetsクエリを使うと、各ファイルの種類の件数を表示することができます。

{
  "@odata.context": "https://cs-dev-poc-001.search.windows.net/indexes('azureblob-index')/$metadata#docs(*)",
  "@search.facets": {
    "metadata_storage_content_type": [
      {
        "count": 2,
        "value": "application/pdf"
      },
      {
        "count": 1,
        "value": "plain/text"
      }
    ]
  },
  "value": [
    {
      "@search.score": 1,
      "metadata_storage_content_type": "application/pdf",
      "metadata_storage_name": "test01.pdf"
    },
    {
      "@search.score": 1,
      "metadata_storage_content_type": "application/pdf",
      "metadata_storage_name": "test02.pdf"
    },
    {
      "@search.score": 1,
      "metadata_storage_content_type": "plain/text",
      "metadata_storage_name": "text03.txt"
    }
  ]
}

https://learn.microsoft.com/ja-jp/azure/search/search-faceted-navigation

参考

• MS公式ドキュメント : oData 言語の概要

• MS公式ドキュメント : Azure AI Search での単純なクエリ構文

• MS公式ドキュメント : Azure AI Search での Lucence クエリ構文

おわりに

この記事では、Azureの「Azure AI Search」について紹介しました。
本記事が、Azure AI Searchを学習するエンジニアの参考になれば幸いです。