This is the /document/v1 API reference documentation. Use this API for synchronous Document operations to a Vespa endpoint - refer to reads and writes for other options.
The document/v1 API guide has examples and use cases.
To enable the API, add document-api in the serving container cluster -
services.xml:
<services>
<container>
<document-api/>
| GET |
Get a document by ID or Visit a set of documents by selection.
|
||||
|---|---|---|---|---|---|
| POST |
Put a given document, by ID, or Copy a set of documents by selection from one content cluster to another.
|
||||
| PUT |
Update a document with the given partial update, by ID, or Update where the given selection is true.
|
||||
| DELETE |
Remove a document, by ID, or Remove where the given selection is true.
|
| Parameter | Type | Description |
|---|---|---|
| bucketSpace | String | Specify the bucket space to visit.
Document types marked as global exist in a separate bucket space from non-global document types.
When visiting a particular document type,
the bucket space is automatically deduced based on the provided type name.
When visiting at a root /document/v1/ level this information is not available,
and the non-global ("default") bucket space is visited by default.
Specify global to visit global documents instead.
Supported values: default (for non-global documents) and global.
|
| cluster | String | Name of content cluster to GET from, or visit. |
| concurrency | Integer | Sends the given number of visitors in parallel to the backend, improving throughput at the cost of resource usage. Caution: given a concurrency parameter of N, the worst case for memory used while processing the request grows linearly with N, unless stream mode is turned on. This is because the container currently buffers all response data in memory before sending them to the client, and all sent visitors must complete before the response can be sent. Default is 1. |
| condition | String | For test-and-set. Run a document operation conditionally — if the condition fails, a 412 Precondition Failed is returned. See example. |
| continuation | String | When visiting, a continuation token is returned as the "continuation" field
in the JSON response, as long as more documents remain.
Use this token as the continuation parameter to visit the next chunk of documents. |
| create | Boolean | If true, updates to non-existent documents will create an empty document to update.
See create if nonexistent. |
| destinationCluster | String | Name of content cluster to copy to, during a copy visit. |
| fieldSet | String | A field set string
with the set of document fields to fetch from the backend.
Default is <document type>:[document], returning all document fields,
when document type is part of the path, or [all] when visiting at the root level.
|
| route | String | The route for single document operations, and for operations generated
by copy, update or
deletion visits. Default value is default.
See routes. |
| selection | String | Select only a subset of documents when visiting — details in document selector language. |
| sliceId | Integer | The slice number of the visit represented by this HTTP request. This number must be non-negative and less than the number of slices specified for the visit. Note: if the number of distribution bits change during a sliced visit, the results are undefined. Thankfully, this is a very rare occurrence, and is only triggered when adding content nodes. |
| slices | Integer | Split the document corpus into this number of independent slices. This lets multiple, concurrent series of HTTP requests advance the same logical visit independently, by specifying a different sliceId for each. |
| stream | Boolean | Whether to stream the HTTP response, allowing data to flow as soon as documents arrive from the backend. This obsoletes the wantedDocumentCount parameter. The HTTP status code will always be 200 if the visit is successfully initiated. Default value is false. |
| timeChunk | String | Target time to spend on one chunk of a copy, update or remove visit; with optional ks, s, ms or µs unit. Default value is 60. |
| timeout | String | Request timeout in seconds, or with optional ks, s, ms or µs unit. Default value is 180s. |
| tracelevel | Integer | Number in the range [0,9], where higher gives more details. The trace dumps which nodes and chains the document operation has touched. See routes. |
| wantedDocumentCount | Integer |
Best effort attempt to not respond to the client before
Note that the maximum value of |
POST and PUT requests must include a body for single document operations, and PUT for update visits. A field has a value for a POST and an update operation object for PUT. Documents and operations use the document JSON format. The document fields must match the schema:
{
"fields": {
"<fieldname>": "<value>",
...
}
}
{
"fields": {
"<fieldname>": {
"<update-operation>" : "<value>",
}
...
}
}
Values for id / put / update in the request body are silently dropped.
The ID is generated from the request path, regardless of request body data - example:
{
"put" : "id:mynamespace:music::123",
"fields": {
"title": "Best of"
}
}
This makes it easier to generate a feed file that can be used for both the vespa-feed-client and this API.
Non-exhaustive list of status codes:
| Code | Description |
|---|---|
| 200 | OK. Note that updating a non-existing document is defined as success. |
| 400 | Bad request. Returned for undefined document types + other request errors.
See 13465
for defined document types not assigned to a content cluster when using PUT.
Inspect message for details. |
| 404 | Not found; the document was not found. |
| 412 | condition is not met.
Inspect message for details. This is also the result when
a condition if specified, and the document is not found. |
| 500 | Server error; an unspecified error occurred when processing the request/response. |
| 502 | Bad gateway; the document API gave an error response. |
| 504 | Gateway timeout; the document API failed to respond within the given (or default 180s) timeout. |
| 507 | Insufficient storage; the content cluster is out of memory or disk space. |
Responses are in JSON format, with the following fields:
| Field | Description |
|---|---|
| path | Request URL path — always included. |
| message | An error message — included for all failed requests. |
| id | Document ID — always included for single document operations, including Get. |
| fields | The requested document fields — included for successful Get operations. |
| documents[] | Array of documents in a visit result — each document has the id and fields. |
| documentCount | Number of visited and selected documents. |
GET can include a fields object if a document was found in a GET request
{
"pathId": "<pathid>",
"id": "<id>",
"fields": {
...
}
}
A GET visit result can include an array of documents
plus a continuation:
{
"pathId": "<pathid>",
"documents": [
{
"id": "<id>",
"fields": {
...
}
},
...
],
"continuation": "<continuation string>",
"documentCount": 123
}
A continuation indicates the client should make further requests to get more data, while lack of a continuation indicates an error occurred, and that visiting should cease, or that there are no more documents.
A message can be returned for failed operations:
{
"pathId": "<pathid>",
"message": "<message text>"
}