程序包 io.agentscope.core.rag.model

类 DocumentMetadata

java.lang.Object
io.agentscope.core.rag.model.DocumentMetadata
public class DocumentMetadata extends Object
Document metadata containing content and chunking information.

This class stores metadata about a document chunk, including the content (which can be text, image, video, etc.), document ID, chunk ID, and optional custom payload fields.

The content field uses ContentBlock which is a sealed hierarchy supporting different content types (TextBlock, ImageBlock, VideoBlock, etc.).

The payload field allows storing custom metadata such as file name, department, author, creation time, tags, and other business-specific fields. These fields are stored as key-value pairs and will be persisted to vector databases along with the document content.

Example usage with payload: 


 Map<String, Object> payload = new HashMap<>();
 payload.put("filename", "report.pdf");
 payload.put("department", "Finance");
 payload.put("author", "John Doe");
 payload.put("created_at", "2024-01-15T10:30:00Z");
 payload.put("tags", Arrays.asList("urgent", "quarterly"));

 TextBlock content = TextBlock.builder().text("Document content").build();
 DocumentMetadata metadata = new DocumentMetadata(content, "doc-123", "chunk-0", payload);

  • 构造器详细资料

    • DocumentMetadata

      public DocumentMetadata(ContentBlock content, String docId, String chunkId)
      Creates a new DocumentMetadata instance without custom payload.

      This constructor is provided for backward compatibility. For new code, consider using the constructor with payload parameter or the builder pattern if you need to add custom metadata fields.

      参数:
      content - the content block (text, image, video, etc.)
      docId - the document ID
      chunkId - the chunk ID within the document

    • DocumentMetadata

      public DocumentMetadata(ContentBlock content, String docId, String chunkId, Map<String,Object> payload)
      Creates a new DocumentMetadata instance with custom payload.

      The payload map is copied to prevent external modifications. The returned payload from getPayload() will be an unmodifiable view.

      参数:
      content - the content block (text, image, video, etc.)
      docId - the document ID
      chunkId - the chunk ID within the document
      payload - the custom metadata fields (can be null or empty)
      抛出:
      IllegalArgumentException - if content, docId, or chunkId is null

  • 方法详细资料

    • getContent

      public ContentBlock getContent()
      Gets the content block.
      返回:
      the content block

    • getDocId

      public String getDocId()
      Gets the document ID.
      返回:
      the document ID

    • getChunkId

      public String getChunkId()
      Gets the chunk ID.
      返回:
      the chunk ID

    • getPayload

      public Map<String,Object> getPayload()
      Gets the custom payload metadata.

      Returns an unmodifiable map of custom metadata fields. This map contains business-specific fields such as filename, department, author, tags, etc. The map is never null but may be empty if no payload was provided.

      返回:
      an unmodifiable map of custom metadata fields (never null)

    • getPayloadValue

      public Object getPayloadValue(String key)
      Gets a specific payload value by key.

      This is a convenience method to retrieve individual payload values without needing to access the entire payload map.

      参数:
      key - the payload key
      返回:
      the payload value, or null if the key doesn't exist
      抛出:
      NullPointerException - if key is null

    • hasPayloadKey

      public boolean hasPayloadKey(String key)
      Checks if the payload contains a specific key.

      Use this method to safely check for the existence of a payload field before attempting to retrieve its value.

      参数:
      key - the payload key to check
      返回:
      true if the key exists in the payload, false otherwise
      抛出:
      NullPointerException - if key is null

    • getContentText

      public String getContentText()
      Gets the text content from the content block.

      This is a convenience method that extracts text from the ContentBlock. For TextBlock, it returns the text. For other block types, it returns their string representation.

      返回:
      the text content, or empty string if not available

    • builder

      public static DocumentMetadata.Builder builder()
      Creates a new builder for constructing DocumentMetadata instances.

      The builder pattern provides a fluent API for creating DocumentMetadata with optional payload fields. This is especially useful when you need to add multiple custom metadata fields.

      Example usage: 

      
 DocumentMetadata metadata = DocumentMetadata.builder()
     .content(TextBlock.builder().text("Content").build())
     .docId("doc-123")
     .chunkId("chunk-0")
     .addPayload("filename", "report.pdf")
     .addPayload("department", "Finance")
     .build();
      返回:
      a new builder instance