elasticsearch/docs/reference/search/request/docvalue-fields.asciidoc

[[search-request-docvalue-fields]]
=== Doc value Fields

Allows to return the <<doc-values,doc value>> representation of a field for each hit, for
example:

[source,js]
--------------------------------------------------
GET /_search
{
    "query" : {
        "match_all": {}
    },
    "docvalue_fields" : [
        {
            "field": "my_ip_field", <1>
            "format": "use_field_mapping" <2>
        },
        {
            "field": "my_date_field",
            "format": "epoch_millis" <3>
        }
    ]
}
--------------------------------------------------
// CONSOLE
<1> the name of the field
<2> the special `use_field_mapping` format tells Elasticsearch to use the format from the mapping
<3> date fields may use a custom format

Doc value fields can work on fields that are not stored.

`*` can be used as a wild card, for example:

[source,js]
--------------------------------------------------
GET /_search
{
    "query" : {
        "match_all": {}
    },
    "docvalue_fields" : [
        {
            "field": "*field", <1>
            "format": "use_field_mapping" <2>
        }
    ]
}
--------------------------------------------------
// CONSOLE
<1> Match all fields ending with `field`
<2> Format to be applied to all matching fields.

Note that if the fields parameter specifies fields without docvalues it will try to load the value from the fielddata cache
causing the terms for that field to be loaded to memory (cached), which will result in more memory consumption.

[float]
==== Custom formats

While most fields do not support custom formats, some of them do:

 - <<date,Date>> fields can take any <<mapping-date-format,date format>>.
 - <<number,Numeric>> fields accept a https://docs.oracle.com/javase/8/docs/api/java/text/DecimalFormat.html[DecimalFormat pattern].

All fields support the special `use_field_mapping` format, which tells
Elasticsearch to use the mappings to figure out a default format.

NOTE: The default is currently to return the same output as
<<search-request-script-fields,script fields>>. However it will change in 7.0
to behave as if the `use_field_mapping` format was provided.