Skip to content

Commit f94ad79

Browse files
committed
docs(external-storage): correct the payload size threshold boundary
All three SDKs offload a payload when its serialized size is greater than or equal to the threshold, not strictly greater: - TypeScript: external-storage-runner.ts, `if (size < payloadSizeThreshold) continue` - Python: _extstore.py, `if payload.ByteSize() < self.payload_size_threshold` - Go: internal_extstore.go, `if proto.Size(p) < v.params.payloadSizeThreshold` The pages said "larger than 256 KiB", and the TypeScript page said payloads "at or below the threshold stay inline", which is backwards at the boundary. The Python SDK's own S3 driver README already documented this correctly. Also notes that the size compared is the serialized Payload including its metadata, not the raw application data. Separately, the encyclopedia told all readers to set the threshold to zero to externalize every payload. That is right for Python and TypeScript but wrong for Go, where zero selects the 256 KiB default and 1 is the value that offloads everything. The Go SDK page already had this right.
1 parent 881fda2 commit f94ad79

4 files changed

Lines changed: 23 additions & 17 deletions

File tree

docs/develop/go/best-practices/data-handling/external-storage.mdx

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -81,7 +81,7 @@ w := worker.New(c, "my-task-queue", worker.Options{})
8181
```
8282
<!--SNIPEND-->
8383

84-
By default, payloads larger than 256 KiB are offloaded to external storage. You can adjust this with the
84+
By default, payloads of 256 KiB or larger are offloaded to external storage. You can adjust this with the
8585
`PayloadSizeThreshold` option, even setting it to 1 to externalize all payloads regardless of size. Refer to
8686
[Configure payload size threshold](#configure-payload-size-threshold) for more information.
8787

@@ -230,9 +230,11 @@ You can also package your driver as a [plugin](/develop/plugins-guide) for easie
230230

231231
## Configure payload size threshold
232232

233-
You can configure the payload size threshold that triggers external storage. By default, payloads larger than 256 KiB
233+
You can configure the payload size threshold that triggers external storage. By default, payloads of 256 KiB or larger
234234
are offloaded to external storage. You can adjust this with the `PayloadSizeThreshold` option, or set it to 1 to
235-
externalize all payloads regardless of size. A value of 0 is interpreted as the default (256 KiB).
235+
externalize all payloads regardless of size. A value of 0 is interpreted as the default (256 KiB). Payloads smaller than
236+
the threshold stay inline in Event History. The size compared against the threshold is that of the serialized Payload,
237+
which includes its metadata, not just your data.
236238

237239
<!--SNIPSTART go-external-storage-threshold-->
238240
[features/snippets/external_storage/threshold/threshold_config.go](https://github.com/temporalio/features/blob/main/features/snippets/external_storage/threshold/threshold_config.go)

docs/develop/python/best-practices/data-handling/external-storage.mdx

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -78,7 +78,7 @@ worker = Worker(
7878
```
7979
<!--SNIPEND-->
8080

