> For the complete documentation index, see [llms.txt](https://docs.augelab.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.augelab.com/function-blocks/blocks-reference/data-logic/data-operations/dictionary-operations.md).

# Dictionary Operations

This function block provides a flexible interface to create, modify, query, and convert dictionary-like data during your scenario. Select a method from the control and the block will adapt its inputs and outputs to match the chosen operation.

## 📥 Inputs <a href="#inputs" id="inputs"></a>

The available inputs depend on the selected method. The block dynamically changes sockets when you pick a method. Common input names you may see:

* `Dict` — Dictionary data to operate on (when required)
* `Keys` — Single key (string) or list of keys for creation
* `Values` — Single value or list of values for creation
* `Input Dict` — Source dictionary for update/remove/extend/get/copy operations
* `Key` — Key string used for update/remove/get operations
* `Value` — Value used for update operation
* `New Dict` — Dictionary to merge into an existing one (extend)
* `Text` — JSON text to parse (parse)
* `Dict` (for conversion) — Dictionary to convert to a text string

## 📤 Outputs <a href="#outputs" id="outputs"></a>

The outputs also depend on the selected method. Typical outputs include:

* `Dict` — Resulting dictionary after create/update/remove/extend/copy operations
* `Text` — JSON string result when using conversion to string or after parsing

When a single-key get is used, the output may return the requested value directly.

## 🕹️ Controls <a href="#controls" id="controls"></a>

`Select Method` Choose the desired dictionary operation. Available methods:

* `create`
* `update`
* `remove`
* `extend`
* `get`
* `copy`
* `parse`
* `to_string`

`Info` A contextual text area that displays help and usage hints for the currently selected method.

Note: changing `Select Method` will immediately update the block sockets to match the chosen operation.

## 🎨 Features <a href="#features" id="features"></a>

* Dynamic sockets: inputs and outputs update automatically based on the chosen method so you only see relevant fields.
* Quick JSON handling: parse JSON text into a dictionary and convert dictionaries to JSON strings with dedicated methods.
* Merge and edit support: update single keys, remove keys, or extend an existing dictionary with another dictionary.
* Copy support: create safe copies to avoid unintentional changes downstream.
* Inline help: method-specific guidance is shown in the info area to reduce guesswork.

## ⚙️ Running mechanism <a href="#running-mechanism" id="running-mechanism"></a>

* Select a method with `Select Method` then connect the sockets that appear.
* When the scenario runs, the block performs the selected operation on the provided inputs and outputs the resulting data on the matching output sockets.
* If inputs are invalid for the chosen operation (for example mismatched list lengths on creation, a missing key on get/remove, or an invalid JSON string on parse), the block will report an error message to help you fix the configuration.

## 📝 Usage instructions <a href="#usage" id="usage"></a>

1. Add the block and click `Select Method` to pick the appropriate operation.
2. Connect sources to the sockets that appear (for example connect `Keys` and `Values` when using `create`).
3. Use the `Info` area for quick examples and notes specific to the selected method.
4. Run the scenario and examine the outputs on the matching sockets.

## 💡 Tips and Tricks <a href="#tips-and-tricks" id="tips-and-tricks"></a>

* Persisting values: combine with `Data Memory` or `Data Write Local` / `Data Write Global` to keep dictionaries accessible across your scenario or between runs.
* Debugging: use `Debug Input` to inspect dictionary content during development.
* JSON flows: pair `parse` with a `String Input` (for manual JSON) or a text-producing block, then use the resulting dictionary downstream. Use `to_string` before saving or publishing.
* Save/export: after `to_string`, send the text to `CSV Export` or `File/Folder Operations` if you need to store results.
* Conditional use: check for missing keys using `Is None` after a `get` operation to avoid errors in later blocks.
* Merging updates: to build up a configuration gradually, use `extend` together with periodic `Data Read Local` / `Data Write Local` to keep a master dictionary.
* String handling: use `String Merge` or `Find Substring` to construct or validate keys/values before passing them to update/create operations.

## 🛠️ Troubleshooting <a href="#troubleshooting" id="troubleshooting"></a>

* Mismatched lists on creation
  * Cause: `Keys` and `Values` were provided as lists of different lengths.
  * Fix: Make sure list lengths match or provide single key/value pairs.
* Key not found on get/remove
  * Cause: Requested `Key` does not exist in the provided `Input Dict`.
  * Fix: Confirm keys using a debug display or use a safe check (e.g., verify existence before calling get/remove).
* Invalid JSON when using parse
  * Cause: The provided `Text` is not valid JSON (double quotes required for keys/strings).
  * Fix: Validate your JSON text (use `String Input` or copy from a JSON-valid source). The `Info` area shows an example format.
* Unexpected shared changes
  * Cause: Downstream changes to a dictionary reference affect other blocks.
  * Fix: Use `copy` or combine with `Data Memory` to control whether you are working on a copy or the original.

If you need to visualize or inspect intermediate images or values while working with dictionary-driven logic, consider connecting appropriate visual or export blocks (for example `Show Image` for image outputs or `CSV Export` for logged results).