Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.ditto.live/llms.txt

Use this file to discover all available pages before exploring further.

Ditto sets two thresholds on the serialized size of an individual document:
ThresholdDefaultParameterBehavior on a user write
Soft limit256 KiBdocument_size_soft_limit_bytesLogs a warn-level message; the write succeeds.
Hard limit5 MiBdocument_size_hard_limit_bytesLogs an error-level message; the write currently succeeds. Future versions will reject writes that exceed this limit and stop replicating documents that exceed it across the mesh.
Both thresholds apply to the size of the serialized document on disk, including all CRDT bookkeeping, not the size of the JSON you pass into your write. Maps, registers, counters, and tombstones from prior updates all count toward the size.
The hard limit is a forward signal. Documents above 5 MiB still sync today, but they will stop syncing in an upcoming release. Any document your application is writing today that exceeds 5 MiB is on a path to breaking. Treat the existing log lines as a deprecation notice and remediate now.

​
Why the limits exist

Ditto is a peer-to-peer CRDT database designed to sync over constrained transports — Bluetooth Low Energy, lossy LAN, intermittent WAN. Every document is the unit of CRDT merge and, in most transports, the unit of replication framing. Two costs scale super-linearly with document size:
  • Merge cost. When two peers reconcile divergent edits to the same document, the merge cost is a function of the size of the document, not just the size of the change. A 5 MiB document with a one-byte field update still pays the cost of a 5 MiB merge.
  • Mesh framing. Replication breaks documents into smaller parts before sending them, and reassembles on the receiver. On Bluetooth LE, the effective throughput is roughly 20 KB/s — a 250 KiB document can take 10+ seconds to replicate for the first time, and a 5 MiB document can take minutes. Until the receiver has every part, the document does not appear in query results.
The soft limit at 256 KiB is the threshold past which these costs become user-visible on real-world transports. The hard limit at 5 MiB is the threshold past which they become unworkable: documents that large degrade not just their own sync but the throughput of every other document sharing the link. For binary payloads larger than the soft limit — images, video, file contents — use the ATTACHMENT CRDT data type instead. Attachments are content-addressed, fetched lazily, and not subject to the document-size thresholds.

​
Monitoring

The current shipping behavior is log-based: you find documents that approach or exceed the limits by reading your application logs. Look for log lines from the ditto-small-peer-store component:
  • warn level — soft limit exceeded: 
    Document `_id = <id>` size is <size> exceeds recommended limit of <soft_limit>
bytes and might have reduced performance
  • error level — hard limit exceeded: 
    WARNING! Document `_id = <id>` will not work correctly in future versions of
Ditto. Its size of <size> exceeds the future limit of <hard_limit>
(recommended max size <soft_limit>)
If you ship logs to a central system, a query for _id = together with recommended limit (soft) or future limit (hard) is enough to surface the offending documents. Treat hard-limit log lines as actionable: the same documents will fail to sync once enforcement ships.

​
Remediation

​
Split documents into smaller pieces

If a document has grown unbounded because you’re appending into a nested map (e.g. a list of orders inside a customer document), the data model is the problem, not the document. Split the nested data into its own collection and use the parent’s _id as a foreign key. See Data Modeling Tips for examples. The flat model also tends to be a better fit for Ditto’s CRDT merge semantics: changes to one item don’t force every peer to re-merge the entire parent document.

​
Move binaries to the ATTACHMENT type

If the document is large because it embeds a binary payload — an image, a PDF, a serialized blob — move that field to an ATTACHMENT. Attachments live outside the document body and are not counted against the size thresholds.
DQL
INSERT INTO photos
DOCUMENTS ({
  '_id': '...',
  'caption': 'My photo',
  'image': :imageAttachment
})

​
A note on already-oversized documents

CRDT merge state carries tombstones for prior writes, so writing a smaller value into an oversized document does not immediately reduce its serialized size — the tombstones from earlier larger values remain part of the document until they are eventually compacted out. A document that is already oversized in steady state is unlikely to shrink back under the limit through ordinary edits alone. The most reliable remediation for a critically oversized document is to write a fresh, smaller document under a new _id and update any references; structural changes to the offending data model (splitting into a sub-collection, moving binaries to ATTACHMENT) are the durable fix.

​
Configuring the limits

Both thresholds are exposed as system parameters and can be inspected and changed at runtime via ALTER SYSTEM:
DQL
SHOW document_size_soft_limit_bytes
SHOW document_size_hard_limit_bytes

ALTER SYSTEM SET document_size_soft_limit_bytes = 262144
ALTER SYSTEM SET document_size_hard_limit_bytes = 5242880
The values shown above are the defaults (256 KiB and 5 MiB); the example demonstrates the syntax, not a recommendation to change anything. We strongly recommend leaving the defaults in place. Lowering the soft limit can be useful as a tighter early-warning signal during development. Raising the hard limit is not recommended: the value is calibrated to the worst-case mesh framing cost and to a value Big Peer (HyDRA) treats consistently.

​
Cross-peer consistency

Both parameters must be set to the same value on every peer in your mesh, including any cloud peers. The thresholds are evaluated locally, so an inconsistency leads to:
  • Soft limit mismatch: different peers log warnings for different documents — confusing, but not data-impacting.
  • Hard limit mismatch (today): different peers log errors for different documents.
  • Hard limit mismatch (after enforcement): a peer with a higher local limit will write and attempt to replicate a document that a peer with a lower local limit refuses, causing the lower-limit peer to disable replication for that session and surface a DocumentTooLarge reason. Replication for that pair stays disabled until both peers agree the document is no longer oversized in the relevant direction.
If you change the value, change it across all peers in the same release.

​
Enforcement behavior (upcoming)

A future Ditto release will turn the hard limit from log-only into real enforcement. The exact version is gated on a fleet-wide rollout plan; this page will be updated when the change ships, with the affected SDK version per platform. When enforcement ships, the following will be true:
  • A user write of a document that exceeds the local hard limit returns a typed error from the SDK’s execute / update / upsert / insert path. Catch it the same way you catch any other DQL error.
  • Documents that exceed the hard limit are filtered out of replication on the send side, while other documents in the same update continue to sync normally.
  • A peer that receives an oversized document from another peer (e.g. across a version skew) disables that one replication session with a structured reason identifying the offending document, its size, and the local limit. Other sessions on the same peer are unaffected.
Per-SDK code samples for catching the typed error will be added here once the FFI surface lands. Check the release notes for the relevant SDK version.

​
See also

Data Modeling Tips

Modeling patterns that keep individual documents small and replication fast.

ATTACHMENT type

The ATTACHMENT CRDT for binary payloads that don’t count against document-size limits.

Customizing System Settings

Use ALTER SYSTEM to inspect and change document_size_*_limit_bytes at runtime.