Skip to content

Commit 2602f65

Browse files
opensearch-trigger-bot[bot]opensearch-trigger-bot[bot]
authored
adding format mapping parameter docs (#9507) (#9620)
1 parent 94f1aa0 commit 2602f65

File tree

2 files changed

+96
-8
lines changed

2 files changed

+96
-8
lines changed

‎_field-types/mapping-parameters/format.md

+88
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
---
2+
layout: default
3+
title: Format
4+
parent: Mapping parameters
5+
grand_parent: Mapping and field types
6+
nav_order: 50
7+
has_children: false
8+
has_toc: false
9+
---
10+
11+
# Format
12+
13+
The `format` mapping parameter specifies the [built-in date formats]({{site.url}}{{site.baseurl}}/field-types/supported-field-types/date/#built-in-formats) that a date field can accept during indexing. By defining the expected date formats, you ensure that date values are correctly parsed and stored, facilitating accurate search and aggregation operations.
14+
15+
## Example: Defining a custom date format
16+
17+
Create an `events` index with the `event_date` field configured to a custom `yyyy-MM-dd HH:mm:ss` date format:
18+
19+
```json
20+
PUT events
21+
{
22+
"mappings": {
23+
"properties": {
24+
"event_date": {
25+
"type": "date",
26+
"format": "yyyy-MM-dd HH:mm:ss"
27+
}
28+
}
29+
}
30+
}
31+
```
32+
{% include copy-curl.html %}
33+
34+
Index a document using the specified format for the `event_date` field:
35+
36+
```json
37+
PUT events/_doc/1
38+
{
39+
"event_name": "Conference",
40+
"event_date": "2025-03-26 15:30:00"
41+
}
42+
```
43+
{% include copy-curl.html %}
44+
45+
## Example: Using multiple date formats
46+
47+
Create an index containing a `log_timestamp` field, which accepts both the custom `yyyy-MM-dd HH:mm:ss` date format and the `epoch_millis` format:
48+
49+
```json
50+
PUT logs
51+
{
52+
"mappings": {
53+
"properties": {
54+
"log_timestamp": {
55+
"type": "date",
56+
"format": "yyyy-MM-dd HH:mm:ss||epoch_millis"
57+
}
58+
}
59+
}
60+
}
61+
```
62+
{% include copy-curl.html %}
63+
64+
Index the first document using the custom format:
65+
66+
```json
67+
PUT logs/_doc/1
68+
{
69+
"message": "System rebooted",
70+
"log_timestamp": "2025-03-26 08:45:00"
71+
}
72+
```
73+
{% include copy-curl.html %}
74+
75+
Index the second document using the millisecond format:
76+
77+
```json
78+
PUT logs/_doc/2
79+
{
80+
"message": "System updated",
81+
"log_timestamp": 1711442700000
82+
}
83+
```
84+
{% include copy-curl.html %}
85+
86+
## Built-in date formats
87+
88+
For a comprehensive list of built-in date formats, see [Built-in formats]({{site.url}}{{site.baseurl}}/field-types/supported-field-types/date/#built-in-formats).

‎_field-types/mapping-parameters/index.md

+8-8
Original file line numberDiff line numberDiff line change
@@ -14,14 +14,14 @@ The following table lists OpenSearch mapping parameters.
1414

1515
Parameter | Description
1616
:--- | :---
17-
`analyzer` | Specifies the analyzer used to analyze string fields. Default is the `standard` analyzer, which is a general-purpose analyzer that splits text on white space and punctuation, converts to lowercase, and removes stop words. Allowed values are `standard`, `simple`, and `whitespace`.
18-
`boost` | Specifies a field-level boost factor applied at query time. Allows you to increase or decrease the relevance score of a specific field during search queries. Default boost value is `1.0`, which means no boost is applied. Allowed values are any positive floating-point number.
19-
`coerce` | Controls how values are converted to the expected field data type during indexing. Default value is `true`, which means that OpenSearch tries to coerce the value to the expected value type. Allowed values are `true` or `false`.
20-
`copy_to` | Copies the value of a field to another field. There is no default value for this parameter. Optional.
21-
`doc_values` | Specifies whether a field should be stored on disk to make sorting and aggregation faster. Default value is `true`, which means that the doc values are enabled. Allowed values are a single field name or a list of field names.
22-
`dynamic` | Determines whether new fields should be added dynamically. Default value is `true`, which means that new fields can be added dynamically. Allowed values are `true`, `false`, or `strict`.
23-
`enabled` | Specifies whether the field is enabled or disabled. Default value is `true`, which means that the field is enabled. Allowed values are `true` or `false`.
24-
`format` | Specifies the date format for date fields. There is no default value for this parameter. Allowed values are any valid date format string, such as `yyyy-MM-dd` or `epoch_millis`.
17+
[`analyzer`]({{site.url}}{{site.baseurl}}/field-types/mapping-parameters/analyzer/) | Specifies the analyzer used to analyze string fields. Default is the `standard` analyzer, which is a general-purpose analyzer that splits text on white space and punctuation, converts to lowercase, and removes stop words. Allowed values are `standard`, `simple`, or `whitespace`.
18+
[`boost`]({{site.url}}{{site.baseurl}}/field-types/mapping-parameters/boost/) | Specifies a field-level boost factor applied at query time. Allows you to increase or decrease the relevance score of a specific field during search queries. Default boost value is `1.0`, which means that no boost is applied. Allowed values are any positive floating-point number.
19+
[`coerce`]({{site.url}}{{site.baseurl}}/field-types/mapping-parameters/coerce/) | Controls how values are converted to the expected field data type during indexing. Default value is `true`, which means that OpenSearch tries to coerce the value to the expected value type. Allowed values are `true` or `false`.
20+
[`copy_to`]({{site.url}}{{site.baseurl}}/field-types/mapping-parameters/copy-to/) | Copies the value of a field to another field. There is no default value for this parameter. Optional.
21+
[`doc_values`]({{site.url}}{{site.baseurl}}/field-types/mapping-parameters/doc-values/) | Specifies whether a field should be stored on disk to make sorting and aggregation faster. Default value is `true`, which means that the doc values are enabled. Allowed values are a single field name or a list of field names.
22+
[`dynamic`]({{site.url}}{{site.baseurl}}/field-types/mapping-parameters/dynamic/) | Determines whether new fields should be added dynamically. Default value is `true`, which means that new fields can be added dynamically. Allowed values are `true`, `false`, or `strict`.
23+
[`enabled`]({{site.url}}{{site.baseurl}}/field-types/mapping-parameters/enabled/) | Specifies whether the field is enabled or disabled. Default value is `true`, which means that the field is enabled. Allowed values are `true` or `false`.
24+
[`format`]({{site.url}}{{site.baseurl}}/field-types/mapping-parameters/format/) | Specifies the date format for date fields. There is no default value for this parameter. Allowed values are any valid date format string, such as `yyyy-MM-dd` or `epoch_millis`.
2525
`ignore_above` | Skips indexing values that exceed the specified length. Default value is `2147483647`, which means that there is no limit on the field value length. Allowed values are any positive integer.
2626
[`ignore_malformed`]({{site.url}}{{site.baseurl}}/field-types/mapping-parameters/ignore-malformed/) | Specifies whether malformed values should be ignored. Default value is `false`, which means that malformed values are not ignored. Allowed values are `true` or `false`.
2727
`index` | Specifies whether a field should be indexed. Default value is `true`, which means that the field is indexed. Allowed values are `true` or `false`.

0 commit comments

Comments
 (0)