# documents/batch
This section describes the HTTP request and response messages for the `documents/batch` resource.
You create document batches to describe the data that you want to upload to an Amazon CloudSearch domain. A document batch is a collection of add and delete operations that represent the documents you want to add, update, or delete from your domain. Batches can be described in either JSON or XML. A batch provides all of the information Amazon CloudSearch needs for indexing. Each item that you want to be able to return as a search result (such as a product) is represented as a document—a batch is simply a collection of add and delete requests for individual documents. Every document has a unique ID and one or more fields that contain the data that you want to search and return in results.
To update a document, you specify an add request with the document ID of the document you want to update. For more information, see [Adding and Updating Documents in Amazon CloudSearch](preparing-data.md#adding-documents). Similarly, to delete a document, you submit a delete request with the document ID of the document you want to delete. For information about deleting documents, see [Deleting Documents in Amazon CloudSearch](preparing-data.md#deleting-documents).
For more information about submitting data for indexing, see [Uploading Data to an Amazon CloudSearch Domain](uploading-data.md).
## documents/batch JSON API
### JSON documents/batch Requests
The body of a `documents/batch` request uses JSON or XML to specify the document operations you want to perform. A JSON representation of a batch is a collection of objects that define individual add and delete operations. The `type` property identifies whether an object represents an add or delete operation. For example, the following JSON batch adds one document and deletes one document:
```
[
{ "type": "add",
"id": "tt0484562",
"fields": {
"title": "The Seeker: The Dark Is Rising",
"directors": ["Cunningham, David L."],
"genres": ["Adventure","Drama","Fantasy","Thriller"],
"actors": ["McShane, Ian","Eccleston, Christopher","Conroy, Frances",
"Crewson, Wendy","Ludwig, Alexander","Cosmo, James",
"Warner, Amelia","Hickey, John Benjamin","Piddock, Jim",
"Lockhart, Emma"]
}
},
{ "type": "delete",
"id": "tt0484575"
}]
```
**Note**
When specifying document batches in JSON, the value for a field cannot be `null`.
The [JSON schema](http://json-schema.org/) representation of a batch is shown below:
```
{
"type": "array",
"minItems": 1,
"items": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": ["add", "delete"],
"required": true
},
"id": {
"type": "string",
"pattern": "[a-z0-9][a-z0-9_]{0,127}",
"minLength": 1,
"maxLength": 128,
"required": true
},
"fields": {
"type": "object",
"patternProperties": {
"[a-zA-Z0-9][a-zA-Z0-9_]{0,63}": {
"type": "string",
}
}
}
}
}
}
```
#### documents/batch Request Properties (JSON)
****
| Property | Description | Required |
| --- | --- | --- |
| type | The operation type, add or delete. | Yes |
| id | An alphanumeric string. Allowed characters are: A-Z (upper-case letters), -a-z (lower-case letters), 0-9, \$1 (underscore), - (hyphen), / (forward slash), \$1 (hash sign), : (colon). The max length is 128 characters. | Yes |
| fields | A collection of one or more field\$1name properties that define the fields the document contains. Condition: Required for add operations. Must contain at least one *field\$1name* property. | Conditional |
| field\$1name | Specifies a field within the document being added. Field names must begin with a letter and can contain the following characters: a-z (lower case), 0-9, and \$1 (underscore). Field names must be at least 3 and no more than 64 characters. The name score is reserved and cannot be used as a field name. To specify multiple values for a field, you specify an array of values instead of a single value. For example: `"genre": ["Adventure","Drama","Fantasy","Thriller"]` Condition: At least one field must be specified in the fields object. | Conditional |
### documents/batch Response (JSON)
The response body lists the number of adds and deletes that were performed and any errors or warnings that were generated.
The JSON schema representation of a document service API response is shown below:
```
{
"type": "object",
"properties": {
"status": {
"type": "text",
"enum": ["success", "error"],
"required": true
},
"adds": {
"type": "integer",
"minimum": 0,
"required": true
},
"deletes": {
"type": "integer",
"minimum": 0,
"required": true
},
"errors": {
"type": "array",
"required": false,
"items": {
"type": "object",
"properties": {
"message": {
"type": "string",
"required": true
}
}
}
},
"warnings": {
"type": "array",
"required": false,
"items": {
"type": "object",
"properties": {
"message": {
"type": "string",
"required": true
}
}
}
}
}
}
```
#### documents/batch Response Properties (JSON)
****
| Property | Description |
| --- | --- |
| status | The result status, which is either success or error. |
| adds | The number of add document operations that were performed. Always zero when the status is error. |
| deletes | The number of delete document operations that were performed. Always zero when the status is error. For information on permanently deleting documents, see [Deleting Documents in Amazon CloudSearch](preparing-data.md#deleting-documents). |
| errors | Provides information about a parsing or validation error. Specified only if the status is error. |
| warning | Provides information about a warning generated during parsing or validation. |
# documents/batch XML API
## XML documents/batch Requests
The body of a `documents/batch` request specifies the document operations you want to perform in XML. For example:
```
The Seeker: The Dark Is Rising
Cunningham, David L.
Adventure
Drama
Fantasy
Thriller
McShane, Ian
Eccleston, Christopher
Conroy, Frances
Ludwig, Alexander
Crewson, Wendy
Warner, Amelia
Cosmo, James
Hickey, John Benjamin
Piddock, Jim
Lockhart, Emma
```
### documents/batch Request Elements (XML)
****
| Element | Description | Required |
| --- | --- | --- |
| batch | The collection of add or delete operations that you want to submit to your search domain. A batch must contain at least one add or delete element. | Yes |
| add | Specifies a document that you want to add to your search domain. The id attributes is required and an add element must contain at least one field. Attributes: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudsearch/latest/developerguide/documents-batch-xml.html) | No |
| field | Specifies a field in the document being added. The name attribute and a field value are required. Field names must begin with a letter and can contain the following characters: a-z (lower case), 0-9, and \$1 (underscore). The name score is reserved and cannot be used as a field name. The field value can be text or CDATA. To specify multiple values for a field, you include multiple field elements with the same name. For example: Adventure
Drama
Fantasy
Thriller
Constraints: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudsearch/latest/developerguide/documents-batch-xml.html) Condition: At least one field must be specified in an add element. | Conditional |
| delete | Specifies a document that you want to remove from your search domain. The id attribute is required. A delete element must be empty. For information on permanently deleting documents, see [Deleting Documents in Amazon CloudSearch](preparing-data.md#deleting-documents).Constraints: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudsearch/latest/developerguide/documents-batch-xml.html) | No |
## documents/batch Response (XML)
The response body lists the number of adds and deletes that were performed and any errors or warnings that were generated.
The RelaxNG schema of a document service API response is:
```
start = response
response = element response {
attribute status { "success" | "error" },
attribute adds { xsd:integer },
attribute deletes { xsd:integer },
element errors {
element error {
text
}+
}? &
element warnings {
element warning {
text
}+
}?
}
```
### documents/batch Response Elements (XML)
****
| Element | Description |
| --- | --- |
| result | Contains elements that list the errors and warnings generated when parsing and validating the request. Attributes: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudsearch/latest/developerguide/documents-batch-xml.html) Constraints: If the status is `error`, the results element contains a list of errors. If the status is `success`, the results element can contain a list of warnings, but no errors. |
| errors | Contains a collection of error elements that identify the errors that occurred when parsing and validating the request. |
| error | Provides information about a parsing or validation error. The value provides a description of the error. |
| warnings | Contains a collection of warning elements that identify the warnings that were generated when parsing and validating the request. |
| warning | Provides information about a parsing or validation warning. The value provides a description of the error. |
## documents/batch Status Codes
A document service request can return three types of status codes:
+ 5xx status codes indicate that there was an internal server error. We recommend catching and retrying all 5xx error codes as they typically represent transient error conditions.
+ 4xx status codes indicate that the request was malformed.
+ 2xx status codes indicate that the request was processed successfully.
****
| Error | Description | HTTP Status Code |
| --- | --- | --- |
| No Content-Type | The Content-Type header is missing. | 400 |
| No Content-Length | The Content-Length header is missing. | 411 |
| Incorrect Path | URL path does not match ''/YYYY-MM-DD/documents/batch''. | 404 |
| Invalid HTTP Method | The HTTP method is not POST. Requests must be posted to documents/batch. | 405 |
| Invalid Accept Type | Accept header specifies a content type other than ''application/xml'' or ''application/json''. Responses can be sent only as XML or JSON. | 406 |
| Request Too Large | The length of the request body is larger than the maximum allowed value. | 413 |
| Invalid Content Type | The content type is something other than "application/json" or "application/xml". | 415 |
| Invalid Character Set | The character set is something other than ''ASCII'', ''ISO-8859-1'', or ''UTF-8''. | 415 |
## Common Request Headers
****
| Name | Description | Required |
| --- | --- | --- |
| Content-Type | A standard MIME type describing the format of the object data. For more information, see [W3C RFC 2616 Section 14](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.17). Default: application/json Constraints: application/json or application/xml only | Required |
| Content-Length | The length in bytes of the body of the request. | Yes |
| Accept | A standard MIME type describing the format of the response data. For more information, see [W3C RFC 2616 Section 14](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.17). Default: the content-type of the request Constraints: application/json or application/xml only | No |
## Common Response Headers
****
| Name | Description |
| --- | --- |
| Content-Type | A standard MIME type describing the format of the object data. For more information, see [W3C RFC 2616 Section 14](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.17). Default: the value of the Accept header in the request, or the Content-Type of the request if the Accept header is missing or doesn't specify either application/xml or application/json. Constraints: application/xml or application/json only |
| Content-Length | The length in bytes of the body in the response. |