Document v1 API

The Document v1 API (/document/v1/) provides HTTP access to document operations in Vespa. It supports creating, reading, updating, and deleting documents, as well as bulk operations through the visitor pattern.

Base URL

http://<host>:8080/document/v1/

Document ID Structure

Vespa document IDs follow the format:

id:<namespace>:<document-type>:[n=<number>|g=<group>]:<user-specified>

The Document v1 API exposes this as a path structure:

/document/v1/<namespace>/<document-type>/docid/<user-specified>
/document/v1/<namespace>/<document-type>/number/<number>/<user-specified>
/document/v1/<namespace>/<document-type>/group/<group>/<user-specified>

Single Document Operations

Get Document

Retrieve a single document by ID.

curl http://localhost:8080/document/v1/mynamespace/music/docid/1

Request

namespace

string

required

Document namespace

document-type

string

required

Document type as defined in your schema

docid

string

required

User-specified document identifier

cluster

string

Target content cluster (required if multiple clusters exist)

fieldSet

string

default:"[document]"

Field set to retrieve. Examples:

[document] - All document fields
[id] - Only document ID
music:[document] - All fields from music document type
artist,title - Specific fields

timeout

string

default:"180s"

Request timeout (e.g., 5s, 1000ms)

tracelevel

integer

default:"0"

Trace level 0-9 for debugging

Response

{
  "pathId": "/document/v1/mynamespace/music/docid/1",
  "id": "id:mynamespace:music::1",
  "fields": {
    "artist": "Tom Waits",
    "title": "Downtown Train",
    "year": 1985
  }
}

pathId

string

The request path

string

The full document ID

fields

object

Document fields as key-value pairs

Put Document (Create/Replace)

Create a new document or replace an existing one.

curl -X POST http://localhost:8080/document/v1/mynamespace/music/docid/1 \
  -H "Content-Type: application/json" \
  -d '{
    "fields": {
      "artist": "Tom Waits",
      "title": "Downtown Train",
      "year": 1985
    }
  }'

Request Body

{
  "fields": {
    "artist": "Tom Waits",
    "title": "Downtown Train",
    "year": 1985
  }
}

fields

object

required

Document fields to set

create

boolean

default:"false"

If true, only create document if it doesn’t exist (returns error if exists)

condition

string

Test-and-set condition that must be true for operation to succeed

route

string

Route string for the operation

Example: Conditional Put

curl -X POST "http://localhost:8080/document/v1/mynamespace/music/docid/1?condition=music.year<2000" \
  -H "Content-Type: application/json" \
  -d '{"fields": {"artist": "Updated Artist"}}'

Response

{
  "pathId": "/document/v1/mynamespace/music/docid/1",
  "id": "id:mynamespace:music::1"
}

Update Document

Partially update an existing document.

curl -X PUT http://localhost:8080/document/v1/mynamespace/music/docid/1 \
  -H "Content-Type: application/json" \
  -d '{
    "fields": {
      "year": {
        "assign": 1988
      }
    }
  }'

Update Operations

Assign
Add to Array
Remove from Array
Increment

Set a field to a new value:

{
  "fields": {
    "year": {"assign": 1988}
  }
}

Add element to array field:

{
  "fields": {
    "tags": {
      "add": ["rock", "blues"]
    }
  }
}

Remove element from array:

{
  "fields": {
    "tags": {
      "remove": ["pop"]
    }
  }
}

Increment numeric field:

{
  "fields": {
    "play_count": {
      "increment": 1
    }
  }
}

create

boolean

default:"false"

If true, create document if it doesn’t exist

condition

string

Test-and-set condition

Delete Document

Delete a document by ID.

curl -X DELETE http://localhost:8080/document/v1/mynamespace/music/docid/1

condition

string

Test-and-set condition that must be true for deletion to succeed

Example: Conditional Delete

curl -X DELETE "http://localhost:8080/document/v1/mynamespace/music/docid/1?condition=music.year<1990"

Bulk Operations (Visitor)

The Document v1 API supports bulk operations through the visitor pattern.

Visit Documents

Retrieve multiple documents matching a selection.

curl "http://localhost:8080/document/v1/mynamespace/music/docid?selection=music.year>2000&cluster=content"

selection

string

Document selection expression (required for most bulk operations)

cluster

string

required

Target content cluster

continuation

string

Continuation token from previous visit response

wantedDocumentCount

integer

default:"unspecified"

Approximate number of documents to return

concurrency

integer

default:"1"

Number of parallel visitors (1-1024)

bucketSpace

string

default:"default"

Bucket space: default or global

fieldSet

string

default:"[document]"

Fields to retrieve

stream

boolean

default:"false"

Enable streaming mode for large result sets (JSONL format)

slices

integer

Number of slices for parallel processing

sliceId

integer

Specific slice to process (0 to slices-1)

Response

{
  "pathId": "/document/v1/mynamespace/music/docid",
  "documents": [
    {
      "id": "id:mynamespace:music::1",
      "fields": {
        "artist": "Tom Waits",
        "year": 2002
      }
    },
    {
      "id": "id:mynamespace:music::2",
      "fields": {
        "artist": "Nick Cave",
        "year": 2003
      }
    }
  ],
  "continuation": "AAAAEAAAAAAAAAM...",
  "documentCount": 2
}

documents

array

Array of matching documents

continuation

string

Token to retrieve next batch (if more documents available)

documentCount

integer

Number of documents in this response

Example: Streaming Visit

curl "http://localhost:8080/document/v1/mynamespace/music/docid?selection=true&cluster=content&stream=true"

Returns JSONL (one JSON object per line):

