Produce a batch of messages

ProduceBatch(ctx context.Context, items ...*ProduceItem[T]) ([]*ProduceResult[T], error)

Produces all items in one transaction and returns after commit. Results follow argument order. This explicit batch has its own transaction and does not combine with concurrent Produce calls or other explicit batches.

Example

Use a registered producer for the payments.requested stream and the example payload.

first, err := sqlstreams.NewProduceItem(&PaymentRequestedV1{OrderId: "order-123"}, nil)
if err != nil {
  return err
}
second, err := sqlstreams.NewProduceItem(&PaymentRequestedV1{OrderId: "order-124"}, nil)
if err != nil {
  return err
}
results, err := producer.ProduceBatch(ctx, first, second)
if err != nil {
  return err
}
for _, result := range results {
  fmt.Println(result.Id, result.Duplicate)
}

Parameters

Parameter	Type	Required	Description
`ctx`	`context.Context`	Yes	Controls the batch operation. A failure at commit can leave its outcome uncertain.
`items`	`...*ProduceItem[T]`	Yes	At least one non-`nil` item with a non-`nil`, JSON-encodable payload and `SchemaVersion` of at least `1`. Caller-supplied idempotency keys are forbidden.

NewProduceItem

NewProduceItem[T Versioned](message *T, options *ProduceOptions) (*ProduceItem[T], error)

Pairs a non-nil payload with its options. nil options use an empty options value. It rejects a caller-supplied IdempotencyKey. Other option validation and producer-default resolution happen when ProduceBatch runs.

ProduceItem

Field	Type	Description
`Message`	`*T`	Payload to produce.
`Options`	`ProduceOptions`	Per-message options. Producer message defaults fill unset fields.

NewProduceItem retains the payload pointer and copies the options struct. Treat the item and its nested values as immutable while producing.

Returns

Condition	Return value
Batch succeeds	`(results, nil)`, one `ProduceResult` per item in argument order.
Batch fails	`(nil, err)`. An item-specific error includes its zero-based index as `item N: ...`.

Batch limits and retries

Batch.AttemptTimeout bounds each transaction attempt. Automatic-batch MaxSize does not split an explicit batch. All its messages commit together or roll back together.

Errors

Error	When
Validation error	Items are empty, an item is `nil`, an item sets `IdempotencyKey`, or resolved options or schema versions are invalid.
`ErrPayloadNotEncodable`	An item’s payload cannot be encoded as JSON.
Partition creation error	The required message partition cannot be created.
Database or context error	A batch attempt fails or its commit cannot be confirmed.

Produce a message — Automatic batching and caller-supplied idempotency keys.
Register a producer — Batch attempt timeout.