Data storage

Store and read persistent values, counters, lists and lookup tables.

Build a shape value

Builds a shape value with named, typed fields, following one of the shapes declared by this module or server. Fill each field with a value or a connection.

Inputs

Name	Type	Required	Details
Shape	Shape	Yes	Which shape the new shape value follows. It decides which fields it has and what type each of them is.
Contents	Shape value	Yes	One value per field of the selected shape. Optional fields may be left empty and then read back as empty.

Outputs

Name	Type	Details
Shape value	Shape value	The new shape value.

Get a field of a shape value

Reads one field of a shape value. The value has the type declared for that field, so it needs no conversion.

Inputs

Name	Type	Required	Details
Shape value	Shape value	Yes	The shape value to read from.
Field	Field of a shape value	Yes	Which field to read. Maximum length: 64 characters.

Outputs

Name	Type	Details
Value	Field value	The field's value, or empty when the shape value does not carry that field. May be empty.

Update fields of a shape value

Makes a copy of a shape value with only the fields you choose changed. Every other field keeps its value, so you never connect them again. Without a chosen shape the new values are not checked when the flow runs. To count up or down, use "Increase a stored number" instead: this step cannot add to a value. Reading, updating and saving an entry are separate steps, so two runs that update the same entry at the same time can overwrite each other.

Inputs

Name	Type	Required	Details
Shape value	Shape value	Yes	The value to change. It is not changed itself: the step gives back an updated copy.
Shape	Shape	No	The shape of the value. When set, the new values are checked against it when the flow runs, and fields the value is missing because they were added to the shape later get their defaults.
Changes	Field changes	Yes	The fields to change and their new values. Leave a field out to keep it. An empty value is only allowed for fields that may be empty.

Outputs

Name	Type	Details
Updated value	Shape value	The copy with your changes. Save it to keep them.

Read a stored value

Reads a value from a storage field.

Inputs

Name	Type	Required	Details
Storage field	Storage field	Yes	Storage field to operate on.
Subject	User	No	User the value belongs to (required for user-scoped fields).
Key	Text	No	Key the value is stored under (required for keyed fields). Maximum length: 100 characters.
Default	Stored value	No	Value returned when nothing is stored (must match the field type).

Outputs

Name	Type	Details
Value	Stored value	Stored value, or empty when nothing is stored. May be empty.

Store a value

Writes a value to a storage field.

Inputs

Name	Type	Required	Details
Storage field	Storage field	Yes	Storage field to operate on.
Subject	User	No	User the value belongs to (required for user-scoped fields).
Key	Text	No	Key the value is stored under (required for keyed fields). Maximum length: 100 characters.
Value	Stored value	Yes	Value to store. Must match the type declared on the field.

Outputs

Name	Type	Details
Replaced	Yes/No	Whether a value was already stored here and has now been overwritten.

Increase a stored number

Adds a number to a numeric storage field, or to a number field inside a stored shape, in one safe step (atomic within one bot process) and returns the new value. A stored shape value saved before a field was added gets that field's default.

Inputs

Name	Type	Required	Details
Storage field	Storage field	Yes	Storage field to operate on.
Field in the shape	Field of a shape value	No	For a stored shape value: the whole number or decimal number field to change. Leave it empty for a plain number field. Maximum length: 64 characters.
Subject	User	No	User the value belongs to (required for user-scoped fields).
Key	Text	No	Key the value is stored under (required for keyed fields). Maximum length: 100 characters.
By	Decimal number	Yes	Amount to add (can be negative). Turn on Subtract to take it away. Default: 1.
Subtract	Yes/No	Yes	Takes the amount away instead of adding it. Default: No.

Outputs

Name	Type	Details
New value	Stored value	Value after the change.

Delete a stored value

Deletes a stored value from a storage field.

Inputs

Name	Type	Required	Details
Storage field	Storage field	Yes	Storage field to operate on.
Subject	User	No	User the value belongs to (required for user-scoped fields).
Key	Text	No	Key the value is stored under (required for keyed fields). Maximum length: 100 characters.

List storage entries

Returns the top entries of a storage field sorted by value (e.g. for leaderboards). People with no number in that field are left out.

