Package org.springframework.ai.document

Class Document

java.lang.Object
org.springframework.ai.document.Document
public class Document extends Object
A document is a container for the content and metadata of a document. It also contains the document's unique ID.

A Document holds either text content or media content, but not both. Text content is accessed via getText(), and media content via getMedia(). Use isText() to determine which type is present.

Documents are intended to carry data through Spring AI's ETL pipeline — from ingestion through transformation to storage in a vector store.

JSON serialization and deserialization

Document is fully Jackson-serializable. The serialized JSON uses the following field names:

  • id — the unique document identifier
  • text — the text content (null for media documents)
  • media — the media content (null for text documents)
  • metadata — the metadata map
  • score — the relevance score, may be null

Deserialization is handled via Document.Builder. JSON round-trips are fully supported: a serialized Document can be deserialized back to an equal instance.

Example round-trip: 


 ObjectMapper mapper = JacksonUtils.getDefaultJsonMapper();
 Document original = Document.builder()
     .id("doc-1")
     .text("hello world")
     .metadata("source", "example")
     .score(0.95)
     .build();

 String json = mapper.writeValueAsString(original);
 // {"id":"doc-1","text":"hello world","media":null,"metadata":{"source":"example"},"score":0.95}

 Document restored = mapper.readValue(json, Document.class);
 // restored.equals(original) == true

Creating documents

Example of creating a text document: 


 // Using constructor
 Document textDoc = new Document("Sample text content", Map.of("source", "user-input"));

 // Using builder (preferred)
 Document textDoc = Document.builder()
     .text("Sample text content")
     .metadata("source", "user-input")
     .build();

Example of creating a media document: 


 // Using constructor
 Media imageContent = new Media(MediaType.IMAGE_PNG, new byte[] {...});
 Document mediaDoc = new Document(imageContent, Map.of("filename", "sample.png"));

 // Using builder (preferred)
 Document mediaDoc = Document.builder()
     .media(new Media(MediaType.IMAGE_PNG, new byte[] {...}))
     .metadata("filename", "sample.png")
     .build();

Example of checking content type and accessing content: 


 if (document.isText()) {
     String text = document.getText();
     // Process text content
 } else {
     Media media = document.getMedia();
     // Process media content
 }

  • Field Details

    • DEFAULT_CONTENT_FORMATTER

      public static final ContentFormatter DEFAULT_CONTENT_FORMATTER

  • Constructor Details

    • Document

      public Document(@Nullable String text)
      Creates a text document with a generated ID and empty metadata.
      Parameters:
      text - the text content of the document

    • Document

      public Document(@Nullable String text, Map<String,Object> metadata)
      Creates a text document with a generated ID and the given metadata.
      Parameters:
      text - the text content of the document
      metadata - the metadata map; must not be null and must not contain null keys or values

    • Document

      public Document(String id, @Nullable String text, Map<String,Object> metadata)
      Creates a text document with an explicit ID and the given metadata.
      Parameters:
      id - the unique document identifier; must not be null or empty
      text - the text content of the document
      metadata - the metadata map; must not be null and must not contain null keys or values

    • Document

      public Document(@Nullable Media media, Map<String,Object> metadata)
      Creates a media document with a generated ID and the given metadata.
      Parameters:
      media - the media content of the document
      metadata - the metadata map; must not be null and must not contain null keys or values

    • Document

      public Document(String id, @Nullable Media media, Map<String,Object> metadata)
      Creates a media document with an explicit ID and the given metadata.
      Parameters:
      id - the unique document identifier; must not be null or empty
      media - the media content of the document
      metadata - the metadata map; must not be null and must not contain null keys or values

  • Method Details

    • builder

      public static Document.Builder builder()

    • getId

      public String getId()
      Returns the unique identifier for this document.

      This ID is either explicitly provided during document creation or generated using the configured IdGenerator (defaults to RandomIdGenerator).

      Returns:
      the unique identifier of this document
      See Also:

    • getText

      public @Nullable String getText()
      Returns the document's text content, if any.
      Returns:
      the text content if isText() is true, null otherwise
      See Also:

    • isText

      public boolean isText()
      Determines whether this document contains text or media content.
      Returns:
      true if this document contains text content (accessible via getText()), false if it contains media content (accessible via getMedia())

    • getMedia

      public @Nullable Media getMedia()
      Returns the document's media content, if any.
      Returns:
      the media content if isText() is false, null otherwise
      See Also:

    • getFormattedContent

      public String getFormattedContent()
      Returns the formatted content of this document using MetadataMode.ALL, including both text and all metadata entries.

      This method is excluded from JSON serialization as it is a computed, ephemeral representation.

      Returns:
      the formatted content string
      See Also:

    • getFormattedContent

      public String getFormattedContent(MetadataMode metadataMode)
      Returns the formatted content of this document using the given MetadataMode.
      Parameters:
      metadataMode - controls which metadata entries are included in the output; must not be null
      Returns:
      the formatted content string

    • getFormattedContent

      public String getFormattedContent(ContentFormatter formatter, MetadataMode metadataMode)
      Helper content extractor that uses and external ContentFormatter.

    • getMetadata

      public Map<String,Object> getMetadata()
      Returns the metadata associated with this document.

      The metadata values are restricted to simple types (string, int, float, boolean) for compatibility with Vector Databases.

      Returns:
      the metadata map

    • getScore

      public @Nullable Double getScore()
      Returns the relevance score associated with this document, if any.

      The score is typically assigned during retrieval and is not set at document creation time. Use Document.Builder.score(Double) or mutate() to produce a new document with a score.

      Returns:
      the relevance score, or null if none has been assigned

    • getContentFormatter

      public ContentFormatter getContentFormatter()
      Returns the content formatter associated with this document.
      Returns:
      the current ContentFormatter instance used for formatting the document content.

    • setContentFormatter

      public void setContentFormatter(ContentFormatter contentFormatter)
      Replace the document's ContentFormatter.
      Parameters:
      contentFormatter - new formatter to use.

    • mutate

      public Document.Builder mutate()
      Returns a new Document.Builder pre-populated with all fields of this document, allowing selective modification without altering the original.
      Returns:
      a builder initialised from this document's state

    • equals

      public boolean equals(@Nullable Object o)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object