Module: ActiveJob::Temporal::SearchAttributes

Extended by:
SearchAttributes
Included in:
SearchAttributes
Defined in:
lib/activejob/temporal/search_attributes.rb

Overview

Note:

Pre-Registration Required Search attributes MUST be pre-registered in the Temporal cluster with the correct type (KEYWORD, TIME, INTEGER, etc.) before use. Unregistered attributes will cause workflow start failures. Use the Temporal CLI to register attributes:

tctl admin cluster add-search-attributes --name ajClass --type Keyword
tctl admin cluster add-search-attributes --name ajQueue --type Keyword
tctl admin cluster add-search-attributes --name ajJobId --type Keyword
tctl admin cluster add-search-attributes --name ajEnqueuedAt --type Datetime
tctl admin cluster add-search-attributes --name ajTenantId --type Int
tctl admin cluster add-search-attributes --name ajTags --type KeywordList
Note:

Tenant ID Extraction The module automatically extracts tenant_id from the first job argument if it responds to the ‘tenant_id` method. This supports multi-tenant architectures where jobs operate on tenant-specific data.

Builds Temporal search attributes for job metadata.

This module constructs typed search attributes that enable filtering and searching workflows in the Temporal UI and via the Temporal API. Attributes include job class, queue name, job ID, enqueued timestamp, and optionally tenant ID.

Examples:

Created attributes

- ajClass: KEYWORD (job class name)
- ajQueue: KEYWORD (queue name)
- ajJobId: KEYWORD (unique job ID)
- ajEnqueuedAt: TIME (enqueue timestamp)
- ajTenantId: INTEGER (optional, if first argument responds to :tenant_id)
- ajTags: KEYWORD_LIST (optional, if tags are configured)

Querying with search attributes (Temporal CLI)

# Find all jobs in the "mailers" queue
tctl workflow list --query "ajQueue='mailers'"

# Find specific job by ID
tctl workflow list --query "ajJobId='abc-123'"

# Find all tenant jobs enqueued today
tctl workflow list --query "ajTenantId=42 AND ajEnqueuedAt > '2025-10-31T00:00:00Z'"

# Find jobs tagged as urgent
tctl workflow list --query "ajTags='urgent'"

See Also:

Constant Summary collapse

SEARCH_ATTRIBUTE_KEY_DEFINITIONS = 
{
  aj_class: ["ajClass", :KEYWORD],
  aj_queue: ["ajQueue", :KEYWORD],
  aj_job_id: ["ajJobId", :KEYWORD],
  aj_enqueued_at: ["ajEnqueuedAt", :TIME],
  aj_tenant_id: ["ajTenantId", :INTEGER],
  aj_tags: ["ajTags", :KEYWORD_LIST]
}.freeze

Instance Method Summary collapse

Instance Method Details

#for(job) ⇒ Temporalio::SearchAttributes

Builds a Temporalio::SearchAttributes object for a job.

Creates typed search attribute keys and populates them with job metadata. If ‘enable_search_attributes` is disabled in configuration, this should still be called but may return an empty attributes object (handled by caller).

Examples:

Basic usage

job = MyJob.new
attributes = SearchAttributes.for(job)
# attributes contains ajClass, ajQueue, ajJobId, ajEnqueuedAt

With tenant ID (automatic extraction)

class TenantJob < ApplicationJob
  def perform(tenant)
    # tenant.tenant_id is extracted automatically
  end
end
tenant = Tenant.find(42)
job = TenantJob.new(tenant)
attributes = SearchAttributes.for(job)
# attributes also contains ajTenantId: 42

Without tenant ID

job = MyJob.new("plain_string_arg")
attributes = SearchAttributes.for(job)
# attributes does NOT contain ajTenantId (first arg doesn't respond to tenant_id)

Parameters:

  • job (ActiveJob::Base) —

    The job instance to extract metadata from

Returns:

  • (Temporalio::SearchAttributes) —

    Typed search attributes for Temporal

Raises:

  • (Temporalio::Error::WorkflowUpdateFailedError) —

    if attributes are not pre-registered in Temporal

  • (ArgumentError) —

    if job is nil

  • (TypeError) —

    if job does not respond to required methods

  • (NameError) —

    if Temporalio::SearchAttributes is not defined



97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
 
# File 'lib/activejob/temporal/search_attributes.rb', line 97

def for(job)
  # Create Temporal search attributes with typed keys
  attributes = Temporalio::SearchAttributes.new

  # Define and set core attributes
  set_core_attributes(attributes, job)

  # Add tenant ID if available
  add_tenant_attribute(attributes, job)

  # Add job tags if available
  add_tags_attribute(attributes, job)

  attributes
end