Claim Check

The Claim Check pattern splits a large message into a small reference and the bulk data. The bulk data is written to an external store, and only a claim check (a reference such as a key or URL) travels through the messaging system. The consumer uses the claim check to retrieve the data.

The problem is that message brokers impose size limits (for example 256 KB on Amazon SQS, 256 KB on standard Azure Service Bus) and that moving large payloads through a broker is slow, costly, and can degrade the whole pipeline.

How It Works

The producer uploads the payload to a data store such as Amazon S3, Azure Blob Storage, or a database, receiving a unique identifier. It then sends a message containing that identifier (the claim check) and any small metadata. The consumer reads the message, uses the identifier to fetch the payload from the store, and processes it. After processing, the payload may be deleted or left for retention.

This keeps messages small and fast while still allowing arbitrarily large data to flow through the logical pipeline. It is essentially a level of indirection through shared storage.

When to Use It

Use it when payloads exceed or approach broker limits: images, video, large documents, datasets, or batch files. Use it to reduce broker cost and latency, and to keep sensitive bulk data out of message logs by storing it in a controlled, access-managed location.

Avoid it for small messages where the extra round trip to storage adds needless latency and complexity.

Trade-offs

The pattern adds an external dependency and an extra read/write per message, increasing latency and introducing failure modes if the store is unavailable. Lifecycle management is required so orphaned payloads (whose messages were lost) are cleaned up, and so payloads are not deleted before all consumers read them.

Consistency between the message and the stored data must be handled: write the data before sending the claim check.

Related Patterns

It combines well with Valet Key, which grants the consumer scoped, time-limited access to fetch the payload directly. In Pipes and Filters pipelines, claim checks pass large intermediate results between stages efficiently.

Example

A video platform accepts uploads. The API stores the raw file in S3 under a generated key and posts a message to SQS containing only that key and the user ID. A transcoding worker reads the message, downloads the object from S3 using the key, produces multiple renditions, and writes them back to S3. The broker only ever carries a few hundred bytes per job, keeping the queue fast and cheap regardless of file size.