検索API - フィールド機能（Field capabilities） - 《Elasticsearchガイドv8.15》日本語

フィールド機能API
リクエスト
前提条件
説明
パスパラメータ
クエリパラメータ
リクエストボディ
レスポンスボディ
例

フィールド機能API

複数のインデックス間でフィールドの機能を取得することを可能にします。データストリームの場合、APIはストリームのバックインデックス間のフィールド機能を返します。

Python

resp = client.field_caps(
   fields="rating",
)
print(resp)

Ruby

response = client.field_caps(
  fields: 'rating'
)
puts response

Js

const response = await client.fieldCaps({
  fields: "rating",
});
console.log(response);

コンソール

GET /_field_caps?fields=rating

リクエスト

GET /_field_caps?fields=<fields>

POST /_field_caps?fields=<fields>

GET /<target>/_field_caps?fields=<fields>

POST /<target>/_field_caps?fields=<fields>

前提条件

Elasticsearchのセキュリティ機能が有効になっている場合、ターゲットデータストリーム、インデックス、またはエイリアスに対してview_index_metadata、read、またはmanage インデックス特権を持っている必要があります。

説明

フィールド機能APIは、複数のインデックス間のフィールドの機能に関する情報を返します。

フィールド機能APIは、他のフィールドと同様にkeywordを返します。たとえば、keywordの型を持つランタイムフィールドは、keywordファミリーに属する他のフィールドと同様に返されます。

パスパラメータ

<target>
(オプション、文字列) リクエストを制限するために使用されるデータストリーム、インデックス、およびエイリアスのカンマ区切りリスト。ワイルドカード(*)をサポートします。すべてのデータストリームとインデックスをターゲットにするには、このパラメータを省略するか、*または_allを使用します。

クエリパラメータ

fields
(必須、文字列) 機能を取得するためのフィールドのカンマ区切りリスト。ワイルドカード(*)式がサポートされています。
allow_no_indices
(オプション、ブール値) falseの場合、リクエストは、ワイルドカード式、インデックスエイリアスまたは_all値が欠落または閉じたインデックスのみをターゲットにする場合にエラーを返します。この動作は、リクエストが他のオープンインデックスをターゲットにしている場合でも適用されます。たとえば、foo*,bar*をターゲットにするリクエストは、fooで始まるインデックスがあるが、barで始まるインデックスがない場合にエラーを返します。
デフォルトはtrueです。
expand_wildcards
(オプション、文字列) ワイルドカードパターンが一致できるインデックスのタイプ。リクエストがデータストリームをターゲットにできる場合、この引数はワイルドカード式が隠しデータストリームに一致するかどうかを決定します。カンマ区切りの値をサポートします。たとえば、open,hidden。有効な値は次のとおりです：
- all
- すべてのデータストリームまたはインデックスに一致し、隠しものも含まれます。
- open
- オープンで非隠しのインデックスに一致します。また、非隠しデータストリームにも一致します。
- closed
- 閉じた非隠しインデックスに一致します。また、非隠しデータストリームにも一致します。データストリームは閉じることができません。
- hidden
- 隠しデータストリームと隠しインデックスに一致します。open、closed、またはその両方と組み合わせる必要があります。
- none
- ワイルドカードパターンは受け入れられません。
  デフォルトはopenです。
