Pub/Sub — topics, subscriptions, the five subscription types, and the delivery guarantee you have to ask for
The object model, the five subscription types including the three that write straight into another service, at-least-once as the default with exactly-once as a configurable feature, ordering keys, dead-letter topics, and the per-message parallelism that distinguishes it from partition-based systems.
markdownreferencev11FBQ-89SGstage: designtrust: officialfamily: messagingservice: pubsubinterface: anypub/subtopicsubscriptionmessageschemapull subscriptionpush subscriptionBigQuery subscriptionBigtable subscriptionCloud Storage subscriptionat-least-onceexactly-once deliveryordering keysdead-letter topicPub/Sub Lite
Pub/Sub
1. Four objects
topic (the channel) · subscription (the delivery endpoint) · message · schema (validation).
A subscription belongs to a topic, and each subscription gets every message published to the topic. Fan-out is therefore "another subscription", not another topic.
2. Five subscription types, and three of them are not code
| Type | What it does |
|---|---|
| pull | your client retrieves messages |
| push | Pub/Sub delivers by HTTP POST to your endpoint |
| BigQuery | writes messages straight into BigQuery |
| Bigtable | writes messages straight into Bigtable |
| Cloud Storage | exports messages straight into a bucket |
The last three remove a consumer service from the architecture. "Stream events into the warehouse" is a subscription type, not a Dataflow job, and that is one of the clearest component-count reductions available on Google Cloud. Check for it before writing an ingestion pipeline — and record it in a migration estimate, because a source-cloud design will almost certainly have a running consumer doing this work.
3. The delivery guarantee
Standard subscriptions are at-least-once. Exactly-once delivery is a configurable feature — you ask for it.
So the default contract requires idempotent consumers, and that is the single most important sentence for anyone porting a queue consumer onto Pub/Sub. If the consumer cannot be made idempotent, enable exactly-once deliberately and know that you have changed the delivery semantics, not just a setting.
Stated latency: "typically on the order of 100 milliseconds".
4. Ordering, and what it costs
Ordering keys give ordered processing. Messages sharing a key are delivered in order.
The structural point the overview makes is the other side of it: Pub/Sub does per-message parallelism, "unlike partition-based systems". There is no partition count to size. But ordering keys reintroduce a serialisation, per key — which is the trade a Kafka partition makes permanently and Pub/Sub makes only where you ask. For a Kafka migration this is the row to study: partitions-for-ordering becomes keys-for-ordering, and the parallelism ceiling changes shape.
5. Failure handling
Dead-letter topics take messages that could not be delivered. Configure one on any subscription whose consumer can fail — without it, a permanently-failing message is retried until retention expires and is then simply gone.
Message retention is configurable per subscription. Recorded as an absence: the overview states no default, so none is written here. Read it from the subscription properties before relying on a replay window.
6. Pub/Sub Lite
Referenced as separate documentation. Nothing about its current status is claimed here — a service with a
separate documentation set and no description on the main overview is exactly the kind of thing to check for a
retirement notice before designing onto it (reference/iac/deployment-manager-status.md §4 explains why this
hub treats that as a first-class check).
Next: reference/messaging/cloud-tasks.md for the per-task case,
reference/messaging/eventarc.md for events from Google Cloud itself, and
guides/messaging/deliver-pubsub-to-cloud-run.md.