Set

Stores a key-value pair in the BadgerDB database.

Common Properties

• Name - The custom name of the node.
• Color - The custom color of the node.
• Delay Before (sec) - Waits in seconds before executing the node.
• Delay After (sec) - Waits in seconds after executing node.
• Continue On Error - Automation will continue regardless of any error. The default value is false.

info

If the ContinueOnError property is true, no error is caught when the project is executed, even if a Catch node is used.

Inputs

• Database Id - The unique identifier of the database, as returned by the Open node.
• Transaction Id - (Optional) The transaction ID from Start Transaction node. If provided, the write operation will be performed within that transaction context and won't be committed until you call Commit Transaction.
• Key - The key under which to store the value. Cannot be empty.
• Value - The value to store. The type depends on the Encoding option selected.

Options

• Encoding - Specifies how to encode the value before storing:
  • JSON - Encodes the value as JSON (supports objects, arrays, strings, numbers, booleans)
  • String - Stores the value as a UTF-8 text string
  • Integer - Stores the value as a 64-bit signed integer
  • Float - Stores the value as a 64-bit floating point number
  • Boolean - Stores the value as a boolean (true/false)
• TTL (Seconds) - (Optional) Time-to-live in seconds. After this duration, the key-value pair will automatically expire and be removed. Set to 0 or leave empty for no expiration.

How It Works

The Set node stores data in BadgerDB by encoding the value according to the specified format and associating it with a key.

When executed, the node:

1. Validates the database ID and key
2. Retrieves the value to store
3. Encodes the value according to the selected Encoding option
4. Creates or uses an existing transaction
5. Stores the encoded bytes under the specified key
6. Applies TTL if specified
7. Commits the transaction (if not part of a larger transaction)

Examples

Example 1: Store JSON Object

Store a user profile as JSON:

Set
  Database Id: {{db_id}}
  Key: user:12345
  Value: {
    "name": "John Doe",
    "email": "john@example.com",
    "role": "admin",
    "last_login": "2025-12-23"
  }
  Encoding: JSON

Example 2: Store String with TTL

Store a session token that expires in 1 hour:

Set
  Database Id: {{db_id}}
  Key: session:abc123
  Value: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  Encoding: String
  TTL (Seconds): 3600

Example 3: Store Counter

Initialize a counter:

Set
  Database Id: {{db_id}}
  Key: page_views
  Value: 0
  Encoding: Integer

Example 4: Store Within Transaction

Update multiple related values atomically:

1. Start Transaction
   Database Id: {{db_id}}
   → txn_id

2. Set Balance
   Database Id: {{db_id}}
   Transaction Id: {{txn_id}}
   Key: account:1001:balance
   Value: 5000.50
   Encoding: Float

3. Set Status
   Database Id: {{db_id}}
   Transaction Id: {{txn_id}}
   Key: account:1001:status
   Value: "active"
   Encoding: String

4. Set Updated Time
   Database Id: {{db_id}}
   Transaction Id: {{txn_id}}
   Key: account:1001:updated
   Value: {{current_timestamp}}
   Encoding: String

5. Commit Transaction
   Transaction Id: {{txn_id}}

Example 5: Store Configuration Flag

Store a feature flag:

Set
  Database Id: {{db_id}}
  Key: feature:new_ui_enabled
  Value: true
  Encoding: Boolean

Example 6: Cache API Response

Cache an API response for 5 minutes:

Set
  Database Id: {{db_id}}
  Key: cache:weather:london
  Value: {{api_response}}
  Encoding: JSON
  TTL (Seconds): 300

Tips for Effective Use

• Match Encoding to Data Type - Use JSON for objects/arrays, String for text, Integer for whole numbers, etc.
• Use Meaningful Keys - Structure keys hierarchically (e.g., "user:123:profile", "cache:api:endpoint")
• Set Appropriate TTLs - Use TTL for temporary data like sessions, cache entries, or rate limits
• Use Transactions for Atomic Updates - When updating multiple related keys, use transactions to ensure all-or-nothing updates
• Overwrite is Safe - Setting a key that already exists will overwrite the previous value
• Consider Key Prefixes - Use prefixes to organize data (e.g., "user:", "session:", "cache:")

Common Errors and Solutions

Error: "database id cannot be empty"

Solution: Ensure you're passing a valid database ID from the Open node.

Correct:
  Open → db_id
  Set (Database Id: {{db_id}})

Error: "key cannot be empty"

Solution: Provide a non-empty key value.

Correct:
  Key: user:12345

Incorrect:
  Key: (empty)

Error: "expected value to be a string"

Solution: When using String encoding, ensure the value is a string type:

Correct (String Encoding):
  Value: "Hello World"

Incorrect:
  Value: 123 (use Integer encoding instead)

Error: "expected value to be an int64"

Solution: When using Integer encoding, ensure the value is a number:

Correct (Integer Encoding):
  Value: 42

Incorrect:
  Value: "42" (this would work too as it's auto-converted)

Error: "failed to convert string to int64"

Solution: The string value cannot be parsed as an integer:

Correct:
  Value: "123" → Integer encoding works

Incorrect:
  Value: "abc" → Cannot convert to integer

Error: JSON Marshal Error

Solution: The value cannot be serialized to JSON:

• Ensure circular references are not present
• Verify the object structure is valid
• Check for unsupported data types

Encoding Details

JSON Encoding

• Serializes objects, arrays, strings, numbers, booleans, and null
• Handles nested structures automatically
• Best for complex data structures
• Slightly larger storage size due to JSON formatting

String Encoding

• Stores UTF-8 text directly
• Most efficient for text data
• No overhead from serialization
• Use for IDs, names, descriptions, URLs, etc.

Integer Encoding

• Stores 64-bit signed integer in binary format (big-endian)
• Very compact storage (8 bytes)
• Best for counters, quantities, IDs
• Range: -9,223,372,036,854,775,808 to 9,223,372,036,854,775,807
• Auto-converts string numbers (e.g., "123" → 123)

Float Encoding

• Stores 64-bit floating point in binary format (IEEE 754)
• Compact storage (8 bytes)
• Best for decimals, percentages, measurements
• Auto-converts string numbers (e.g., "3.14" → 3.14)

Boolean Encoding

• Stores single byte (0 = false, 1 = true)
• Most compact encoding (1 byte)
• Best for flags, switches, settings
• Auto-converts string booleans (e.g., "true" → true)

TTL (Time-To-Live)

How TTL Works

• Keys with TTL automatically expire after the specified duration
• Expired keys are removed from the database during garbage collection
• Reading an expired key returns a "key not found" error
• TTL is specified in seconds

TTL Use Cases

• Session Management - Auto-expire user sessions
• Cache Entries - Auto-remove stale cached data
• Rate Limiting - Track API calls within a time window
• Temporary Tokens - Auto-delete one-time-use tokens
• Scheduled Cleanup - Automatically remove temporary data

TTL Example

Store a rate limit counter that resets every minute:
Set
  Key: rate_limit:user:123
  Value: 1
  Encoding: Integer
  TTL (Seconds): 60

Performance Considerations

• Write Performance - BadgerDB handles thousands of writes per second
• Transaction Writes - Batching multiple Sets in a transaction is more efficient
• Key Size - Shorter keys improve performance and reduce storage
• Value Size - Consider compression for large values
• TTL Overhead - Minimal performance impact

Related Nodes

• Get - Retrieves values from the database
• Delete - Removes values from the database
• Start Transaction - Starts a transaction for atomic writes
• Commit Transaction - Commits transaction changes
• Start Merge - Performs atomic increment/decrement/merge operations