Principle:Vespa engine Vespa Script Resolution
| Knowledge Sources | |
|---|---|
| Domains | Document_Processing, Indexing |
| Last Updated | 2026-02-09 00:00 GMT |
Overview
Script resolution is the process of mapping a document type to the executable indexing script that defines how that document's fields should be transformed during indexing.
Description
In a schema-driven indexing system, each document type is associated with a set of indexing expressions that define field-level transformations. These expressions are compiled into executable scripts at configuration time. When a document arrives for processing, the system must resolve which script applies to it based on its declared type.
Script resolution operates at two levels of granularity:
- Full-document scripts: A single script that processes all fields of a given document type. This is used for document put operations where the entire document is being indexed. The full-document script is identified by a special sentinel key (typically a constant like "[all]") in the script registry.
- Per-field scripts: Individual scripts that process a single field of a document. These are used for partial update operations where only specific fields are being modified. The per-field script is looked up by both the document type and the field name.
The resolution mechanism uses a two-level map structure:
documentType -> fieldName -> script
Where the full-document script is stored under the sentinel field name. This allows a uniform lookup interface regardless of whether the caller needs a full-document or per-field script.
Usage
Script resolution is used every time a document operation needs to be processed through the indexing pipeline. It is the bridge between the document's type metadata and the concrete processing logic.
Use this pattern when:
- You need to look up the processing rules for a given document type at indexing time.
- You are implementing a system where different entity types have different transformation pipelines.
- You want to support both full-entity and partial-field processing using a unified resolution mechanism.
- You need to handle the case where a document type has no associated script (indicating it should pass through without transformation).
Theoretical Basis
Script resolution implements a type-to-behavior mapping pattern, which is a form of the Strategy pattern applied at the document type level. The key insight is that the processing behavior is not hardcoded but is determined by configuration (the schema definitions) that are compiled into executable form.
The resolution algorithm is:
function resolveScript(documentType):
return resolveScript(documentType, FULL_DOCUMENT_KEY)
function resolveScript(documentType, fieldName):
fieldScripts = scriptRegistry.get(documentType.name)
if fieldScripts is null:
return null // no script for this type
return fieldScripts.get(fieldName)
The two-level lookup provides O(1) average-case performance for script resolution, which is critical since it occurs for every document operation in the pipeline.
Null result semantics: When resolution returns null, it signals that no indexing script exists for the given document type. This is not an error condition; it means the document type does not require indexing transformations and should pass through the pipeline unchanged. The caller must handle this case by forwarding the document operation without modification.
The registry is populated at configuration time by compiling the indexing expressions defined in the schema. This separation between configuration-time compilation and runtime resolution ensures that the indexing pipeline does not incur compilation overhead during document processing.