[DOCS] Reformats Field capabilities API (#46866)
* [DOCS] Reformats Field capabilities API. Co-Authored-By: James Rodewig <james.rodewig@elastic.co>
This commit is contained in:
István Zoltán Szabó
parent
363075cf1d
commit
fcea154f2e
|
|
@ -1,16 +1,89 @@
|
|||
[[search-field-caps]]
|
||||
=== Field Capabilities API
|
||||
|
||||
The field capabilities API allows to retrieve the capabilities of fields among multiple indices.
|
||||
|
||||
The field capabilities API by default executes on all indices:
|
||||
Allows you to retrieve the capabilities of fields among multiple indices.
|
||||
|
||||
[source,console]
|
||||
--------------------------------------------------
|
||||
GET _field_caps?fields=rating
|
||||
GET /_field_caps?fields=rating
|
||||
--------------------------------------------------
|
||||
|
||||
The request can also be restricted to specific indices:
|
||||
|
||||
[[search-field-caps-api-request]]
|
||||
==== {api-request-title}
|
||||
|
||||
`GET /_field_caps`
|
||||
|
||||
`POST /_field_caps`
|
||||
|
||||
`GET /<index>/_field_caps`
|
||||
|
||||
`POST /<index>/_field_caps`
|
||||
|
||||
|
||||
[[search-field-caps-api-desc]]
|
||||
==== {api-description-title}
|
||||
|
||||
|
||||
The field capabilities API returns the information about the capabilities of
|
||||
fields among multiple indices.
|
||||
|
||||
|
||||
[[search-field-caps-api-path-params]]
|
||||
==== {api-path-parms-title}
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=index]
|
||||
|
||||
|
||||
[[search-field-caps-api-query-params]]
|
||||
==== {api-query-parms-title}
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=allow-no-indices]
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=expand-wildcards]
|
||||
+
|
||||
--
|
||||
Defaults to `open`.
|
||||
--
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=fields]
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=index-ignore-unavailable]
|
||||
|
||||
`include_unmapped`::
|
||||
(Optional, boolean) If `true`, unmapped fields are included in the response.
|
||||
Defaults to `false`.
|
||||
|
||||
|
||||
[[search-field-caps-api-response-body]]
|
||||
==== {api-response-body-title}
|
||||
|
||||
|
||||
|
||||
`searchable`::
|
||||
Whether this field is indexed for search on all indices.
|
||||
|
||||
`aggregatable`::
|
||||
Whether this field can be aggregated on all indices.
|
||||
|
||||
`indices`::
|
||||
The list of indices where this field has the same type, or null if all indices
|
||||
have the same type for the field.
|
||||
|
||||
`non_searchable_indices`::
|
||||
The list of indices where this field is not searchable, or null if all indices
|
||||
have the same definition for the field.
|
||||
|
||||
`non_aggregatable_indices`::
|
||||
The list of indices where this field is not aggregatable, or null if all
|
||||
indices have the same definition for the field.
|
||||
|
||||
|
||||
[[search-field-caps-api-example]]
|
||||
==== {api-examples-title}
|
||||
|
||||
|
||||
The request can be restricted to specific indices:
|
||||
|
||||
[source,console]
|
||||
--------------------------------------------------
|
||||
|
|
@ -18,53 +91,18 @@ GET twitter/_field_caps?fields=rating
|
|||
--------------------------------------------------
|
||||
// TEST[setup:twitter]
|
||||
|
||||
Supported request options:
|
||||
|
||||
[horizontal]
|
||||
`fields`:: A list of fields to compute stats for. The field name supports wildcard notation. For example, using `text_*`
|
||||
will cause all fields that match the expression to be returned.
|
||||
|
||||
[float]
|
||||
==== Field Capabilities
|
||||
|
||||
The field capabilities API returns the following information per field:
|
||||
|
||||
[horizontal]
|
||||
`searchable`::
|
||||
|
||||
Whether this field is indexed for search on all indices.
|
||||
|
||||
`aggregatable`::
|
||||
|
||||
Whether this field can be aggregated on all indices.
|
||||
|
||||
`indices`::
|
||||
|
||||
The list of indices where this field has the same type,
|
||||
or null if all indices have the same type for the field.
|
||||
|
||||
`non_searchable_indices`::
|
||||
|
||||
The list of indices where this field is not searchable,
|
||||
or null if all indices have the same definition for the field.
|
||||
|
||||
`non_aggregatable_indices`::
|
||||
|
||||
The list of indices where this field is not aggregatable,
|
||||
or null if all indices have the same definition for the field.
|
||||
|
||||
|
||||
[float]
|
||||
==== Response format
|
||||
|
||||
Request:
|
||||
The next example API call requests information about the `rating` and the
|
||||
`title` fields:
|
||||
|
||||
[source,console]
|
||||
--------------------------------------------------
|
||||
GET _field_caps?fields=rating,title
|
||||
--------------------------------------------------
|
||||
|
||||
[source,js]
|
||||
The API returns the following response:
|
||||
|
||||
[source,console-result]
|
||||
--------------------------------------------------
|
||||
{
|
||||
"indices": ["index1", "index2", "index3", "index4", "index5"],
|
||||
|
|
@ -93,7 +131,7 @@ GET _field_caps?fields=rating,title
|
|||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
// NOTCONSOLE
|
||||
// TESTRESPONSE[skip:historically skipped]
|
||||
|
||||
<1> The field `rating` is defined as a long in `index1` and `index2`
|
||||
and as a `keyword` in `index3` and `index4`.
|
||||
|
|
@ -101,8 +139,6 @@ and as a `keyword` in `index3` and `index4`.
|
|||
<3> The field `rating` is not searchable in `index4`.
|
||||
<4> The field `title` is defined as `text` in all indices.
|
||||
|
||||
[float]
|
||||
==== Unmapped fields
|
||||
|
||||
By default unmapped fields are ignored. You can include them in the response by
|
||||
adding a parameter called `include_unmapped` in the request:
|
||||
|
|
@ -112,10 +148,10 @@ adding a parameter called `include_unmapped` in the request:
|
|||
GET _field_caps?fields=rating,title&include_unmapped
|
||||
--------------------------------------------------
|
||||
|
||||
In which case the response will contain an entry for each field that is present in
|
||||
some indices but not all:
|
||||
In which case the response will contain an entry for each field that is present
|
||||
in some indices but not all:
|
||||
|
||||
[source,js]
|
||||
[source,console-result]
|
||||
--------------------------------------------------
|
||||
{
|
||||
"indices": ["index1", "index2", "index3"],
|
||||
|
|
@ -154,7 +190,7 @@ some indices but not all:
|
|||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
// NOTCONSOLE
|
||||
// TESTRESPONSE[skip:historically skipped]
|
||||
|
||||
<1> The `rating` field is unmapped` in `index5`.
|
||||
<2> The `title` field is unmapped` in `index5`.
|
||||
|
|
|
|||
Loading…
Reference in New Issue