Document JSON format

This document describes the JSON format used for sending document operations to Vespa. Field names and types are defined in the search definition reference. There are three types of operations:

  • Put - for submitting full document, will insert and overwrite any old document with same ID
  • Remove - for removing a document with a given ID
  • Update - for updating fields in a document with a specified ID
The are two channels for sending document operations, with a slightly different format:

The Vespa HTTP Client RESTified Document Operation API
This is a Java API and command line tool to feed asynchronous document operations to Vespa content clusters (for high performance operations) This channel accepts one operation per request and is synchronous (not for high performance operations)

Put

Writing a document to Vespa looks like:

The Vespa HTTP Client RESTified Document Operation API
{
    "put": "id:music:music::123",
    "fields": {
        "title": "Best of Bob Dylan"
    }
}
http post /document/v1/music/music/docid/123
{
    "fields": {
        "title": "Best of Bob Dylan"
    }
}
Values for the document fields may be set using elements as shown above in the fields object. In this example, title field is specified in the document type. See examples using arrays, maps, structs, raw, tensor, and weighted sets.

Update

Updates make changes to documents without submitting the entire document - great for efficiency. If the document does not exist, Vespa creates creates a new document if create if nonexistent is used - otherwise, returns error.

The Vespa HTTP Client RESTified Document Operation API
{
    "update": "id:music:music::123",
    "fields": {
        "title": {
            "assign": "The best of Bob Dylan"
        }
    }
}
http put /document/v1/music/music/docid/123
{
    "fields": {
        "title": {
            "assign": "The best of Bob Dylan"
        }
    }
}
There are three basic operation on field level:
  • Assign: Replace the content of the field
  • Add: Add a new value to a field (array, weightedset etc)
  • Remove: Remove a value from a field
Find more examples of arithmetic updates and updating composite fields.

Note: Messages can be re-sent by Vespa's Message Bus. This can cause unexpected results for all operations except assign and remove! If greater consistency is needed, use a conditional update instead.

Remove

The Vespa HTTP Client RESTified Document Operation API
{
    "remove": "id:music:music::HitMe"
}
http delete /document/v1/music/music/docid/HitMe


Conditional execution - test and set

An optional condition can be added to operations to specify a test and set condition. The value of the condition is a document selection encoded as a string. The put/update/remove operation is only applied if the condition matches an already existing document with that id. Example: Increment the sales field only if it is already equal to 999:

The Vespa HTTP Client RESTified Document Operation API
{
    "update": "id:music:music::BestOf",
        "condition": "music.sales==999",
        "fields": {
            "sales": {
                "increment": 1
            }
    }
}
http put /document/v1/music/music/docid/BestOf?condition=music.sales=='999'
{
   "fields": {
       "sales": {
           "increment": 1
        }
    }
}

Note: Use documenttype.fieldname in the condition, not only fieldname.

Note: If the condition is not met, an error is returned. ToDo: There is a discussion whether to change to not return error, and instead return a condition-not-met in the response.