Skip to main content

Documentation Index

Fetch the complete documentation index at: https://s2.dev/docs/llms.txt

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

Basins and streams each have configuration that can be set at creation time and modified later via reconfigure (streams, basins). The most important choices are:
  • Storage class: standard or express. This controls append latency, not durability. Both classes are regionally durable. See Architecture: Storage classes.
  • Retention: how long records stick around. Defaults to 7 days. See Retention.
  • Auto-creation: whether streams are created implicitly on first append or read, useful when you have many short-lived or dynamic streams.
  • Stream encryption: optionally require request-time encryption keys for newly created streams. See Encryption.
You can view and edit configs from the CLI: 
# view current config
s2 get-stream-config s2://my-basin/my-stream

# reconfigure stream
s2 reconfigure-stream s2://my-basin/my-stream --storage-class express
… or from the dashboard: Basin config in the S2 dashboard

​
Stream config

For the full set of fields, see the create and reconfigure API docs, or the docs for the SDK you are using.
Encryption is configured on the basin, not in StreamConfig. A stream captures the basin’s stream_cipher when it is created and keeps that cipher for life. See Encryption.
A summary:
FieldDefaultDescription
storage_classstandardstandard or express. Stream storage class affects initial acknowledgement latency only, not durability.
retention_policy7 daysAge-based (in seconds) or infinite.
delete_on_emptyDisabledAuto-delete empty streams after a minimum age.
timestamping.modeclient-preferHow timestamps should be assigned: by S2 on arrival; from the client, if provided, with client-prefer; or always from the client, with client-require.
timestamping.uncappedfalseAllow client timestamps to exceed arrival time.

​
Retention

S2 is designed to accommodate both infinite accumulation of data and time-bounded retention. You can use a stream as the long-term source of truth for your data, or as a momentary durable buffer on the way to somewhere else. A retention policy can be configured on a stream, and S2 will automatically delete records that are older than the configured threshold. This can be set when creating a stream or by reconfiguring an existing one.
Records may stay visible for a brief period after their retention window expires, typically on the order of minutes.

​
Delete on empty

When enabled, a stream is automatically deleted once all its records have been trimmed and the stream is empty. The min_age_secs field requires the stream to have existed for at least that long before it can be auto-deleted. Useful for ephemeral streams, e.g. one stream per job run where the data is consumed and no longer needed.

​
Timestamping

Every record has a timestamp alongside its sequence number, and reads can start from a timestamp. timestamping.mode controls which clock is used:
  • client-prefer (default): use the client timestamp when present, otherwise use S2 arrival time.
  • client-require: require the client to provide a timestamp.
  • arrival: always use S2 arrival time, in milliseconds since the Unix epoch.
S2 keeps timestamps monotonic within each stream. If a timestamp would move backwards, S2 adjusts it to the highest timestamp already seen on that stream. Adjacent records may share the same timestamp. By default, arrival time caps client timestamps so a bad clock cannot push the stream far into the future. Set timestamping.uncapped to true when your timestamp scale is not wall-clock time.
See Keeping time on a stream for background.

​
Basin config

FieldDefaultDescription
create_stream_on_appendfalseAuto-create streams on first append.
create_stream_on_readfalseAuto-create streams on first read.
default_stream_configSee aboveDefaults used when not explicitly specified.
stream_cipherUnsetCipher for newly created streams: aegis-256, aes-256-gcm, or unset for plaintext streams.