Inputs

Name	Type	Required	Details
Storage field	Storage field	Yes	Storage field to operate on.
Rank by field	Field of a shape value	No	For a stored shape value: the number field to order the entries by. Leave it empty to list every entry. Maximum length: 64 characters.
Direction	Sort direction	Yes	Sort direction (descending returns the highest values first). Default: Descending.
Limit	Whole number	Yes	Maximum number of entries to return (1-100). Value: 1 to 100. Default: 10.

Outputs

Name	Type	Details
Entries	List of Storage entry	Sorted entries, each with its subject and value.

List storage entries (paginated)

Returns one page of storage entries sorted by value, with total/page metadata. User-scoped entries expose their Discord user directly. People with no number in that field are left out.

Inputs

Name	Type	Required	Details
Storage field	Storage field	Yes	Storage field to operate on.
Rank by field	Field of a shape value	No	For a stored shape value: the number field to order the entries by. Leave it empty to list every entry. Maximum length: 64 characters.
Direction	Sort direction	Yes	Sort direction (descending returns the highest values first). Default: Descending.
Entries per page	Whole number	Yes	Maximum entries per page (1-100). Value: 1 to 100. Default: 10.
Page	Whole number	Yes	One-based page number to return. Value: 1 to 1000000. Default: 1.

Outputs

Name	Type	Details
Entries	List of Storage entry	Entries on this page. The value is already the selected field's stored value; user fields expose a resolved user.
Total entries	Whole number	Total entries across all pages.
Page	Whole number	The requested page number.
Page count	Whole number	Total available pages.
Has next page	Yes/No	Whether another page follows.
Has previous page	Yes/No	Whether a previous page exists.

Get rank of a stored value

Returns the position of a subject inside a storage field when sorted by value (e.g. "#42 on the leaderboard"). People with no number in that field are left out.

Inputs

Name	Type	Required	Details
Storage field	Storage field	Yes	Storage field to operate on.
Rank by field	Field of a shape value	No	For a stored shape value: the whole number or decimal number field to rank by. Maximum length: 64 characters.
Subject	User	No	User the value belongs to (required for user-scoped fields).
Key	Text	No	Key the value is stored under (required for keyed fields). Maximum length: 100 characters.

Outputs

Name	Type	Details
Rank	Whole number	Position sorted by value (starting at 1), or empty when nothing is stored. May be empty.

Add item to stored list

Safely adds an item to the end of a stored list.

Inputs

Name	Type	Required	Details
Storage field	Storage field	Yes	Storage field to operate on.
Subject	User	No	User the value belongs to (required for user-scoped fields).
Key	Text	No	Key the value is stored under (required for keyed fields). Maximum length: 100 characters.
Item	Any	Yes	Item to append.

Outputs

Name	Type	Details
New length	Whole number	Number of items in the list after this add. It is 1 when this add created the list, which is the safe way to check "am I the first one?" without a separate read.

Remove from stored list

Safely removes the item at the given position from a stored list.

Inputs

Name	Type	Required	Details
Storage field	Storage field	Yes	Storage field to operate on.
Subject	User	No	User the value belongs to (required for user-scoped fields).
Key	Text	No	Key the value is stored under (required for keyed fields). Maximum length: 100 characters.
Index	Whole number	Yes	Position of the item to remove (starting at 0).

Outputs

Name	Type	Details
Removed	Yes/No	Whether an item was actually removed. False when there was no item at that position.
New length	Whole number	Number of items in the list afterwards.

Set key in stored lookup table

Safely sets a key in a stored lookup table to a value.

Inputs

Name	Type	Required	Details
Storage field	Storage field	Yes	Storage field to operate on.
Subject	User	No	User the value belongs to (required for user-scoped fields).
Key	Text	No	Key the value is stored under (required for keyed fields). Maximum length: 100 characters.
Key	Text	Yes	Key inside the stored lookup table.
Value	Any	Yes	Value to store under the key.

Outputs

Name	Type	Details
Replaced	Yes/No	Whether that key already existed and has now been overwritten.
New key count	Whole number	Number of keys in the lookup table afterwards.

Remove key from stored lookup table

