elasticsearch/docs/reference/cat/fielddata.asciidoc

[[cat-fielddata]]
=== cat fielddata API
++++
<titleabbrev>cat fielddata</titleabbrev>
++++

[IMPORTANT]
====
cat APIs are only intended for human consumption using the command line or {kib} 
console. They are _not_ intended for use by applications. For application 
consumption, use the <<cluster-nodes-stats,nodes stats API>>.
====

Returns the amount of heap memory currently used by the
<<modules-fielddata, field data cache>> on every data node in the cluster.


[[cat-fielddata-api-request]]
==== {api-request-title}

`GET /_cat/fielddata/<field>`

`GET /_cat/fielddata`

[[cat-fielddata-api-prereqs]]
==== {api-prereq-title}

* If the {es} {security-features} are enabled, you must have the `monitor` or
`manage` <<privileges-list-cluster,cluster privilege>> to use this API.

[[cat-fielddata-api-path-params]]
==== {api-path-parms-title}

`<field>`::
(Optional, string) Comma-separated list of fields used to limit returned
information.


[[cat-fielddata-api-query-params]]
==== {api-query-parms-title}

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=bytes]

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=http-format]

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=cat-h]

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=help]

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=cat-s]

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=cat-v]


[[cat-fielddata-api-example]]
==== {api-examples-title}

////
Hidden setup snippet to build an index with fielddata so our results are real:

[source,console,id=cat-fielddata-example]
--------------------------------------------------
PUT test
{
  "mappings": {
    "properties": {
      "body": {
        "type": "text",
        "fielddata":true
      },
      "soul": {
        "type": "text",
        "fielddata":true
      },
      "mind": {
        "type": "text",
        "fielddata":true
      }
    }
  }
}
POST test/_doc?refresh
{
  "body": "some words so there is a little field data",
  "soul": "some more words",
  "mind": "even more words"
}

# Perform a search to load the field data
POST test/_search?sort=body,soul,mind
--------------------------------------------------
////

[[cat-fielddata-api-example-ind]]
===== Example with an individual field

You can specify an individual field in the request body or URL path. The
following `fieldata` API request retrieves heap memory size information for the
`body` field.

[source,console]
--------------------------------------------------
GET /_cat/fielddata?v=true&fields=body
--------------------------------------------------
// TEST[continued]

The API returns the following response:

[source,txt]
--------------------------------------------------
id                     host      ip        node    field   size
Nqk-6inXQq-OxUfOUI8jNQ 127.0.0.1 127.0.0.1 Nqk-6in body    544b
--------------------------------------------------
// TESTRESPONSE[s/544b|480b/\\d+(\\.\\d+)?[tgmk]?b/]
// TESTRESPONSE[s/Nqk-6in[^ ]*/.+/ non_json]

[[cat-fielddata-api-example-list]]
===== Example with a list of fields

You can specify a comma-separated list of fields in the request body or URL
path. The following `fieldata` API request retrieves heap memory size
information for the `body` and `soul` fields.


[source,console]
--------------------------------------------------
GET /_cat/fielddata/body,soul?v=true
--------------------------------------------------
// TEST[continued]

The API returns the following response:

[source,txt]
--------------------------------------------------
id                     host      ip        node    field   size
Nqk-6inXQq-OxUfOUI8jNQ 127.0.0.1 127.0.0.1 Nqk-6in body    544b
Nqk-6inXQq-OxUfOUI8jNQ 127.0.0.1 127.0.0.1 Nqk-6in soul    480b
--------------------------------------------------
// TESTRESPONSE[s/544b|480b/\\d+(\\.\\d+)?[tgmk]?b/]
// TESTRESPONSE[s/Nqk-6in[^ ]*/.+/ s/soul|body/\\w+/ non_json]

The response shows the individual fielddata for the `body` and `soul` fields,
one row per field per node.

[[cat-fielddata-api-example-all]]
===== Example with all fields in a cluster

The following `fieldata` API request retrieves heap memory size
information all fields.

[source,console]
--------------------------------------------------
GET /_cat/fielddata?v=true
--------------------------------------------------
// TEST[continued]

The API returns the following response:

[source,txt]
--------------------------------------------------
id                     host      ip        node    field   size
Nqk-6inXQq-OxUfOUI8jNQ 127.0.0.1 127.0.0.1 Nqk-6in body    544b
Nqk-6inXQq-OxUfOUI8jNQ 127.0.0.1 127.0.0.1 Nqk-6in mind    360b
Nqk-6inXQq-OxUfOUI8jNQ 127.0.0.1 127.0.0.1 Nqk-6in soul    480b
--------------------------------------------------
// TESTRESPONSE[s/544b|480b|360b/\\d+(\\.\\d+)?[tgmk]?b/]
// TESTRESPONSE[s/Nqk-6in[^ ]*/.+/ s/soul|body|mind/\\w+/ non_json]