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.

Read records from a stream.

​
Read from the beginning

s2 read s2://my-basin/my-stream -s 0 -n 10

⦿ 54 bytes (3 records in range 0..=2)
hello world
foo bar
third record

​
JSON output

s2 read s2://my-basin/my-stream -s 0 -n 3 --format json

{"seq_num":0,"timestamp":1771390606217,"body":"hello world"}
{"seq_num":1,"timestamp":1771390606217,"body":"foo bar"}
{"seq_num":2,"timestamp":1771390606217,"body":"third record"}

​
Read from a timestamp

# Absolute (milliseconds since epoch)
s2 read s2://my-basin/my-stream --timestamp 1771390606217

# Relative
s2 read s2://my-basin/my-stream --ago 1h

​
Read from a tail offset

s2 read s2://my-basin/my-stream --tail-offset 100

​
Follow for new records

Without a limit (-n or -b), read keeps tailing and waits for new records indefinitely: 
s2 read s2://my-basin/my-stream -s 0

​
Encrypted streams

export S2_ENCRYPTION_KEY="$(cat ./stream-key.b64)"

s2 read s2://my-basin/my-stream -s 0 -n 10
Or pass the key on the command line: 
s2 read s2://my-basin/my-stream \
  --encryption-key-file ./stream-key.b64 \
  -s 0 -n 10
The same --encryption-key and --encryption-key-file flags also apply to s2 tail.

​
Options

FlagDescription
-s, --seq-numStarting sequence number (inclusive).
--timestampStarting timestamp in milliseconds since Unix epoch (inclusive).
--agoStarting timestamp as a human-friendly delta from current time e.g. “1h”, which will be converted to milliseconds since Unix epoch.
--tail-offsetStart from N records before the tail of the stream.
-n, --countLimit the number of records returned.
-b, --bytesLimit the number of bytes returned.
--untilExclusive end-timestamp in milliseconds since Unix epoch. If provided, results will be limited such that all records returned will have a timestamp < the one provided via until.
--clampClamp the start position at the tail position.
--formatOutput format.
-o, --outputOutput records to a file or stdout. Use - to write to stdout.
-k, --encryption-keyBase64-encoded encryption key material. Alternatively, set S2_ENCRYPTION_KEY.
--encryption-key-fileRead base64-encoded encryption key material from file.

​
Tail

Like tail on Unix, it shows the last N records from a stream. 
s2 tail s2://my-basin/my-stream -n 5
Follow for new records with -f: 
s2 tail s2://my-basin/my-stream -f