Azure Search で基本的なインデックスを作成するCreate a basic index in Azure Search

Azure Search におけるインデックスとは、Azure Search サービスでのフィルターされたおよびフル テキストの検索に使用されるドキュメントなどの構成要素の永続的なストアです。In Azure Search, an index is a persistent store of documents and other constructs used for filtered and full text search on an Azure Search service. 概念的に、ドキュメントはインデックス内で検索可能なデータの 1 つの単位です。Conceptually, a document is a single unit of searchable data in your index. たとえば、eコマースの小売業者であれば販売品目ごとにドキュメントがあり、報道機関であれば記事ごとにドキュメントがあります。For example, an e-commerce retailer might have a document for each item they sell, a news organization might have a document for each article, and so forth. これらの概念をなじみのあるデータベースの同等のものに対応させるなら、インデックスは概念的にはテーブルに似ており、ドキュメントはテーブルにおけるとほぼ同じです。Mapping these concepts to more familiar database equivalents: an index is conceptually similar to a table, and documents are roughly equivalent to rows in a table.

インデックスを追加またはアップロードすると、ユーザーが提供したスキーマを基に Azure Search によって物理構造が作成されます。When you add or upload an index, Azure Search creates physical structures based on the schema you provide. たとえば、インデックス内のフィールドが検索可能としてマークされていると、そのフィールドの転置インデックスが作成されます。For example, if a field in your index is marked as searchable, an inverted index is created for that field. 後で、ドキュメントを追加またはアップロードするとき、または検索クエリを Azure Search に送信するときは、検索サービス内の特定のインデックスに対して要求を送信していることになります。Later, when you add or upload documents, or submit search queries to Azure Search, you are sending requests to a specific index in your search service. フィールドにドキュメントの値を読み込むことを、"インデックス付け" またはデータ インジェストと呼びます。Loading fields with document values is called indexing or data ingestion.

インデックスの作成は、ポータル、REST API、または .NET SDK で行うことができます。You can create an index in the portal, REST API, or .NET SDK.

適切なインデックス設計は、通常は複数回のイテレーションを経て得られます。Arriving at the right index design is typically achieved through multiple iterations. ツールと API の組み合わせを使用すれば、設計をすばやく完了することができます。Using a combination of tools and APIs can help you finalize your design quickly.

  1. インデクサーを使用できるかどうかを判断します。Determine whether you can use an indexer. 外部データがサポートされているデータソースのものである場合、データのインポート ウィザードを使用してインデックスのプロトタイプ作成と読み込みを行うことができます。If your external data is one of the supported data sources, you can prototype and load an index using the Import data wizard.

  2. データのインポートを使用できない場合でも、ポータルで初期インデックスを作成し、フィールドとデータ型を追加し、 [インデックスの追加] ページのコントロールを使用して属性を割り当てることができます。If you can't use Import data, you can still create an initial index in the portal, adding fields, data types, and assigning attributes using controls on the Add Index page. ポータルでは、さまざまなデータ型に対してどの属性が使用できるかが表示されます。The portal shows you which attributes are available for different data types. インデックスの作成が初めての場合、これが役立ちます。If you're new to index design, this is helpful.

    データ型ごとに属性が表示されるインデックス追加ページAdd index page showing attributes by data type

    [作成] をクリックすると、このインデックスをサポートしているすべての物理構造が検索サービスに作成されます。When you click Create, all of the physical structures supporting your index are created in your search service.

  3. Get Index REST API や、Postman などの Web テスト ツールを使用してインデックス スキーマをダウンロードします。Download the index schema using Get Index REST API and a web testing tool like Postman. これで、ポータルで作成したインデックスの JSON 表現ができました。You now have a JSON representation of the index you created in the portal.

    ここからはコード ベースのアプローチに切り替えます。You are switching to a code-based approach at this point. 既に作成されているインデックスは編集できないため、ポータルはイテレーションにあまり適していません。The portal is not well-suited for iteration because you cannot edit an index that is already created. ただし、残りのタスクには Postman や REST を使用できます。But you can use Postman and REST for the remaining tasks.

  4. インデックスにデータを読み込みますLoad your index with data. Azure Search は JSON ドキュメントを受け入れます。Azure Search accepts JSON documents. プログラムによってデータを読み込むために、Postman を使用し、要求ペイロードに JSON ドキュメントを含めることができます。To load your data programmatically, you can use Postman with JSON documents in the request payload. データを JSON で表現することが簡単でない場合、この手順に最も多くの労力がかかります。If your data is not easily expressed as JSON, this step will be the most labor intensive.

  5. インデックスをクエリし、結果を確認し、期待した結果が得られるようになるまでインデックス スキーマをさらに反復処理します。Query your index, examine results, and further iterate on the index schema until you begin to see the results you expect. インデックスのクエリには Search エクスプローラーまたは Postman を使用できます。You can use Search explorer or Postman to query your index.

  6. 引き続き、コードを使用して設計を反復処理します。Continue using code to iterate over your design.