Safely removes a key from a stored lookup table.

Inputs

Name	Type	Required	Details
Storage field	Storage field	Yes	Storage field to operate on.
Subject	User	No	User the value belongs to (required for user-scoped fields).
Key	Text	No	Key the value is stored under (required for keyed fields). Maximum length: 100 characters.
Key	Text	Yes	Key to remove from the stored lookup table.

Outputs

Name	Type	Details
Removed	Yes/No	Whether the key was actually there and has now been removed.
New key count	Whole number	Number of keys in the lookup table afterwards.

Is a value stored?

Checks whether a storage field currently has a value.

Inputs

Name	Type	Required	Details
Storage field	Storage field	Yes	Storage field to operate on.
Subject	User	No	User the value belongs to (required for user-scoped fields).
Key	Text	No	Key the value is stored under (required for keyed fields). Maximum length: 100 characters.

Outputs

Name	Type	Details
Exists	Yes/No	True when a value is stored, otherwise false.

Remove item from stored list

Removes matching item(s) by value from a stored list.

Inputs

Name	Type	Required	Details
Storage field	Storage field	Yes	Storage field to operate on.
Subject	User	No	User the value belongs to (required for user-scoped fields).
Key	Text	No	Key the value is stored under (required for keyed fields). Maximum length: 100 characters.
Item	Any	Yes	Value to remove from the list.
Remove all	Yes/No	Yes	Remove every matching item instead of only the first. Default: No.

Outputs

Name	Type	Details
Removed	Yes/No	Whether at least one matching item was removed.
Removed count	Whole number	How many items were removed. At most 1 unless "Remove all" is on.
New length	Whole number	Number of items in the list afterwards.

Stored list contains item?

Checks whether a stored list contains a value.

Inputs

Name	Type	Required	Details
Storage field	Storage field	Yes	Storage field to operate on.
Subject	User	No	User the value belongs to (required for user-scoped fields).
Key	Text	No	Key the value is stored under (required for keyed fields). Maximum length: 100 characters.
Item	Any	Yes	Value to look for in the list.

Outputs

Name	Type	Details
Contains	Yes/No	Yes when the list contains the item.

Get key from stored lookup table

Reads a single key from a stored lookup table.

Inputs

Name	Type	Required	Details
Storage field	Storage field	Yes	Storage field to operate on.
Subject	User	No	User the value belongs to (required for user-scoped fields).
Key	Text	No	Key the value is stored under (required for keyed fields). Maximum length: 100 characters.
Key	Text	Yes	Key inside the stored lookup table.
Default	Any	No	Value returned when the key is not present.

Outputs

Name	Type	Details
Value	Any	Value stored under the key, or the default (or empty) when absent. May be empty.

Stored lookup table has key?

Checks whether a stored lookup table contains a key.

Inputs

Name	Type	Required	Details
Storage field	Storage field	Yes	Storage field to operate on.
Subject	User	No	User the value belongs to (required for user-scoped fields).
Key	Text	No	Key the value is stored under (required for keyed fields). Maximum length: 100 characters.
Key	Text	Yes	Key inside the stored lookup table.

Outputs

Name	Type	Details
Exists	Yes/No	Yes when the lookup table has the key.

List stored lookup table entries

Returns every key and value of a stored lookup table.

Inputs

Name	Type	Required	Details
Storage field	Storage field	Yes	Storage field to operate on.
Subject	User	No	User the value belongs to (required for user-scoped fields).
Key	Text	No	Key the value is stored under (required for keyed fields). Maximum length: 100 characters.

Outputs

Name	Type	Details
Entries	List of Lookup table entry	Each lookup table entry, with its key and value.

List storage keys

Returns the keys (subject ids) that currently have a stored value for the field. Works on fields with up to 10,000 keys; a bigger field fails with a limit error you can catch.

Inputs

Name	Type	Required	Details
Storage field	Storage field	Yes	Storage field to operate on.

Outputs

Name	Type	Details
Keys	List of Text	The stored keys / subject ids.

Search storage keys

Filters the field's keys (subject ids) by a query, ranked prefix-first then contains - like autocomplete. A blank query returns keys up to the limit. Works on fields with up to 10,000 keys; a bigger field fails with a limit error you can catch.

