Skip to content

Commit 12fbdc5

Browse files
opensearch-trigger-bot[bot]opensearch-trigger-bot[bot]
authored
adding field_caps api docs (#10272) (#10315)
1 parent c60f590 commit 12fbdc5

File tree

1 file changed

+198
-0
lines changed

1 file changed

+198
-0
lines changed

‎_api-reference/search-apis/field-caps.md

Lines changed: 198 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,198 @@
1+
---
2+
layout: default
3+
title: Field capabilities
4+
parent: Search APIs
5+
nav_order: 45
6+
---
7+
8+
# Field capabilities API
9+
10+
The `_field_caps` API provides information about the capabilities of fields across one or more indexes. It is typically used by clients to determine how fields are mapped and whether they can be used for search, sorting, and aggregations across multiple indexes.
11+
12+
This API is particularly useful when indexes have varying mappings and a query needs to evaluate field compatibility across them.
13+
14+
## Endpoints
15+
16+
```json
17+
GET /_field_caps
18+
POST /_field_caps
19+
GET /{index}/_field_caps
20+
POST /{index}/_field_caps
21+
```
22+
23+
## Path parameters
24+
25+
The following table lists the available path parameters.
26+
27+
| Parameter | Data type | Description |
28+
| :--- | :--- | :--- |
29+
| `index` | List or String | A comma-separated list of data streams, indexes, and aliases used to limit the request. Supports wildcards (*). To target all data streams and indexes, omit this parameter or use * or `_all`. _Optional_. |
30+
31+
## Query parameters
32+
33+
The following table lists the available query parameters. All query parameters are optional.
34+
35+
| Parameter | Data type | Description |
36+
| :--- | :--- | :--- |
37+
| `allow_no_indices` | Boolean | If `false`, the request returns an error if any wildcard expression, index alias, or `_all` value targets only missing or closed indexes. This behavior applies even if the request targets other open indexes. For example, a request targeting `foo*,bar*` returns an error if an index starts with foo but no index starts with bar. Default is `true`. |
38+
| `expand_wildcards` | List or String | The type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. Supports comma-separated values, such as `open,hidden`. <br> Valid values are: <br> - `all`: Match any index, including hidden ones. <br> - `closed`: Match closed, non-hidden indexes. <br> - `hidden`: Match hidden indexes. Must be combined with `open`, `closed`, or both. <br> - `none`: Wildcard expressions are not accepted. <br> - `open`: Match open, non-hidden indexes. <br> Default is `open`. |
39+
| `fields` | List or String | A comma-separated list of fields to retrieve capabilities for. Wildcard (`*`) expressions are supported. |
40+
| `ignore_unavailable` | Boolean | If `true`, missing or closed indexes are not included in the response. Default is `false`. |
41+
| `include_unmapped` | Boolean | If `true`, unmapped fields are included in the response. Default is `false`. |
42+
43+
## Request body fields
44+
45+
The following table lists the available request body fields.
46+
47+
| Field | Data type | Description |
48+
| :------------- | :-------- | :---------------------------------------------------------------------- |
49+
| `index_filter` | Object | A query DSL object used to filter indexes included in the request. See [Example: Using an index filter](#example-using-an-index-filter). _Optional_.|
50+
51+
## Example
52+
53+
Create two indexes with different mappings for the same field:
54+
55+
```json
56+
PUT /store-west
57+
{
58+
"mappings": {
59+
"properties": {
60+
"product": { "type": "text" },
61+
"price": { "type": "float" }
62+
}
63+
}
64+
}
65+
```
66+
{% include copy-curl.html %}
67+
68+
```json
69+
PUT /store-east
70+
{
71+
"mappings": {
72+
"properties": {
73+
"product": { "type": "keyword" },
74+
"price": { "type": "float" }
75+
}
76+
}
77+
}
78+
```
79+
{% include copy-curl.html %}
80+
81+
Query field capabilities across both indexes:
82+
83+
```json
84+
GET /store-west,store-east/_field_caps?fields=product,price
85+
```
86+
{% include copy-curl.html %}
87+
88+
### Example response
89+
90+
The response provides the capabilities of the available fields:
91+
92+
```json
93+
{
94+
"indices": [
95+
"store-east",
96+
"store-west"
97+
],
98+
"fields": {
99+
"product": {
100+
"text": {
101+
"type": "text",
102+
"searchable": true,
103+
"aggregatable": false,
104+
"indices": [
105+
"store-west"
106+
]
107+
},
108+
"keyword": {
109+
"type": "keyword",
110+
"searchable": true,
111+
"aggregatable": true,
112+
"indices": [
113+
"store-east"
114+
]
115+
}
116+
},
117+
"price": {
118+
"float": {
119+
"type": "float",
120+
"searchable": true,
121+
"aggregatable": true
122+
}
123+
}
124+
}
125+
}
126+
```
127+
128+
## Example: Using an index filter
129+
130+
You can restrict the indexes considered using an `index_filter`. The `index_filter` filters out indexes based on field-level metadata, not actual document content. The following request limits the index selection to those that contain mappings containing a `product` field, even if there are no documents indexed:
131+
132+
```json
133+
POST /_field_caps?fields=product,price
134+
{
135+
"index_filter": {
136+
"term": {
137+
"product": "notebook"
138+
}
139+
}
140+
}
141+
```
142+
{% include copy-curl.html %}
143+
144+
### Example response
145+
146+
The response only includes the field from indexes that contain a `product` field with a value of `notebook`:
147+
148+
```json
149+
{
150+
"indices": [
151+
"store-east",
152+
"store-west"
153+
],
154+
"fields": {
155+
"product": {
156+
"text": {
157+
"type": "text",
158+
"searchable": true,
159+
"aggregatable": false,
160+
"indices": [
161+
"store-west"
162+
]
163+
},
164+
"keyword": {
165+
"type": "keyword",
166+
"searchable": true,
167+
"aggregatable": true,
168+
"indices": [
169+
"store-east"
170+
]
171+
}
172+
},
173+
"price": {
174+
"float": {
175+
"type": "float",
176+
"searchable": true,
177+
"aggregatable": true
178+
}
179+
}
180+
}
181+
}
182+
```
183+
184+
### Response body fields
185+
186+
The following table lists all response body fields.
187+
188+
| Field | Data type | Description |
189+
| :----------------------------------------------- | :----------- | :----------------------------------------------------------------------------------------------------------------------- |
190+
| `indices` | List | The list of indexes included in the response. |
191+
| `fields` | Object | A map of types to field capabilities, where each key is a field name and its value is an object. |
192+
| `fields.<field>.<type>.type` | String | The data type of the field (for example, `float`, `text`, `keyword`). |
193+
| `fields.<field>.<type>.searchable` | Boolean | Whether the field is indexed and searchable. |
194+
| `fields.<field>.<type>.aggregatable` | Boolean | Whether the field can be used in aggregations like `sum` or `terms`. |
195+
| `fields.<field>.<type>.indices` | List | A list of indexes in which this field appears with the corresponding type. |
196+
| `fields.<field>.<type>.non_searchable_indices` | List or null | A list of indexes in which the field is *not* searchable. `null` means that the field is not searchable in any index. |
197+
| `fields.<field>.<type>.non_aggregatable_indices` | List or null | A list of indexes in which the field is *not* aggregatable. `null` means that the field is not aggregatable in any index. |
198+
| `fields.<field>.<type>.meta` | Object | Merged metadata values from all mappings. Keys are custom metadata keys, and values are arrays of values across indexes. |

0 commit comments

Comments
 (0)