Are `Document` objects supposed to be immutable?

[ThomasVitale]

The Document class contains only final fields (except "embeddings" which is about to be removed). However, the media (collection) and metadata (map) are mutable. All vector store implementations, at least, rely on the metadata field to be mutable because they add new metadata.

#1794 introduced a mutate() method to build new instances of Document objects. This issue is to discuss whether Document should be immutable. If yes, we need to to refactor all vector store implementations to work accordingly. Also, it's a breaking change, so it should be documented and communicated in the release notes.

[markpollack]

Also, there seems to be an inconsistency in what we want to be nullable in the current set of constructors vs. the builder, where only score is nullable. The builder should prob check that items are not nullable.

[markpollack]

I looked at a few implementations of the VectorStores, but don't see that we are adding metadata to an existing instace of document, instead we are creating a new instance. It seems from first glance this would not be a big change, and even if it was, I think the immutability aspect is important to have.

[ThomasVitale]

I agree on turning Document into a fully immutable object. The vector store implementations for Elasticsearch and OpenSearch parse the database result directly into a Document object and then subsequently add metadata to it (primarily, the "distance" metadata that we could probably remove entirely since now we have the "score" field). That should be easily fixable.

[markpollack]

At the moment it looks to be mutable, there is the ability to set the contentFormatter though, but that doesn't change the data. Thoughts @ThomasVitale ?