PhoenixmlDb.Core

IDocument

Represents a stored document retrieved from a container, providing access to its content, parsed XDM node tree, and application-defined metadata.

#IDocument

Namespace: PhoenixmlDb.Core

Represents a stored document retrieved from a container, providing access to its content, parsed XDM node tree, and application-defined metadata.

An IDocument is an immutable snapshot of a document at the time it was retrieved. It does not track changes — if you modify the content, you must call IContainer.PutDocumentAsync again to persist the updated version.

Accessing content: Document content can be consumed in three ways, depending on your use case:

• IDocument.GetContentAsync — returns the raw XML or JSON as a String. Best for serialization, logging, or passing to external systems.

• IDocument.GetContentStreamAsync — returns a Stream for large documents where you want to avoid allocating the entire content as a single string.

• IDocument.GetRootNodeAsync — returns the parsed XDM node tree (IXdmNode). This is the representation that XQuery operates on. Use it for programmatic tree walking or when you need structured access to the document's elements and attributes.

Metadata: Each document can carry arbitrary key-value metadata that is stored separately from the document content. Metadata is useful for classification, tagging, workflow state, or application-specific attributes. Metadata can be set at document creation time via DocumentOptions.Metadata or added later with IContainer.SetMetadataAsync.

#Example

Retrieve and inspect a document:

var doc = await container.GetDocumentAsync("orders/order-001.xml");
if (doc is not null)
{
    // Access raw content
    string xml = await doc.GetContentAsync();

    // Access parsed XDM tree
    var root = await doc.GetRootNodeAsync();
    Console.WriteLine($"Root element: {root.NodeName}");

    // Read metadata
    var status = await doc.GetMetadataAsync(Routing.Status.QName);
    Console.WriteLine($"Document {doc.Name}, status={status}, size={doc.SizeBytes} bytes");
}
                                  

#Properties

#Methods

#GetAllMetadataAsync(Threading.CancellationToken)

Gets all metadata key-value pairs for this document.

Parameters:

• cancellationToken — Cancellation token.

Returns: A read-only dictionary of all metadata entries. Returns an empty dictionary if the document has no metadata.

Use this when you need to inspect or display all metadata at once. For a single known key,

is more direct.

#GetContentAsync(Threading.CancellationToken)

Gets the document content as a string.

Parameters:

• cancellationToken — Cancellation token.

Returns: The raw XML or JSON content of the document.

This allocates the entire document content as a single string. For large documents, consider

to reduce memory pressure. For structured access to the document's elements, use

instead.

#GetContentStreamAsync(Threading.CancellationToken)

Gets the document content as a readable stream.

Parameters:

• cancellationToken — Cancellation token.

Returns: A Stream positioned at the beginning of the document content.

Prefer this overload over IDocument.GetContentAsync when the document is large and you want to process it incrementally (e.g., writing to an HTTP response, piping to an XML reader, or copying to a file).

The caller is responsible for disposing the returned stream.

#GetMetadataAsync(PhoenixmlDb.Xdm.XdmQName,Threading.CancellationToken)

Gets a single metadata value by qualified name.

Parameters:

• name — The qualified metadata name to retrieve (case-sensitive).

• cancellationToken — Cancellation token.

Returns: The metadata value if the name exists, or null if it is not set.

Metadata is separate from document content — it consists of application-defined key-value pairs. To retrieve all metadata at once, use

.

#GetRootNodeAsync(Threading.CancellationToken)

Gets the root node of the document's XDM (XQuery Data Model) tree.

Parameters:

• cancellationToken — Cancellation token.

Returns: The root IXdmNode of the document tree. For XML documents, this is a XdmNodeKind.Document node whose first child is the root element.

The XDM node tree is the parsed, in-memory representation of the document that the XQuery engine operates on. It provides structured access to elements, attributes, text nodes, and other XDM node types.

Use this method when you need to walk the document tree programmatically rather than using XQuery. For most query use cases, prefer IContainer.QueryAsync which operates on XDM trees internally.

#See also

• IContainer.GetDocumentAsync

• IContainer.PutDocumentAsync