81-
By default, payloads larger than 256 KiB are offloaded to external storage. You can adjust this with the
81+
By default, payloads of 256 KiB or larger are offloaded to external storage. You can adjust this with the
8282
`payload_size_threshold` parameter, even setting it to 0 to externalize all payloads regardless of size. Refer to
8383
[Configure payload size threshold](#configure-payload-size-threshold) for more information.
8484

@@ -200,9 +200,10 @@ data_converter = dataclasses.replace(
200200

201201
## Configure payload size threshold
202202

203-
You can configure the payload size threshold that triggers external storage. By default, payloads larger than 256 KiB
203+
You can configure the payload size threshold that triggers external storage. By default, payloads of 256 KiB or larger
204204
are offloaded to external storage. You can adjust this with the `payload_size_threshold` parameter, or set it to 0 to
205-
externalize all payloads regardless of size.
205+
externalize all payloads regardless of size. Payloads smaller than the threshold stay inline in Event History. The size
206+
compared against the threshold is that of the serialized Payload, which includes its metadata, not just your data.
206207

207208
<!--SNIPSTART python-external-storage-threshold-->
208209
[features/snippets/external_storage/threshold/threshold_config.py](https://github.com/temporalio/features/blob/main/features/snippets/external_storage/threshold/threshold_config.py)

docs/develop/typescript/best-practices/data-handling/external-storage.mdx

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -138,7 +138,7 @@ tabs that follow. Only the driver setup differs between the two. Everything afte
138138
```
139139
<!--SNIPEND-->
140140

141-
By default, payloads larger than 256 KiB are offloaded to external storage. You can adjust this with the
141+
By default, payloads of 256 KiB or larger are offloaded to external storage. You can adjust this with the
142142
`payloadSizeThreshold` option, even setting it to `0` to externalize all payloads regardless of size. Refer to
143143
[Configure payload size threshold](#configure-payload-size-threshold) for more information.
144144

@@ -397,9 +397,10 @@ export function createDataConverter(rootDir: string = STORAGE_ROOT): DataConvert
397397

398398
## Configure payload size threshold
399399

400-
You can configure the payload size threshold that triggers external storage. By default, payloads larger than 256 KiB
400+
You can configure the payload size threshold that triggers external storage. By default, payloads of 256 KiB or larger
401401
are offloaded to external storage. You can adjust this with the `payloadSizeThreshold` option, or set it to `0` to
402-
externalize all payloads regardless of size. Payloads at or below the threshold stay inline in Event History.
402+
externalize all payloads regardless of size. Payloads smaller than the threshold stay inline in Event History. The size
403+
compared against the threshold is that of the serialized Payload, which includes its metadata, not just your data.
403404

404405
<!--SNIPSTART typescript-external-storage-threshold-->
405406
```ts

docs/encyclopedia/data-conversion/external-storage.mdx

Lines changed: 10 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -56,12 +56,13 @@ External Storage addresses several common scenarios:
5656
- **AI agent conversations.** Long conversation histories grow with each turn, and the cumulative size can degrade
5757
Workflow performance.
5858
- **Spiky data sizes.** Some Workflows handle data that is usually small but occasionally large. The Claim check pattern
59-
handles these spikes transparently, offloading only the payloads that exceed the size threshold.
59+
handles these spikes transparently, offloading only the payloads that reach the size threshold.
6060
- **Migration to Temporal Cloud.** Self-hosted deployments may have higher configured payload limits. External Storage
6161
lets you migrate to Cloud without restructuring Workflows that exceed the 2 MB limit.
6262
- **Data governance.** While Temporal supports end-to-end client-side encryption, some organizations prefer to store
63-
payload data in infrastructure they control. Set the offload size threshold to zero to externalize all payloads
64-
regardless of size.
63+
payload data in infrastructure they control. Lower the offload size threshold to externalize all payloads regardless
64+
of size. In the Python and TypeScript SDKs, set the threshold to 0. In the Go SDK, set it to 1, because 0 selects the
65+
256 KiB default.
6566

6667
For SDK-specific usage guides, see:
6768

@@ -81,16 +82,16 @@ During [Data Conversion](/dataconversion), External Storage sits at the end of t
8182
alt="The Flow of Data through a Data Converter"
8283
/>
8384

84-
When a Temporal Client sends a payload that exceeds the configured size threshold, the storage driver uploads the
85-
payload to your external store and replaces it with a lightweight reference. Payloads below the threshold stay inline in
86-
the Event History.
85+
When a Temporal Client sends a payload that reaches or exceeds the configured size threshold, the storage driver uploads
86+
the payload to your external store and replaces it with a lightweight reference. Payloads below the threshold stay
87+
inline in the Event History.
8788

8889
When the Temporal Service dispatches Tasks to the Worker, the process reverses. The Worker downloads the referenced
8990
payloads from external storage in parallel, then passes them back through the Payload Codec and Payload Converter to
9091
reconstruct the original data.
9192

9293
The SDK parallelizes uploads and downloads to minimize latency. When a single Workflow Task involves multiple payloads
93-
that exceed the threshold, the SDK uploads or downloads all of them concurrently rather than one at a time. This allows
94+
that reach the threshold, the SDK uploads or downloads all of them concurrently rather than one at a time. This allows
9495
external storage operations to scale well even when a Task carries many large payloads.
9596

9697
When a payload is offloaded to external storage, the Temporal UI displays a reference token instead of the actual data.
@@ -152,7 +153,8 @@ For example, see the
152153

153154
Configure External Storage on the Data Converter. The key settings are:
154155

155-
- **Size threshold**. The driver offloads payloads larger than this value, which defaults to 256 KiB.
156+
- **Size threshold**. The driver offloads payloads whose serialized size reaches or exceeds this value. Defaults to
157+
256 KiB.
156158
- **Drivers**. One or more storage driver implementations.
157159
- **Driver selector**. When using multiple drivers, you must provide a function that chooses which driver handles each
158160
payload.

0 commit comments

Comments
 (0)