Skip to main content

Search attributes

A search attribute is a typed value a run carries so that you can find it later: the customer an order belongs to, its amount, the stage it has reached. The Runs list filters on them, fluidgrids runs count groups by them, and batch operations select runs by them. They work for durable functions and canvas workflows alike.

Defining attributes​

A workspace defines its attributes first, at most 50. In the app, open Settings → Run control → Search attributes and add a name, a type and an optional description. Names start with a letter and use letters, digits and underscores, at most 64 characters. From the CLI:

fluidgrids search-attributes create customerId --type keyword
fluidgrids search-attributes create orderAmount --type double --description 'Order total in EUR'
fluidgrids search-attributes list
fluidgrids search-attributes delete orderAmount # runs keep their values
TypeHolds
KEYWORDAn exact string, such as an id
TEXTFree text, searched by words
KEYWORD_LISTA list of exact strings, such as tags
INT, DOUBLENumbers
BOOLtrue or false
DATETIMEAn ISO 8601 date and time

Setting attributes​

At the start: pass them with the start, for example fluidgrids runs start order --search-attributes '{"customerId":"c-42"}'.

From a durable function: ctx.upsertSearchAttributes merges values into the run's attributes; null removes one.

ctx.upsertSearchAttributes({ customerId: order.customerId, orderAmount: order.total });
// later
ctx.upsertSearchAttributes({ stage: 'shipped' });

Child runs and continue-as-new take a searchAttributes option. A child starts with exactly the attributes you give it; it inherits nothing from its parent. A continued run inherits the attributes of the run it continues, unless the option replaces them.

From the canvas: the Set Search Attributes node (under Flow in the Node Store) sets or removes attributes of the run as it passes the node. Its values can be expressions, such as {{ $json.customer.id }}.

By hand: on the run page, the Search attributes card shows the run's values, and Set attributes changes them.

Every value is checked against its attribute's type. A name the workspace has not defined is refused.

Finding runs​

In the Runs list, open Search attributes to filter: add conditions on attributes, and choose whether runs must match all of them or any. Text attributes match by words.

fluidgrids runs count --key approvals --group-by status --group-by-attribute customerId
fluidgrids runs batch cancel --key approvals --search-attributes '{"and":[{"name":"customerId","op":"EQ","value":"c-42"}]}' --dry-run

On the command line and in the API, a filter has and and or lists of conditions (name, op, value) and an optional text for words in text attributes, at most 20 conditions in all. The operators are EQ, NEQ, IN, GT, GTE, LT and LTE, among others, each for the types it makes sense for.

runs count --group-by-attribute groups by KEYWORD, INT, DOUBLE, BOOL or DATETIME attributes, after any --group-by columns, two columns in all. Runs without the attribute are counted under (none).

Schedules​

A schedule can stamp attributes on every run it starts; see Schedules.

Next steps​