{"id":"id:mynamespace:music::1","fields":{"artist":"Tom Waits"}}
{"id":"id:mynamespace:music::2","fields":{"artist":"Nick Cave"}}

Bulk Update

Update multiple documents matching a selection.

curl -X PUT "http://localhost:8080/document/v1/mynamespace/music/docid/?selection=music.year<2000&cluster=content" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": {
      "category": {
        "assign": "classic"
      }
    }
  }'

The selection parameter is required for bulk updates to prevent accidental modification of all documents.

Bulk Delete

Delete multiple documents matching a selection.

curl -X DELETE "http://localhost:8080/document/v1/mynamespace/music/docid/?selection=music.year<1980&cluster=content"

Copy Documents

Copy documents from one cluster to another.

curl -X POST "http://localhost:8080/document/v1/mynamespace/music/docid/?selection=true&cluster=content&destinationCluster=content2"

destinationCluster

string

required

Target cluster for copy operation

Advanced Features

Test-and-Set (Conditional Operations)

Use test-and-set to ensure operations only succeed when conditions are met:

curl -X PUT "http://localhost:8080/document/v1/mynamespace/music/docid/1?condition=music.version==1" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": {
      "version": {"assign": 2}
    }
  }'

If the condition fails, the API returns HTTP 412 (Precondition Failed).

Grouping Documents

Use number or group distribution for data locality: Number Grouping

# Documents with user_id 123 co-located
curl http://localhost:8080/document/v1/mynamespace/music/number/123/song1
curl http://localhost:8080/document/v1/mynamespace/music/number/123/song2

Group Grouping

# Documents in same group co-located
curl http://localhost:8080/document/v1/mynamespace/music/group/rock/song1
curl http://localhost:8080/document/v1/mynamespace/music/group/rock/song2

Time-based Visiting

Visit documents modified within a time range:

fromTimestamp

integer

Unix timestamp (microseconds) - start of range

toTimestamp

integer

Unix timestamp (microseconds) - end of range

includeRemoves

boolean

default:"false"

Include removed documents (tombstones)

curl "http://localhost:8080/document/v1/mynamespace/music/docid/?selection=true&cluster=content&fromTimestamp=1609459200000000"

Dry Run Mode

Test operations without actually executing them:

dryRun

boolean

default:"false"

If true, validate operation but don’t execute

curl -X POST "http://localhost:8080/document/v1/mynamespace/music/docid/1?dryRun=true" \
  -H "Content-Type: application/json" \
  -d '{"fields": {"artist": "Test"}}'

Request Size Limits

The Document v1 API has configurable request size limits:

Default maximum request size: configurable per deployment
Large documents should be split or use streaming

If a request exceeds limits, the API returns HTTP 413 (Request Too Large).

Performance Tips

Use Streaming for Large Visits: Enable stream=true for large result sets to reduce memory usage
Parallel Visiting: Use concurrency parameter to speed up bulk operations
Field Sets: Request only needed fields using fieldSet parameter
Batch Updates: Use bulk update operations instead of individual updates
Connection Pooling: Reuse HTTP connections for better throughput

Error Handling

message

string

Error message describing what went wrong

Common Error Status Codes

Status	Meaning
400	Invalid request format or parameters
404	Document not found
412	Test-and-set condition failed
413	Request size too large
429	Too many requests (rate limited)
500	Internal server error
504	Request timeout
507	Insufficient storage space

Example Error Response

{
  "pathId": "/document/v1/mynamespace/music/docid/1",
  "message": "Document not found"
}

Examples

# Get document
curl http://localhost:8080/document/v1/mynamespace/music/docid/1

# Put document
curl -X POST http://localhost:8080/document/v1/mynamespace/music/docid/1 \
  -H "Content-Type: application/json" \
  -d '{"fields": {"artist": "Tom Waits"}}'

# Update document
curl -X PUT http://localhost:8080/document/v1/mynamespace/music/docid/1 \
  -H "Content-Type: application/json" \
  -d '{"fields": {"year": {"assign": 1985}}}'

# Visit documents
curl "http://localhost:8080/document/v1/mynamespace/music/docid?selection=true&cluster=content"

HTTP APIs

Java APIs

Client Libraries

Document v1 API

Base URL

Document ID Structure

Single Document Operations

Get Document

Put Document (Create/Replace)

Update Document

Delete Document

Bulk Operations (Visitor)

Visit Documents

Bulk Update

Bulk Delete

Copy Documents

Advanced Features

Test-and-Set (Conditional Operations)

Grouping Documents

Time-based Visiting

Dry Run Mode

Request Size Limits

Performance Tips

Error Handling

Examples

Build docs developers (and LLMs) love

HTTP APIs

Java APIs

Client Libraries

​Base URL

​Document ID Structure

​Single Document Operations

​Get Document

​Put Document (Create/Replace)

​Update Document

​Delete Document

​Bulk Operations (Visitor)

​Visit Documents

​Bulk Update

​Bulk Delete

​Copy Documents

​Advanced Features

​Test-and-Set (Conditional Operations)

​Grouping Documents

​Time-based Visiting

​Dry Run Mode

​Request Size Limits

​Performance Tips

​Error Handling

​Examples

​Related Documentation

Build docs developers (and LLMs) love

Base URL

Document ID Structure

Single Document Operations

Get Document

Put Document (Create/Replace)

Update Document

Delete Document

Bulk Operations (Visitor)

Visit Documents

Bulk Update

Bulk Delete

Copy Documents

Advanced Features

Test-and-Set (Conditional Operations)

Grouping Documents

Time-based Visiting

Dry Run Mode

Request Size Limits

Performance Tips

Error Handling

Examples

Related Documentation