V2NodesKey/Value
Key/Value
V2

Key/Value

Stores and retrieves small values, including structured objects, in named collections scoped to the current site environment.

Revision History

0.0.0.1 - Initial release.
0.0.0.6 - Added support for reading legacy compressed values.
0.0.0.8 - Added single-record SetSingle and GetSingle methods.
0.0.0.12 - Added structured value support and renamed Group to Collection.
0.0.0.14 - Improved date-range read performance by reading daily partitions concurrently.
0.0.0.15 - Released Run Anywhere Cluster support with the date-range read performance improvements.

Setup Notes

You can add this Node to a Workflow without configuring authentication or external access.

Use this Node when you need to keep a simple lookup table in Flowgear, such as matching a source system ID to the corresponding ID in a target system.

  • Key/value records are scoped to the current site environment. A record written in one environment is not available in another environment.
  • Use Collection to separate unrelated records. E.g., you might use one collection for customer IDs and another for invoice numbers.
  • Use stable Collection names so you can reuse the same lookup set across multiple Workflows.
  • Collection and Key are required and can each contain up to 1000 characters.
  • Value supports text and structured objects. The maximum serialized value size is 32 KB.
  • Each record is timestamped when it is written.
  • You can run this Node on Flowgear Cloud and Run Anywhere Clusters.

Methods

This Node provides batch and single-record methods for writing values, reading values in a date range, and reading one key directly.

Set

Creates or updates multiple key/value records in a collection.

Each item includes a Key, Value, and optional Status. If you do not provide a Status, the Node stores Unknown.

Parameter Type Description
Collection String The name of the collection that the records belong to.
Items Array The records to create or update. Each item includes Key, Value, and optional Status.
Items.Key String The key to create or update. This value is required and can contain up to 1000 characters.
Items.Value Object The text or structured value to store for the key. The maximum serialized size is 32 KB.
Items.Status String Optional status metadata for the record. If omitted or blank, the Node stores Unknown.

This method does not return a value.

SetSingle

Creates or updates one key/value record in a collection.

If you provide a blank Status, the Node stores Unknown.

Parameter Type Description
Collection String The name of the collection that the record belongs to.
Key String The key to create or update. This value is required and can contain up to 1000 characters.
Value Object The text or structured value to store for the key. The maximum serialized size is 32 KB.
Status String Status metadata for the record. If blank, the Node stores Unknown.

This method does not return a value.

Get

Gets the latest value for each key in a collection whose stored timestamp falls within a specified range.

DateFrom and DateTo are inclusive. DateFrom must be earlier than or equal to DateTo. If DateFrom is later than DateTo, the Node throws an error.

The Node reads up to five daily partitions concurrently, then returns only the latest record for each Key.

Parameter Type Description
Collection String The collection to query.
DateFrom DateTime The inclusive start of the date range to query.
DateTo DateTime The inclusive end of the date range to query.
Return Type Description
Items Array The latest matching record for each key in the collection, returned in key order.
Items.Key String The key for the returned record.
Items.Value Object The stored text or structured value for the key.
Items.Status String The status stored with the key.
Items.Timestamp DateTime The UTC date and time when the record was written.

GetSingle

Gets the current value for one key in a collection.

Parameter Type Description
Collection String The collection to query.
Key String The key to retrieve.
Return Type Description
Item Object The matching record, or no value if the key does not exist.
Item.Key String The key for the returned record.
Item.Value Object The stored text or structured value for the key.
Item.Status String The status stored with the key.
Item.Timestamp DateTime The UTC date and time when the record was written.

Usage Notes

  • Use Set when you need to write several records. Use SetSingle when you only need to write one record.
  • Use Get when you need records written in a specific date range. Use GetSingle when you need the current value for a known key.
  • If you write the same Key more than once, Get returns the latest matching record for that key in the requested date range.
  • Use Status as lightweight metadata when you want to track the state of a record alongside the stored value.
  • The date range filter uses the stored UTC timestamp. Use UTC-aware values for DateFrom and DateTo when you need precise results.
  • Legacy compressed values are decompressed automatically when they are read.
  • Structured values are serialized when they are stored and reconstructed when they are read. Text values remain text.
  • Store a smaller value or use a relational database when your serialized Value exceeds 32 KB.

Examples

Store source and target identifiers

After a Workflow creates a record in a target system, use SetSingle to store the source record ID as the Key and the target record ID as the Value.

Later, use GetSingle to look up the stored target ID before you send an update.

Track the latest status for a record

Use Set to store the same Key with a new Value or Status each time processing changes.

Use Get with a suitable date range when you need the latest stored state for each key in the collection.

See also