Inputs

Name	Type	Required	Details
Storage field	Storage field	Yes	Storage field to operate on.
Query	Text	No	Text to match keys against (prefix-first, then contains). Leave blank to return all keys. Maximum length: 100 characters.
Limit	Whole number	Yes	Maximum number of keys to return (1-100). Value: 1 to 100. Default: 25.

Outputs

Name	Type	Details
Keys	List of Text	The matching keys / subject ids, best matches first.

Search storage entries

Returns the field's entries within a numeric value range, each with its overall rank in the sorted field.

Inputs

Name	Type	Required	Details
Storage field	Storage field	Yes	Storage field to operate on.
Minimum value	Decimal number	No	Only include entries whose value is at least this (leave blank for no lower bound).
Maximum value	Decimal number	No	Only include entries whose value is at most this (leave blank for no upper bound).
Direction	Sort direction	Yes	Sort direction used for ranking (descending ranks the highest value #1). Default: Descending.
Limit	Whole number	Yes	Maximum number of matching entries to return (1-100). Value: 1 to 100. Default: 10.

Outputs

Name	Type	Details
Entries	List of Storage entry	Matching entries, each with its subject, value and overall rank.

Aggregate storage field

Computes a single number over a field's entries - sum, average, count, minimum, maximum or median - with an optional value range filter.

Inputs

Name	Type	Required	Details
Storage field	Storage field	Yes	Storage field to operate on.
Operation	Aggregate operation	Yes	Which aggregate to compute over the field's values. Default: Sum.
Minimum value	Decimal number	No	Only include entries whose value is at least this (leave blank for no lower bound).
Maximum value	Decimal number	No	Only include entries whose value is at most this (leave blank for no upper bound).

Outputs

Name	Type	Details
Result	Decimal number	The computed number. Empty when there is nothing to aggregate (count returns 0). For a large whole number field it is an exact whole number of any size, and the average and median are rounded to the nearest whole number. May be empty.
Count	Whole number	How many entries contributed to the result.

Random pick from storage

Draws random entries from a field - uniformly, or weighted by each entry's value (a raffle by ticket count). Picks are without replacement.

Inputs

Name	Type	Required	Details
Storage field	Storage field	Yes	Storage field to operate on.
Count	Whole number	Yes	How many entries to draw (1-100). Clamped to the number of eligible entries. Value: 1 to 100. Default: 1.
Weight by	Pick weighting	Yes	How likely each entry is to be drawn: uniform over keys, or weighted by its value. Default: Uniform.

Outputs

Name	Type	Details
Picks	List of Storage entry	The drawn entries, each with its subject, value and overall rank.

Increment if (atomic)

Increases a stored number only when its current value meets a condition. The safe way to "spend if the balance is enough".

Inputs

Name	Type	Required	Details
Storage field	Storage field	Yes	Storage field to operate on.
Subject	User	No	User the value belongs to (for user-scoped fields).
Key	Text	No	Key the value is stored under (for keyed fields). Maximum length: 100 characters.
Condition	Comparison	Yes	How the current value is compared to the threshold before applying. Default: At least (≥)
Threshold	Decimal number	Yes	Value the current value is compared against. Default: 0.
Amount	Decimal number	Yes	How much to add when the condition holds (use a negative amount to subtract). Default: 1.

Outputs

Name	Type	Details
Applied	Yes/No	Whether the condition held and the value was changed.
New value	Decimal number	The resulting stored value (unchanged when the condition did not hold).

Set stored value if (atomic)

Writes a value to a storage field only when the value stored there right now meets a condition. Checking and writing happen in one single step, so two runs at the same time can never both succeed. Set "only if nothing is stored" to build a lock: whoever gets "Applied" = true may proceed, everyone else has to wait. Set "only if it equals" to change a value safely after reading it.

Inputs

Name	Type	Required	Details
Storage field	Storage field	Yes	Storage field to operate on.
Subject	User	No	User the value belongs to (required for user-scoped fields).
Key	Text	No	Key the value is stored under (required for keyed fields). Maximum length: 100 characters.
Condition	Condition	Yes	What must be true of the currently stored value for the new value to be written. Default: Only if nothing is stored.
Expected value	Stored value	No	Value the stored value is compared against. Only used by the "equals" and "does not equal" conditions.
Value	Stored value	Yes	Value to store when the condition holds. Must match the type declared on the field.

Outputs

Name	Type	Details
Applied	Yes/No	Whether the condition held and the value was written. With "only if nothing is stored" this is your lock: true means this run got it.
New value	Stored value	The value stored afterwards: the new value when it was written, otherwise the value that is already there (so you can see who holds the lock, or retry with the current value). May be empty.

Clear storage field

Deletes every stored value for a field - or just one subject's/key's when a subject or key is given.

Inputs

Name	Type	Required	Details
Storage field	Storage field	Yes	Storage field to operate on.
Subject	User	No	User the value belongs to (required for user-scoped fields).
Key	Text	No	Key the value is stored under (required for keyed fields). Maximum length: 100 characters.

Format leaderboard

Builds a ready-to-send leaderboard text from a field's top entries. Row-template tokens: %rank%, %mention% (renders <@key>, only meaningful for user-keyed fields), %key%, %value%. People with no number in that field are left out.

Inputs

Name	Type	Required	Details
Storage field	Storage field	Yes	Storage field to operate on.
Rank by field	Field of a shape value	No	For a stored shape value: the whole number or decimal number field to rank by. Each row shows that number. Maximum length: 64 characters.
Direction	Sort direction	Yes	Sort direction (descending lists the highest values first). Default: Descending.
Limit	Whole number	Yes	Maximum number of rows to render (1-100). Value: 1 to 100. Default: 10.
Row template	Text	Yes	Template for each row. Tokens: %rank%, %mention%, %key%, %value%. Maximum length: 500 characters. Default: **#%rank%** %mention% - %value%.
Empty text	Text	No	Text used when the field has no entries. Maximum length: 2000 characters.
Format numbers	Yes/No	Yes	Add thousands separators to a numeric %value%. Default: No.

Outputs

Name	Type	Details
Text	Text	The rendered leaderboard text.

Format leaderboard pages

Builds Discord-safe leaderboard pages for Send paginated message. Tokens: %rank%, %mention%, %key%, %value%. People with no number in that field are left out.

Inputs

Name	Type	Required	Details
Storage field	Storage field	Yes	Storage field to operate on.
Rank by field	Field of a shape value	No	For a stored shape value: the whole number or decimal number field to rank by. Each row shows that number. Maximum length: 64 characters.
Direction	Sort direction	Yes	Sort direction (descending lists the highest values first). Default: Descending.
Limit	Whole number	Yes	Maximum rows to render (1-100). Value: 1 to 100. Default: 10.
Row template	Text	Yes	Template for each row. Tokens: %rank%, %mention%, %key%, %value%. Maximum length: 500 characters. Default: **#%rank%** %mention% - %value%.
Empty text	Text	No	Text used when the field has no entries. Maximum length: 2000 characters.
Format numbers	Yes/No	Yes	Add thousands separators to numeric values. Default: No.
Rows per page	Whole number	Yes	Maximum rows per Discord page (1-100); Discord's message limit may split earlier. Value: 1 to 100. Default: 10.

Outputs

Name	Type	Details
Pages	List of Message content	Pages that connect directly to Send paginated message.
Page count	Whole number	Number of generated pages.

Check and set cooldown

Checks whether a subject is on cooldown and, if not, starts a new cooldown, all in one safe step. The safe way to rate-limit a command per user or key.

Inputs

Name	Type	Required	Details
Storage field	Storage field	Yes	Storage field that holds the cooldown timestamps.
Subject	User	No	User the cooldown belongs to (for user-scoped fields).
Key	Text	No	Key the cooldown is stored under (for keyed fields). Maximum length: 100 characters.
Duration	Duration	Yes	How long the cooldown lasts once started. Value: 1000 to 2592000000.

Outputs

Name	Type	Details
On cooldown	Yes/No	True when the subject was still on cooldown (nothing was changed).
Retry after	Duration	Time remaining until the cooldown ends (zero when a new cooldown was just started).