Skip to content

Commit d5b4a74

Browse files
CahidArdagithub-actions[bot]
CahidArda
and
github-actions[bot]
authored
DX-2698: document multi-label support in workflow docs (#716)
* DX-2698: document multi-label support in workflow docs Reflect workflow-js multi-label changes: label accepts string | string[] on trigger, log/DLQ/cancel filters accept arrays with OR semantics, context.labels replaces deprecated context.label, and workflow run logs expose a labels[] field. * chore(llms): regenerate llms.txt and llms-full.txt --------- Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
1 parent a8a7afd commit d5b4a74

11 files changed

Lines changed: 114 additions & 34 deletions

File tree

‎_snippets/workflow/logs.mdx‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -28,8 +28,13 @@
2828
The Unix timestamp (in milliseconds) when the workflow run was completed, if applicable.
2929
</ResponseField>
3030

31-
<ResponseField name="label" type="string">
32-
The label of the run assigned by the user on trigger.
31+
<ResponseField name="labels" type="string[]">
32+
The labels of the run assigned by the user on trigger.
33+
</ResponseField>
34+
35+
<ResponseField name="label" type="string" deprecated>
36+
Deprecated. Use `labels` instead. When a run has multiple labels, this only
37+
contains the first one.
3338
</ResponseField>
3439

3540
<ResponseField name="failureFunction" type="FailureFunction">

‎llms-full.txt‎

Lines changed: 57 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -41814,8 +41814,9 @@ Pass an object with a `filter` field containing one or more filter criteria:
4181441814
Cancel workflows whose URL starts with this prefix. Cannot be combined with `workflowUrl`.
4181541815
</ParamField>
4181641816

41817-
<ParamField body="label" type="string" optional>
41818-
Cancel workflows with this label.
41817+
<ParamField body="label" type="string | string[]" optional>
41818+
Cancel workflows with this label. Pass an array to match runs that
41819+
have any of the given labels (OR semantics).
4181941820
</ParamField>
4182041821

4182141822
<ParamField body="fromDate" type="Date | number" optional>
@@ -41975,8 +41976,9 @@ await client.dlq.delete({ dlqIds: ["dlq-123", "dlq-456"] });
4197541976
Filter by workflow run ID.
4197641977
</ParamField>
4197741978

41978-
<ParamField body="label" type="string" optional>
41979-
Delete workflows with this label.
41979+
<ParamField body="label" type="string | string[]" optional>
41980+
Delete workflows with this label. Pass an array to match runs that
41981+
have any of the given labels (OR semantics).
4198041982
</ParamField>
4198141983

4198241984
<ParamField body="fromDate" type="Date | number" optional>
@@ -42089,8 +42091,9 @@ DLQ messages represent failed workflow or QStash deliveries that could not be re
4208942091
Filter by workflow run ID.
4209042092
</ParamField>
4209142093

42092-
<ParamField body="label" type="string" optional>
42093-
Filter by workflow label.
42094+
<ParamField body="label" type="string | string[]" optional>
42095+
Filter by workflow label. Pass an array to match runs that have any
42096+
of the given labels (OR semantics).
4209442097
</ParamField>
4209542098

4209642099
<ParamField body="fromDate" type="Date | number" optional>
@@ -42186,8 +42189,9 @@ Pass an object with a `filter` field:
4218642189
Filter by workflow run ID.
4218742190
</ParamField>
4218842191

42189-
<ParamField body="label" type="string" optional>
42190-
Restart workflows with this label.
42192+
<ParamField body="label" type="string | string[]" optional>
42193+
Restart workflows with this label. Pass an array to match runs that
42194+
have any of the given labels (OR semantics).
4219142195
</ParamField>
4219242196

4219342197
<ParamField body="fromDate" type="Date | number" optional>
@@ -42349,8 +42353,9 @@ Pass an object with a `filter` field:
4234942353
Filter by workflow run ID.
4235042354
</ParamField>
4235142355

42352-
<ParamField body="label" type="string" optional>
42353-
Resume workflows with this label.
42356+
<ParamField body="label" type="string | string[]" optional>
42357+
Resume workflows with this label. Pass an array to match runs that
42358+
have any of the given labels (OR semantics).
4235442359
</ParamField>
4235542360

4235642361
<ParamField body="fromDate" type="Date | number" optional>
@@ -42521,8 +42526,9 @@ The `logs` method retrieves workflow run logs using the [List Workflow Runs API]
4252142526
Filter by the exact workflow URL.
4252242527
</ParamField>
4252342528

42524-
<ParamField body="label" type="string" optional>
42525-
Filter by workflow label.
42529+
<ParamField body="label" type="string | string[]" optional>
42530+
Filter by workflow label. Pass an array to match runs that have any
42531+
of the given labels (OR semantics).
4252642532
</ParamField>
4252742533

4252842534
<ParamField body="workflowCreatedAt" type="number" optional>
@@ -42588,8 +42594,13 @@ The `logs` method retrieves workflow run logs using the [List Workflow Runs API]
4258842594
The Unix timestamp (in milliseconds) when the workflow run was completed, if applicable.
4258942595
</ResponseField>
4259042596

42591-
<ResponseField name="label" type="string">
42592-
The label of the run assigned by the user on trigger.
42597+
<ResponseField name="labels" type="string[]">
42598+
The labels of the run assigned by the user on trigger.
42599+
</ResponseField>
42600+
42601+
<ResponseField name="label" type="string" deprecated>
42602+
Deprecated. Use `labels` instead. When a run has multiple labels, this only
42603+
contains the first one.
4259342604
</ResponseField>
4259442605

4259542606
<ResponseField name="failureFunction" type="FailureFunction">
@@ -42879,6 +42890,20 @@ const { runs } = await client.logs({
4287942890
})
4288042891
```
4288142892

42893+
### Filter by multiple labels
42894+
42895+
Passing an array matches runs that have any of the given labels (OR semantics).
42896+
For example, with runs labelled `["label-1", "label-2"]` and `["label-2", "label-3"]`,
42897+
filtering by `["label-1", "label-2"]` returns both.
42898+
42899+
```ts
42900+
const { runs } = await client.logs({
42901+
filter: {
42902+
label: ["label-1", "label-2"],
42903+
}
42904+
})
42905+
```
42906+
4288242907
# client.notify
4288342908
Source: https://upstash.com/docs/workflow/basics/client/notify
4288442909

@@ -43041,9 +43066,13 @@ You can also trigger multiple workflow runs in a single call by passing an array
4304143066
Unix timestamp in seconds.
4304243067
</ParamField>
4304343068

43044-
<ParamField body="label" type="string">
43069+
<ParamField body="label" type="string | string[]">
4304543070
An optional label to assign to the workflow run.
4304643071
This can be useful for identifying and filtering runs in the dashboard or logs.
43072+
43073+
Pass an array to attach multiple labels to a single workflow run. The run will
43074+
then match a [logs](/docs/workflow/basics/client/logs) or DLQ filter for any of its
43075+
labels (OR semantics).
4304743076
</ParamField>
4304843077

4304943078
<ParamField body="disableTelemetry" type="boolean">
@@ -43217,8 +43246,14 @@ The context object provides:
4321743246
The QStash client instance used by the workflow endpoint.
4321843247
</ParamField>
4321943248

43220-
<ParamField path="label" type="srting | undefined">
43221-
The label of the current workflow run, if set in [client.trigger](/docs/workflow/basics/client/trigger).
43249+
<ParamField path="labels" type="string[]">
43250+
The labels attached to the current workflow run, if set in [client.trigger](/docs/workflow/basics/client/trigger).
43251+
Defaults to an empty array when no label was set.
43252+
</ParamField>
43253+
43254+
<ParamField path="label" type="string | undefined" deprecated>
43255+
Deprecated. Use `labels` instead. When a run has multiple labels, this only
43256+
returns the first one.
4322243257
</ParamField>
4322343258

4322443259
## Context Object Functions
@@ -44834,6 +44869,11 @@ Source: https://upstash.com/docs/workflow/changelog
4483444869
We have moved the roadmap and the changelog to [Github Discussions](https://github.com/orgs/upstash/discussions) starting from October 2025.Now you can follow `In Progress` features. You can see that your `Feature Requests` are recorded. You can vote for them and comment your specific use-cases to shape the feature to your needs.
4483544870
</Note>
4483644871

44872+
<Update label="June 2026">
44873+
* **TypeScript SDK (`workflow-js`):**
44874+
* Multiple labels per workflow run are now supported. `label` on [`client.trigger`](/docs/workflow/basics/client/trigger) and `context.invoke` accepts `string | string[]`, and log/DLQ/cancel filters accept an array to match runs that have any of the given labels (OR semantics). Workflow run logs now expose a `labels: string[]` field, and `context.labels: string[]` replaces the now-deprecated `context.label`.
44875+
</Update>
44876+
4483744877
<Update label="March 2026">
4483844878
* **TypeScript SDK (`workflow-js`):**
4483944879
* Added optional `workflowRunId` parameter to `notify` method, enabling **lookback functionality**. When provided, notifications are stored and delivered even if sent before a workflow reaches `waitForEvent`, preventing race conditions. See [notify documentation](/docs/workflow/basics/client/notify) and [wait-for-event guide](/docs/workflow/features/wait-for-event#race-condition-between-wait-and-notify) for details.

‎workflow/basics/client/cancel.mdx‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -31,8 +31,9 @@ Pass an object with a `filter` field containing one or more filter criteria:
3131
Cancel workflows whose URL starts with this prefix. Cannot be combined with `workflowUrl`.
3232
</ParamField>
3333

34-
<ParamField body="label" type="string" optional>
35-
Cancel workflows with this label.
34+
<ParamField body="label" type="string | string[]" optional>
35+
Cancel workflows with this label. Pass an array to match runs that
36+
have any of the given labels (OR semantics).
3637
</ParamField>
3738

3839
<ParamField body="fromDate" type="Date | number" optional>

‎workflow/basics/client/dlq/delete.mdx‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -35,8 +35,9 @@ await client.dlq.delete({ dlqIds: ["dlq-123", "dlq-456"] });
3535
Filter by workflow run ID.
3636
</ParamField>
3737

38-
<ParamField body="label" type="string" optional>
39-
Delete workflows with this label.
38+
<ParamField body="label" type="string | string[]" optional>
39+
Delete workflows with this label. Pass an array to match runs that
40+
have any of the given labels (OR semantics).
4041
</ParamField>
4142

4243
<ParamField body="fromDate" type="Date | number" optional>

‎workflow/basics/client/dlq/list.mdx‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -30,8 +30,9 @@ DLQ messages represent failed workflow or QStash deliveries that could not be re
3030
Filter by workflow run ID.
3131
</ParamField>
3232

33-
<ParamField body="label" type="string" optional>
34-
Filter by workflow label.
33+
<ParamField body="label" type="string | string[]" optional>
34+
Filter by workflow label. Pass an array to match runs that have any
35+
of the given labels (OR semantics).
3536
</ParamField>
3637

3738
<ParamField body="fromDate" type="Date | number" optional>

‎workflow/basics/client/dlq/restart.mdx‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -32,8 +32,9 @@ Pass an object with a `filter` field:
3232
Filter by workflow run ID.
3333
</ParamField>
3434

35-
<ParamField body="label" type="string" optional>
36-
Restart workflows with this label.
35+
<ParamField body="label" type="string | string[]" optional>
36+
Restart workflows with this label. Pass an array to match runs that
37+
have any of the given labels (OR semantics).
3738
</ParamField>
3839

3940
<ParamField body="fromDate" type="Date | number" optional>

‎workflow/basics/client/dlq/resume.mdx‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -32,8 +32,9 @@ Pass an object with a `filter` field:
3232
Filter by workflow run ID.
3333
</ParamField>
3434

35-
<ParamField body="label" type="string" optional>
36-
Resume workflows with this label.
35+
<ParamField body="label" type="string | string[]" optional>
36+
Resume workflows with this label. Pass an array to match runs that
37+
have any of the given labels (OR semantics).
3738
</ParamField>
3839

3940
<ParamField body="fromDate" type="Date | number" optional>

‎workflow/basics/client/logs.mdx‎

Lines changed: 17 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -38,8 +38,9 @@ The `logs` method retrieves workflow run logs using the [List Workflow Runs API]
3838
Filter by the exact workflow URL.
3939
</ParamField>
4040

41-
<ParamField body="label" type="string" optional>
42-
Filter by workflow label.
41+
<ParamField body="label" type="string | string[]" optional>
42+
Filter by workflow label. Pass an array to match runs that have any
43+
of the given labels (OR semantics).
4344
</ParamField>
4445

4546
<ParamField body="workflowCreatedAt" type="number" optional>
@@ -122,3 +123,17 @@ const { runs } = await client.logs({
122123
}
123124
})
124125
```
126+
127+
### Filter by multiple labels
128+
129+
Passing an array matches runs that have any of the given labels (OR semantics).
130+
For example, with runs labelled `["label-1", "label-2"]` and `["label-2", "label-3"]`,
131+
filtering by `["label-1", "label-2"]` returns both.
132+
133+
```ts
134+
const { runs } = await client.logs({
135+
filter: {
136+
label: ["label-1", "label-2"],
137+
}
138+
})
139+
```

‎workflow/basics/client/trigger.mdx‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -76,9 +76,13 @@ You can also trigger multiple workflow runs in a single call by passing an array
7676
Unix timestamp in seconds.
7777
</ParamField>
7878

79-
<ParamField body="label" type="string">
79+
<ParamField body="label" type="string | string[]">
8080
An optional label to assign to the workflow run.
8181
This can be useful for identifying and filtering runs in the dashboard or logs.
82+
83+
Pass an array to attach multiple labels to a single workflow run. The run will
84+
then match a [logs](/workflow/basics/client/logs) or DLQ filter for any of its
85+
labels (OR semantics).
8286
</ParamField>
8387

8488
<ParamField body="disableTelemetry" type="boolean">

‎workflow/basics/context.mdx‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -67,8 +67,14 @@ The context object provides:
6767
The QStash client instance used by the workflow endpoint.
6868
</ParamField>
6969

70-
<ParamField path="label" type="srting | undefined">
71-
The label of the current workflow run, if set in [client.trigger](/workflow/basics/client/trigger).
70+
<ParamField path="labels" type="string[]">
71+
The labels attached to the current workflow run, if set in [client.trigger](/workflow/basics/client/trigger).
72+
Defaults to an empty array when no label was set.
73+
</ParamField>
74+
75+
<ParamField path="label" type="string | undefined" deprecated>
76+
Deprecated. Use `labels` instead. When a run has multiple labels, this only
77+
returns the first one.
7278
</ParamField>
7379

7480
## Context Object Functions

0 commit comments

Comments
 (0)