Platform Manual
Document Model

Evaluation Criteria

The decision to use deeply embedded maps in a single document or opt for a flat model instead depends on your specific requirements, relationships between data, and tolerance for certain tradeoffs.

The flat model is a simple, non‑embedded structure in which you spread your data across multiple separate documents. For more information, see Relationships > Good Pattern: Flat Models.

When assessing whether to embed maps in a document or distribute the data across multiple smaller documents, refer to the following criteria to guide you:

Data Complexity

The following table provides criteria for the levels of complexity in your data model:

Criteria

Model

You have a clear relationship between data items stored together in a collection.

Embedded

Your data items are relatively simple and do not need a strong relationship.

Flat

Query Performance

The following table provides criteria for the speed and efficiency of read and write operations:

Criteria

Model

You frequently retrieve or update the embedded map items together.

Embedded

You frequently access or modify only certain parts of the data.

Flat

Data Size

The following table provides criteria for the potential size of the embedded map:

Syncing large documents can significantly impact network performance:

Caution is advised when handling large binary data, such as a high-resolution image or video exceeding 50 megapixels; a deeply embedded document; or a very large document.

Instead of storing files exceeding 250kb directly within a document object, carefully consider using attachments . For more information, see Data Types > Attachment.

Criteria

Model

You do not anticipate the embedded map to become too large and potentially impact overall system performance.

Embedded

You anticipate the embedded map to increase in complexity and size and therefore become difficult to manage and so large that system performance degrades.

Flat

Concurrency

The following table provides criteria for the potential for concurrent edits and resulting merge conflicts:

Criteria

Model

It is very likely that your end users will modify the same data items stored locally on their respective environments while internet is unavailable.

Embedded

It is not likely that your end users will modify the same data items stored locally on their respective environments while internet is unavailable.

Flat

Document Structure

The following table provides a criteria for assessing the overall structure of your documents:

Criteria

Model

Your embedded maps are relatively simple in structure and do not require maintainability over time.

Embedded

Multiple embedded maps are becoming deeply nested; as in you have an embedded map representing three or more levels in a hierarchy, necessitating better organization.

Flat

Scalability

The following table provides criteria for assessing how your data model may evolve over time:

Criteria

Model

You anticipate that you'll add more data or expand relationships in the future.

Embedded

You do not anticipate that you'll add more data or expand relationships in the future.

Flat