Package org.springframework.ai.document

Class Document.Builder

java.lang.Object
org.springframework.ai.document.Document.Builder
Enclosing class:
Document
public static final class Document.Builder extends Object
Builder for Document.

Exactly one of text(String) or media(Media) must be set before calling build(). If no id(String) is provided, one is generated by the configured IdGenerator.

JSON deserialization

This builder is used by Jackson to deserialize Document instances (configured via @JsonDeserialize(builder = Builder.class)). Jackson maps JSON field names to builder methods by name: "id" → id, "text" → text, "metadata" → metadata(Map), "score" → score.

  • Constructor Details

    • Builder

      public Builder()

  • Method Details

    • idGenerator

      public Document.Builder idGenerator(IdGenerator idGenerator)
      Sets the IdGenerator used to generate the document ID when none is provided explicitly. Defaults to RandomIdGenerator.
      Parameters:
      idGenerator - the ID generator to use; must not be null
      Returns:
      the builder instance

    • id

      public Document.Builder id(String id)
      Sets an explicit ID for the document. If not called, an ID is generated automatically by the configured IdGenerator at build() time.
      Parameters:
      id - the unique document identifier; must not be null or empty
      Returns:
      the builder instance

    • text

      public Document.Builder text(@Nullable String text)
      Sets the text content of the document.

      Either text or media content must be set before building the document, but not both.

      Parameters:
      text - the text content
      Returns:
      the builder instance
      See Also:

    • media

      public Document.Builder media(@Nullable Media media)
      Sets the media content of the document.

      Either text or media content must be set before building the document, but not both.

      Parameters:
      media - the media content
      Returns:
      the builder instance
      See Also:

    • metadata

      public Document.Builder metadata(Map<String,Object> metadata)
      Replaces the metadata map with the given map.
      Parameters:
      metadata - the metadata map; must not be null and must not contain null keys or values
      Returns:
      the builder instance

    • metadata

      public Document.Builder metadata(String key, Object value)
      Adds a single key-value pair to the metadata map.
      Parameters:
      key - the metadata key; must not be null
      value - the metadata value; must not be null
      Returns:
      the builder instance

    • score

      public Document.Builder score(@Nullable Double score)
      Sets a score value for this document.

      Common uses include:

      • Measure of similarity between the embedding value of the document's text/media and a query vector, where higher scores indicate greater similarity (opposite of distance measure)
      • Text relevancy rankings from retrieval systems
      • Custom relevancy metrics from RAG patterns

      Higher values typically indicate greater relevance or similarity.

      Parameters:
      score - the document score, may be null
      Returns:
      the builder instance

    • build

      public Document build()
      Builds the Document.

      If no id(String) was set, an ID is generated from the text content and metadata using the configured IdGenerator. Exactly one of text(String) or media(Media) must have been set.

      Returns:
      a new Document
      Throws:
      IllegalArgumentException - if both or neither of text and media are set, or if the metadata contains null keys or values