82 lines
3.6 KiB
Plaintext
82 lines
3.6 KiB
Plaintext
|
[[java-rest-high-field-caps]]
|
||
|
|
=== Field Capabilities API
|
||
|
|
|
||
|
|
The field capabilities API allows for retrieving the capabilities of fields across multiple indices.
|
||
|
|
|
||
|
|
[[java-rest-high-field-caps-request]]
|
||
|
|
==== Field Capabilities Request
|
||
|
|
|
||
|
|
A `FieldCapabilitiesRequest` contains a list of fields to get capabilities for,
|
||
|
|
should be returned, plus an optional list of target indices. If no indices
|
||
|
|
are provided, the request will be executed on all indices.
|
||
|
|
|
||
|
|
Note that fields parameter supports wildcard notation. For example, providing `text_*`
|
||
|
|
will cause all fields that match the expression to be returned.
|
||
|
|
|
||
|
|
["source","java",subs="attributes,callouts,macros"]
|
||
|
|
--------------------------------------------------
|
||
|
|
include-tagged::{doc-tests}/SearchDocumentationIT.java[field-caps-request]
|
||
|
|
--------------------------------------------------
|
||
|
|
|
||
|
|
[[java-rest-high-field-caps-request-optional]]
|
||
|
|
===== Optional arguments
|
||
|
|
|
||
|
|
["source","java",subs="attributes,callouts,macros"]
|
||
|
|
--------------------------------------------------
|
||
|
|
include-tagged::{doc-tests}/SearchDocumentationIT.java[field-caps-request-indicesOptions]
|
||
|
|
--------------------------------------------------
|
||
|
|
<1> Setting `IndicesOptions` controls how unavailable indices are resolved and
|
||
|
|
how wildcard expressions are expanded.
|
||
|
|
|
||
|
|
[[java-rest-high-field-caps-sync]]
|
||
|
|
==== Synchronous Execution
|
||
|
|
|
||
|
|
The `fieldCaps` method executes the request synchronously:
|
||
|
|
|
||
|
|
["source","java",subs="attributes,callouts,macros"]
|
||
|
|
--------------------------------------------------
|
||
|
|
include-tagged::{doc-tests}/SearchDocumentationIT.java[field-caps-execute]
|
||
|
|
--------------------------------------------------
|
||
|
|
|
||
|
|
[[java-rest-high-field-caps-async]]
|
||
|
|
==== Asynchronous Execution
|
||
|
|
|
||
|
|
The `fieldCapsAsync` method executes the request asynchronously,
|
||
|
|
calling the provided `ActionListener` when the response is ready:
|
||
|
|
|
||
|
|
["source","java",subs="attributes,callouts,macros"]
|
||
|
|
--------------------------------------------------
|
||
|
|
include-tagged::{doc-tests}/SearchDocumentationIT.java[field-caps-execute-async]
|
||
|
|
--------------------------------------------------
|
||
|
|
<1> The `FieldCapabilitiesRequest` to execute and the `ActionListener` to use when
|
||
|
|
the execution completes.
|
||
|
|
|
||
|
|
The asynchronous method does not block and returns immediately. Once the request
|
||
|
|
completes, the `ActionListener` is called back using the `onResponse` method
|
||
|
|
if the execution successfully completed or using the `onFailure` method if
|
||
|
|
it failed.
|
||
|
|
|
||
|
|
A typical listener for `FieldCapabilitiesResponse` is constructed as follows:
|
||
|
|
|
||
|
|
["source","java",subs="attributes,callouts,macros"]
|
||
|
|
--------------------------------------------------
|
||
|
|
include-tagged::{doc-tests}/SearchDocumentationIT.java[field-caps-execute-listener]
|
||
|
|
--------------------------------------------------
|
||
|
|
<1> Called when the execution is successfully completed.
|
||
|
|
<2> Called when the whole `FieldCapabilitiesRequest` fails.
|
||
|
|
|
||
|
|
[[java-rest-high-field-caps-response]]
|
||
|
|
==== FieldCapabilitiesResponse
|
||
|
|
|
||
|
|
For each requested field, the returned `FieldCapabilitiesResponse` contains its type
|
||
|
|
and whether or not it can be searched or aggregated on. The response also gives
|
||
|
|
information about how each index contributes to the field's capabilities.
|
||
|
|
|
||
|
|
["source","java",subs="attributes,callouts,macros"]
|
||
|
|
--------------------------------------------------
|
||
|
|
include-tagged::{doc-tests}/SearchDocumentationIT.java[field-caps-response]
|
||
|
|
--------------------------------------------------
|
||
|
|
<1> The `user` field has two possible types, `keyword` and `text`.
|
||
|
|
<2> This field only has type `keyword` in the `authors` and `contributors` indices.
|
||
|
|
<3> Null, since the field is searchable in all indices for which it has the `keyword` type.
|
||
|
|
<4> The `user` field is not aggregatable in the `authors` index.
|