Skip to main content
Command records signal operations that are interpreted by the service. S2 SDKs and the CLI make it easy to create supported command records, so most applications do not need to construct them directly. Concretely, a command record is a record with:
  1. A single header with an empty name. Empty header names are not allowed in any other context.
  2. The operation encoded in that header value.
  3. The command payload in the record body.
Command records take up a sequence number on the stream, and will be returned to reads. It is easy to test and filter out commands if needed, with the logic len(headers) == 1 && headers[0].name == b"".

​
Operations

Operations that are currently supported:
  • fence — set a fencing token for cooperative write exclusion. Payload is up to 36 UTF-8 bytes; an empty payload clears the token.
  • trim — set a trim point to remove older records. Payload is exactly 8 big-endian bytes representing the desired earliest sequence number.
curl -X POST "https://{basin}.b.s2.dev/v1/streams/my-stream/records" \
    -H "Authorization: Bearer <token>" \
    -H "s2-format: raw" \
    -H "Content-Type: application/json" \
    -d '{
      "records": [
        {
          "headers": [
            ["", "fence"]
          ],
          "body": "producer-123"
        }
      ]
    }'

​
See also

Concurrency control

Coordinate writers with match sequence numbers and fencing tokens.

Trimming

Discard older records by setting a stream trim point.

Appends

Understand append acknowledgements, batching, and durability.