Added supported field types (#712)
* Added supported field types Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> * Added geo shape and cleaned up other files Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> * Fixed a typo Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> * Fixed typo Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> * Implemented reviewer changes Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> * Added a section for null value Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> * Implemented editorial comments Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> Signed-off-by: Fanit Kolchina <kolchfa@amazon.com>
This commit is contained in:
kolchfa-aws
GitHub
parent
98c3ecd7fc
commit
29d719a461
|
|
@ -0,0 +1,89 @@
|
|||
---
|
||||
layout: default
|
||||
title: Alias
|
||||
nav_order: 10
|
||||
has_children: false
|
||||
parent: Supported field types
|
||||
---
|
||||
|
||||
# Alias field type
|
||||
|
||||
An alias field type creates another name for an existing field. You can use aliases in the[search](#using-aliases-in-search-api-operations) and [field capabilities](#using-aliases-in-field-capabilities-api-operations) API operations, with some [exceptions](#exceptions). To set up an [alias](#alias-field), you need to specify the [original field](#original-field) name in the `path` parameter.
|
||||
|
||||
## Example
|
||||
|
||||
```json
|
||||
PUT movies
|
||||
{
|
||||
"mappings" : {
|
||||
"properties" : {
|
||||
"year" : {
|
||||
"type" : "date"
|
||||
},
|
||||
"release_date" : {
|
||||
"type" : "alias",
|
||||
"path" : "year"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Parameters
|
||||
|
||||
Parameter | Description
|
||||
:--- | :---
|
||||
`path` | The full path to the original field, including all parent objects. For example, parent.child.field_name. Required.
|
||||
|
||||
## Alias field
|
||||
|
||||
Alias fields must obey the following rules:
|
||||
|
||||
- An alias field can only have one original field.
|
||||
- In nested objects, the alias must have the same nesting level as the original field.
|
||||
|
||||
To change the field that the alias references, update the mappings. Note that aliases in any previously stored percolator queries will still reference the original field.
|
||||
{: .note }
|
||||
|
||||
## Original field
|
||||
|
||||
The original field for an alias must obey the following rules:
|
||||
- The original field must be created before the alias is created.
|
||||
- The original field cannot be an object or another alias.
|
||||
|
||||
## Using aliases in search API operations
|
||||
|
||||
You can use aliases in the following read operations of the search API:
|
||||
- Queries
|
||||
- Sorts
|
||||
- Aggregations
|
||||
- `stored_fields`
|
||||
- `docvalue_fields`
|
||||
- Suggestions
|
||||
- Highlights
|
||||
- Scripts that access field values
|
||||
|
||||
## Using aliases in field capabilities API operations
|
||||
|
||||
To use an alias in the field capabilities API, specify it in the fields parameter.
|
||||
|
||||
```json
|
||||
GET movies/_field_caps?fields=release_date
|
||||
```
|
||||
|
||||
## Exceptions
|
||||
|
||||
You cannot use aliases in the following situations:
|
||||
- In write requests, such as update requests.
|
||||
- In multi-fields or as a target of `copy_to`.
|
||||
- As a _source parameter for filtering results.
|
||||
- In APIs that take field names, such as term vectors.
|
||||
- In `terms`, `more_like_this`, and `geo_shape` queries (aliases are not supported when retrieving documents).
|
||||
|
||||
## Wildcards
|
||||
|
||||
In search and field capabilities wildcard queries, both the original field and the alias are matched against the wildcard pattern.
|
||||
|
||||
```json
|
||||
GET movies/_field_caps?fields=release*
|
||||
```
|
||||
|
|
@ -0,0 +1,17 @@
|
|||
---
|
||||
layout: default
|
||||
title: Autocomplete field types
|
||||
nav_order: 50
|
||||
has_children: true
|
||||
has_toc: false
|
||||
parent: Supported field types
|
||||
---
|
||||
|
||||
# Autocomplete field types
|
||||
|
||||
The following table lists all autocomplete field types that OpenSearch supports.
|
||||
|
||||
Field data type | Description
|
||||
:--- | :---
|
||||
[`completion`]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/completion/) | A completion suggester that provides autocomplete functionality using prefix completion. You need to upload a list of all possible completions into the index before using this feature.
|
||||
[`search_as_you_type`]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/search-as-you-type/) | Provides search-as-you-type functionality using both prefix and infix completion.
|
||||
|
|
@ -0,0 +1,49 @@
|
|||
---
|
||||
layout: default
|
||||
title: Binary
|
||||
parent: Supported field types
|
||||
nav_order: 12
|
||||
has_children: false
|
||||
---
|
||||
|
||||
# Binary field type
|
||||
|
||||
A binary field type contains a binary value in [Base64](https://en.wikipedia.org/wiki/Base64) encoding that is not searchable.
|
||||
|
||||
## Example
|
||||
|
||||
Create a mapping with a binary field:
|
||||
|
||||
```json
|
||||
PUT testindex
|
||||
{
|
||||
"mappings" : {
|
||||
"properties" : {
|
||||
"binary_value" : {
|
||||
"type" : "binary"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Index a document with a binary value:
|
||||
|
||||
```json
|
||||
PUT testindex/_doc/1
|
||||
{
|
||||
"binary_value" : "bGlkaHQtd29rfx4="
|
||||
}
|
||||
```
|
||||
|
||||
Use `=` as a padding character. Embedded newline characters are not allowed.
|
||||
{: .note }
|
||||
|
||||
## Parameters
|
||||
|
||||
The following table lists the parameters accepted by binary field types. All parameters are optional.
|
||||
|
||||
Parameter | Description
|
||||
:--- | :---
|
||||
`doc_values` | A Boolean value that specifies whether the field should be stored on disk so that it can be used for aggregations, sorting, or scripting. Optional. Default is `false`.
|
||||
`store` | A Boolean value that specifies whether the field value should be stored and can be retrieved separately from the _source field. Optional. Default is `false`.
|
||||
|
|
@ -0,0 +1,150 @@
|
|||
---
|
||||
layout: default
|
||||
title: Boolean
|
||||
nav_order: 20
|
||||
has_children: false
|
||||
parent: Supported field types
|
||||
---
|
||||
|
||||
# Boolean field type
|
||||
|
||||
A Boolean field type takes `true` or `false` values, or `"true"` or `"false"` strings. You can also pass an empty string (`""`) in place of a `false` value.
|
||||
|
||||
## Example
|
||||
|
||||
Create a mapping where a, b, and c are Boolean fields:
|
||||
|
||||
```json
|
||||
PUT testindex
|
||||
{
|
||||
"mappings" : {
|
||||
"properties" : {
|
||||
"a" : {
|
||||
"type" : "boolean"
|
||||
},
|
||||
"b" : {
|
||||
"type" : "boolean"
|
||||
},
|
||||
"c" : {
|
||||
"type" : "boolean"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Index a document with Boolean values:
|
||||
|
||||
```json
|
||||
PUT testindex/_doc/1
|
||||
{
|
||||
"a" : true,
|
||||
"b" : "true",
|
||||
"c" : ""
|
||||
}
|
||||
```
|
||||
|
||||
As a result, `a` and `b` will be set to `true`, and `c` will be set to `false`.
|
||||
|
||||
Search for all documents where `c` is false:
|
||||
|
||||
```json
|
||||
GET testindex/_search
|
||||
{
|
||||
"query": {
|
||||
"term" : {
|
||||
"c" : false
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Parameters
|
||||
|
||||
The following table lists the parameters accepted by Boolean field types. All parameters are optional.
|
||||
|
||||
Parameter | Description
|
||||
:--- | :---
|
||||
`boost` | A floating-point value that specifies the weight of this field toward the relevance score. Values above 1.0 increase the field's relevance. Values between 0.0 and 1.0 decrease the field's relevance. Default is 1.0.
|
||||
`doc_values` | A Boolean value that specifies whether the field should be stored on disk so that it can be used for aggregations, sorting or scripting. Default is `false`.
|
||||
`index` | A Boolean value that specifies whether the field should be searchable. Default is `true`.
|
||||
`meta` | Accepts metadata for this field.
|
||||
[`null_value`]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/index#null-value) | A value to be used in place of `null`. Must be of the same type as the field. If this parameter is not specified, the field is treated as missing when its value is `null`. Default is `null`.
|
||||
`store` | A Boolean value that specifies whether the field value should be stored and can be retrieved separately from the _source field. Default is `false`.
|
||||
|
||||
## Boolean values in aggregations and scripts
|
||||
|
||||
In aggregations on Boolean fields, `key` returns numeric values (1 for `true` or 0 for `false`), and `key_as_string` returns strings (`"true"` or `"false"`). Scripts return `true` and `false` for Boolean values.
|
||||
|
||||
### Example
|
||||
|
||||
Run a terms aggregation query on the field `a`:
|
||||
|
||||
```json
|
||||
GET testindex/_search
|
||||
{
|
||||
"aggs": {
|
||||
"agg1": {
|
||||
"terms": {
|
||||
"field": "a"
|
||||
}
|
||||
}
|
||||
},
|
||||
"script_fields": {
|
||||
"a": {
|
||||
"script": {
|
||||
"lang": "painless",
|
||||
"source": "doc['a'].value"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The script returns the value of `a` as `true`, `key` returns the value of `a` as `1`, and `key_as_string` returns the value of `a` as `"true"`:
|
||||
|
||||
```json
|
||||
{
|
||||
"took" : 1133,
|
||||
"timed_out" : false,
|
||||
"_shards" : {
|
||||
"total" : 1,
|
||||
"successful" : 1,
|
||||
"skipped" : 0,
|
||||
"failed" : 0
|
||||
},
|
||||
"hits" : {
|
||||
"total" : {
|
||||
"value" : 1,
|
||||
"relation" : "eq"
|
||||
},
|
||||
"max_score" : 1.0,
|
||||
"hits" : [
|
||||
{
|
||||
"_index" : "testindex",
|
||||
"_type" : "_doc",
|
||||
"_id" : "1",
|
||||
"_score" : 1.0,
|
||||
"fields" : {
|
||||
"a" : [
|
||||
true
|
||||
]
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
"aggregations" : {
|
||||
"agg1" : {
|
||||
"doc_count_error_upper_bound" : 0,
|
||||
"sum_other_doc_count" : 0,
|
||||
"buckets" : [
|
||||
{
|
||||
"key" : 1,
|
||||
"key_as_string" : "true",
|
||||
"doc_count" : 1
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
|
@ -0,0 +1,381 @@
|
|||
---
|
||||
layout: default
|
||||
title: Completion
|
||||
nav_order: 51
|
||||
has_children: false
|
||||
parent: Autocomplete field types
|
||||
grand_parent: Supported field types
|
||||
---
|
||||
|
||||
# Completion field type
|
||||
|
||||
A completion field type provides autocomplete functionality through a completion suggester. The completion suggester is a prefix suggester, so it matches the beginning of text only. A completion suggester creates an in-memory data structure, which provides faster lookups but leads to increased memory usage. You need to upload a list of all possible completions into the index before using this feature.
|
||||
|
||||
## Example
|
||||
|
||||
Create a mapping with a completion field:
|
||||
|
||||
```json
|
||||
PUT chess_store
|
||||
{
|
||||
"mappings": {
|
||||
"properties": {
|
||||
"suggestions": {
|
||||
"type": "completion"
|
||||
},
|
||||
"product": {
|
||||
"type": "keyword"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Index suggestions into OpenSearch:
|
||||
|
||||
```json
|
||||
PUT chess_store/_doc/1
|
||||
{
|
||||
"suggestions": {
|
||||
"input": ["Books on openings", "Books on endgames"],
|
||||
"weight" : 10
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Parameters
|
||||
|
||||
The following table lists the parameters accepted by completion fields.
|
||||
|
||||
Parameter | Description
|
||||
:--- | :---
|
||||
`input` | A list of possible completions as a string or array of strings. Cannot contain `\u0000` (null), `\u001f` (information separator one), or `u001e` (information separator two). Required.
|
||||
`weight` | A positive integer or a positive integer string for ranking suggestions. Optional.
|
||||
|
||||
Multiple suggestions can be indexed as follows:
|
||||
|
||||
```json
|
||||
PUT chess_store/_doc/2
|
||||
{
|
||||
"suggestions": [
|
||||
{
|
||||
"input": "Chess set",
|
||||
"weight": 20
|
||||
},
|
||||
{
|
||||
"input": "Chess pieces",
|
||||
"weight": 10
|
||||
},
|
||||
{
|
||||
"input": "Chess board",
|
||||
"weight": 5
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
As an alternative, you can use the following shorthand notation (note that you cannot provide the `weight` parameter in this notation):
|
||||
|
||||
```json
|
||||
PUT chess_store/_doc/3
|
||||
{
|
||||
"suggestions" : [ "Chess clock", "Chess timer" ]
|
||||
}
|
||||
```
|
||||
|
||||
## Querying completion field types
|
||||
|
||||
To query completion field types, specify the prefix that you want to search for and the name of the field in which to look for suggestions.
|
||||
|
||||
Query the index for suggestions that start with the word "chess":
|
||||
|
||||
```json
|
||||
GET chess_store/_search
|
||||
{
|
||||
"suggest": {
|
||||
"product-suggestions": {
|
||||
"prefix": "chess",
|
||||
"completion": {
|
||||
"field": "suggestions"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The response contains autocomplete suggestions:
|
||||
|
||||
```json
|
||||
{
|
||||
"took" : 3,
|
||||
"timed_out" : false,
|
||||
"_shards" : {
|
||||
"total" : 1,
|
||||
"successful" : 1,
|
||||
"skipped" : 0,
|
||||
"failed" : 0
|
||||
},
|
||||
"hits" : {
|
||||
"total" : {
|
||||
"value" : 0,
|
||||
"relation" : "eq"
|
||||
},
|
||||
"max_score" : null,
|
||||
"hits" : [ ]
|
||||
},
|
||||
"suggest" : {
|
||||
"product-suggestions" : [
|
||||
{
|
||||
"text" : "chess",
|
||||
"offset" : 0,
|
||||
"length" : 5,
|
||||
"options" : [
|
||||
{
|
||||
"text" : "Chess set",
|
||||
"_index" : "chess_store",
|
||||
"_type" : "_doc",
|
||||
"_id" : "2",
|
||||
"_score" : 20.0,
|
||||
"_source" : {
|
||||
"suggestions" : [
|
||||
{
|
||||
"input" : "Chess set",
|
||||
"weight" : 20
|
||||
},
|
||||
{
|
||||
"input" : "Chess pieces",
|
||||
"weight" : 10
|
||||
},
|
||||
{
|
||||
"input" : "Chess board",
|
||||
"weight" : 5
|
||||
}
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"text" : "Chess clock",
|
||||
"_index" : "chess_store",
|
||||
"_type" : "_doc",
|
||||
"_id" : "3",
|
||||
"_score" : 1.0,
|
||||
"_source" : {
|
||||
"suggestions" : [
|
||||
"Chess clock",
|
||||
"Chess timer"
|
||||
]
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
In the response, the `_score` field contains the value of the `weight` parameter that was set up at index time. The `text` field is populated with the suggestion's `input` parameter.
|
||||
|
||||
By default, the response contains the whole document, including the `_source` field, which may impact performance. To return only the `suggestions` field, you can specify that in the `_source` parameter. You can also restrict the number of returned suggestions by specifying the `size` parameter.
|
||||
|
||||
```json
|
||||
GET chess_store/_search
|
||||
{
|
||||
"_source": "suggestions",
|
||||
"suggest": {
|
||||
"product-suggestions": {
|
||||
"prefix": "chess",
|
||||
"completion": {
|
||||
"field": "suggestions",
|
||||
"size" : 3
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The response contains the suggestions:
|
||||
|
||||
```json
|
||||
{
|
||||
"took" : 5,
|
||||
"timed_out" : false,
|
||||
"_shards" : {
|
||||
"total" : 1,
|
||||
"successful" : 1,
|
||||
"skipped" : 0,
|
||||
"failed" : 0
|
||||
},
|
||||
"hits" : {
|
||||
"total" : {
|
||||
"value" : 0,
|
||||
"relation" : "eq"
|
||||
},
|
||||
"max_score" : null,
|
||||
"hits" : [ ]
|
||||
},
|
||||
"suggest" : {
|
||||
"product-suggestions" : [
|
||||
{
|
||||
"text" : "chess",
|
||||
"offset" : 0,
|
||||
"length" : 5,
|
||||
"options" : [
|
||||
{
|
||||
"text" : "Chess set",
|
||||
"_index" : "chess_store",
|
||||
"_type" : "_doc",
|
||||
"_id" : "2",
|
||||
"_score" : 20.0,
|
||||
"_source" : {
|
||||
"suggestions" : [
|
||||
{
|
||||
"input" : "Chess set",
|
||||
"weight" : 20
|
||||
},
|
||||
{
|
||||
"input" : "Chess pieces",
|
||||
"weight" : 10
|
||||
},
|
||||
{
|
||||
"input" : "Chess board",
|
||||
"weight" : 5
|
||||
}
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"text" : "Chess clock",
|
||||
"_index" : "chess_store",
|
||||
"_type" : "_doc",
|
||||
"_id" : "3",
|
||||
"_score" : 1.0,
|
||||
"_source" : {
|
||||
"suggestions" : [
|
||||
"Chess clock",
|
||||
"Chess timer"
|
||||
]
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
To take advantage of source filtering, use the suggest functionality on the `_search` endpoint. The `_suggest` endpoint does not support source filtering.
|
||||
{: .note}
|
||||
|
||||
## Completion query parameters
|
||||
|
||||
The following table lists the parameters accepted by the completion suggester query.
|
||||
|
||||
Parameter | Description
|
||||
:--- | :---
|
||||
`field` | A string that specifies the field on which to run the query. Required.
|
||||
`size` | An integer that specifies the maximum number of returned suggestions. Optional. Default is 5.
|
||||
`skip_duplicates` | A Boolean value that specifies whether to skip duplicate suggestions. Optional. Default is `false`.
|
||||
|
||||
## Fuzzy completion query
|
||||
|
||||
To allow for fuzzy matching, you can specify the `fuzziness` parameter for the completion query. In this case, even if the user mistypes a search term, the completion query still returns results. Additionally, the longer the prefix that matches the query, the higher the document's score.
|
||||
|
||||
```json
|
||||
GET chess_store/_search
|
||||
{
|
||||
"suggest": {
|
||||
"product-suggestions": {
|
||||
"prefix": "chesc",
|
||||
"completion": {
|
||||
"field": "suggestions",
|
||||
"size" : 3,
|
||||
"fuzzy" : {
|
||||
"fuzziness" : "AUTO"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
To use all default fuzziness options, specify `"fuzzy": {}` or `"fuzzy": true`.
|
||||
{: .tip}
|
||||
|
||||
The following table lists the parameters accepted by the fuzzy completion suggester query. All of the parameters are optional.
|
||||
|
||||
Parameter | Description
|
||||
:--- | :---
|
||||
`fuzziness` | Fuzziness can be set as one of the following: <br> 1. An integer that specifies the maximum allowed [Levenshtein distance](https://en.wikipedia.org/wiki/Levenshtein_distance) for this edit. <br> 2. `AUTO`: Strings of 0–2 characters must match exactly, strings of 3–5 characters allow 1 edit, and strings longer than 5 characters allow 2 edits.<br> Default is `AUTO`.
|
||||
`min_length` | An integer that specifies the minimum length the input must be to start returning suggestions. If the search term is shorter than `min_length`, no suggestions are returned. Default is 3.
|
||||
`prefix_length` | An integer that specifies the minimum length the matched prefix must be to start returning suggestions. If the prefix of `prefix_length` is not matched, but the search term is still within the Levenshtein distance, no suggestions are returned. Default is 1.
|
||||
`transpositions` | A Boolean value that specifies to count transpositions (interchanges of adjacent characters) as one edit instead of two. Example: The suggestion's `input` parameter is `abcde` and the `fuzziness` is 1. If `transpositions` is set to `true`, `abdce` will match, but if `transpositions` is set to `false`, `abdce` will not match. Default is `true`.
|
||||
`unicode_aware` | A Boolean value that specifies whether to use Unicode code points when measuring the edit distance, transposition, and length. If `unicode_aware` is set to `true`, the measurement is slower. Default is `false`, in which case distances are measured in bytes.
|
||||
|
||||
## Regex queries
|
||||
|
||||
You can use a regular expression to define the prefix for the completion suggester query.
|
||||
|
||||
For example, to search for strings that start with "a" and have a "d" later on, use the following query:
|
||||
|
||||
```json
|
||||
GET chess_store/_search
|
||||
{
|
||||
"suggest": {
|
||||
"product-suggestions": {
|
||||
"regex": "a.*d",
|
||||
"completion": {
|
||||
"field": "suggestions"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The response matches the string "abcde":
|
||||
|
||||
```json
|
||||
{
|
||||
"took" : 2,
|
||||
"timed_out" : false,
|
||||
"_shards" : {
|
||||
"total" : 1,
|
||||
"successful" : 1,
|
||||
"skipped" : 0,
|
||||
"failed" : 0
|
||||
},
|
||||
"hits" : {
|
||||
"total" : {
|
||||
"value" : 0,
|
||||
"relation" : "eq"
|
||||
},
|
||||
"max_score" : null,
|
||||
"hits" : [ ]
|
||||
},
|
||||
"suggest" : {
|
||||
"product-suggestions" : [
|
||||
{
|
||||
"text" : "a.*d",
|
||||
"offset" : 0,
|
||||
"length" : 4,
|
||||
"options" : [
|
||||
{
|
||||
"text" : "abcde",
|
||||
"_index" : "chess_store",
|
||||
"_type" : "_doc",
|
||||
"_id" : "2",
|
||||
"_score" : 20.0,
|
||||
"_source" : {
|
||||
"suggestions" : [
|
||||
{
|
||||
"input" : "abcde",
|
||||
"weight" : 20
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
|
@ -0,0 +1,211 @@
|
|||
---
|
||||
layout: default
|
||||
title: Date
|
||||
nav_order: 25
|
||||
has_children: false
|
||||
parent: Supported field types
|
||||
---
|
||||
|
||||
# Date field type
|
||||
|
||||
A date in OpenSearch can be represented as one of the following:
|
||||
|
||||
- A long value that corresponds to milliseconds since the epoch (the value must be non-negative). Dates are stored in this form internally.
|
||||
- A formatted string.
|
||||
- An integer value that corresponds to seconds since the epoch (the value must be non-negative).
|
||||
|
||||
To represent date ranges, there is a date [range field type]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/range/).
|
||||
{: .note }
|
||||
|
||||
## Example
|
||||
|
||||
Create a mapping with a date field and two date formats:
|
||||
|
||||
```json
|
||||
PUT testindex
|
||||
{
|
||||
"mappings" : {
|
||||
"properties" : {
|
||||
"release_date" : {
|
||||
"type" : "date",
|
||||
"format" : "strict_date_optional_time||epoch_millis"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Parameters
|
||||
|
||||
The following table lists the parameters accepted by date field types. All parameters are optional.
|
||||
|
||||
Parameter | Description
|
||||
:--- | :---
|
||||
`boost` | A floating-point value that specifies the weight of this field toward the relevance score. Values above 1.0 increase the field's relevance. Values between 0.0 and 1.0 decrease the field's relevance. Default is 1.0.
|
||||
`doc_values` | A Boolean value that specifies whether the field should be stored on disk so that it can be used for aggregations, sorting, or scripting. Default is `false`.
|
||||
`format` | The format for parsing dates. Default is `strict_date_optional_time||epoch_millis`.
|
||||
`ignore_malformed` | A Boolean value that specifies to ignore malformed values and not to throw an exception. Default is `false`.
|
||||
`index` | A Boolean value that specifies whether the field should be searchable. Default is `true`.
|
||||
`locale` | A region- and language-specific way of representing the date. Default is [`ROOT`](https://docs.oracle.com/javase/8/docs/api/java/util/Locale.html#ROOT) (a region- and language-neutral locale).
|
||||
`meta` | Accepts metadata for this field.
|
||||
[`null_value`]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/index#null-value) | A value to be used in place of `null`. Must be of the same type as the field. If this parameter is not specified, the field is treated as missing when its value is `null`. Default is `null`.
|
||||
`store` | A Boolean value that specifies whether the field value should be stored and can be retrieved separately from the _source field. Default is `false`.
|
||||
|
||||
## Formats
|
||||
|
||||
OpenSearch has built-in date formats, but you can also create your own custom formats. The default format is `strict_date_optional_time||epoch_millis`. You can specify multiple date formats, separated by `||`.
|
||||
|
||||
## Built-in formats
|
||||
|
||||
Most of the date formats have a `strict_` counterpart. When the format starts with `strict_`, the date must have the correct number of digits specified in the format. For example, if the format is set to `strict_year_month_day` ("yyyy-MM-dd"), both month and day have to be two-digit numbers. So, "2020-06-09" is valid, while "2020-6-9" is invalid.
|
||||
|
||||
Epoch is defined as 00:00:00 UTC on January 1, 1970.
|
||||
{: .note }
|
||||
|
||||
y: year<br>
|
||||
Y: [week-based year](https://en.wikipedia.org/wiki/ISO_8601#Week_dates)<br>
|
||||
M: month<br>
|
||||
w: ordinal [week of the year](https://en.wikipedia.org/wiki/ISO_8601#Week_dates) from 01 to 53<br>
|
||||
d: day<br>
|
||||
D: ordinal day of the year from 001 to 365 (366 for leap years)<br>
|
||||
e: ordinal day of the week from 1 (Monday) to 7 (Sunday)<br>
|
||||
H: hour from 0 to 23<br>
|
||||
m: minute<br>
|
||||
s: second<br>
|
||||
S: fraction of a second<br>
|
||||
Z: time zone offset (for example, +0400; -0400; -04:00)<br>
|
||||
{: .note }
|
||||
|
||||
### Numeric date formats
|
||||
|
||||
Format name and description | Examples
|
||||
:--- | :---
|
||||
`epoch_millis` <br> The number of milliseconds since the epoch. Minimum is -2<sup>63</sup>. Maximum is 2<sup>63</sup> − 1. | 1553391286000
|
||||
`epoch_second` <br> The number of seconds since the epoch. Minimum is -2<sup>63</sup> ÷ 1000. Maximum is (2<sup>63</sup> − 1) ÷ 1000. | 1553391286
|
||||
|
||||
### Basic date formats
|
||||
|
||||
Components of basic date formats are not separated by a delimiter. For example, "20190323".
|
||||
|
||||
Format name and description | Pattern and examples
|
||||
:--- | :---
|
||||
**Dates**|
|
||||
`basic_date_time` <br> A basic date and time separated by `T`. | "yyyyMMdd`T`HHmmss.SSSZ"<br>"20190323T213446.123-04:00"
|
||||
`basic_date_time_no_millis` <br> A basic date and time without milliseconds, separated by `T`. | "yyyyMMdd`T`HHmmssZ"<br>"20190323T213446-04:00"
|
||||
`basic_date` <br> A date with a four-digit year, two-digit month, and two-digit day. | "yyyyMMdd"<br>"20190323"
|
||||
**Times** |
|
||||
`basic_time` <br> A time with a two-digit hour, two-digit minute, two-digit second, three-digit millisecond, and time zone offset. |"HHmmss.SSSZ" <br> "213446.123-04:00"
|
||||
`basic_time_no_millis` <br> A basic time without milliseconds. | "HHmmssZ" <br> "213446-04:00"
|
||||
**T times** |
|
||||
`basic_t_time` <br> A basic time preceded by `T`. | "`T`HHmmss.SSSZ" <br> "T213446.123-04:00"
|
||||
`basic_t_time_no_millis` <br> A basic time without milliseconds, preceded by `T`. | "`T`HHmmssZ" <br> "T213446-04:00"
|
||||
**Ordinal dates** |
|
||||
`basic_ordinal_date_time` <br> A full ordinal date and time. | "yyyyDDD`T`HHmmss.SSSZ"<br>"2019082T213446.123-04:00"
|
||||
`basic_ordinal_date_time_no_millis` <br> A full ordinal date and time without milliseconds. | "yyyyDDD`T`HHmmssZ"<br>"2019082T213446-04:00"
|
||||
`basic_ordinal_date` <br> A date with a four-digit year and three-digit ordinal day of the year. | "yyyyDDD" <br> "2019082"
|
||||
**Week-based dates** |
|
||||
`basic_week_date_time` <br> `strict_basic_week_date_time` <br> A full week-based date and time separated by `T`. | "YYYY`W`wwe`T`HHmmss.SSSZ" <br> "2019W126213446.123-04:00"
|
||||
`basic_week_date_time_no_millis` <br> `strict_basic_week_date_time_no_millis` <br> A basic week-based year date and time without milliseconds, separated by `T`. | "YYYY`W`wwe`T`HHmmssZ" <br> "2019W126213446-04:00"
|
||||
`basic_week_date` <br> `strict_basic_week_date` <br> A full week-based date with a four-digit week-based year, two-digit ordinal week of the year, and one-digit ordinal day of the week separated by `W`. | "YYYY`W`wwe" <br> "2019W126"
|
||||
|
||||
### Full date formats
|
||||
|
||||
Components of full date formats are separated by a `-` delimiter for date and `:` delimiter for time. For example, "2019-03-23T21:34".
|
||||
|
||||
Format name and description | Pattern and examples
|
||||
:--- | :---
|
||||
**Dates** |
|
||||
`date_optional_time`<br>`strict_date_optional_time` <br> A generic full date and time. Year is required. Month, day, and time are optional. Time is separated from date by `T`. | Multiple patterns. <br>"2019-03-23T21:34:46.123456789-04:00" <br> "2019-03-23T21:34:46" <br> "2019-03-23T21:34" <br> "2019"
|
||||
`strict_date_optional_time_nanos` <br>A generic full date and time. Year is required. Month, day, and time are optional. If time is specified, it must contain hours, minutes, and seconds, but fraction of a second is optional. Fraction of a second is one to nine digits long and has nanosecond resolution. Time is separated from date by `T`. | Multiple patterns. <br> "2019-03-23T21:34:46.123456789-04:00" <br> "2019-03-23T21:34:46" <br> "2019"
|
||||
`date_time` <br> `strict_date_time` <br> A full date and time separated by `T`. | "yyyy-MM-dd`T`HH:mm:ss.SSSZ" <br> "2019-03-23T21:34:46.123-04:00"
|
||||
`date_time_no_millis` <br> `strict_date_time_no_millis` <br> A full date and time without milliseconds, separated by `T`. | "yyyy-MM-dd'T'HH:mm:ssZ" <br> "2019-03-23T21:34:46-04:00"
|
||||
`date_hour_minute_second_fraction` <br> `strict_date_hour_minute_second_fraction` <br> A full date, two-digit hour, two-digit minute, two-digit second, and one- to nine-digit fraction of a second separated by `T`. | "yyyy-MM-dd`T`HH:mm:ss.SSSSSSSSS"<br>"2019-03-23T21:34:46.123456789" <br> "2019-03-23T21:34:46.1"
|
||||
`date_hour_minute_second_millis` <br> `strict_date_hour_minute_second_millis` <br> A full date, two-digit hour, two-digit minute, two-digit second, and three-digit millisecond separated by `T`. | "yyyy-MM-dd`T`HH:mm:ss.SSS" <br> "2019-03-23T21:34:46.123"
|
||||
`date_hour_minute_second` <br> `strict_date_hour_minute_second` <br> A full date, two-digit hour, two-digit minute, and two-digit second separated by `T`.| "yyyy-MM-dd`T`HH:mm:ss"<br>"2019-03-23T21:34:46"
|
||||
`date_hour_minute` <br> `strict_date_hour_minute` <br> A full date, two-digit hour, and two-digit minute. | "yyyy-MM-dd`T`HH:mm" <br> "2019-03-23T21:34"
|
||||
`date_hour` <br> `strict_date_hour` <br> A full date and two-digit hour, separated by `T`. | "yyyy-MM-dd`T`HH" <br> "2019-03-23T21"
|
||||
`date` <br> `strict_date` <br> A four-digit year, two-digit month, and two-digit day. | "yyyy-MM-dd" <br> "2019-03-23"
|
||||
`year_month_day` <br> `strict_year_month_day` <br> A four-digit year, two-digit month, and two-digit day. | "yyyy-MM-dd" <br> "2019-03-23"
|
||||
`year_month` <br> `strict_year_month` <br> A four-digit year and two-digit month. | "yyyy-MM" <br> "2019-03"
|
||||
`year` <br> `strict_year` <br> A four-digit year. | "yyyy" <br> "2019"
|
||||
**Times** |
|
||||
`time` <br> `strict_time` <br> A two-digit hour, two-digit minute, two-digit second, one- to nine-digit fraction of a second, and time zone offset. | "HH:mm:ss.SSSSSSSSSZ" <br> "21:34:46.123456789-04:00" <br> "21:34:46.1-04:00"
|
||||
`time_no_millis` <br> `strict_time_no_millis` <br> A two-digit hour, two-digit minute, two-digit second, and time zone offset. | "HH:mm:ssZ" <br> "21:34:46-04:00"
|
||||
`hour_minute_second_fraction` <br> `strict_hour_minute_second_fraction` <br> A two-digit hour, two-digit minute, two-digit second, and one- to nine-digit fraction of a second. | "HH:mm:ss.SSSSSSSSS" <br> "21:34:46.1" <br> "21:34:46.123456789"
|
||||
`hour_minute_second_millis` <br> `strict_hour_minute_second_millis` <br> A two-digit hour, two-digit minute, two-digit second, and three-digit millisecond. | "HH:mm:ss.SSS" <br> "21:34:46.123"
|
||||
`hour_minute_second` <br> `strict_hour_minute_second` <br> A two-digit hour, two-digit minute, and two-digit second. | "HH:mm:ss" <br> "21:34:46"
|
||||
`hour_minute` <br> `strict_hour_minute` <br> A two-digit hour and two-digit minute. | "HH:mm" <br> "21:34"
|
||||
`hour` <br> `strict_hour` <br> A two-digit hour. | "HH" <br> "21"
|
||||
**T times** |
|
||||
`t_time` <br> `strict_t_time` <br> A two-digit hour, two-digit minute, two-digit second, one- to nine-digit fraction of a second, and time zone offset, preceded by `T`. | "`T`HH:mm:ss.SSSSSSSSSZ"<br>"T21:34:46.123456789-04:00" <br> "T21:34:46.1-04:00"
|
||||
`t_time_no_millis` <br> `strict_t_time_no_millis` <br> A two-digit hour, two-digit minute, two-digit second, and time zone offset, preceded by `T`. | "`T`HH:mm:ssZ" <br> "T21:34:46-04:00"
|
||||
**Ordinal dates** |
|
||||
`ordinal_date_time` <br> `strict_ordinal_date_time` <br> A full ordinal date and time separated by `T`. | "yyyy-DDD`T`HH:mm:ss.SSSZ" <br> "2019-082T21:34:46.123-04:00"
|
||||
`ordinal_date_time_no_millis` <br> `strict_ordinal_date_time_no_millis` <br> A full ordinal date and time without milliseconds, separated by `T`. | "yyyy-DDD`T`HH:mm:ssZ" <br> "2019-082T21:34:46-04:00"
|
||||
`ordinal_date` <br> `strict_ordinal_date`<br> A full ordinal date with a four-digit year and three-digit ordinal day of the year. | "yyyy-DDD" <br> "2019-082"
|
||||
**Week-based dates** |
|
||||
`week_date_time` <br> `strict_week_date_time` <br> A full week-based date and time separated by `T`. Week date is a four-digit week-based year, two-digit ordinal week of the year, and one-digit ordinal day of the week. Time is a two-digit hour, two-digit minute, two-digit second, one- to nine-digit fraction of a second, and a time zone offset. | "YYYY-`W`ww-e`T`HH:mm:ss.SSSSSSSSSZ" <br> "2019-W12-6T21:34:46.1-04:00" <br> "2019-W12-6T21:34:46.123456789-04:00"
|
||||
`week_date_time_no_millis` <br> `strict_week_date_time_no_millis` <br> A full week-based date and time without milliseconds, separated by `T`. Week date is a four-digit week-based year, two-digit ordinal week of the year, and one-digit ordinal day of the week. Time is a two-digit hour, two-digit minute, two-digit second, and time zone offset. | "YYYY-`W`ww-e`T`HH:mm:ssZ" <br> "2019-W12-6T21:34:46-04:00"
|
||||
`week_date` <br> `strict_week_date` <br> A full week-based date with a four-digit week-based year, two-digit ordinal week of the year, and one-digit ordinal day of the week. | "YYYY-`W`ww-e" <br> "2019-W12-6"
|
||||
`weekyear_week_day` <br> `strict_weekyear_week_day` <br> A four-digit week-based year, two-digit ordinal week of the year, and one digit day of the week. | "YYYY-'W'ww-e" <br> "2019-W12-6"
|
||||
`weekyear_week` <br> `strict_weekyear_week` <br> A four-digit week-based year and two-digit ordinal week of the year. | "YYYY-`W`ww" <br> "2019-W12"
|
||||
`weekyear` <br> `strict_weekyear` <br> A four-digit week-based year. | "YYYY" <br> "2019"
|
||||
|
||||
## Custom formats
|
||||
|
||||
You can create custom formats for date fields. For example, the following request specifies a date in the common "MM/dd/yyyy" format.
|
||||
|
||||
```json
|
||||
PUT testindex
|
||||
{
|
||||
"mappings" : {
|
||||
"properties" : {
|
||||
"release_date" : {
|
||||
"type" : "date",
|
||||
"format" : "MM/dd/yyyy"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Index a document with a date:
|
||||
|
||||
```json
|
||||
PUT testindex/_doc/21
|
||||
{
|
||||
"release_date" : "03/21/2019"
|
||||
}
|
||||
```
|
||||
|
||||
When searching for an exact date, provide that date in the same format:
|
||||
|
||||
```json
|
||||
GET testindex/_search
|
||||
{
|
||||
"query" : {
|
||||
"match": {
|
||||
"release_date" : {
|
||||
"query": "03/21/2019"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Range queries by default use the field's mapped format. You can also specify the range of dates in a different format by providing the `format` parameter:
|
||||
|
||||
```json
|
||||
GET testindex/_search
|
||||
{
|
||||
"query": {
|
||||
"range": {
|
||||
"release_date": {
|
||||
"gte": "2019-01-01",
|
||||
"lte": "2019-12-31",
|
||||
"format": "yyyy-MM-dd"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
|
@ -0,0 +1,91 @@
|
|||
---
|
||||
layout: default
|
||||
title: Geopoint
|
||||
nav_order: 56
|
||||
has_children: false
|
||||
parent: Geographic field types
|
||||
grand_parent: Supported field types
|
||||
---
|
||||
|
||||
# Geopoint field type
|
||||
|
||||
A geopoint field type contains a geographic point specified by latitude and longitude.
|
||||
|
||||
## Example
|
||||
|
||||
Create a mapping with a geopoint field type:
|
||||
|
||||
```json
|
||||
PUT testindex1
|
||||
{
|
||||
"mappings": {
|
||||
"properties": {
|
||||
"point": {
|
||||
"type": "geo_point"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Formats
|
||||
|
||||
Geopoints can be indexed in the following formats:
|
||||
|
||||
- An object with a latitude and longitude
|
||||
|
||||
```json
|
||||
PUT testindex1/_doc/1
|
||||
{
|
||||
"point": {
|
||||
"lat": 40.71,
|
||||
"lon": 74.00
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- A string in the "`latitude`,`longitude`" format
|
||||
|
||||
```json
|
||||
PUT testindex1/_doc/2
|
||||
{
|
||||
"point": "40.71,74.00"
|
||||
}
|
||||
```
|
||||
|
||||
- A geohash
|
||||
|
||||
```json
|
||||
PUT testindex1/_doc/3
|
||||
{
|
||||
"point": "txhxegj0uyp3"
|
||||
}
|
||||
```
|
||||
|
||||
- An array in the [`longitude`, `latitude`] format
|
||||
|
||||
```json
|
||||
PUT testindex1/_doc/4
|
||||
{
|
||||
"point": [74.00, 40.71]
|
||||
}
|
||||
```
|
||||
|
||||
- A [Well-Known Text](https://docs.opengeospatial.org/is/12-063r5/12-063r5.html) POINT in the "POINT(`longitude` `latitude`)" format
|
||||
|
||||
```json
|
||||
PUT testindex1/_doc/5
|
||||
{
|
||||
"point": "POINT (74.00 40.71)"
|
||||
}
|
||||
```
|
||||
|
||||
## Parameters
|
||||
|
||||
The following table lists the parameters accepted by geopoint field types. All parameters are optional.
|
||||
|
||||
Parameter | Description
|
||||
:--- | :---
|
||||
`ignore_malformed` | A Boolean value that specifies to ignore malformed values and not to throw an exception. Valid values for latitude are [-90, 90]. Valid values for longitude are [-180, 180]. Default is `false`.
|
||||
`ignore_z_values` | Specific to points with three coordinates. If `ignore_z_values` is `true`, the third coordinate is not indexed but is still stored in the _source field. If `ignore_z_values` is `false`, an exception is thrown.
|
||||
[`null_value`]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/index#null-value) | A value to be used in place of `null`. Must be of the same type as the field. If this parameter is not specified, the field is treated as missing when its value is `null`. Default is `null`.
|
||||
|
|
@ -0,0 +1,373 @@
|
|||
---
|
||||
layout: default
|
||||
title: Geoshape
|
||||
nav_order: 57
|
||||
has_children: false
|
||||
parent: Geographic field types
|
||||
grand_parent: Supported field types
|
||||
---
|
||||
|
||||
# Geoshape field type
|
||||
|
||||
A geoshape field type contains a geographic shape, such as a polygon or a collection of geographic points. To index a geoshape, OpenSearch tesselates the shape into a triangular mesh and stores each triangle in a BKD tree. This provides a 10<sup>-7</sup>decimal degree of precision, which represents near-perfect spatial resolution. Performance of this process is mostly impacted by the number of vertices in a polygon you are indexing.
|
||||
|
||||
## Example
|
||||
|
||||
Create a mapping with a geoshape field type:
|
||||
|
||||
```json
|
||||
PUT testindex
|
||||
{
|
||||
"mappings": {
|
||||
"properties": {
|
||||
"location": {
|
||||
"type": "geo_shape"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Formats
|
||||
|
||||
Geoshapes can be indexed in the following formats:
|
||||
|
||||
- [GeoJSON](https://geojson.org/)
|
||||
- [Well-Known Text (WKT)](https://docs.opengeospatial.org/is/12-063r5/12-063r5.html)
|
||||
|
||||
In both GeoJSON and WKT, the coordinates must be specified in the `longitude, latitude` order within coordinate arrays. Note that the longitude comes first in this format.
|
||||
{: .note}
|
||||
|
||||
## Geoshape types
|
||||
|
||||
The following table describes the possible geoshape types and their relationship to the GeoJSON and WKT types.
|
||||
|
||||
OpenSearch type | GeoJSON type | WKT type | Description
|
||||
:--- | :--- | :--- | :---
|
||||
[`point`](#point) | Point | POINT | A geographic point specified by latitude and longitude. OpenSearch uses World Geodetic System (WGS84) coordinates.
|
||||
[`linestring`](#line-string) | LineString | LINESTRING | A line specified by two or more points. May be a straight line or a path of connected line segments.
|
||||
[`polygon`](#polygon) | Polygon | POLYGON | A polygon specified by a list of vertices in coordinate form. The polygon must be closed, meaning the last point must be the same as the first point. Therefore, to create an n-gon, n+1 vertices are required. The minimum number of vertices is four, which creates a triangle.
|
||||
[`multipoint`](#multi-point) | MultiPoint | MULTIPOINT | An array of discrete related points that are not connected.
|
||||
[`multilinestring`](#multiline-string) | MultiLineString | MULTILINESTRING | An array of linestrings.
|
||||
[`multipolygon`](#multi-polygon) | MultiPolygon | MULTIPOLYGON | An array of polygons.
|
||||
[`geometrycollection`](#geometry-collection) | GeometryCollection | GEOMETRYCOLLECTION | A collection of geoshapes that may be of different types.
|
||||
[`envelope`](#envelope) | N/A | BBOX | A bounding rectangle specified by top-left and bottom-right vertices.
|
||||
|
||||
## Point
|
||||
|
||||
A point is a single pair of coordinates specified by latitude and longitude.
|
||||
|
||||
Index a point in GeoJSON format:
|
||||
|
||||
```json
|
||||
PUT testindex/_doc/1
|
||||
{
|
||||
"location" : {
|
||||
"type" : "point",
|
||||
"coordinates" : [74.00, 40.71]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Index a point in WKT format:
|
||||
|
||||
```json
|
||||
PUT testindex/_doc/1
|
||||
{
|
||||
"location" : "POINT (74.0060 40.7128)"
|
||||
}
|
||||
```
|
||||
|
||||
## Line string
|
||||
|
||||
A line string is a line specified by two or more points. If the points are collinear, the line string is a straight line. Otherwise, the line string represents a path made of line segments.
|
||||
|
||||
Index a line string in GeoJSON format:
|
||||
|
||||
```json
|
||||
PUT testindex/_doc/2
|
||||
{
|
||||
"location" : {
|
||||
"type" : "linestring",
|
||||
"coordinates" : [[74.0060, 40.7128], [71.0589, 42.3601]]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Index a line string in WKT format:
|
||||
|
||||
```json
|
||||
PUT testindex/_doc/2
|
||||
{
|
||||
"location" : "LINESTRING (74.0060 40.7128, 71.0589 42.3601)"
|
||||
}
|
||||
```
|
||||
|
||||
## Polygon
|
||||
|
||||
A polygon is specified by a list of vertices in coordinate form. The polygon must be closed, meaning the last point must be the same as the first point. In the following example, a triangle is created using four points.
|
||||
|
||||
GeoJSON requires that you list the vertices of the polygon counterclockwise. WKT does not impose a specific order on vertices.
|
||||
{: .note}
|
||||
|
||||
Index a polygon (triangle) in GeoJSON format:
|
||||
|
||||
```json
|
||||
PUT testindex/_doc/3
|
||||
{
|
||||
"location" : {
|
||||
"type" : "polygon",
|
||||
"coordinates" : [
|
||||
[[74.0060, 40.7128],
|
||||
[71.0589, 42.3601],
|
||||
[73.7562, 42.6526],
|
||||
[74.0060, 40.7128]]
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Index a polygon (triangle) in WKT format:
|
||||
|
||||
```json
|
||||
PUT testindex/_doc/3
|
||||
{
|
||||
"location" : "POLYGON ((74.0060 40.7128, 71.0589 42.3601, 73.7562 42.6526, 74.0060 40.7128))"
|
||||
}
|
||||
```
|
||||
|
||||
The polygon may have holes inside. In this case, the `coordinates` field will contain multiple arrays. The first array represents the outer polygon, and each subsequent array represents a hole. Holes are represented as polygons and specified as arrays of coordinates.
|
||||
|
||||
GeoJSON requires that you list the vertices of the polygon counterclockwise and the vertices of the hole clockwise. WKT does not impose a specific order on vertices.
|
||||
{: .note}
|
||||
|
||||
Index a polygon (triangle) with a triangular hole in GeoJSON format:
|
||||
|
||||
```json
|
||||
PUT testindex/_doc/4
|
||||
{
|
||||
"location" : {
|
||||
"type" : "polygon",
|
||||
"coordinates" : [
|
||||
[[74.0060, 40.7128],
|
||||
[71.0589, 42.3601],
|
||||
[73.7562, 42.6526],
|
||||
[74.0060, 40.7128]],
|
||||
|
||||
[[72.6734,41.7658],
|
||||
[72.6506, 41.5623],
|
||||
[73.0515, 41.5582],
|
||||
[72.6734, 41.7658]]
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Index a polygon (triangle) with a triangular hole in WKT format:
|
||||
|
||||
```json
|
||||
PUT testindex/_doc/4
|
||||
{
|
||||
"location" : "POLYGON ((40.7128 74.0060, 42.3601 71.0589, 42.6526 73.7562, 40.7128 74.0060), (41.7658 72.6734, 41.5623 72.6506, 41.5582 73.0515, 41.7658 72.6734))"
|
||||
}
|
||||
```
|
||||
|
||||
In OpenSearch, you can specify a polygon by listing its vertices clockwise or counterclockwise. This works well for polygons that do not cross the date line (are narrower than 180°). However, a polygon that crosses the date line (is wider than 180°) might be ambiguous because WKT does not impose a specific order on vertices. Thus, you must specify polygons that cross the date line by listing their vertices counterclockwise.
|
||||
|
||||
You can define an [`orientation`](#parameters) parameter to specify the vertex traversal order at mapping time:
|
||||
|
||||
```json
|
||||
PUT testindex
|
||||
{
|
||||
"mappings": {
|
||||
"properties": {
|
||||
"location": {
|
||||
"type": "geo_shape",
|
||||
"orientation" : "left"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Subsequently indexed documents can override the `orientation` setting:
|
||||
|
||||
```json
|
||||
PUT testindex/_doc/3
|
||||
{
|
||||
"location" : {
|
||||
"type" : "polygon",
|
||||
"orientation" : "cw",
|
||||
"coordinates" : [
|
||||
[[74.0060, 40.7128],
|
||||
[71.0589, 42.3601],
|
||||
[73.7562, 42.6526],
|
||||
[74.0060, 40.7128]]
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Multi point
|
||||
|
||||
A multi point is an array of discrete related points that are not connected.
|
||||
|
||||
Index a multi point in GeoJSON format:
|
||||
|
||||
```json
|
||||
PUT testindex/_doc/6
|
||||
{
|
||||
"location" : {
|
||||
"type" : "multipoint",
|
||||
"coordinates" : [
|
||||
[74.0060, 40.7128],
|
||||
[71.0589, 42.3601]
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Index a multi point in WKT format:
|
||||
|
||||
```json
|
||||
PUT testindex/_doc/6
|
||||
{
|
||||
"location" : "MULTIPOINT (74.0060 40.7128, 71.0589 42.3601)"
|
||||
}
|
||||
```
|
||||
|
||||
## Multiline string
|
||||
|
||||
A multiline string is an array of line strings.
|
||||
|
||||
Index a line string in GeoJSON format:
|
||||
|
||||
```json
|
||||
PUT testindex/_doc/2
|
||||
{
|
||||
"location" : {
|
||||
"type" : "multilinestring",
|
||||
"coordinates" : [
|
||||
[[74.0060, 40.7128], [71.0589, 42.3601]],
|
||||
[[73.7562, 42.6526], [72.6734, 41.7658]]
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Index a line string in WKT format:
|
||||
|
||||
```json
|
||||
PUT testindex/_doc/2
|
||||
{
|
||||
"location" : "MULTILINESTRING ((74.0060 40.7128, 71.0589 42.3601), (73.7562 42.6526, 72.6734 41.7658))"
|
||||
}
|
||||
```
|
||||
|
||||
## Multi polygon
|
||||
|
||||
A multi polygon is an array of polygons. In this example, the first polygon contains a hole, and the second does not.
|
||||
|
||||
Index a multi polygon in GeoJSON format:
|
||||
|
||||
```json
|
||||
PUT testindex/_doc/4
|
||||
{
|
||||
"location" : {
|
||||
"type" : "multipolygon",
|
||||
"coordinates" : [
|
||||
[
|
||||
[[74.0060, 40.7128],
|
||||
[71.0589, 42.3601],
|
||||
[73.7562, 42.6526],
|
||||
[74.0060, 40.7128]],
|
||||
|
||||
[[72.6734,41.7658],
|
||||
[72.6506, 41.5623],
|
||||
[73.0515, 41.5582],
|
||||
[72.6734, 41.7658]]
|
||||
],
|
||||
[
|
||||
[[73.9776, 40.7614],
|
||||
[73.9554, 40.7827],
|
||||
[73.9631, 40.7812],
|
||||
[73.9776, 40.7614]]
|
||||
]
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Index a multi polygon in WKT format:
|
||||
|
||||
```json
|
||||
PUT testindex/_doc/4
|
||||
{
|
||||
"location" : "MULTIPOLYGON (((40.7128 74.0060, 42.3601 71.0589, 42.6526 73.7562, 40.7128 74.0060), (41.7658 72.6734, 41.5623 72.6506, 41.5582 73.0515, 41.7658 72.6734)), ((73.9776 40.7614, 73.9554 40.7827, 73.9631 40.7812, 73.9776 40.7614)))"
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
|
||||
## Geometry collection
|
||||
|
||||
A geometry collection is a collection of geoshapes that may be of different types.
|
||||
|
||||
Index a geometry collection in GeoJSON format:
|
||||
|
||||
```json
|
||||
PUT testindex/_doc/2
|
||||
{
|
||||
"location" : {
|
||||
"type" : "linestring",
|
||||
"coordinates" : [[74.0060, 40.7128], [71.0589, 42.3601]]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Index a geometry collection in WKT format:
|
||||
|
||||
```json
|
||||
PUT testindex/_doc/7
|
||||
{
|
||||
"location" : "GEOMETRYCOLLECTION (POINT (74.0060 40.7128), LINESTRING(73.7562 42.6526, 72.6734 41.7658))"
|
||||
}
|
||||
```
|
||||
|
||||
## Envelope
|
||||
|
||||
An envelope is a bounding rectangle specified by top-left and bottom-right vertices. The GeoJSON format is `[[minLon, maxLat], [maxLon, minLat]]`.
|
||||
|
||||
Index an envelope in GeoJSON format:
|
||||
|
||||
```json
|
||||
PUT testindex/_doc/2
|
||||
{
|
||||
"location" : {
|
||||
"type" : "envelope",
|
||||
"coordinates" : [[71.0589, 42.3601], [74.0060, 40.7128]]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
In WKT format, use `BBOX (minLon, maxLon, maxLat, minLat)`.
|
||||
|
||||
Index an envelope in WKT BBOX format:
|
||||
|
||||
```json
|
||||
PUT testindex/_doc/8
|
||||
{
|
||||
"location" : "BBOX (71.0589, 74.0060, 42.3601, 40.7128)"
|
||||
}
|
||||
```
|
||||
|
||||
## Parameters
|
||||
|
||||
The following table lists the parameters accepted by geoshape field types. All parameters are optional.
|
||||
|
||||
Parameter | Description
|
||||
:--- | :---
|
||||
`coerce` | A Boolean value that specifies whether to automatically close unclosed linear rings. Default is `false`.
|
||||
`ignore_malformed` | A Boolean value that specifies to ignore malformed GeoJSON or WKT geoshapes and not to throw an exception. Default is `false` (throw an exception when geoshapes are malformed).
|
||||
`ignore_z_values` | Specific to points with three coordinates. If `ignore_z_values` is `true`, the third coordinate is not indexed but is still stored in the _source field. If `ignore_z_values` is `false`, an exception is thrown. Default is `true`.
|
||||
`orientation` | Specifies the traversal order of the vertices in the geoshape's list of coordinates. `orientation` takes the following values: <br> 1. RIGHT: counterclockwise. Specify RIGHT orientation by using one of the following strings (uppercase or lowercase): `right`, `counterclockwise`, `ccw`. <br> 2. LEFT: clockwise. Specify LEFT orientation by using one of the following strings (uppercase or lowercase): `left`, `clockwise`, `cw`. This value can be overridden by individual documents.<br> Default is `RIGHT`.
|
||||
|
|
@ -0,0 +1,17 @@
|
|||
---
|
||||
layout: default
|
||||
title: Geographic field types
|
||||
nav_order: 55
|
||||
has_children: true
|
||||
has_toc: false
|
||||
parent: Supported field types
|
||||
---
|
||||
|
||||
# Geographic field types
|
||||
|
||||
The following table lists all geographic field types that OpenSearch supports.
|
||||
|
||||
Field data type | Description
|
||||
:--- | :---
|
||||
[`geo_point`]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/geo-point/) | A geographic point specified by latitude and longitude.
|
||||
[`geo_shape`]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/geo-shape/) | A geographic shape, such as a polygon or a collection of geographic points.
|
||||
|
|
@ -0,0 +1,188 @@
|
|||
---
|
||||
layout: default
|
||||
title: Supported field types
|
||||
nav_order: 80
|
||||
has_children: true
|
||||
has_toc: false
|
||||
redirect_from:
|
||||
- /opensearch/supported-field-types/
|
||||
---
|
||||
|
||||
# Supported field types
|
||||
|
||||
You can specify data types for your fields when creating a mapping. The following table lists all data field types that OpenSearch supports.
|
||||
|
||||
Field data type | Description
|
||||
:--- | :---
|
||||
[`alias`]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/alias/) | An additional name for an existing field.
|
||||
[`binary`]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/binary/) | A binary value in Base64 encoding.
|
||||
[Numeric]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/numeric/) | `byte`, `double`, `float`, `half_float`, `integer`, `long`, `scaled_float`, `short`.
|
||||
[`boolean`]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/boolean/) | A Boolean value.
|
||||
[`date`]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/date/) | A date value as a formatted string, a long value, or an integer.
|
||||
[`ip`]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/ip/) | An IP address in IPv4 or IPv6 format.
|
||||
[Range]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/range/) | `integer_range`, `long_range`,`double_range`, `float_range`, `date_range`,`ip_range`.
|
||||
[Object]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/object/) | `object`, `nested`, `join`.
|
||||
String | [`keyword`]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/keyword/), [`text`]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/text/), [`token_count`]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/token-count/).
|
||||
[Autocomplete]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/autocomplete/) | `completion`, `search_as_you_type`.
|
||||
[Geographic]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/geographic/) | `geo_point`, `geo_shape`.
|
||||
[Rank]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/rank/) | `rank_feature`, `rank_features`.
|
||||
[`percolator`]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/percolator/) | Specifies to treat this field as a query.
|
||||
|
||||
## Arrays
|
||||
|
||||
There is no dedicated array field type in OpenSearch. Instead, you can pass an array of values into any field. All values in the array must have the same field type.
|
||||
|
||||
```json
|
||||
PUT testindex1/_doc/1
|
||||
{
|
||||
"number": 1
|
||||
}
|
||||
|
||||
PUT testindex1/_doc/2
|
||||
{
|
||||
"number": [1, 2, 3]
|
||||
}
|
||||
```
|
||||
|
||||
## Multifields
|
||||
|
||||
Multifields are used to index the same field differently. Strings are often mapped as `text` for full-text queries and `keyword` for exact-value queries.
|
||||
|
||||
Multifields can be created using the `fields` parameter. For example, you can map a book `title` to be of type `text` and keep a `title.raw` subfield of type `keyword`.
|
||||
|
||||
```json
|
||||
PUT books
|
||||
{
|
||||
"mappings" : {
|
||||
"properties" : {
|
||||
"title" : {
|
||||
"type" : "text",
|
||||
"fields" : {
|
||||
"raw" : {
|
||||
"type" : "keyword"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Null value
|
||||
|
||||
Setting a field's value to `null`, an empty array or an array of `null` values makes this field equivalent to an empty field. Therefore, you cannot search for documents that have `null` in this field.
|
||||
|
||||
To make a field searchable for `null` values, you can specify its `null_value` parameter in the index's mappings. Then, all `null` values passed to this field will be replaced with the specified `null_value`.
|
||||
|
||||
The `null_value` parameter must be of the same type as the field. For example, if your field is a string, the `null_value` for this field must also be a string.
|
||||
{: .note}
|
||||
|
||||
### Example
|
||||
|
||||
Create a mapping to replace `null` values in the `emergency_phone` field with the string "NONE":
|
||||
|
||||
```json
|
||||
PUT testindex
|
||||
{
|
||||
"mappings": {
|
||||
"properties": {
|
||||
"name": {
|
||||
"type": "keyword"
|
||||
},
|
||||
"emergency_phone": {
|
||||
"type": "keyword",
|
||||
"null_value": "NONE"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Index three documents into testindex. The `emergency_phone` fields of documents 1 and 3 contain `null`, while the `emergency_phone` field of document 2 has an empty array:
|
||||
|
||||
```json
|
||||
PUT testindex/_doc/1
|
||||
{
|
||||
"name": "Akua Mansa",
|
||||
"emergency_phone": null
|
||||
}
|
||||
```
|
||||
|
||||
```json
|
||||
PUT testindex/_doc/2
|
||||
{
|
||||
"name": "Diego Ramirez",
|
||||
"emergency_phone" : []
|
||||
}
|
||||
```
|
||||
|
||||
```json
|
||||
PUT testindex/_doc/3
|
||||
{
|
||||
"name": "Jane Doe",
|
||||
"emergency_phone": [null, null]
|
||||
}
|
||||
```
|
||||
|
||||
Search for people who do not have an emergency phone:
|
||||
|
||||
```json
|
||||
GET testindex/_search
|
||||
{
|
||||
"query": {
|
||||
"term": {
|
||||
"emergency_phone": "NONE"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The response contains documents 1 and 3 but not document 2 because only explicit `null` values are replaced with the string "NONE":
|
||||
|
||||
```json
|
||||
{
|
||||
"took" : 1,
|
||||
"timed_out" : false,
|
||||
"_shards" : {
|
||||
"total" : 1,
|
||||
"successful" : 1,
|
||||
"skipped" : 0,
|
||||
"failed" : 0
|
||||
},
|
||||
"hits" : {
|
||||
"total" : {
|
||||
"value" : 2,
|
||||
"relation" : "eq"
|
||||
},
|
||||
"max_score" : 0.18232156,
|
||||
"hits" : [
|
||||
{
|
||||
"_index" : "testindex",
|
||||
"_type" : "_doc",
|
||||
"_id" : "1",
|
||||
"_score" : 0.18232156,
|
||||
"_source" : {
|
||||
"name" : "Akua Mansa",
|
||||
"emergency_phone" : null
|
||||
}
|
||||
},
|
||||
{
|
||||
"_index" : "testindex",
|
||||
"_type" : "_doc",
|
||||
"_id" : "3",
|
||||
"_score" : 0.18232156,
|
||||
"_source" : {
|
||||
"name" : "Jane Doe",
|
||||
"emergency_phone" : [
|
||||
null,
|
||||
null
|
||||
]
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The `_source` field still contains explicit `null` values because it is not affected by the `null_value`.
|
||||
{: .note}
|
||||
|
|
@ -0,0 +1,111 @@
|
|||
---
|
||||
layout: default
|
||||
title: IP address
|
||||
nav_order: 30
|
||||
has_children: false
|
||||
parent: Supported field types
|
||||
---
|
||||
|
||||
# IP address field type
|
||||
|
||||
An ip field type contains an IP address in IPv4 or IPv6 format.
|
||||
|
||||
To represent IP address ranges, there is an IP [range field type]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/range/).
|
||||
{: .note }
|
||||
|
||||
## Example
|
||||
|
||||
Create a mapping with an IP address:
|
||||
|
||||
```json
|
||||
PUT testindex
|
||||
{
|
||||
"mappings" : {
|
||||
"properties" : {
|
||||
"ip_address" : {
|
||||
"type" : "ip"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Index a document with an IP address:
|
||||
|
||||
```json
|
||||
PUT testindex/_doc/1
|
||||
{
|
||||
"ip_address" : "10.24.34.0"
|
||||
}
|
||||
```
|
||||
|
||||
Query an index for a specific IP address:
|
||||
|
||||
```json
|
||||
GET testindex/_doc/1
|
||||
{
|
||||
"query": {
|
||||
"term": {
|
||||
"ip_address": "10.24.34.0"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Searching for an IP address and its associated network mask
|
||||
|
||||
You can query an index for an IP address in [Classless Inter-Domain Routing (CIDR) notation](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing#CIDR_notation). Using CIDR notation, specify the IP address and the prefix length (0–32), separated by `/`. For example, the prefix length of 24 will match all IP addresses with the same initial 24 bits.
|
||||
|
||||
#### Example query in IPv4 format
|
||||
|
||||
```json
|
||||
GET testindex/_search
|
||||
{
|
||||
"query": {
|
||||
"term": {
|
||||
"ip_address": "10.24.34.0/24"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Example query in IPv6 format
|
||||
|
||||
```json
|
||||
GET testindex/_search
|
||||
{
|
||||
"query": {
|
||||
"term": {
|
||||
"ip_address": "2001:DB8::/24"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
If you use an IP address in IPv6 format in a `query_string` query, you need to escape `:` characters because they are parsed as special characters. You can accomplish this by wrapping the IP address in quotation marks and escaping those quotation marks with `\`.
|
||||
|
||||
```json
|
||||
GET testindex/_search
|
||||
{
|
||||
"query" : {
|
||||
"query_string": {
|
||||
"query": "ip_address:\"2001:DB8::/24\""
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Parameters
|
||||
|
||||
The following table lists the parameters accepted by ip field types. All parameters are optional.
|
||||
|
||||
Parameter | Description
|
||||
:--- | :---
|
||||
`boost` | A floating-point value that specifies the weight of this field toward the relevance score. Values above 1.0 increase the field's relevance. Values between 0.0 and 1.0 decrease the field's relevance. Default is 1.0.
|
||||
`doc_values` | A Boolean value that specifies if the field should be stored on disk so that it can be used for aggregations, sorting, or scripting. Default is `false`.
|
||||
`ignore_malformed` | A Boolean value that specifies to ignore malformed values and not to throw an exception. Default is `false`.
|
||||
`index` | A Boolean value that specifies whether the field should be searchable. Default is `true`.
|
||||
[`null_value`]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/index#null-value) | A value to be used in place of `null`. Must be of the same type as the field. If this parameter is not specified, the field is treated as missing when its value is `null`. Default is `null`.
|
||||
`store` | A Boolean value that specifies whether the field value should be stored and can be retrieved separately from the _source field. Default is `false`.
|
||||
|
||||
|
||||
|
|
@ -0,0 +1,313 @@
|
|||
---
|
||||
layout: default
|
||||
title: Join
|
||||
nav_order: 43
|
||||
has_children: false
|
||||
parent: Object field types
|
||||
grand_parent: Supported field types
|
||||
---
|
||||
|
||||
# Join field type
|
||||
|
||||
A join field type establishes a parent/child relationship between documents in the same index.
|
||||
|
||||
## Example
|
||||
|
||||
Create a mapping to establish a parent-child relationship between products and their brands:
|
||||
|
||||
```json
|
||||
PUT testindex1/_mappings
|
||||
{
|
||||
"mappings": {
|
||||
"properties": {
|
||||
"product_to_brand": {
|
||||
"type": "join",
|
||||
"relations": {
|
||||
"brand": "product"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Then, index a parent document with a join field type:
|
||||
|
||||
```json
|
||||
PUT testindex1/_doc/1
|
||||
{
|
||||
"name": "Brand 1",
|
||||
"product_to_brand": {
|
||||
"name": "brand"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
You can also use a shortcut without object notation to index a parent document:
|
||||
|
||||
```json
|
||||
PUT testindex1/_doc/1
|
||||
{
|
||||
"name": "Brand 1",
|
||||
"product_to_brand" : "brand"
|
||||
}
|
||||
```
|
||||
|
||||
When indexing child documents, you have to specify the `routing` query parameter because parent and child documents in the same relation have to be indexed on the same shard. Each child document refers to its parent's ID in the `parent` field.
|
||||
|
||||
Index two child documents, one for each parent:
|
||||
|
||||
```json
|
||||
PUT testindex1/_doc/3?routing=1
|
||||
{
|
||||
"name": "Product 1",
|
||||
"product_to_brand": {
|
||||
"name": "product",
|
||||
"parent": "1"
|
||||
}
|
||||
}
|
||||
|
||||
PUT testindex1/_doc/4?routing=1
|
||||
{
|
||||
"name": "Product 2",
|
||||
"product_to_brand": {
|
||||
"name": "product",
|
||||
"parent": "1"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Querying a join field
|
||||
|
||||
When you query a join field, the response contains subfields that specify whether the returned document is a parent or a child. For child objects, the parent ID is also returned.
|
||||
|
||||
### Search for all documents
|
||||
|
||||
```json
|
||||
GET testindex1/_search
|
||||
{
|
||||
"query": {
|
||||
"match_all": {}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The response indicates whether a document is a parent or a child:
|
||||
|
||||
```json
|
||||
{
|
||||
"took" : 4,
|
||||
"timed_out" : false,
|
||||
"_shards" : {
|
||||
"total" : 1,
|
||||
"successful" : 1,
|
||||
"skipped" : 0,
|
||||
"failed" : 0
|
||||
},
|
||||
"hits" : {
|
||||
"total" : {
|
||||
"value" : 3,
|
||||
"relation" : "eq"
|
||||
},
|
||||
"max_score" : 1.0,
|
||||
"hits" : [
|
||||
{
|
||||
"_index" : "testindex1",
|
||||
"_type" : "_doc",
|
||||
"_id" : "1",
|
||||
"_score" : 1.0,
|
||||
"_source" : {
|
||||
"name" : "Brand 1",
|
||||
"product_to_brand" : {
|
||||
"name" : "brand"
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
"_index" : "testindex1",
|
||||
"_type" : "_doc",
|
||||
"_id" : "3",
|
||||
"_score" : 1.0,
|
||||
"_routing" : "1",
|
||||
"_source" : {
|
||||
"name" : "Product 1",
|
||||
"product_to_brand" : {
|
||||
"name" : "product",
|
||||
"parent" : "1"
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
"_index" : "testindex1",
|
||||
"_type" : "_doc",
|
||||
"_id" : "4",
|
||||
"_score" : 1.0,
|
||||
"_routing" : "1",
|
||||
"_source" : {
|
||||
"name" : "Product 2",
|
||||
"product_to_brand" : {
|
||||
"name" : "product",
|
||||
"parent" : "1"
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Search for all children of a parent
|
||||
|
||||
Find all products associated with Brand 1:
|
||||
|
||||
```json
|
||||
GET testindex1/_search
|
||||
{
|
||||
"query" : {
|
||||
"has_parent": {
|
||||
"parent_type":"brand",
|
||||
"query": {
|
||||
"match" : {
|
||||
"name": "Brand 1"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The response contains Product 1 and Product 2, which are associated with Brand 1:
|
||||
|
||||
```json
|
||||
{
|
||||
"took" : 7,
|
||||
"timed_out" : false,
|
||||
"_shards" : {
|
||||
"total" : 1,
|
||||
"successful" : 1,
|
||||
"skipped" : 0,
|
||||
"failed" : 0
|
||||
},
|
||||
"hits" : {
|
||||
"total" : {
|
||||
"value" : 2,
|
||||
"relation" : "eq"
|
||||
},
|
||||
"max_score" : 1.0,
|
||||
"hits" : [
|
||||
{
|
||||
"_index" : "testindex1",
|
||||
"_type" : "_doc",
|
||||
"_id" : "3",
|
||||
"_score" : 1.0,
|
||||
"_routing" : "1",
|
||||
"_source" : {
|
||||
"name" : "Product 1",
|
||||
"product_to_brand" : {
|
||||
"name" : "product",
|
||||
"parent" : "1"
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
"_index" : "testindex1",
|
||||
"_type" : "_doc",
|
||||
"_id" : "4",
|
||||
"_score" : 1.0,
|
||||
"_routing" : "1",
|
||||
"_source" : {
|
||||
"name" : "Product 2",
|
||||
"product_to_brand" : {
|
||||
"name" : "product",
|
||||
"parent" : "1"
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Search for the parent of a child
|
||||
|
||||
Find the parent of Product 1:
|
||||
|
||||
```json
|
||||
GET testindex1/_search
|
||||
{
|
||||
"query" : {
|
||||
"has_child": {
|
||||
"type":"product",
|
||||
"query": {
|
||||
"match" : {
|
||||
"name": "Product 1"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The response returns Brand 1 as Product 1's parent:
|
||||
|
||||
```json
|
||||
{
|
||||
"took" : 4,
|
||||
"timed_out" : false,
|
||||
"_shards" : {
|
||||
"total" : 1,
|
||||
"successful" : 1,
|
||||
"skipped" : 0,
|
||||
"failed" : 0
|
||||
},
|
||||
"hits" : {
|
||||
"total" : {
|
||||
"value" : 1,
|
||||
"relation" : "eq"
|
||||
},
|
||||
"max_score" : 1.0,
|
||||
"hits" : [
|
||||
{
|
||||
"_index" : "testindex1",
|
||||
"_type" : "_doc",
|
||||
"_id" : "1",
|
||||
"_score" : 1.0,
|
||||
"_source" : {
|
||||
"name" : "Brand 1",
|
||||
"product_to_brand" : {
|
||||
"name" : "brand"
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Parent with many children
|
||||
|
||||
One parent can have many children. Create a mapping with multiple children:
|
||||
|
||||
```json
|
||||
PUT testindex1
|
||||
{
|
||||
"mappings": {
|
||||
"properties": {
|
||||
"parent_to_child": {
|
||||
"type": "join",
|
||||
"relations": {
|
||||
"parent": ["child 1", "child 2"]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Join field type notes
|
||||
|
||||
- There can only be one join field mapping in an index.
|
||||
- You need to provide the routing parameter when retrieving, updating, or deleting a child document. This is because parent and child documents in the same relation have to be indexed on the same shard.
|
||||
- Multiple parents are not supported.
|
||||
- You can add a child document to an existing document only if the existing document is already marked as a parent.
|
||||
- You can add a new relation to an existing join field.
|
||||
|
|
@ -0,0 +1,53 @@
|
|||
---
|
||||
layout: default
|
||||
title: Keyword
|
||||
nav_order: 46
|
||||
has_children: false
|
||||
parent: String field types
|
||||
grand_parent: Supported field types
|
||||
---
|
||||
|
||||
# Keyword field type
|
||||
|
||||
A keyword field type contains a string that is not analyzed. It allows only exact, case-sensitive matches.
|
||||
|
||||
If you need to use a field for full-text search, map it as [`text`]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/text/) instead.
|
||||
{: .note }
|
||||
|
||||
## Example
|
||||
|
||||
Create a mapping with a keyword field:
|
||||
|
||||
```json
|
||||
PUT movies
|
||||
{
|
||||
"mappings" : {
|
||||
"properties" : {
|
||||
"genre" : {
|
||||
"type" : "keyword"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Parameters
|
||||
|
||||
The following table lists the parameters accepted by keyword field types. All parameters are optional.
|
||||
|
||||
Parameter | Description
|
||||
:--- | :---
|
||||
`boost` | A floating-point value that specifies the weight of this field toward the relevance score. Values above 1.0 increase the field's relevance. Values between 0.0 and 1.0 decrease the field's relevance. Default is 1.0.
|
||||
`doc_values` | A Boolean value that specifies whether the field should be stored on disk so that it can be used for aggregations, sorting, or scripting. Default is `false`.
|
||||
`eager_global_ordinals` | Specifies whether global ordinals should be loaded eagerly on refresh. If the field is often used for aggregations, this parameter should be set to `true`. Default is `false`.
|
||||
`fields` | To index the same string in several ways (for example, as a keyword and text), provide the fields parameter. You can specify one version of the field to be used for search and another to be used for sorting and aggregations.
|
||||
`ignore_above` | Any string longer than this integer value should not be indexed. Default is 2147483647. Default dynamic mapping creates a keyword subfield for which `ignore_above` is set to 256.
|
||||
`index` | A Boolean value that specifies whether the field should be searchable. Default is `true`.
|
||||
`index_options` | Information to be stored in the index that will be considered when calculating relevance scores. Can be set to `freqs` for term frequency. Default is `docs`.
|
||||
`meta` | Accepts metadata for this field.
|
||||
`normalizer` | Specifies how to preprocess this field before indexing (for example, make it lowercase). Default is `null` (no preprocessing).
|
||||
`norms` | A Boolean value that specifies whether the field length should be used when calculating relevance scores. Default is `false`.
|
||||
[`null_value`]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/index#null-value) | A value to be used in place of `null`. Must be of the same type as the field. If this parameter is not specified, the field is treated as missing when its value is `null`. Default is `null`.
|
||||
`similarity` | The ranking algorithm for calculating relevance scores. Default is `BM25`.
|
||||
`split_queries_on_whitespace` | A Boolean value that specifies whether full-text queries should be split on whitespace. Default is `false`.
|
||||
`store` | A Boolean value that specifies whether the field value should be stored and can be retrieved separately from the _source field. Default is `false`.
|
||||
|
|
@ -0,0 +1,199 @@
|
|||
---
|
||||
layout: default
|
||||
title: Nested
|
||||
nav_order: 42
|
||||
has_children: false
|
||||
parent: Object field types
|
||||
grand_parent: Supported field types
|
||||
---
|
||||
|
||||
# Nested field type
|
||||
|
||||
A nested field type is a special type of [object field type]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/object/).
|
||||
|
||||
Any object field can take an array of objects. Each of the objects in the array is dynamically mapped as an object field type and stored in flattened form. This means that the objects in the array are broken down into individual fields, and values for each field across all objects are stored together. It is sometimes necessary to use the nested type to preserve a nested object as a whole so that you can perform a search on it.
|
||||
|
||||
## Flattened form
|
||||
|
||||
By default, each of the nested objects is dynamically mapped as object field type. Any object field can take an array of objects.
|
||||
|
||||
```json
|
||||
PUT testindex1/_doc/100
|
||||
{
|
||||
"patients": [
|
||||
{"name" : "John Doe", "age" : 56, "smoker" : true},
|
||||
{"name" : "Mary Major", "age" : 85, "smoker" : false}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
When these objects are stored, they are flattened, so their internal represenation has an array of all values for each field:
|
||||
|
||||
```json
|
||||
{
|
||||
"patients.name" : ["John Doe", "Mary Major"],
|
||||
"patients.age" : [56, 85],
|
||||
"smoker" : [true, false]
|
||||
}
|
||||
```
|
||||
|
||||
Some queries will work correctly in this representation. If you search for patients older than 75 OR smokers, document 100 should match.
|
||||
|
||||
```json
|
||||
GET testindex1/_search
|
||||
{
|
||||
"query": {
|
||||
"bool": {
|
||||
"should": [
|
||||
{
|
||||
"term": {
|
||||
"patients.smoker": true
|
||||
}
|
||||
},
|
||||
{
|
||||
"range": {
|
||||
"patients.age": {
|
||||
"gte": 75
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The query correctly returns document 100:
|
||||
|
||||
```json
|
||||
{
|
||||
"took" : 3,
|
||||
"timed_out" : false,
|
||||
"_shards" : {
|
||||
"total" : 1,
|
||||
"successful" : 1,
|
||||
"skipped" : 0,
|
||||
"failed" : 0
|
||||
},
|
||||
"hits" : {
|
||||
"total" : {
|
||||
"value" : 1,
|
||||
"relation" : "eq"
|
||||
},
|
||||
"max_score" : 1.3616575,
|
||||
"hits" : [
|
||||
{
|
||||
"_index" : "testindex1",
|
||||
"_type" : "_doc",
|
||||
"_id" : "100",
|
||||
"_score" : 1.3616575,
|
||||
"_source" : {
|
||||
"patients" : [
|
||||
{
|
||||
"name" : "John Doe",
|
||||
"age" : "56",
|
||||
"smoker" : true
|
||||
},
|
||||
{
|
||||
"name" : "Mary Major",
|
||||
"age" : "85",
|
||||
"smoker" : false
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Alternatively, if you search for patients older than 75 AND smokers, document 100 should not match.
|
||||
|
||||
```json
|
||||
GET testindex1/_search
|
||||
{
|
||||
"query": {
|
||||
"bool": {
|
||||
"must": [
|
||||
{
|
||||
"term": {
|
||||
"patients.smoker": true
|
||||
}
|
||||
},
|
||||
{
|
||||
"range": {
|
||||
"patients.age": {
|
||||
"gte": 75
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
However, this query still incorrectly returns document 100. This is because the relation between age and smoking was lost when arrays of values for individual fields were created.
|
||||
|
||||
## Nested field type
|
||||
|
||||
Nested objects are stored as separate documents, and the parent object has references to its children. To mark objects as nested, create a mapping with a nested field type.
|
||||
|
||||
```json
|
||||
PUT testindex1
|
||||
{
|
||||
"mappings" : {
|
||||
"properties": {
|
||||
"patients": {
|
||||
"type" : "nested"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Then, index a document with a nested field type:
|
||||
|
||||
```json
|
||||
PUT testindex1/_doc/100
|
||||
{
|
||||
"patients": [
|
||||
{"name" : "John Doe", "age" : 56, "smoker" : true},
|
||||
{"name" : "Mary Major", "age" : 85, "smoker" : false}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Now if you run the same query to search for patients older than 75 AND smokers, nothing is returned, which is correct.
|
||||
|
||||
```json
|
||||
{
|
||||
"took" : 3,
|
||||
"timed_out" : false,
|
||||
"_shards" : {
|
||||
"total" : 1,
|
||||
"successful" : 1,
|
||||
"skipped" : 0,
|
||||
"failed" : 0
|
||||
},
|
||||
"hits" : {
|
||||
"total" : {
|
||||
"value" : 0,
|
||||
"relation" : "eq"
|
||||
},
|
||||
"max_score" : null,
|
||||
"hits" : [ ]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Parameters
|
||||
|
||||
The following table lists the parameters accepted by object field types. All parameters are optional.
|
||||
|
||||
Parameter | Description
|
||||
:--- | :---
|
||||
[`dynamic`]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/object#the-dynamic-parameter) | Specifies whether new fields can be dynamically added to this object. Valid values are `true`, `false`, and `strict`. Default is `true`.
|
||||
`include_in_parent` | A Boolean value that specifies whether all fields in the child nested object should also be added to the parent document in flattened form. Default is `false`.
|
||||
`incude_in_root` | A Boolean value that specifies whether all fields in the child nested object should also be added to the root document in flattened form. Default is `false`.
|
||||
`properties` | Fields of this object, which can be of any supported type. New properties can be dynamically added to this object if `dynamic` is set to `true`.
|
||||
|
|
@ -0,0 +1,113 @@
|
|||
---
|
||||
layout: default
|
||||
title: Numeric field types
|
||||
parent: Supported field types
|
||||
nav_order: 15
|
||||
has_children: false
|
||||
---
|
||||
|
||||
# Numeric field types
|
||||
|
||||
The following table lists all numeric field types that OpenSearch supports.
|
||||
|
||||
Field data type | Description
|
||||
:--- | :---
|
||||
`byte` | A signed 8-bit integer. Minimum is -128. Maximum is 127.
|
||||
`double` | A double-precision 64-bit IEEE 754 floating-point value. Minimum magnitude is 2<sup>-1074 </sup>. Maximum magnitude is (2 − 2<sup>-52</sup>) · 2<sup>1023</sup>. The number of significant bits is 53. The number of significant digits is 15.95.
|
||||
`float` | A single-precision 32-bit IEEE 754 floating-point value. Minimum magnitude is 2<sup>-149 </sup>. Maximum magnitude is (2 − 2<sup>-23</sup>) · 2<sup>127</sup>. The number of significant bits is 24. The number of significant digits is 7.22.
|
||||
`half_float` | A half-precision 16-bit IEEE 754 floating-point value. Minimum magnitude is 2<sup>-24 </sup>. Maximum magnitude is 65504. The number of significant bits is 11. The number of significant digits is 3.31.
|
||||
`integer` | A signed 32-bit integer. Minimum is -2<sup>31</sup>. Maximum is 2<sup>31</sup> − 1.
|
||||
`long` | A signed 64-bit integer. Minimum is -2<sup>63</sup>. Maximum is 2<sup>63</sup> − 1.
|
||||
`short` | A signed 16-bit integer. Minimum is -2<sup>15</sup>. Maximum is 2<sup>15</sup> − 1.
|
||||
|
||||
:--- | :---
|
||||
[`scaled_float`](#scaled-float-field-type) | A floating-point value that is multiplied by the double scale factor and stored as a long value.
|
||||
|
||||
Integer, long, float, and double field types have corresponding [range field types]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/range/).
|
||||
{: .note }
|
||||
|
||||
If your numeric field contains an identifier such as an ID, you can map this field as a [keyword]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/keyword/) to optimize for faster term-level queries. If you need to use range queries on this field, you can map this field as a numeric field type in addition to a keyword field type.
|
||||
{: .tip }
|
||||
|
||||
## Example
|
||||
|
||||
Create a mapping where integer_value is an integer field:
|
||||
|
||||
```json
|
||||
PUT testindex
|
||||
{
|
||||
"mappings" : {
|
||||
"properties" : {
|
||||
"integer_value" : {
|
||||
"type" : "integer"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Index a document with an integer value:
|
||||
|
||||
```json
|
||||
PUT testindex/_doc/1
|
||||
{
|
||||
"integer_value" : 123
|
||||
}
|
||||
```
|
||||
|
||||
## Scaled float field type
|
||||
|
||||
A scaled float field type is a floating-point value that is multiplied by the scale factor and stored as a long value. It takes all optional parameters taken by number field types, plus an additional scaling_factor parameter. The scale factor is required when creating a scaled float.
|
||||
|
||||
Scaled floats are useful for saving disk space. Larger scaling_factor values lead to better accuracy but higher space overhead.
|
||||
{: .note }
|
||||
|
||||
## Scaled float example
|
||||
|
||||
Create a mapping where `scaled` is a scaled_float field:
|
||||
|
||||
```json
|
||||
PUT testindex
|
||||
{
|
||||
"mappings" : {
|
||||
"properties" : {
|
||||
"scaled" : {
|
||||
"type" : "scaled_float",
|
||||
"scaling_factor" : 10
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Index a document with a scaled_float value:
|
||||
|
||||
```json
|
||||
PUT testindex/_doc/1
|
||||
{
|
||||
"scaled" : 2.3
|
||||
}
|
||||
```
|
||||
|
||||
The `scaled` value will be stored as 23.
|
||||
|
||||
## Parameters
|
||||
|
||||
The following table lists the parameters accepted by numeric field types. All parameters are optional.
|
||||
|
||||
Parameter | Description
|
||||
:--- | :---
|
||||
`boost` | A floating-point value that specifies the weight of this field toward the relevance score. Values above 1.0 increase the field's relevance. Values between 0.0 and 1.0 decrease the field's relevance. Default is 1.0.
|
||||
`coerce` | A Boolean value that signals to truncate decimals for integer values and to convert strings to numeric values. Default is `true`.
|
||||
`doc_values` | A Boolean value that specifies whether the field should be stored on disk so that it can be used for aggregations, sorting, or scripting. Default is `false`.
|
||||
`ignore_malformed` | A Boolean value that specifies to ignore malformed values and not to throw an exception. Default is `false`.
|
||||
`index` | A Boolean value that specifies whether the field should be searchable. Default is `true`.
|
||||
`meta` | Accepts metadata for this field.
|
||||
[`null_value`]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/index#null-value) | A value to be used in place of `null`. Must be of the same type as the field. If this parameter is not specified, the field is treated as missing when its value is `null`. Default is `null`.
|
||||
`store` | A Boolean value that specifies whether the field value should be stored and can be retrieved separately from the _source field. Default is `false`.
|
||||
|
||||
Scaled float has an additional required parameter: `scaling_factor`.
|
||||
|
||||
Parameter | Description
|
||||
:--- | :---
|
||||
`scaling_factor` | A double value that is multiplied by the field value and rounded to the nearest long. Required.
|
||||
|
|
@ -0,0 +1,19 @@
|
|||
---
|
||||
layout: default
|
||||
title: Object field types
|
||||
nav_order: 40
|
||||
has_children: true
|
||||
has_toc: false
|
||||
parent: Supported field types
|
||||
---
|
||||
|
||||
# Object field types
|
||||
|
||||
The following table lists all object field types that OpenSearch supports.
|
||||
|
||||
Field data type | Description
|
||||
:--- | :---
|
||||
[`object`]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/object/) | A JSON object.
|
||||
[`nested`]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/nested/) | Used when objects in an array need to be indexed independently as separate documents.
|
||||
[`join`]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/join/) | Establishes a parent-child relationship between documents in the same index.
|
||||
|
||||
|
|
@ -0,0 +1,146 @@
|
|||
---
|
||||
layout: default
|
||||
title: Object
|
||||
nav_order: 41
|
||||
has_children: false
|
||||
parent: Object field types
|
||||
grand_parent: Supported field types
|
||||
---
|
||||
|
||||
# Object field type
|
||||
|
||||
An object field type contains a JSON object (a set of name/value pairs). A value in a JSON object may be another JSON object. It is not necessary to specify `object` as the type when mapping object fields because `object` is the default type.
|
||||
|
||||
## Example
|
||||
|
||||
Create a mapping with an object field:
|
||||
|
||||
```json
|
||||
PUT testindex1/_mappings
|
||||
{
|
||||
"properties": {
|
||||
"patient": {
|
||||
"properties" :
|
||||
{
|
||||
"name" : {
|
||||
"type" : "text"
|
||||
},
|
||||
"id" : {
|
||||
"type" : "keyword"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Index a document with an object field:
|
||||
|
||||
```json
|
||||
PUT testindex1/_doc/1
|
||||
{
|
||||
"patient": {
|
||||
"name" : "John Doe",
|
||||
"id" : "123456"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Nested objects are stored as flat key/value pairs internally. To refer to a field in a nested object, use `parent field`.`child field` (for example, `patient.id`).
|
||||
|
||||
Search for a patient with ID 123456:
|
||||
|
||||
```json
|
||||
GET testindex1/_search
|
||||
{
|
||||
"query": {
|
||||
"term" : {
|
||||
"patient.id" : "123456"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Parameters
|
||||
|
||||
The following table lists the parameters accepted by object field types. All parameters are optional.
|
||||
|
||||
Parameter | Description
|
||||
:--- | :---
|
||||
[`dynamic`](#the-dynamic-parameter) | Specifies whether new fields can be dynamically added to this object. Valid values are `true`, `false`, and `strict`. Default is `true`.
|
||||
`enabled` | A Boolean value that specifies whether the JSON contents of the object should be parsed. If `enabled` is set to `false`, the object's contents are not indexed or searchable, but they are still retrievable from the _source field. Default is `true`.
|
||||
`properties` | Fields of this object, which can be of any supported type. New properties can be dynamically added to this object if `dynamic` is set to `true`.
|
||||
|
||||
### The `dynamic` parameter
|
||||
|
||||
The `dynamic` parameter specifies whether new fields can be dynamically added to an object that is already indexed.
|
||||
|
||||
For example, you can initially create a mapping with a `patient` object that has only one field:
|
||||
|
||||
```json
|
||||
PUT testindex1/_mappings
|
||||
{
|
||||
"properties": {
|
||||
"patient": {
|
||||
"properties" :
|
||||
{
|
||||
"name" : {
|
||||
"type" : "text"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Then you index a document with a new `id` field in `patient`:
|
||||
|
||||
```json
|
||||
PUT testindex1/_doc/1
|
||||
{
|
||||
"patient": {
|
||||
"name" : "John Doe",
|
||||
"id" : "123456"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
As a result, the field `id` is added to the mappings:
|
||||
|
||||
```json
|
||||
{
|
||||
"testindex1" : {
|
||||
"mappings" : {
|
||||
"properties" : {
|
||||
"patient" : {
|
||||
"properties" : {
|
||||
"id" : {
|
||||
"type" : "text",
|
||||
"fields" : {
|
||||
"keyword" : {
|
||||
"type" : "keyword",
|
||||
"ignore_above" : 256
|
||||
}
|
||||
}
|
||||
},
|
||||
"name" : {
|
||||
"type" : "text"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The `dynamic` parameter has the following valid values.
|
||||
|
||||
Value | Description
|
||||
:--- | :---
|
||||
`true` | New fields can be added to the mapping dynamically. This is the default.
|
||||
`false` | New fields cannot be added to the mapping dynamically. If a new field is detected, it is not indexed or searchable. However, it is still retrievable from the _source field.
|
||||
`strict` | When new fields are added to the mapping dynamically, an exception is thrown. To add a new field to an object, you have to add it to the mapping first.
|
||||
|
||||
Inner objects inherit the `dynamic` parameter value from their parent unless they declare their own `dynamic` parameter value.
|
||||
{: .note }
|
||||
|
|
@ -0,0 +1,154 @@
|
|||
---
|
||||
layout: default
|
||||
title: Percolator
|
||||
nav_order: 65
|
||||
has_children: false
|
||||
parent: Supported field types
|
||||
---
|
||||
|
||||
# Percolator field type
|
||||
|
||||
A percolator field type specifies to treat this field as a query. Any JSON object field can be marked as a percolator field. Normally, documents are indexed and searches are run against them. When you use a percolator field, you store a search, and later the percolate query matches documents to that search.
|
||||
|
||||
## Example
|
||||
|
||||
A customer is searching for a table priced at $400 or less and wants to create an alert for this search.
|
||||
|
||||
Create a mapping assigning a percolator field type to the query field:
|
||||
|
||||
```json
|
||||
PUT testindex1
|
||||
{
|
||||
"mappings": {
|
||||
"properties": {
|
||||
"search": {
|
||||
"properties": {
|
||||
"query": {
|
||||
"type": "percolator"
|
||||
}
|
||||
}
|
||||
},
|
||||
"price": {
|
||||
"type": "float"
|
||||
},
|
||||
"item": {
|
||||
"type": "text"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Index a query:
|
||||
|
||||
```json
|
||||
PUT testindex1/_doc/1
|
||||
{
|
||||
"search": {
|
||||
"query": {
|
||||
"bool": {
|
||||
"filter": [
|
||||
{
|
||||
"match": {
|
||||
"item": {
|
||||
"query": "table"
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
"range": {
|
||||
"price": {
|
||||
"lte": 400.00
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Fields referenced in the query must already exist in the mapping.
|
||||
{: .note }
|
||||
|
||||
Run a percolate query to search for matching documents:
|
||||
|
||||
```json
|
||||
GET testindex1/_search
|
||||
{
|
||||
"query" : {
|
||||
"bool" : {
|
||||
"filter" :
|
||||
{
|
||||
"percolate" : {
|
||||
"field" : "search.query",
|
||||
"document" : {
|
||||
"item" : "Mahogany table",
|
||||
"price": 399.99
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The response contains the originally indexed query:
|
||||
|
||||
```json
|
||||
{
|
||||
"took" : 30,
|
||||
"timed_out" : false,
|
||||
"_shards" : {
|
||||
"total" : 1,
|
||||
"successful" : 1,
|
||||
"skipped" : 0,
|
||||
"failed" : 0
|
||||
},
|
||||
"hits" : {
|
||||
"total" : {
|
||||
"value" : 1,
|
||||
"relation" : "eq"
|
||||
},
|
||||
"max_score" : 0.0,
|
||||
"hits" : [
|
||||
{
|
||||
"_index" : "testindex1",
|
||||
"_type" : "_doc",
|
||||
"_id" : "1",
|
||||
"_score" : 0.0,
|
||||
"_source" : {
|
||||
"search" : {
|
||||
"query" : {
|
||||
"bool" : {
|
||||
"filter" : [
|
||||
{
|
||||
"match" : {
|
||||
"item" : {
|
||||
"query" : "table"
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
"range" : {
|
||||
"price" : {
|
||||
"lte" : 400.0
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"fields" : {
|
||||
"_percolator_document_slot" : [
|
||||
0
|
||||
]
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
|
@ -0,0 +1,155 @@
|
|||
---
|
||||
layout: default
|
||||
title: Range field types
|
||||
nav_order: 35
|
||||
has_children: false
|
||||
parent: Supported field types
|
||||
---
|
||||
|
||||
# Range field types
|
||||
|
||||
The following table lists all range field types that OpenSearch supports.
|
||||
|
||||
Field data type | Description
|
||||
:--- | :---
|
||||
`integer_range` | A range of [integer]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/numeric/) values.
|
||||
`long_range` | A range of [long]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/numeric/) values.
|
||||
`double_range` | A range of [double]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/numeric/) values.
|
||||
`float_range` | A range of [float]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/numeric/) values.
|
||||
`ip_range` | A range of [IP addresses]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/ip/) in IPv4 or IPv6 format. Start and end IP addresses may be in different formats.
|
||||
`date_range` | A range of [date]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/date/) values. Start and end dates may be in different [formats]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/date/#formats). Internally, all dates are stored as unsigned 64-bit integers representing milliseconds since the epoch.
|
||||
|
||||
## Example
|
||||
|
||||
Create a mapping with a double range and a date range:
|
||||
|
||||
```json
|
||||
PUT testindex
|
||||
{
|
||||
"mappings" : {
|
||||
"properties" : {
|
||||
"gpa" : {
|
||||
"type" : "double_range"
|
||||
},
|
||||
"graduation_date" : {
|
||||
"type" : "date_range",
|
||||
"format" : "strict_year_month||strict_year_month_day"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Index a document with a double range and a date range:
|
||||
|
||||
```json
|
||||
PUT testindex/_doc/1
|
||||
{
|
||||
"gpa" : {
|
||||
"gte" : 1.0,
|
||||
"lte" : 4.0
|
||||
},
|
||||
"graduation_date" : {
|
||||
"gte" : "2019-05-01",
|
||||
"lte" : "2019-05-15"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
You can use a [term query](#term-query) or a [range query](#range-query) to search for values within range fields.
|
||||
|
||||
### Term query
|
||||
|
||||
A term query takes a value and matches all range fields for which the value is within the range.
|
||||
|
||||
The following query will return document 1 because 3.5 is within the range [1.0, 4.0].
|
||||
|
||||
```json
|
||||
GET testindex/_search
|
||||
{
|
||||
"query" : {
|
||||
"term" : {
|
||||
"gpa" : {
|
||||
"value" : 3.5
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Range query
|
||||
|
||||
A range query on a range field returns documents within that range. Along with the field to be matched, range queries take the following optional parameters.
|
||||
|
||||
Parameter | Description
|
||||
:--- | :---
|
||||
format | A [format]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/date/#formats) for dates in this query. Default is the field's mapped format.
|
||||
relation | Provides a relation between the query's date range and the document's date range. There are three types of relations that you can specify:<br> 1. `intersects` matches documents for which there are dates that belong to both the query's date range and document's date range. This is the default. <br> 2. `contains` matches documents for which the query's date range is a subset of the document's date range. <br> 3. `within` matches documents for which the document's date range is a subset of the query's date range.
|
||||
|
||||
To use a date format other than the field's mapped format in a query, specify it in the `format` field.
|
||||
|
||||
Query for all graduation dates in 2019, providing the date range in a "MM/dd/yyyy" format:
|
||||
|
||||
```json
|
||||
GET testindex1/_search
|
||||
{
|
||||
"query": {
|
||||
"range": {
|
||||
"graduation_date": {
|
||||
"gte": "01/01/2019",
|
||||
"lte": "12/31/2019",
|
||||
"format": "MM/dd/yyyy",
|
||||
"relation" : "within"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The above query will return document 1 for the `within` and `intersects` relations but will not return it for the `contains` relation.
|
||||
|
||||
### IP address ranges
|
||||
|
||||
You can specify IP address ranges in two formats: as a range and in [CIDR notation](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing#CIDR_notation).
|
||||
|
||||
Create a mapping with an IP address range:
|
||||
|
||||
```json
|
||||
PUT testindex
|
||||
{
|
||||
"mappings" : {
|
||||
"properties" : {
|
||||
"ip_address_range" : {
|
||||
"type" : "ip_range"
|
||||
},
|
||||
"ip_address_cidr" : {
|
||||
"type" : "ip_range"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Index a document with IP address ranges in both formats:
|
||||
|
||||
```json
|
||||
PUT testindex/_doc/2
|
||||
{
|
||||
"ip_address_range" : {
|
||||
"gte" : "10.24.34.0",
|
||||
"lte" : "10.24.35.255"
|
||||
},
|
||||
"ip_address_cidr" : "10.24.34.0/24"
|
||||
}
|
||||
```
|
||||
|
||||
## Parameters
|
||||
|
||||
The following table lists the parameters accepted by range field types. All parameters are optional.
|
||||
|
||||
Parameter | Description
|
||||
:--- | :---
|
||||
`boost` | A floating-point value that specifies the weight of this field toward the relevance score. Values above 1.0 increase the field's relevance. Values between 0.0 and 1.0 decrease the field's relevance. Default is 1.0.
|
||||
`coerce` | A Boolean value that signals to truncate decimals for integer values and to convert strings to numeric values. Default is `true`.
|
||||
`index` | A Boolean value that specifies whether the field should be searchable. Default is `true`.
|
||||
`store` | A Boolean value that specifies whether the field value should be stored and can be retrieved separately from the _source field. Default is `false`.
|
||||
|
|
@ -0,0 +1,264 @@
|
|||
---
|
||||
layout: default
|
||||
title: Rank field types
|
||||
nav_order: 60
|
||||
has_children: false
|
||||
parent: Supported field types
|
||||
---
|
||||
|
||||
# Rank field types
|
||||
|
||||
The following table lists all rank field types that OpenSearch supports.
|
||||
|
||||
Field data type | Description
|
||||
:--- | :---
|
||||
[`rank_feature`](#rank-feature) | Boosts or decreases the relevance score of documents.
|
||||
[`rank_features`](#rank-features) | Boosts or decreases the relevance score of documents. Used when the list of features is sparse.
|
||||
|
||||
Rank feature and rank features fields can be queried with [rank feature queries](#rank-feature-query) only. They do not support aggregating or sorting.
|
||||
{: .note }
|
||||
|
||||
## Rank feature
|
||||
|
||||
A rank feature field type uses a positive [float]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/numeric/) value to boost or decrease the relevance score of a document in a `rank_feature` query. By default, this value boosts the relevance score. To decrease the relevance score, set the optional `positive_score_impact` parameter to false.
|
||||
|
||||
### Example
|
||||
|
||||
Create a mapping with a rank feature field:
|
||||
|
||||
```json
|
||||
PUT chessplayers
|
||||
{
|
||||
"mappings": {
|
||||
"properties": {
|
||||
"name" : {
|
||||
"type" : "text"
|
||||
},
|
||||
"rating": {
|
||||
"type": "rank_feature"
|
||||
},
|
||||
"age": {
|
||||
"type": "rank_feature",
|
||||
"positive_score_impact": false
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Index three documents with a rank_feature field that boosts the score (`rating`) and a rank_feature field that decreases the score (`age`):
|
||||
|
||||
```json
|
||||
PUT testindex1/_doc/1
|
||||
{
|
||||
"name" : "John Doe",
|
||||
"rating" : 2554,
|
||||
"age" : 75
|
||||
}
|
||||
|
||||
PUT testindex1/_doc/2
|
||||
{
|
||||
"name" : "Kwaku Mensah",
|
||||
"rating" : 2067,
|
||||
"age": 10
|
||||
}
|
||||
|
||||
PUT testindex1/_doc/3
|
||||
{
|
||||
"name" : "Nikki Wolf",
|
||||
"rating" : 1864,
|
||||
"age" : 22
|
||||
}
|
||||
```
|
||||
|
||||
## Rank feature query
|
||||
|
||||
Using a rank feature query, you can rank players by rating, by age, or by both rating and age. If you rank players by rating, higher-rated players will have higher relevance scores. If you rank players by age, younger players will have higher relevance scores.
|
||||
|
||||
Use a rank feature query to search for players based on age and rating:
|
||||
|
||||
```json
|
||||
GET chessplayers/_search
|
||||
{
|
||||
"query": {
|
||||
"bool": {
|
||||
"should": [
|
||||
{
|
||||
"rank_feature": {
|
||||
"field": "rating"
|
||||
}
|
||||
},
|
||||
{
|
||||
"rank_feature": {
|
||||
"field": "age"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
When ranked by both age and rating, younger players and players who are more highly ranked score better:
|
||||
|
||||
```json
|
||||
{
|
||||
"took" : 2,
|
||||
"timed_out" : false,
|
||||
"_shards" : {
|
||||
"total" : 1,
|
||||
"successful" : 1,
|
||||
"skipped" : 0,
|
||||
"failed" : 0
|
||||
},
|
||||
"hits" : {
|
||||
"total" : {
|
||||
"value" : 3,
|
||||
"relation" : "eq"
|
||||
},
|
||||
"max_score" : 1.2093145,
|
||||
"hits" : [
|
||||
{
|
||||
"_index" : "chessplayers",
|
||||
"_type" : "_doc",
|
||||
"_id" : "2",
|
||||
"_score" : 1.2093145,
|
||||
"_source" : {
|
||||
"name" : "Kwaku Mensah",
|
||||
"rating" : 1967,
|
||||
"age" : 10
|
||||
}
|
||||
},
|
||||
{
|
||||
"_index" : "chessplayers",
|
||||
"_type" : "_doc",
|
||||
"_id" : "3",
|
||||
"_score" : 1.0150313,
|
||||
"_source" : {
|
||||
"name" : "Nikki Wolf",
|
||||
"rating" : 1864,
|
||||
"age" : 22
|
||||
}
|
||||
},
|
||||
{
|
||||
"_index" : "chessplayers",
|
||||
"_type" : "_doc",
|
||||
"_id" : "1",
|
||||
"_score" : 0.8098284,
|
||||
"_source" : {
|
||||
"name" : "John Doe",
|
||||
"rating" : 2554,
|
||||
"age" : 75
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Rank features
|
||||
|
||||
A rank features field type is similar to the rank feature field type, but it is more suitable for a sparse list of features. A rank features field can index numeric feature vectors that are later used to boost or decrease documents' relevance scores in `rank_feature` queries.
|
||||
|
||||
### Example
|
||||
|
||||
Create a mapping with a rank features field:
|
||||
|
||||
```json
|
||||
PUT testindex1
|
||||
{
|
||||
"mappings": {
|
||||
"properties": {
|
||||
"correlations": {
|
||||
"type": "rank_features"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
To index a document with a rank features field, use a hashmap with string keys and positive float values:
|
||||
|
||||
```json
|
||||
PUT testindex1/_doc/1
|
||||
{
|
||||
"correlations": {
|
||||
"young kids" : 1,
|
||||
"older kids" : 15,
|
||||
"teens" : 25.9
|
||||
}
|
||||
}
|
||||
|
||||
PUT testindex1/_doc/2
|
||||
{
|
||||
"correlations": {
|
||||
"teens": 10,
|
||||
"adults": 95.7
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Query the documents using a rank feature query:
|
||||
|
||||
```json
|
||||
GET testindex1/_search
|
||||
{
|
||||
"query": {
|
||||
"rank_feature": {
|
||||
"field": "correlations.teens"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The response is ranked by relevance score:
|
||||
|
||||
```json
|
||||
{
|
||||
"took" : 123,
|
||||
"timed_out" : false,
|
||||
"_shards" : {
|
||||
"total" : 1,
|
||||
"successful" : 1,
|
||||
"skipped" : 0,
|
||||
"failed" : 0
|
||||
},
|
||||
"hits" : {
|
||||
"total" : {
|
||||
"value" : 2,
|
||||
"relation" : "eq"
|
||||
},
|
||||
"max_score" : 0.6258503,
|
||||
"hits" : [
|
||||
{
|
||||
"_index" : "testindex1",
|
||||
"_type" : "_doc",
|
||||
"_id" : "1",
|
||||
"_score" : 0.6258503,
|
||||
"_source" : {
|
||||
"correlations" : {
|
||||
"young kids" : 1,
|
||||
"older kids" : 15,
|
||||
"teens" : 25.9
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
"_index" : "testindex1",
|
||||
"_type" : "_doc",
|
||||
"_id" : "2",
|
||||
"_score" : 0.39263803,
|
||||
"_source" : {
|
||||
"correlations" : {
|
||||
"teens" : 10,
|
||||
"adults" : 95.7
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Rank feature and rank features fields use top nine significant bits for precision, leading to about 0.4% relative error. Values are stored with a relative precision of 2<sup>−8</sup> = 0.00390625.
|
||||
{: .note }
|
||||
|
|
@ -0,0 +1,203 @@
|
|||
---
|
||||
layout: default
|
||||
title: Search as you type
|
||||
nav_order: 53
|
||||
has_children: false
|
||||
parent: Autocomplete field types
|
||||
grand_parent: Supported field types
|
||||
---
|
||||
|
||||
# Search-as-you-type field type
|
||||
|
||||
A search-as-you-type field type provides search-as-you-type functionality using both prefix and infix completion.
|
||||
|
||||
## Example
|
||||
|
||||
Mapping a search-as-you-type field creates n-gram subfields of this field, where n is in the range [2, `max_shingle_size`]. Additionally, it creates an index prefix subfield.
|
||||
|
||||
Create a mapping with a search-as-you-type field:
|
||||
|
||||
```json
|
||||
PUT books
|
||||
{
|
||||
"mappings": {
|
||||
"properties": {
|
||||
"suggestions": {
|
||||
"type": "search_as_you_type"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
In addition to the `suggestions` field, this creates `suggestions._2gram`, `suggestions._3gram`, and `suggestions._index_prefix` fields.
|
||||
|
||||
Index a document with a search-as-you-type field:
|
||||
|
||||
```json
|
||||
PUT books/_doc/1
|
||||
{
|
||||
"suggestions": "one two three four"
|
||||
}
|
||||
```
|
||||
|
||||
To match terms in any order, use a bool_prefix or multi-match query. These queries rank the documents in which search terms are in the specified order higher than the documents in which terms are out of order.
|
||||
|
||||
```json
|
||||
GET books/_search
|
||||
{
|
||||
"query": {
|
||||
"multi_match": {
|
||||
"query": "tw one",
|
||||
"type": "bool_prefix",
|
||||
"fields": [
|
||||
"suggestions",
|
||||
"suggestions._2gram",
|
||||
"suggestions._3gram"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The response contains the matching document:
|
||||
|
||||
```json
|
||||
{
|
||||
"took" : 13,
|
||||
"timed_out" : false,
|
||||
"_shards" : {
|
||||
"total" : 1,
|
||||
"successful" : 1,
|
||||
"skipped" : 0,
|
||||
"failed" : 0
|
||||
},
|
||||
"hits" : {
|
||||
"total" : {
|
||||
"value" : 1,
|
||||
"relation" : "eq"
|
||||
},
|
||||
"max_score" : 1.0,
|
||||
"hits" : [
|
||||
{
|
||||
"_index" : "books",
|
||||
"_type" : "_doc",
|
||||
"_id" : "1",
|
||||
"_score" : 1.0,
|
||||
"_source" : {
|
||||
"suggestions" : "one two three four"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
To match terms in order, use a match_phrase_prefix query:
|
||||
|
||||
```json
|
||||
GET books/_search
|
||||
{
|
||||
"query": {
|
||||
"match_phrase_prefix": {
|
||||
"suggestions": "two th"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The response contains the matching document:
|
||||
|
||||
```json
|
||||
{
|
||||
"took" : 23,
|
||||
"timed_out" : false,
|
||||
"_shards" : {
|
||||
"total" : 1,
|
||||
"successful" : 1,
|
||||
"skipped" : 0,
|
||||
"failed" : 0
|
||||
},
|
||||
"hits" : {
|
||||
"total" : {
|
||||
"value" : 1,
|
||||
"relation" : "eq"
|
||||
},
|
||||
"max_score" : 0.4793051,
|
||||
"hits" : [
|
||||
{
|
||||
"_index" : "books",
|
||||
"_type" : "_doc",
|
||||
"_id" : "1",
|
||||
"_score" : 0.4793051,
|
||||
"_source" : {
|
||||
"suggestions" : "one two three four"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
To match the last terms exactly, use a match_phrase query:
|
||||
|
||||
```json
|
||||
GET books/_search
|
||||
{
|
||||
"query": {
|
||||
"match_phrase": {
|
||||
"suggestions": "four"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Response:
|
||||
|
||||
```json
|
||||
{
|
||||
"took" : 2,
|
||||
"timed_out" : false,
|
||||
"_shards" : {
|
||||
"total" : 1,
|
||||
"successful" : 1,
|
||||
"skipped" : 0,
|
||||
"failed" : 0
|
||||
},
|
||||
"hits" : {
|
||||
"total" : {
|
||||
"value" : 1,
|
||||
"relation" : "eq"
|
||||
},
|
||||
"max_score" : 0.2876821,
|
||||
"hits" : [
|
||||
{
|
||||
"_index" : "books",
|
||||
"_type" : "_doc",
|
||||
"_id" : "1",
|
||||
"_score" : 0.2876821,
|
||||
"_source" : {
|
||||
"suggestions" : "one two three four"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Parameters
|
||||
|
||||
The following table lists the parameters accepted by search-as-you-type field types. All parameters are optional.
|
||||
|
||||
Parameter | Description
|
||||
:--- | :---
|
||||
`analyzer` | The analyzer to be used for this field. By default, it will be used at index time and at search time. To override it at search time, set the `search_analyzer` parameter. Default is the `standard` analyzer, which uses grammar-based tokenization and is based on the [Unicode Text Segmentation](https://unicode.org/reports/tr29/) algorithm. Configures the root field and subfields.
|
||||
`index` | A Boolean value that specifies whether the field should be searchable. Default is `true`. Configures the root field and subfields.
|
||||
`index_options` | Specifies the information to be stored in the index for search and highlighting. Valid values: `docs` (doc number only), `freqs` (doc number and term frequencies), `positions` (doc number, term frequencies, and term positions), `offsets` (doc number, term frequencies, term positions, and start and end character offsets). Default is `positions`. Configures the root field and subfields.
|
||||
`max_shingle_size` | An integer that specifies the maximum n-gram size. Valid values are in the range [2, 4]. N-grams to be created are in the range [2, `max_shingle_size`]. Default is 3, which creates a 2-gram and a 3-gram. Larger `max_shingle_size` values work better for more specific queries but lead to a larger index size.
|
||||
`norms` | A Boolean value that specifies whether the field length should be used when calculating relevance scores. Configures the root field and n-gram subfields (default is `false`). Does not configure the prefix subfield (in the prefix subfield, `norms` is `false`).
|
||||
`search_analyzer` | The analyzer to be used at search time. Default is the analyzer specified in the `analyzer` parameter. Configures the root field and subfields.
|
||||
`search_quote_analyzer` | The analyzer to be used at search time with phrases. Default is the analyzer specified in the `analyzer` parameter. Configures the root field and subfields.
|
||||
`similarity` | The ranking algorithm for calculating relevance scores. Default is `BM25`. Configures the root field and subfields.
|
||||
`store` | A Boolean value that specifies whether the field value should be stored and can be retrieved separately from the _source field. Default is `false`. Configures the root field only.
|
||||
[`term_vector`]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/text#term-vector-parameter) | A Boolean value that specifies whether a term vector for this field should be stored. Default is `no`. Configures the root field and n-gram subfields. Does not configure the prefix subfield.
|
||||
|
|
@ -0,0 +1,18 @@
|
|||
---
|
||||
layout: default
|
||||
title: String field types
|
||||
nav_order: 45
|
||||
has_children: true
|
||||
has_toc: false
|
||||
parent: Supported field types
|
||||
---
|
||||
|
||||
# String field types
|
||||
|
||||
The following table lists all string field types that OpenSearch supports.
|
||||
|
||||
Field data type | Description
|
||||
:--- | :---
|
||||
[`keyword`]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/keyword/) | A string that is not analyzed. Useful for exact-value search.
|
||||
[`text`]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/text/) | A string that is analyzed. Useful for full-text search.
|
||||
[`token_count`]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/token-count/) | Counts the number of tokens in a string.
|
||||
|
|
@ -0,0 +1,161 @@
|
|||
---
|
||||
layout: default
|
||||
title: Text
|
||||
nav_order: 47
|
||||
has_children: false
|
||||
parent: String field types
|
||||
grand_parent: Supported field types
|
||||
---
|
||||
|
||||
# Text field type
|
||||
|
||||
A text field type contains a string that is analyzed. It is used for full-text search because it allows partial matches. Searches with multiple terms can match some but not all of them. Depending on the analyzer, results can be case insensitive, stemmed, stopwords removed, synonyms applied, etc.
|
||||
|
||||
|
||||
If you need to use a field for exact-value search, map it as a [`keyword`]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/keyword/) instead.
|
||||
{: .note }
|
||||
|
||||
## Example
|
||||
|
||||
Create a mapping with a text field:
|
||||
|
||||
```json
|
||||
PUT movies
|
||||
{
|
||||
"mappings" : {
|
||||
"properties" : {
|
||||
"title" : {
|
||||
"type" : "text"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Parameters
|
||||
|
||||
The following table lists the parameters accepted by text field types. All parameters are optional.
|
||||
|
||||
Parameter | Description
|
||||
:--- | :---
|
||||
`analyzer` | The analyzer to be used for this field. By default, it will be used at index time and at search time. To override it at search time, set the `search_analyzer` parameter. Default is the `standard` analyzer, which uses grammar-based tokenization and is based on the [Unicode Text Segmentation](https://unicode.org/reports/tr29/) algorithm.
|
||||
`boost` | A floating-point value that specifies the weight of this field toward the relevance score. Values above 1.0 increase the field's relevance. Values between 0.0 and 1.0 decrease the field's relevance. Default is 1.0.
|
||||
`eager_global_ordinals` | Specifies whether global ordinals should be loaded eagerly on refresh. If the field is often used for aggregations, this parameter should be set to `true`. Default is `false`.
|
||||
`fielddata` | A Boolean value that specifies whether to access analyzed tokens for this field for sorting, aggregation, and scripting. Default is `false`.
|
||||
`fielddata_frequency_filter` | A JSON object that specifies to load into memory only those analyzed tokens whose document frequency is between the `min` and `max` values (provided as either an absolute number or a percentage). Frequency is computed per segment. Parameters: `min`, `max`, `min_segment_size`. Default is to load all analyzed tokens.
|
||||
`fields` | To index the same string in several ways (for example, as a keyword and text), provide the fields parameter. You can specify one version of the field to be used for search and another to be used for sorting and aggregations.
|
||||
`index` | A Boolean value that specifies whether the field should be searchable. Default is `true`.
|
||||
`index_options` | Specifies the information to be stored in the index for search and highlighting. Valid values: `docs` (doc number only), `freqs` (doc number and term frequencies), `positions` (doc number, term frequencies, and term positions), `offsets` (doc number, term frequencies, term positions, and start and end character offsets). Default is `positions`.
|
||||
`index_phrases` | A Boolean value that specifies to index 2-grams separately. 2-grams are combinations of two consecutive words in this field's string. Leads to faster exact phrase queries with no slop but a larger index. Works best when stopwords are not removed. Default is `false`.
|
||||
`index_prefixes` | A JSON object that specifies to index term prefixes separately. The number of characters in the prefix is between `min_chars` and `max_chars`, inclusive. Leads to faster prefix searches but a larger index. Optional parameters: `min_chars`, `max_chars`. Default `min_chars` is 2, `max_chars` is 5.
|
||||
`meta` | Accepts metadata for this field.
|
||||
`norms` | A Boolean value that specifies whether the field length should be used when calculating relevance scores. Default is `false`.
|
||||
`position_increment_gap` | When text fields are analyzed, they are assigned positions. If a field contained an array of strings, and these positions were consecutive, this would lead to potentially matching across different array elements. To prevent this, an artificial gap is inserted between consecutive array elements. You can change this gap by specifying an integer `position_increment_gap`. Note: If `slop` is greater than `position_element_gap`, matching across different array elements may occur. Default is 100.
|
||||
`similarity` | The ranking algorithm for calculating relevance scores. Default is `BM25`.
|
||||
[`term_vector`](#term-vector-parameter) | A Boolean value that specifies whether a term vector for this field should be stored. Default is `no`.
|
||||
|
||||
## Term vector parameter
|
||||
|
||||
A term vector is produced during analysis. It contains:
|
||||
- A list of terms.
|
||||
- The ordinal position of each term.
|
||||
- The start and end character offsets of the search string within the field.
|
||||
- Payloads (if available). Each term can have custom binary data associated with the term's position.
|
||||
|
||||
The `term_vector` field contains a JSON object that accepts the following parameters:
|
||||
|
||||
Parameter | Stored values
|
||||
:--- | :---
|
||||
`no` | None. This is the default.
|
||||
`yes` | Terms in the field.
|
||||
`with_offsets` | Terms and character offsets.
|
||||
`with_positions_offsets` | Terms, positions, and character offsets.
|
||||
`with_positions_offsets_payloads` | Terms, positions, character offsets, and payloads.
|
||||
`with_positions` | Terms and positions.
|
||||
`with_positions_payloads` | Terms, positions, and payloads.
|
||||
|
||||
Storing positions is useful for proximity queries. Storing character offsets is useful for highlighting.
|
||||
{: .tip }
|
||||
|
||||
## Example
|
||||
|
||||
Create a mapping with a text field that stores character offsets in a term vector:
|
||||
|
||||
```json
|
||||
PUT testindex
|
||||
{
|
||||
"mappings" : {
|
||||
"properties" : {
|
||||
"dob" : {
|
||||
"type" : "text",
|
||||
"term_vector": "with_positions_offsets"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Index a document with a text field:
|
||||
|
||||
```json
|
||||
PUT testindex/_doc/1
|
||||
{
|
||||
"dob" : "The patient's date of birth."
|
||||
}
|
||||
```
|
||||
|
||||
Query for "date of birth" and highlight it in the original field:
|
||||
|
||||
```json
|
||||
GET testindex/_search
|
||||
{
|
||||
"query": {
|
||||
"match": {
|
||||
"text": "date of birth"
|
||||
}
|
||||
},
|
||||
"highlight": {
|
||||
"fields": {
|
||||
"text": {}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The words "date of birth" are highlighted in the response:
|
||||
|
||||
```json
|
||||
{
|
||||
"took" : 854,
|
||||
"timed_out" : false,
|
||||
"_shards" : {
|
||||
"total" : 1,
|
||||
"successful" : 1,
|
||||
"skipped" : 0,
|
||||
"failed" : 0
|
||||
},
|
||||
"hits" : {
|
||||
"total" : {
|
||||
"value" : 1,
|
||||
"relation" : "eq"
|
||||
},
|
||||
"max_score" : 0.8630463,
|
||||
"hits" : [
|
||||
{
|
||||
"_index" : "testindex",
|
||||
"_type" : "_doc",
|
||||
"_id" : "1",
|
||||
"_score" : 0.8630463,
|
||||
"_source" : {
|
||||
"text" : "The patient's date of birth."
|
||||
},
|
||||
"highlight" : {
|
||||
"text" : [
|
||||
"The patient's <em>date</em> <em>of</em> <em>birth</em>."
|
||||
]
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
|
@ -0,0 +1,110 @@
|
|||
---
|
||||
layout: default
|
||||
title: Token count
|
||||
nav_order: 48
|
||||
has_children: false
|
||||
parent: String field types
|
||||
grand_parent: Supported field types
|
||||
---
|
||||
|
||||
# Token count field type
|
||||
|
||||
A token count field type stores the number of analyzed tokens in a string.
|
||||
|
||||
## Example
|
||||
|
||||
Create a mapping with a token count field:
|
||||
|
||||
```json
|
||||
PUT testindex
|
||||
{
|
||||
"mappings": {
|
||||
"properties": {
|
||||
"sentence": {
|
||||
"type": "text",
|
||||
"fields": {
|
||||
"num_words": {
|
||||
"type": "token_count",
|
||||
"analyzer": "english"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Index three documents with text fields:
|
||||
|
||||
```json
|
||||
PUT testindex/_doc/1
|
||||
{ "sentence": "To be, or not to be: that is the question." }
|
||||
|
||||
PUT testindex/_doc/2
|
||||
{ "sentence": "All the world’s a stage, and all the men and women are merely players." }
|
||||
|
||||
PUT testindex/_doc/3
|
||||
{ "sentence": "Now is the winter of our discontent." }
|
||||
```
|
||||
|
||||
Search for sentences with fewer than 10 words:
|
||||
|
||||
```json
|
||||
GET testindex/_search
|
||||
{
|
||||
"query": {
|
||||
"range": {
|
||||
"sentence.num_words": {
|
||||
"lt": 10
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The response contains one matching sentence:
|
||||
|
||||
```json
|
||||
{
|
||||
"took" : 8,
|
||||
"timed_out" : false,
|
||||
"_shards" : {
|
||||
"total" : 1,
|
||||
"successful" : 1,
|
||||
"skipped" : 0,
|
||||
"failed" : 0
|
||||
},
|
||||
"hits" : {
|
||||
"total" : {
|
||||
"value" : 1,
|
||||
"relation" : "eq"
|
||||
},
|
||||
"max_score" : 1.0,
|
||||
"hits" : [
|
||||
{
|
||||
"_index" : "testindex",
|
||||
"_type" : "_doc",
|
||||
"_id" : "3",
|
||||
"_score" : 1.0,
|
||||
"_source" : {
|
||||
"sentence" : "Now is the winter of our discontent."
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Parameters
|
||||
|
||||
The following table lists the parameters accepted by token count field types. The `analyzer` parameter is required; all other parameters are optional.
|
||||
|
||||
Parameter | Description
|
||||
:--- | :---
|
||||
`analyzer` | The analyzer to be used for this field. Specify an analyzer without token filters for optimal performance. Required.
|
||||
`boost` | A floating-point value that specifies the weight of this field toward the relevance score. Values above 1.0 increase the field's relevance. Values between 0.0 and 1.0 decrease the field's relevance. Default is 1.0.
|
||||
`doc_values` | A Boolean value that specifies whether the field should be stored on disk so that it can be used for aggregations, sorting, or scripting. Default is `false`.
|
||||
`enable_position_increments` | A Boolean value that specifies whether position increments should be counted. To avoid removing stopwords, set this field to `false`. Default is `true`.
|
||||
`index` | A Boolean value that specifies whether the field should be searchable. Default is `true`.
|
||||
[`null_value`]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/index#null-value) | A value to be used in place of `null`. Must be of the same type as the field. If this parameter is not specified, the field is treated as missing when its value is `null`. Default is `null`.
|
||||
`store` | A Boolean value that specifies whether the field value should be stored and can be retrieved separately from the _source field. Default is `false`.
|
||||
Loading…
Reference in New Issue