物理構造はサービス内で作成されるため、既存のフィールド定義に重要な変更を加えるたびにインデックスの削除と再作成が必要です。Because physical structures are created in the service, dropping and recreating indexes is necessary whenever you make material changes to an existing field definition. つまり、開発中は頻繁なリビルドを計画する必要があります。This means that during development, you should plan on frequent rebuilds. リビルドを高速化するために、データのサブセットを使って作業することを検討してもよいでしょう。You might consider working with a subset of your data to make rebuilds go faster.

反復的な設計には、ポータルを使う方法よりもコードのほうをお勧めします。Code, rather than a portal approach, is recommended for iterative design. インデックス定義にポータルを使用する場合、リビルドのたびにインデックス定義を入力する必要があります。If you rely on the portal for index definition, you will have to fill out the index definition on each rebuild. 開発プロジェクトがまだ初期段階の場合、代わりに Postman や REST API などのツールを使用すると、概念実証テストに役立ちます。As an alternative, tools like Postman and the REST API are helpful for proof-of-concept testing when development projects are still in early phases. 要求本文のインデックス定義に増分的変更を加えてから要求をサービスに送信し、更新されたスキーマを使用してインデックスを再作成できます。You can make incremental changes to an index definition in a request body, and then send the request to your service to recreate an index using an updated schema.

インデックスのコンポーネントComponents of an index

スキーマ的には、Azure Search のインデックスは次の要素で構成されます。Schematically, an Azure Search index is composed of the following elements.

"フィールド コレクション" は通常、インデックスの最大の部分であり、各フィールドには、名前、型、および使用方法を決定する許容される動作を示す属性が設定されます。The fields collection is typically the largest part of an index, where each field is named, typed, and attributed with allowable behaviors that determine how it is used. 他の要素としては、suggesterスコアリング プロファイル、カスタマイズをサポートする構成要素を含むアナライザーCORS、および暗号化キー オプションがあります。Other elements include suggesters, scoring profiles, analyzers with component parts to support customization, CORS and encryption key options.

