{"page":{"agent_metadata":{"content_type":"guide","outputs":["create-manage-namespaces","design-task-queue-topology","configure-retention-policies"],"prerequisites":["temporal-concepts"]},"categories":["workflow-orchestration"],"content_plain":"Temporal Namespaces and Task Queues# Namespaces and task queues are Temporal\u0026rsquo;s two primary organizational mechanisms. Namespaces provide isolation \u0026ndash; separate history, retention, and access. Task queues route work to specific workers. Together, they determine where workflows run and how long their history is kept.\nFor the underlying architecture, see Introduction to Temporal.\nNamespaces# A namespace is a logical isolation boundary. Every workflow belongs to exactly one namespace. Namespaces provide history isolation (workflows cannot see across boundaries), independent retention policies, per-namespace search attributes, and scoped access control.\nCreating Namespaces# With the Temporal CLI:\ntemporal operator namespace create \\ --namespace order-processing \\ --retention 72h \\ --description \u0026#34;Order processing workflows\u0026#34; temporal operator namespace create \\ --namespace compliance \\ --retention 720h \\ --description \u0026#34;Compliance workflows with 30-day retention\u0026#34;With the Go SDK:\nfunc createNamespace() error { nsClient, err := client.NewNamespaceClient(client.Options{ HostPort: \u0026#34;localhost:7233\u0026#34;, }) if err != nil { return err } defer nsClient.Close() retention := 72 * time.Hour return nsClient.Register(context.Background(), \u0026amp;workflowservice.RegisterNamespaceRequest{ Namespace: \u0026#34;order-processing\u0026#34;, WorkflowExecutionRetentionPeriod: durationpb.New(retention), }) }Retention Policies# Retention defines how long Temporal keeps event history for completed workflows. Choose based on your needs:\nScenario Retention Development / testing 24h Standard production 72h Financial / regulated 720h (30 days), with archival High-volume, low-value 24-48h Namespace Best Practices# One namespace per environment. Use order-processing-dev, order-processing-staging, order-processing-prod to prevent cross-environment accidents.\nOne namespace per team or domain. Independent teams get independent namespaces. This avoids workflow ID collisions and allows team-specific retention.\nAvoid sprawl. Do not create a namespace per microservice unless you have a genuine isolation requirement. Multiple services can share a namespace within the same domain.\nNaming conventions. Lowercase with hyphens: payment-processing, user-onboarding. Add environment suffix when sharing a cluster: payment-processing-prod.\nTask Queues# A task queue routes work to workers. When you start a workflow, you specify which task queue it runs on. Workers poll specific queues. Task queues are created implicitly \u0026ndash; the first reference to a queue name starts tracking it.\nThe flow: client starts workflow on \u0026quot;order-queue\u0026quot; -\u0026gt; Temporal places task on \u0026quot;order-queue\u0026quot; -\u0026gt; worker polling \u0026quot;order-queue\u0026quot; picks it up and executes.\nTask Queue Patterns# One Queue Per Workflow Type# Each workflow type gets its own queue with dedicated workers:\nw := worker.New(c, \u0026#34;order-queue\u0026#34;, worker.Options{}) w.RegisterWorkflow(OrderWorkflow) w.RegisterActivity(orderActivities) w2 := worker.New(c, \u0026#34;notification-queue\u0026#34;, worker.Options{}) w2.RegisterWorkflow(NotificationWorkflow) w2.RegisterActivity(notificationActivities)Clean separation, but every new workflow type requires a new deployment.\nOne Queue Per Resource Pool# Route based on resource needs, not workflow type:\n// Heavy compute -- deployed on large instances w := worker.New(c, \u0026#34;compute-heavy\u0026#34;, worker.Options{ MaxConcurrentActivityExecutionSize: 4, }) w.RegisterWorkflow(VideoTranscodeWorkflow) w.RegisterWorkflow(DataPipelineWorkflow) // I/O bound -- smaller instances, many concurrent calls w2 := worker.New(c, \u0026#34;io-bound\u0026#34;, worker.Options{ MaxConcurrentActivityExecutionSize: 50, }) w2.RegisterActivity(apiCallActivities)Activity-Specific Queues# A workflow can dispatch different activities to different queues. The orchestration runs on a lightweight worker while heavy activities run on specialized ones:\nfunc ProcessOrderWorkflow(ctx workflow.Context, order Order) error { // Validate on the main queue ctx1 := workflow.WithActivityOptions(ctx, workflow.ActivityOptions{ TaskQueue: \u0026#34;order-queue\u0026#34;, StartToCloseTimeout: 10 * time.Second, }) err := workflow.ExecuteActivity(ctx1, ValidateOrder, order).Get(ctx, nil) if err != nil { return err } // Charge on the payment-specific queue ctx2 := workflow.WithActivityOptions(ctx, workflow.ActivityOptions{ TaskQueue: \u0026#34;payment-queue\u0026#34;, StartToCloseTimeout: 30 * time.Second, RetryPolicy: \u0026amp;temporal.RetryPolicy{MaximumAttempts: 3}, }) err = workflow.ExecuteActivity(ctx2, ChargePayment, order.PaymentInfo).Get(ctx, nil) if err != nil { return err } // Notify on the notification queue ctx3 := workflow.WithActivityOptions(ctx, workflow.ActivityOptions{ TaskQueue: \u0026#34;notification-queue\u0026#34;, StartToCloseTimeout: 15 * time.Second, }) return workflow.ExecuteActivity(ctx3, SendConfirmation, order).Get(ctx, nil) }This pattern is powerful for microservice architectures. Each service runs its own worker on its own queue, exposing capabilities as activities. The workflow ties them together.\nWorker Binding# A worker registers specific workflows and activities on a specific task queue. Multiple workers can poll the same queue for horizontal scaling.\nfunc main() { c, err := client.Dial(client.Options{ HostPort: \u0026#34;localhost:7233\u0026#34;, Namespace: \u0026#34;order-processing\u0026#34;, }) if err != nil { log.Fatalln(\u0026#34;Unable to create client\u0026#34;, err) } defer c.Close() w := worker.New(c, \u0026#34;order-queue\u0026#34;, worker.Options{ MaxConcurrentWorkflowTaskExecutionSize: 100, MaxConcurrentActivityExecutionSize: 50, }) w.RegisterWorkflow(OrderWorkflow) w.RegisterWorkflow(RefundWorkflow) orderActs := NewOrderActivities(paymentClient, inventoryClient) w.RegisterActivity(orderActs) err = w.Run(worker.InterruptCh()) if err != nil { log.Fatalln(\u0026#34;Worker failed\u0026#34;, err) } }Key worker.Options:\nOption Purpose Default MaxConcurrentWorkflowTaskExecutionSize Max concurrent workflow tasks 1000 MaxConcurrentActivityExecutionSize Max concurrent activity tasks 1000 WorkerActivitiesPerSecond Rate limit for activity dispatch Unlimited Set these based on your worker\u0026rsquo;s resources. A 2-CPU worker should not run 1000 concurrent CPU-bound activities.\nPutting It Together# A complete topology for an e-commerce platform:\nNamespace: commerce-prod (retention: 72h) Task Queue: \u0026#34;order-orchestration\u0026#34; Workers: 3 replicas (lightweight orchestration) Workflows: OrderWorkflow, RefundWorkflow Task Queue: \u0026#34;payment-processing\u0026#34; Workers: 2 replicas (PCI-scoped network) Activities: ChargeCard, RefundCard Task Queue: \u0026#34;notification-dispatch\u0026#34; Workers: 2 replicas (I/O-bound) Activities: SendEmail, SendSMS Namespace: commerce-analytics (retention: 168h) Task Queue: \u0026#34;analytics-pipeline\u0026#34; Workers: 2 replicas (compute-heavy) Workflows: DailyAggregationWorkflowEach queue maps to a Kubernetes Deployment. Workers scale independently based on backlog. Orchestration workers are small. Payment workers have restricted network policies.\nNext Steps# With namespaces and task queues configured, write actual workflow code with Your First Temporal Workflow in Go.\n","date":"2026-02-22","description":"Design namespace boundaries for isolation and retention, configure task queue topologies for routing, and bind workers to queues using the Go SDK.","lastmod":"2026-02-22","levels":["beginner"],"reading_time_minutes":4,"section":"knowledge","skills":["temporal-namespace-management","task-queue-design","workflow-routing"],"tags":["temporal","namespaces","task-queues","isolation","routing","retention"],"title":"Temporal Namespaces and Task Queues: Organizing Workflows","tools":["temporal","go"],"url":"https://agent-zone.ai/knowledge/workflow-orchestration/temporal-namespaces-task-queues/","word_count":793}}