[[docs-multi-termvectors]]
=== Multi term vectors API
++++
<titleabbrev>Multi term vectors</titleabbrev>
++++

Retrieves multiple term vectors with a single request. 

[source,console]
--------------------------------------------------
POST /_mtermvectors
{
   "docs": [
      {
         "_index": "my-index-000001",
         "_id": "2",
         "term_statistics": true
      },
      {
         "_index": "my-index-000001",
         "_id": "1",
         "fields": [
            "message"
         ]
      }
   ]
}
--------------------------------------------------
// TEST[setup:my_index]

[[docs-multi-termvectors-api-request]]
==== {api-request-title}

`POST /_mtermvectors`

`POST /<index>/_mtermvectors`

[[docs-multi-termvectors-api-prereqs]]
==== {api-prereq-title}

* If the {es} {security-features} are enabled, you must have the `read`
<<privileges-list-indices,index privilege>> for the target index or index alias.

[[docs-multi-termvectors-api-desc]]
==== {api-description-title}

You can specify existing documents by index and ID or 
provide artificial documents in the body of the request.  
You can specify the index in the request body or request URI.

The response contains a `docs` array with all the fetched termvectors. 
Each element has the structure provided by the <<docs-termvectors,termvectors>>
API. 

See the <<docs-termvectors,termvectors>> API for more information about the information
that can be included in the response.  

[[docs-multi-termvectors-api-path-params]]
==== {api-path-parms-title}

`<index>`::
(Optional, string) Name of the index that contains the documents.

[[docs-multi-termvectors-api-query-params]]
==== {api-query-parms-title}

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

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

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

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

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

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

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

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

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

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

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

[discrete]
[[docs-multi-termvectors-api-example]]
==== {api-examples-title}

If you specify an index in the request URI, the index does not need to be specified for each documents
in the request body:

[source,console]
--------------------------------------------------
POST /my-index-000001/_mtermvectors
{
   "docs": [
      {
         "_id": "2",
         "fields": [
            "message"
         ],
         "term_statistics": true
      },
      {
         "_id": "1"
      }
   ]
}
--------------------------------------------------
// TEST[setup:my_index]

If all requested documents are in same index and the parameters are the same, you can use the
following simplified syntax:

[source,console]
--------------------------------------------------
POST /my-index-000001/_mtermvectors
{
  "ids": [ "1", "2" ],
  "parameters": {
    "fields": [
      "message"
    ],
    "term_statistics": true
  }
}
--------------------------------------------------
// TEST[setup:my_index]

[[docs-multi-termvectors-artificial-doc]]
===== Artificial documents

You can also use `mtermvectors` to generate term vectors for _artificial_ documents provided
in the body of the request. The mapping used is determined by the specified `_index`.

[source,console]
--------------------------------------------------
POST /_mtermvectors
{
   "docs": [
      {
         "_index": "my-index-000001",
         "doc" : {
            "message" : "test test test"
         }
      },
      {
         "_index": "my-index-000001",
         "doc" : {
           "message" : "Another test ..."
         }
      }
   ]
}
--------------------------------------------------
// TEST[setup:my_index]
