Changelog #78

·

Run metadata

Attach a small amount of data to a run and update it as the run progresses.

Eric Allam

Eric Allam

CTO, Trigger.dev

Image for Run metadata

You can now attach up to 4KB (4,096 bytes) of metadata to a run, which you can then access from inside the run function, via the API, and in the dashboard. You can use metadata to store additional, structured information on a run. For example, you could use metadata to update the progress of a run.

Usage

Add metadata to a run by passing it as an object to the trigger function:


_10
const handle = await myTask.trigger(
_10
{ message: "hello world" },
_10
{ metadata: { user: { name: "Eric", id: "user_1234" } } }
_10
);

Then inside your run function, you can access the metadata like this:


_10
import { task, metadata } from "@trigger.dev/sdk/v3";
_10
_10
export const myTask = task({
_10
id: "my-task",
_10
run: async (payload: { message: string }) => {
_10
const user = metadata.get("user");
_10
console.log(user.name); // "Eric"
_10
console.log(user.id); // "user_1234"
_10
},
_10
});

You can also update the metadata during the run:


_34
import { task, metadata } from "@trigger.dev/sdk/v3";
_34
_34
export const myTask = task({
_34
id: "my-task",
_34
run: async (payload: { message: string }) => {
_34
// Do some work
_34
await metadata.set("status", {
_34
state: "running",
_34
progress: 0.1,
_34
message: "Starting",
_34
});
_34
_34
// Do some more work
_34
await metadata.set("status", {
_34
state: "running",
_34
progress: 0.5,
_34
message: "Halfway there",
_34
});
_34
_34
// Do even more work
_34
await metadata.set("status", {
_34
state: "running",
_34
progress: 0.9,
_34
message: "Almost done",
_34
});
_34
_34
// Finish up
_34
await metadata.set("status", {
_34
state: "complete",
_34
progress: 1,
_34
message: "Done",
_34
});
_34
},
_34
});

Access the metadata outside of a task via the API:


_10
// Somewhere in your backend code
_10
import { runs } from "@trigger.dev/sdk/v3";
_10
_10
async function main() {
_10
const run = await runs.retrieve("run_1234");
_10
console.log(run.metadata.user.name); // "Eric"
_10
console.log(run.metadata.user.id); // "user_1234"
_10
}

Learn all about how to use metadata in the metadata documentation.

Updating

Run metadata is available as of version 3.0.8 of the SDK. To update, run:


_10
npx trigger.dev@latest update

If you are self-hosting Trigger.dev, you will need to update to version 3.0.8 or later. See our self-hosting updating docs for more information.

#77
#79

Ready to start building?

Build and deploy your first task in 3 minutes.

Get started now
,