Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[DOCS] Edit validation section of dynamic templates docs #57510

Merged
merged 3 commits into from
Jun 2, 2020
Merged
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 20 additions & 19 deletions docs/reference/mapping/dynamic/templates.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -9,13 +9,13 @@ dynamically added fields based on:
* the full dotted path to the field, with <<path-match-unmatch,`path_match` and `path_unmatch`>>.

The original field name `{name}` and the detected datatype
`{dynamic_type`} <<template-variables,template variables>> can be used in
`{dynamic_type}` <<template-variables,template variables>> can be used in
the mapping specification as placeholders.

IMPORTANT: Dynamic field mappings are only added when a field contains a
concrete value -- not `null` or an empty array. This means that if the
`null_value` option is used in a `dynamic_template`, it will only be applied
after the first document with a concrete value for the field has been
`null_value` option is used in a `dynamic_template`, it will only be applied
after the first document with a concrete value for the field has been
indexed.

Dynamic templates are specified as an array of named objects:
Expand All @@ -37,19 +37,20 @@ Dynamic templates are specified as an array of named objects:
<2> The match conditions can include any of : `match_mapping_type`, `match`, `match_pattern`, `unmatch`, `path_match`, `path_unmatch`.
<3> The mapping that the matched field should use.

If a provided mapping contains an invalid mapping snippet then that results in
a validation error. Validation always occurs when applying the dynamic template
at index time or in most cases when updating the dynamic template.
If a provided mapping contains an invalid mapping snippet, a validation error
will be thrown. Validation occurs when applying the dynamic template at index time,
jrodewig marked this conversation as resolved.
Show resolved Hide resolved
and in most cases when the dynamic template is updated. Providing an invalid mapping
jrodewig marked this conversation as resolved.
Show resolved Hide resolved
snippet may cause updating or validating the dynamic template to fail under certain conditions:
jrodewig marked this conversation as resolved.
Show resolved Hide resolved

Whether updating the dynamic template fails when supplying an invalid mapping snippet depends on the following:
* If no `match_mapping_type` has been specified then if the template is valid with one predefined mapping type then
the mapping snippet is considered valid. However if at index time a field that matches with the template is indexed
as a different type then an validation error will occur at index time instead. For example configuring a dynamic
template with no `match_mapping_type` is considered valid as string type, but at index time a field that matches with
the dynamic template is indexed as a long, then at index time a validation error may still occur.
* If the `{{name}}` placeholder is used in the mapping snippet then the validation is skipped when updating
the dynamic template. This is because the field name is unknown at that time. The validation will then occur
when applying the template at index time.
* If no `match_mapping_type` has been specified, but the template is valid for at least one predefined mapping type,
jrodewig marked this conversation as resolved.
Show resolved Hide resolved
the mapping snippet is considered valid. However, a validation error will occur at index time if a field matching
jrodewig marked this conversation as resolved.
Show resolved Hide resolved
the template is indexed as a different type. For example, configuring a dynamic template with no `match_mapping_type`
is considered valid as string type, but if a field matching the dynamic template is indexed as a long, a validation
error may still occur at index time.
jrodewig marked this conversation as resolved.
Show resolved Hide resolved
jrodewig marked this conversation as resolved.
Show resolved Hide resolved

* If the `{{name}}` placeholder is used in the mapping snippet, validation is skipped when updating the dynamic
template because the field name is unknown at that time. Validation will instead occur when applying the template
jrodewig marked this conversation as resolved.
Show resolved Hide resolved
at index time.

Templates are processed in order -- the first matching template wins. When
putting new dynamic templates through the <<indices-put-mapping, put mapping>> API,
Expand All @@ -59,16 +60,16 @@ reordered or deleted after they were initially added.
[[match-mapping-type]]
==== `match_mapping_type`

The `match_mapping_type` is the datatype detected by the json parser. Since
JSON doesn't allow to distinguish a `long` from an `integer` or a `double` from
The `match_mapping_type` is the datatype detected by the JSON parser. Since
JSON doesn't allow distinguishing a `long` from an `integer` or a `double` from
jrodewig marked this conversation as resolved.
Show resolved Hide resolved
a `float`, it will always choose the wider datatype, i.e. `long` for integers
and `double` for floating-point numbers.

The following datatypes may be automatically detected:

- `boolean` when `true` or `false` are encountered.
- `date` when <<date-detection,date detection>> is enabled and a string is
found that matches any of the configured date formats.
- `date` when <<date-detection,date detection>> is enabled and a string matching
any of the configured date formats is found.
- `double` for numbers with a decimal part.
- `long` for numbers without a decimal part.
- `object` for objects, also called hashes.
Expand Down