{
  "name": (optional on PUT; required on POST) "name_of_index",
  "fields": [
    {
      "name": "name_of_field",
      "type": "Edm.String | Collection(Edm.String) | Edm.Int32 | Edm.Int64 | Edm.Double | Edm.Boolean | Edm.DateTimeOffset | Edm.GeographyPoint",
      "searchable": true (default where applicable) | false (only Edm.String and Collection(Edm.String) fields can be searchable),
      "filterable": true (default) | false,
      "sortable": true (default where applicable) | false (Collection(Edm.String) fields cannot be sortable),
      "facetable": true (default where applicable) | false (Edm.GeographyPoint fields cannot be facetable),
      "key": true | false (default, only Edm.String fields can be keys),
      "retrievable": true (default) | false,
      "analyzer": "name_of_analyzer_for_search_and_indexing", (only if 'searchAnalyzer' and 'indexAnalyzer' are not set)
      "searchAnalyzer": "name_of_search_analyzer", (only if 'indexAnalyzer' is set and 'analyzer' is not set)
      "indexAnalyzer": "name_of_indexing_analyzer", (only if 'searchAnalyzer' is set and 'analyzer' is not set)
      "synonymMaps": [ "name_of_synonym_map" ] (optional, only one synonym map per field is currently supported)
    }
  ],
  "suggesters": [
    {
      "name": "name of suggester",
      "searchMode": "analyzingInfixMatching",
      "sourceFields": ["field1", "field2", ...]
    }
  ],
  "scoringProfiles": [
    {
      "name": "name of scoring profile",
      "text": (optional, only applies to searchable fields) {
        "weights": {
          "searchable_field_name": relative_weight_value (positive #'s),
          ...
        }
      },
      "functions": (optional) [
        {
          "type": "magnitude | freshness | distance | tag",
          "boost": # (positive number used as multiplier for raw score != 1),
          "fieldName": "...",
          "interpolation": "constant | linear (default) | quadratic | logarithmic",
          "magnitude": {
            "boostingRangeStart": #,
            "boostingRangeEnd": #,
            "constantBoostBeyondRange": true | false (default)
          },
          "freshness": {
            "boostingDuration": "..." (value representing timespan leading to now over which boosting occurs)
          },
          "distance": {
            "referencePointParameter": "...", (parameter to be passed in queries to use as reference location)
            "boostingDistance": # (the distance in kilometers from the reference location where the boosting range ends)
          },
          "tag": {
            "tagsParameter": "..." (parameter to be passed in queries to specify a list of tags to compare against target fields)
          }
        }
      ],
      "functionAggregation": (optional, applies only when functions are specified) 
        "sum (default) | average | minimum | maximum | firstMatching"
    }
  ],
  "analyzers":(optional)[ ... ],
  "charFilters":(optional)[ ... ],
  "tokenizers":(optional)[ ... ],
  "tokenFilters":(optional)[ ... ],
  "defaultScoringProfile": (optional) "...",
  "corsOptions": (optional) {
    "allowedOrigins": ["*"] | ["origin_1", "origin_2", ...],
    "maxAgeInSeconds": (optional) max_age_in_seconds (non-negative integer)
  },
  "encryptionKey":(optional){
    "keyVaultUri": "azure_key_vault_uri",
    "keyVaultKeyName": "name_of_azure_key_vault_key",
    "keyVaultKeyVersion": "version_of_azure_key_vault_key",
    "accessCredentials":(optional){
      "applicationId": "azure_active_directory_application_id",
      "applicationSecret": "azure_active_directory_application_authentication_key"
    }
  }
}

フィールド コレクションとフィールド属性Fields collection and field attributes

スキーマを定義する際に、インデックスの各フィールドの名前、型、属性を指定する必要があります。As you define your schema, you must specify the name, type, and attributes of each field in your index. フィールドの型によって、そのフィールドに格納されているデータが分類されます。The field type classifies the data that is stored in that field. 属性は個々のフィールドに設定されてフィールドの使用方法を指定します。Attributes are set on individual fields to specify how the field is used. 次の表に、指定できる型と属性をまとめます。The following tables enumerate the types and attributes you can specify.

データの種類Data types

TypeType 説明Description
Edm.StringEdm.String フルテキスト検索 (単語区切り、ステミングなど) のために必要に応じてトークン化できるテキスト。Text that can optionally be tokenized for full-text search (word-breaking, stemming, and so forth).
Collection(Edm.String)Collection(Edm.String) フルテキスト検索のために必要に応じてトークン化することのできる一連の文字列。A list of strings that can optionally be tokenized for full-text search. コレクション内の項目の数に理論上の上限はありませんが、ペイロードのサイズに対する 16 MB の上限がコレクションに適用されます。There is no theoretical upper limit on the number of items in a collection, but the 16 MB upper limit on payload size applies to collections.
Edm.BooleanEdm.Boolean true または false の値が含まれます。Contains true/false values.
Edm.Int32Edm.Int32 32 ビット整数値です。32-bit integer values.
Edm.Int64Edm.Int64 64 ビット整数値です。64-bit integer values.
Edm.DoubleEdm.Double 倍精度数値データです。Double-precision numeric data.
Edm.DateTimeOffsetEdm.DateTimeOffset OData V4 形式で表された日時の値です (例: yyyy-MM-ddTHH:mm:ss.fffZ または yyyy-MM-ddTHH:mm:ss.fff[+/-]HH:mm)。Date time values represented in the OData V4 format (for example, yyyy-MM-ddTHH:mm:ss.fffZ or yyyy-MM-ddTHH:mm:ss.fff[+/-]HH:mm).
Edm.GeographyPointEdm.GeographyPoint 地球上の地理的な場所を表すポイントです。A point representing a geographic location on the globe.

Azure Search のサポートされるデータ型の詳細については、このページを参照してください。You can find more detailed information about Azure Search's supported data types here.

インデックスの属性Index attributes

インデックス内の 1 つのフィールドのみが、各ドキュメントを一意に識別するキー フィールドとして指定されている必要があります。Exactly one field in your index must be the designated as a key field that uniquely identifies each document.

他の属性によって、フィールドがアプリケーション内でどのように使用されるかが決まります。Other attributes determine how a field is used in an application. たとえば、フルテキスト検索に含める必要があるすべてのフィールドには、searchable 属性が割り当てられています。For example, the searchable attribute is assigned to every field that should be included in a full text search.

インデックスの作成に使用する API には、さまざまな既定の動作があります。The APIs you use to build an index have varying default behaviors. REST API の場合、ほとんどの属性は既定で有効であり (たとえば、文字列フィールドの searchable および retrievable は true です)、無効にする場合は、単にそれらを設定するだけです。For the REST APIs, most attributes are enabled by default (for example, searchable and retrievable are true for string fields) and you often only need to set them if you want to turn them off. .NET SDK の場合は、逆のことが言えます。For the .NET SDK, the opposite is true. 明示的に設定していないプロパティの場合、既定では、特に有効にしない限り、対応する検索動作は無効にされています。On any property you do not explicitly set, the default is to disable the corresponding search behavior unless you specifically enable it.

AttributeAttribute 説明Description
key ドキュメント検索に使用される各ドキュメントの一意の ID を提供する文字列です。A string that provides the unique ID of each document, used for document lookup. 各インデックスに、1 つのキーが必要です。Every index must have one key. 1 つのフィールドだけをキーにすることができ、その型を Edm.String に設定する必要があります。Only one field can be the key, and its type must be set to Edm.String.
retrievable 検索結果でフィールドを返すことができるかどうかを設定します。Specifies whether a field can be returned in a search result.
filterable フィルター クエリでフィールドを使用できるようにします。Allows the field to be used in filter queries.
Sortable このフィールドを使ってクエリで検索結果を並べ替えられるようにします。Allows a query to sort search results using this field.
facetable ユーザー自律フィルター処理の ファセット ナビゲーション 構造でフィールドを使用できるようにします。Allows a field to be used in a faceted navigation structure for user self-directed filtering. 通常は、複数のドキュメント (たとえば、1 つのブランドやサービス カテゴリに属する複数のドキュメント) をまとめてグループ化するために使用できる、反復する値があるフィールドが、ファセットとして最適です。Typically fields containing repetitive values that you can use to group multiple documents together (for example, multiple documents that fall under a single brand or service category) work best as facets.
searchable フィールドをフルテキスト検索可能としてマークします。Marks the field as full-text searchable.

ストレージへの影響Storage implications

選択した属性はストレージに影響を与えます。The attributes you select have an impact on storage. 次のスクリーンショットは、属性のさまざまな組み合わせの結果であるインデックス格納パターンを示しています。The following screenshot illustrates index storage patterns resulting from various combinations of attributes.

インデックスは組み込みの real estateサンプル データ ソースに基づいており、このデータ ソースはポータルでインデックスを作成したりクエリを実行したりできます。The index is based on the built-in real estate sample data source, which you can index and query in the portal. インデックスのスキーマは表示されませんが、インデックス名に基づいて属性を推測できます。Although the index schemas are not shown, you can infer the attributes based on the index name. たとえば、realestate-searchable インデックスでは searchable 属性が選択されていて他には何もなく、realestate-retrievable インデックスでは retrievable 属性が選択されていて他には何もなく、以下同様です。For example, realestate-searchable index has the searchable attribute selected and nothing else, realestate-retrievable index has the retrievable attribute selected and nothing else, and so forth.

属性選択に基づいたインデックスのサイズIndex size based on attribute selection

これらのインデックスのバリエーションは人為的なものですが、属性がストレージに与える影響の広範な比較のために参照できます。Although these index variants are artificial, we can refer to them for broad comparisons of how attributes affect storage. 設定 retrievable はインデックスのサイズを増加させますか?Does setting retrievable increase index size? いいえ。No. Suggester にフィールドを追加するとインデックスのサイズが増加しますか?Does adding fields to a Suggester increase index size? はい。Yes.

フィルターと並べ替えをサポートするインデックスは、フルテキスト検索しかサポートしないインデックスに比べて大きくなります。Indexes that support filter and sort are proportionally larger than indexes that support just full text search. フィルターと並べ替えは完全一致をクエリするので、ドキュメントがそのまま格納されることがその理由です。The reason is that filter and sort query on exact matches so documents are stored intact. これに対し、フルテキスト検索とあいまい検索をサポートする検索可能フィールドでは転置インデックスを使用します。転置インデックスはトークン化された語句によって事前設定され、使用するディスク容量はドキュメント全体よりも少なくなります。In contrast, searchable fields supporting full-text and fuzzy search use inverted indexes, which are populated with tokenized terms that consume less space than whole documents.

注意

ストレージ アーキテクチャは Azure Search の実装の詳細と考えられており、予告なく変更されることがあります。Storage architecture is considered an implementation detail of Azure Search and could change without notice. 現在の動作が将来も変わらないという保証はありません。There is no guarantee that current behavior will persist in the future.

サジェスターSuggesters

suggester は、検索においてオートコンプリートまたは先行入力クエリをサポートするために使用されるインデックス内のフィールドが定義されている、スキーマのセクションです。A suggester is a section of the schema that defines which fields in an index are used to support auto-complete or type-ahead queries in searches. 通常、ユーザーが検索クエリを入力している間に部分的な検索文字列が Suggestions (REST API) に送信されて、API は検索候補の語句のセットを返します。Typically, partial search strings are sent to the Suggestions (REST API) while the user is typing a search query, and the API returns a set of suggested phrases.

サジェスターに追加されるフィールドは、先行入力検索語句の構築に使用されます。Fields added to a suggester are used to build type-ahead search terms. すべての検索語句はインデックス作成時に作成され、個別に格納されます。All of the search terms are created during indexing and stored separately. サジェスター構造の作成の詳細については、サジェスターの追加に関する記事を参照してください。For more information about creating a suggester structure, see Add suggesters.

スコアリング プロファイルScoring profiles

スコアリング プロファイルは、検索結果での項目の表示順序を変更できるカスタム スコアリング動作が定義されている、スキーマのセクションです。A scoring profile is a section of the schema that defines custom scoring behaviors that let you influence which items appear higher in the search results. スコアリング プロファイルは、フィールドの重みと関数で構成されます。Scoring profiles are made up of field weights and functions. 使用するには、クエリ文字列にプロファイル名を指定します。To use them, you specify a profile by name on the query string.

既定のスコアリング プロファイルはバックグラウンドで実行され、検索セットの各項目の検索スコアがコンピューティングされます。A default scoring profile operates behind the scenes to compute a search score for every item in a result set. 内部的な名前のないスコアリング プロファイルを使用できます。You can use the internal, unnamed scoring profile. または、クエリ文字列にカスタム プロファイルが指定されていない場合に常に呼び出される既定値として、カスタム プロファイルを使用するように defaultScoringProfile を設定します。Alternatively, set defaultScoringProfile to use a custom profile as the default, invoked whenever a custom profile is not specified on the query string.

アナライザーAnalyzers

アナライザー要素では、フィールドに対して使用される言語アナライザーの名前が設定されます。The analyzers element sets the name of the language analyzer to use for the field. 利用可能なアナライザーの範囲の詳細については、Azure Search インデックスへのアナライザーの追加に関する記事を参照してください。For more information about the range of analyzers available to you, see Adding analyzers to an Azure Search index. アナライザーは検索可能フィールドでのみ使用できます。Analyzers can only be used with searchable fields. フィールドに割り当てられたアナライザーは、インデックスを再構築しない限り変更できません。Once the analyzer is assigned to a field, it cannot be changed unless you rebuild the index.

CORSCORS

ブラウザーではすべてのクロスオリジン要求が禁止されるので、既定ではクライアント側 JavaScript で API を呼び出すことはできません。Client-side JavaScript cannot call any APIs by default since the browser will prevent all cross-origin requests. インデックスに対するクロスオリジン クエリを許可するには、corsOptions 属性を設定することによって、CORS (クロスオリジン リソース共有) を有効にします。To allow cross-origin queries to your index, enable CORS (Cross-Origin Resource Sharing) by setting the corsOptions attribute. セキュリティ上の理由から、CORS がサポートされているのはクエリ API だけです。For security reasons, only query APIs support CORS.

CORS に対しては以下のオプションを設定できます。The following options can be set for CORS:

  • allowedOrigins (必須):インデックスへのアクセスが許可されるオリジンのリストです。allowedOrigins (required): This is a list of origins that will be granted access to your index. つまり、これらのオリジンから提供されるすべての JavaScript コードは、インデックスのクエリを許可されます (正しい api-key を提供する場合)。This means that any JavaScript code served from those origins will be allowed to query your index (assuming it provides the correct api-key). 各オリジンの標準的な形式は protocol://<fully-qualified-domain-name>:<port> ですが、多くの場合 <port> は省略されます。Each origin is typically of the form protocol://<fully-qualified-domain-name>:<port> although <port> is often omitted. 詳しくは、「Cross-origin resource sharing (クロスオリジン リソース共有)」(Wikipedia) をご覧ください。See Cross-origin resource sharing (Wikipedia) for more details.

    すべてのオリジンにアクセスを許可する場合は、allowedOrigins 配列の唯一の要素として * を指定します。If you want to allow access to all origins, include * as a single item in the allowedOrigins array. "運用環境の検索サービスに対してはこれは推奨されません" が、開発およびデバッグでは役に立つことがよくあります。This is not recommended practice for production search services but it is often useful for development and debugging.

  • maxAgeInSeconds (省略可能):ブラウザーでは、この値を使用して、CORS プレフライト応答をキャッシュする期間 (秒) が決定されます。maxAgeInSeconds (optional): Browsers use this value to determine the duration (in seconds) to cache CORS preflight responses. 負ではない整数を指定する必要があります。This must be a non-negative integer. この値が大きいほどパフォーマンスはよくなりますが、CORS ポリシーの変更が有効になるまでの時間は長くなります。The larger this value is, the better performance will be, but the longer it will take for CORS policy changes to take effect. これを設定しないと、既定の期間として 5 分が使用されます。If it is not set, a default duration of 5 minutes will be used.

暗号化キーEncryption Key

既定では、Azure Search のすべてのインデックスは、Microsoft のマネージド キーを使用して暗号化されますが、Key Vault 内で顧客管理のキーを使用してインデックスを暗号化するように構成することもできます。While all Azure search indexes are encrypted by default using Microsoft managed keys, indexes can be configured to be encrypted with customer managed keys in Key Vault. 詳細については、Azure Search での暗号化キーの管理に関するページを参照してください。To learn more, see Manage encryption keys in Azure Search.

次の手順Next steps

インデックスの構成を理解したなら、続けてポータルで最初のインデックスを作成できます。With an understanding of index composition, you can continue in the portal to create your first index.