elasticsearch/docs/reference/docs/multi-termvectors.asciidoc

[[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": "twitter",
         "_id": "2",
         "term_statistics": true
      },
      {
         "_index": "twitter",
         "_id": "1",
         "fields": [
            "message"
         ]
      }
   ]
}
--------------------------------------------------
// TEST[setup:twitter]

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

`POST /_mtermvectors`

`POST /<index>/_mtermvectors`

[[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.  
The index can be specified the body of the request or in the 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]

[float]
[[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 /twitter/_mtermvectors
{
   "docs": [
      {
         "_id": "2",
         "fields": [
            "message"
         ],
         "term_statistics": true
      },
      {
         "_id": "1"
      }
   ]
}
--------------------------------------------------
// TEST[setup:twitter]

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

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

[[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": "twitter",
         "doc" : {
            "user" : "John Doe",
            "message" : "twitter test test test"
         }
      },
      {
         "_index": "twitter",
         "doc" : {
           "user" : "Jane Doe",
           "message" : "Another twitter test ..."
         }
      }
   ]
}
--------------------------------------------------
// TEST[setup:twitter]