ignore_unavailable
(オプション、ブール値) falseの場合、リクエストは欠落または閉じたインデックスをターゲットにする場合にエラーを返します。デフォルトはfalseです。
include_unmapped
(オプション、ブール値) trueの場合、1つのインデックスでマッピングされているが別のインデックスではマッピングされていない未マッピングフィールドが応答に含まれます。マッピングがないフィールドは決して含まれません。デフォルトはfalseです。
include_empty_fields
(オプション、ブール値) falseの場合、すべてのシャードで値を持たなかったフィールドは応答に含まれません。空でないフィールドは常に含まれます。このフラグは削除や更新を考慮しません。フィールドが空でなく、フィールドを含むすべてのドキュメントが削除された場合、またはフィールドが更新によって削除された場合でも、フラグがfalseであっても返されます。デフォルトはtrueです。
filters
(オプション、文字列) 応答に適用するフィルターのカンマ区切りリスト。
```
-   `````+metadata
```
- メタデータフィールドのみを含める
- -metadata
- メタデータフィールドを除外する
- -parent
- 親フィールドを除外する
- -nested
- ネストされたフィールドを除外する
- -multifield
- マルチフィールドを除外する
types
(オプション、文字列) 含めるフィールドタイプのカンマ区切りリスト。これらのタイプのいずれかに一致しないフィールドは結果から除外されます。デフォルトは空であり、すべてのフィールドタイプが返されます。フィールド機能リクエストおよび応答におけるフィールドタイプに関する詳細はこちらを参照してください。

リクエストボディ

index_filter
(オプション、クエリオブジェクト提供されたクエリがすべてのシャードでmatch_noneに書き換えられる場合、インデックスをフィルタリングできます。
runtime_mappings
(オプション、オブジェクト) 検索リクエストで行われるのと同様に、リクエスト内でアドホックindex_filterを定義します。これらのフィールドはクエリの一部としてのみ存在し、インデックスマッピングで同じ名前で定義されたフィールドよりも優先されます。

レスポンスボディ

レスポンスで使用されるタイプは、フィールドタイプのファミリーを説明します。通常、タイプファミリーはマッピングで宣言されたフィールドタイプと同じですが、同様に動作する特定のフィールドタイプは、タイプファミリーを使用して説明されます。たとえば、keyword、constant_keyword、wildcardフィールドタイプはすべてkeywordタイプファミリーとして説明されます。

metadata_field
このフィールドがメタデータフィールドとして登録されているかどうか。
searchable
このフィールドがすべてのインデックスで検索用にインデックスされているかどうか。
aggregatable
このフィールドがすべてのインデックスで集約可能かどうか。
time_series_dimension
このフィールドがすべてのインデックスで時系列次元として使用されているかどうか。非時系列インデックスではこのフィールドは存在しません。
time_series_metric
このフィールドがすべてのインデックスで時系列メトリックとして使用されている場合、メトリックタイプが含まれ、フィールドがメトリックとして使用されていない場合は存在しません。非時系列インデックスではこのフィールドは含まれません。
indices
このフィールドが同じタイプファミリーを持つインデックスのリスト、またはすべてのインデックスがフィールドの同じタイプファミリーを持つ場合はnull。
non_searchable_indices
このフィールドが検索可能でないインデックスのリスト、またはすべてのインデックスがフィールドの同じ定義を持つ場合はnull。
non_aggregatable_indices
このフィールドが集約可能でないインデックスのリスト、またはすべてのインデックスがフィールドの同じ定義を持つ場合はnull。
non_dimension_indices
[プレビュー] この機能は技術プレビュー中であり、将来のリリースで変更または削除される可能性があります。Elasticは問題を修正するために取り組みますが、技術プレビューの機能は公式GA機能のサポートSLAの対象ではありません。このリストがレスポンスに存在する場合、一部のインデックスはこのフィールドを次元としてマークし、他のインデックスはこのリストにあるインデックスはそうではありません。
metric_conflicts_indices
[プレビュー] この機能は技術プレビュー中であり、将来のリリースで変更または削除される可能性があります。Elasticは問題を修正するために取り組みますが、技術プレビューの機能は公式GA機能のサポートSLAの対象ではありません。このフィールドが存在するインデックスのリスト、これらのインデックスがこのフィールドの同じtime_series_metric値を持たない場合。
meta
すべてのインデックスにわたるマージされたメタデータを文字列キーと値の配列のマップとして示します。値の長さが1の場合、すべてのインデックスがこのキーの同じ値を持っていたことを示し、長さが2以上の場合は、すべてのインデックスがこのキーの同じ値を持っていなかったことを示します。

例

リクエストは特定のデータストリームとインデックスに制限できます：

Python

resp = client.field_caps(
   index="my-index-000001",
   fields="rating",
)
print(resp)

Ruby

response = client.field_caps(
  index: 'my-index-000001',
  fields: 'rating'
)
puts response

Js

const response = await client.fieldCaps({
  index: "my-index-000001",
  fields: "rating",
});
console.log(response);

コンソール

GET my-index-000001/_field_caps?fields=rating

次の例API呼び出しは、ratingおよびtitleフィールドに関する情報を要求します：

Python

resp = client.field_caps(
   fields="rating,title",
)
print(resp)

Ruby

response = client.field_caps(
  fields: 'rating,title'
)
puts response

Js

const response = await client.fieldCaps({
  fields: "rating,title",
});
console.log(response);

コンソール

GET _field_caps?fields=rating,title

APIは次のレスポンスを返します：

コンソール-結果

{
  "indices": [ "index1", "index2", "index3", "index4", "index5" ],
  "fields": {
   "rating": {
   "long": {
   "metadata_field": false,
   "searchable": true,
   "aggregatable": false,
   "indices": [ "index1", "index2" ],
   "non_aggregatable_indices": [ "index1" ]
   },
   "keyword": {
   "metadata_field": false,
   "searchable": false,
   "aggregatable": true,
   "indices": [ "index3", "index4" ],
   "non_searchable_indices": [ "index4" ]
   }
   },
   "title": {
   "text": {
   "metadata_field": false,
   "searchable": true,
   "aggregatable": false
   }
   }
  }
}


	フィールド`rating`は`index1`および`index2`でlongとして定義されており、 `keyword`として`index3`および`index4`で定義されています。
	フィールド`rating`は`index1`で集約可能ではありません。
	フィールド`rating`は`index4`で検索可能ではありません。
	フィールド`title`はすべてのインデックスで`text`として定義されています。

デフォルトでは、未マッピングフィールドは無視されます。リクエストにinclude_unmappedというパラメータを追加することで、応答に含めることができます：

Python

resp = client.field_caps(
   fields="rating,title",
   include_unmapped=True,
)
print(resp)

Ruby

response = client.field_caps(
  fields: 'rating,title',
  include_unmapped: true
)
puts response

Js

const response = await client.fieldCaps({
  fields: "rating,title",
  include_unmapped: "true",
});
console.log(response);

コンソール

GET _field_caps?fields=rating,title&include_unmapped

この場合、応答には一部のインデックスに存在するがすべてのインデックスには存在しない各フィールドのエントリが含まれます：

コンソール-結果

{
  "indices": [ "index1", "index2", "index3" ],
  "fields": {
   "rating": {
   "long": {
   "metadata_field": false,
   "searchable": true,
   "aggregatable": false,
   "indices": [ "index1", "index2" ],
   "non_aggregatable_indices": [ "index1" ]
   },
   "keyword": {
   "metadata_field": false,
   "searchable": false,
   "aggregatable": true,
   "indices": [ "index3", "index4" ],
   "non_searchable_indices": [ "index4" ]
   },
   "unmapped": {
   "metadata_field": false,
   "indices": [ "index5" ],
   "searchable": false,
   "aggregatable": false
   }
   },
   "title": {
   "text": {
   "metadata_field": false,
   "indices": [ "index1", "index2", "index3", "index4" ],
   "searchable": true,
   "aggregatable": false
   },
   "unmapped": {
   "metadata_field": false,
   "indices": [ "index5" ],
   "searchable": false,
   "aggregatable": false
   }
   }
  }
}


	フィールド`rating`は`index5`で未マッピングです。
	フィールド`title`は`index5`で未マッピングです。

クエリでインデックスをフィルタリングすることも可能です：

Python

resp = client.field_caps(
   index="my-index-*",
   fields="rating",
   index_filter={
   "range": {
   "@timestamp": {
   "gte": "2018"
   }
   }
   },
)
print(resp)

Ruby

response = client.field_caps(
  index: 'my-index-*',
  fields: 'rating',
  body: {
   index_filter: {
   range: {
   "@timestamp": {
   gte: '2018'
   }
   }
   }
  }
)
puts response

Js

const response = await client.fieldCaps({
  index: "my-index-*",
  fields: "rating",
  index_filter: {
   range: {
   "@timestamp": {
   gte: "2018",
   },
   },
  },
});
console.log(response);

コンソール

POST my-index-*/_field_caps?fields=rating
{
  "index_filter": {
   "range": {
   "@timestamp": {
   "gte": "2018"
   }
   }
  }
}

この場合、提供されたフィルターをmatch_noneに書き換えるインデックスは、応答からフィルタリングされます。

フィルタリングは最善の努力に基づいて行われ、インデックス統計とマッピングを使用して、リクエストを完全に実行するのではなく、match_noneにクエリを書き換えます。たとえば、rangeクエリがdateフィールドに対してmatch_noneに書き換えられる場合、すべてのドキュメントが提供された範囲の外にある場合（削除されたドキュメントを含む）。ただし、すべてのクエリがmatch_noneに書き換えられるわけではないため、このAPIは提供されたフィルターがドキュメントに一致しない場合でもインデックスを返す可能性があります。