Implementation:Vespa engine Vespa DocumentScript Execute

Knowledge Sources	Vespa
Domains	Document_Processing, Indexing
Last Updated	2026-02-09 00:00 GMT

Overview

Concrete tool for executing compiled indexing expressions against a document, provided by Vespa's document processing framework.

Description

The DocumentScript.execute() method is the central execution point for applying indexing transformations to a document. It performs three steps in sequence:

1. Field validation: Iterates over all fields in the document and calls requireThatFieldIsDeclaredInDocument() for each one, ensuring that no undeclared fields are present.
2. Span tree cleanup: Calls removeAnyLinguisticsSpanTree() on each field value to remove stale linguistic annotations from any previous indexing pass.
3. Expression execution: Delegates to expression.execute(), passing the FieldValuesFactory, the document, the re-indexing flag, and the processing deadline.

The method returns the processed Document with all indexing transformations applied. The returned document may be a modified version of the input document or a newly constructed document, depending on the expression implementation.

DocumentScript holds three key fields:

• documentType: The expected document type, used for field validation.
• inputFields: The set of field names that the script reads as inputs.
• expression: The compiled ScriptExpression that performs the actual field transformations.

Usage

This method is called by IndexingProcessor.processDocument() after resolving the appropriate script via ScriptManager. It is the core execution step in the indexing pipeline for document put operations.

Use this implementation reference when:

• You need to understand the execution flow from document reception to indexed output.
• You are debugging field validation errors during indexing.
• You want to trace how a specific field's value is transformed by the indexing expression.
• You are investigating re-indexing behavior and need to understand the cleanup-then-execute sequence.

Code Reference

Source Location

• Repository: Vespa
• File: docprocs/src/main/java/com/yahoo/docprocs/indexing/DocumentScript.java
• Lines: 49-56

Signature

Document execute(FieldValuesFactory fieldValuesFactory,
                 Document document,
                 boolean isReindexing,
                 Instant deadline)

Import

import com.yahoo.docprocs.indexing.DocumentScript;

Full Method Body

Document execute(FieldValuesFactory fieldValuesFactory, Document document,
                 boolean isReindexing, Instant deadline) {
    for (var i = document.iterator(); i.hasNext(); ) {
        Map.Entry<Field, FieldValue> entry = i.next();
        requireThatFieldIsDeclaredInDocument(entry.getKey());
        removeAnyLinguisticsSpanTree(entry.getValue());
    }
    return expression.execute(fieldValuesFactory, document, isReindexing, deadline);
}

I/O Contract

Inputs

Name	Type	Required	Description
fieldValuesFactory	FieldValuesFactory	Yes	Factory for creating field value containers during expression execution. Used by the expression tree to allocate intermediate and output field values.
document	Document	Yes	The input document to be processed. All fields are validated and cleaned before expression execution.
isReindexing	boolean	Yes	Flag indicating whether this is a re-indexing operation. When true, the expression may optimize its behavior (e.g., skipping certain validations or applying incremental updates).
deadline	Instant	No	The processing deadline. May be null if no timeout is configured. Long-running operations within the expression check this deadline and throw TimeoutException if exceeded.

Outputs

Name	Type	Description
return value	Document	The fully indexed document with all field transformations applied. Contains populated index fields, attributes, and summary fields as defined by the schema's indexing expressions.

Key Fields

Field	Type	Description
documentType	DocumentType	The expected document type for this script. Used to validate that all fields in the input document are declared in the type definition.
inputFields	Set<String>	The set of field names that this script reads as inputs. Used to determine which fields are relevant for processing.
expression	ScriptExpression	The compiled indexing expression tree. This is the executable representation of the schema's indexing language declarations for this document type.

Usage Examples

// DocumentScript.execute() is called internally by IndexingProcessor.
// The following shows the typical calling pattern:

DocumentType articleType = documentTypeManager.getDocumentType("article");
DocumentScript script = scriptManager.getScript(articleType);

if (script != null) {
    Document inputDoc = new Document(articleType, "id:namespace:article::1");
    inputDoc.setFieldValue("title", new StringFieldValue("Vespa Search Engine"));
    inputDoc.setFieldValue("body", new StringFieldValue("Vespa is an open-source..."));

    // Execute the indexing script
    Document indexedDoc = script.execute(
        fieldValuesFactory,
        inputDoc,
        false,       // not re-indexing
        deadline     // processing deadline (may be null)
    );

    // indexedDoc now contains all indexed fields, attributes, and summaries
    // as defined by the schema's indexing expressions for the "article" type
}

// For re-indexing, pass true to allow optimization:
Document reindexedDoc = script.execute(
    fieldValuesFactory,
    existingDoc,
    true,        // re-indexing mode
    deadline
);

Related Pages

Implements Principle

• Principle:Vespa_engine_Vespa_Indexing_Expression_Execution
• Heuristic:Vespa_engine_Vespa_Document_Batch_Processing_Strategy