You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: _field-types/mapping-parameters/doc-values.md
+2Lines changed: 2 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -21,6 +21,8 @@ Option | Description
21
21
22
22
The `doc_values` parameter is not supported for use in text fields.
23
23
24
+
For more information on using `doc_values` with the `index` parameter, see [The `index` and `doc_values` parameters compared]({{site.url}}{{site.baseurl}}/field-types/mapping-parameters/index-parameter/#the-index-and-doc-values-parameters-compared).
25
+
24
26
---
25
27
26
28
## Example: Creating an index with `doc_values` enabled and disabled
Copy file name to clipboardExpand all lines: _field-types/mapping-parameters/index-parameter.md
+77-8Lines changed: 77 additions & 8 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -10,10 +10,25 @@ has_toc: false
10
10
11
11
# Index
12
12
13
-
The `index` mapping parameter controls whether a field is searchable by including it in the inverted index. When set to `true`, the field is indexed and available for queries. When set to `false`, the field is stored in the document but not indexed, making it non-searchable. If you do not need to search a particular field, disabling indexing for that field can reduce index size and improve indexing performance. For example, you can disable indexing on large text fields or metadata that is only used for display.
13
+
The `index` mapping parameter controls whether a field is included in the inverted index. When set to `true`, the field is indexed and available for queries. When set to `false`, the field is stored in the document but not indexed, making it non-searchable when [`doc_values`]({{site.url}}{{site.baseurl}}/field-types/mapping-parameters/doc-values/) are not enabled. If you do not need to search a particular field, disabling indexing and `doc_values` for that field can reduce index size and improve indexing performance. For example, you can disable indexing on large text fields or metadata that is only used for display.
14
14
15
15
By default, all field types are indexed.
16
16
17
+
## The index and doc values parameters compared
18
+
19
+
When you enable the `index` parameter, OpenSearch creates a mapping of terms to the documents that contain them. For each new document, the values of the indexed fields are broken into terms, and each term is linked to the document ID in the mapping.
20
+
21
+
When you enable the `doc_values` parameter, OpenSearch creates a reverse mapping: each document is linked to the list of terms found in that field. This is useful for operations like sorting, where the system needs fast access to a document's field values.
22
+
23
+
The following table illustrates the field behavior depending on the combination of `index` and `doc_values`.
24
+
25
+
| `index` parameter value | `doc_values` parameter value | Behavior | Use case
26
+
| :-- | :-- | :-- | :-- |
27
+
|`true`|`true`| The field is searchable and supports sorting, scripting, and aggregations. | Use for any field you want to query directly and perform complex operations on. |
28
+
|`true`|`false`| The field is searchable but does not support document-to-term lookup (thus, sorting, scripting, and aggregations take longer). | Use for fields you want to query but don't need for sorting or aggregations, such as `text` fields. |
29
+
|`false`|`true`| The field is searchable (although not as efficiently) and supports sorting, scripting, and aggregations. Note that not all field types support `doc_values` (for example, `text` fields do not support `doc_values`). | Use for fields that you want to aggregate on but not filter or query. |
30
+
|`false`|`false`| The field is not searchable. Queries that attempt to search the field return an error. | Use for fields on which you do not want to perform any operations, such as metadata fields. |
31
+
17
32
## Supported data types
18
33
19
34
The `index` mapping parameter can be applied to the following data types:
@@ -27,7 +42,7 @@ The `index` mapping parameter can be applied to the following data types:
27
42
28
43
## Enabling indexing on a field
29
44
30
-
The following request creates an index named `products` with a `description`field that is indexed (the default behavior):
45
+
The following request creates an index named `products` with `description`and `name` fields that are indexed (the default behavior):
31
46
32
47
```json
33
48
PUT /products
@@ -36,6 +51,9 @@ PUT /products
36
51
"properties": {
37
52
"description": {
38
53
"type": "text"
54
+
},
55
+
"name": {
56
+
"type": "keyword"
39
57
}
40
58
}
41
59
}
@@ -48,7 +66,8 @@ Index a document using the following request:
48
66
```json
49
67
PUT /products/_doc/1
50
68
{
51
-
"description": "This product has a searchable description."
69
+
"description": "This product has a searchable description.",
70
+
"name": "doc1"
52
71
}
53
72
```
54
73
{% include copy-curl.html %}
@@ -77,14 +96,15 @@ The following response confirms that the indexed document was successfully match
77
96
"value": 1,
78
97
"relation": "eq"
79
98
},
80
-
"max_score": 0.2876821,
99
+
"max_score": 0.13076457,
81
100
"hits": [
82
101
{
83
102
"_index": "products",
84
103
"_id": "1",
85
-
"_score": 0.2876821,
104
+
"_score": 0.13076457,
86
105
"_source": {
87
-
"description": "This product has a searchable description."
106
+
"description": "This product has a searchable description.",
107
+
"name": "doc1"
88
108
}
89
109
}
90
110
]
@@ -94,7 +114,7 @@ The following response confirms that the indexed document was successfully match
94
114
95
115
## Disabling indexing on a field
96
116
97
-
Create an index named `products-no-index` with a `description` field that is not indexed:
117
+
Create an index named `products-no-index` with a `description` field and a `name` field that are not indexed:
98
118
99
119
```json
100
120
PUT /products-no-index
@@ -104,6 +124,10 @@ PUT /products-no-index
104
124
"description": {
105
125
"type": "text",
106
126
"index": false
127
+
},
128
+
"name": {
129
+
"type": "keyword",
130
+
"index": false
107
131
}
108
132
}
109
133
}
@@ -116,7 +140,8 @@ Index a document using the following request:
116
140
```json
117
141
PUT /products-no-index/_doc/1
118
142
{
119
-
"description": "This product has a non-searchable description."
143
+
"description": "This product has a non-searchable description.",
144
+
"name": "doc1"
120
145
}
121
146
```
122
147
{% include copy-curl.html %}
@@ -173,3 +198,47 @@ The following error response indicates that the search query failed because the
173
198
"status": 400
174
199
}
175
200
```
201
+
202
+
For `text` fields, setting the `index` parameter to `false` disables search on the field because `text` fields do not support `doc_values`. To make other fields not searchable, you must additionally set `doc_values` to `false`.
203
+
204
+
Query `products-no-index` using the `name` field:
205
+
206
+
```json
207
+
POST /products-no-index/_search
208
+
{
209
+
"query": {
210
+
"term": {
211
+
"name": {
212
+
"value": "doc1"
213
+
}
214
+
}
215
+
}
216
+
}
217
+
```
218
+
{% include copy-curl.html %}
219
+
220
+
The following response confirms that the search query succeeded because the `name` field, though not indexed, has `doc_values` enabled:
221
+
222
+
```json
223
+
{
224
+
...
225
+
"hits": {
226
+
"total": {
227
+
"value": 1,
228
+
"relation": "eq"
229
+
},
230
+
"max_score": 1.0,
231
+
"hits": [
232
+
{
233
+
"_index": "products-no-index",
234
+
"_id": "1",
235
+
"_score": 1.0,
236
+
"_source": {
237
+
"description": "This product has a non-searchable description.",
0 commit comments