Additional Metadata

Hatchet allows you to attach arbitrary key-value string pairs to events and workflow runs, which can be used for filtering, searching, or any other lookup purposes. This additional metadata is not part of the event payload or workflow input data but provides supplementary information for better organization and discoverability.

You can attach additional metadata when pushing events or triggering workflow runs using the Hatchet client libraries:

hatchet.event.push(
    "user:create",
    {'userId': '1234'},
    options=PushEventOptions(
        additional_metadata={
            "source": "api" # Arbitrary key-value pair
        }
    )
)

hatchet.event.push(
  'user:create',
  {
    test: 'test',
  },
  {
    additionalMetadata: {
      source: 'api', // Arbitrary key-value pair
    },
  }
);

err := c.Event().Push(
    context.Background(),
    "user:create",
    testEvent,
    client.WithEventMetadata(map[string]string{
        "source": "api", // Arbitrary key-value pair
    }),
)

simple_workflow.run(
    SimpleInput(user_id=1234),
    options=TriggerWorkflowOptions(
        additional_metadata={
          "hello": "moon" # Arbitrary key-value pair
        }
    )
)

const workflowRunId = await hatchet.admin.run_workflow(
  'user-workflow',
  {
    userId: '1234',
  },
  {
    additionalMetadata: {
      source: 'api', // Arbitrary key-value pair
    },
  }
);

workflowRunId, err := c.Admin().RunWorkflow(
    "user-workflow",
    &userCreateEvent{
        UserID: "1234",
    },
    client.WithRunMetadata(map[string]interface{}{
        "source": "api", // Arbitrary key-value pair
    }),
)

Note: This feature is in development. Cron, Schedule, and Child Workflow triggers do not currently support additional metadata.

Filtering in the Dashboard

Once you’ve attached additional metadata to events or workflow runs, this data will be available in the Event and Workflow Run list views in the Hatchet dashboard. You can use the filter input field to search for events or workflow runs based on the additional metadata key-value pairs you’ve attached.

For example, you can filter events by the source metadata keys to quickly find events originating from a specific source or environment.

Use Cases

Some common use cases for additional metadata include:

• Tagging events or workflow runs with environment information (e.g., production, staging, development)
• Specifying the source or origin of events (e.g., api, webhook, manual)
• Categorizing events or workflow runs based on business-specific criteria (e.g., priority, region, product)

By leveraging additional metadata, you can enhance the organization, searchability, and discoverability of your events and workflow runs within Hatchet.