Shard

A shard is a slice of the keyspace hash(NamespaceID, WorkflowID) mod NumShards. It is the unit of horizontal scaling for the History service. The shard count is fixed at cluster creation and cannot be changed without a re-shard migration.

Aspect	Detail
Owner	Exactly one History host at a time. Owned via the Ringpop membership ring.
Identity	An integer ShardID in [1, NumHistoryShards].
Fence	RangeID — incremented on every ownership change. Stale writes are rejected.
In-memory state	Per-shard executor for each task queue family; LRU mutable-state cache; queue ack levels.
Persistence	One row in shards; per-shard executions, timer_tasks, transfer_tasks, visibility_tasks, replication_tasks.
Lifecycle	Acquire (bump RangeID, load queue states) → owned → release (drain, persist final ack levels).

Why shards are fixed-count

The shard hash is the routing key for every workflow's home. Changing the count would migrate every workflow in the cluster. The team has explored re-shard tooling several times; it has not landed in tree.

Code references

• Shard controller: service/history/shard/.
• Shard persistence: common/persistence/shard_manager.go.
• Membership integration: common/membership/.

Where to read more

• History service
• Membership
• docs/architecture/history-service.md