From db6b50c060c0fea3d4707bc875657ac81ca32b60 Mon Sep 17 00:00:00 2001 From: AJ Emerich Date: Wed, 20 May 2026 17:01:31 +0200 Subject: [PATCH] docs(plugin-transform): update how-to docs --- .../resources/doc/io.kestra.plugin.transform.grok.md | 11 +++++++++++ .../doc/io.kestra.plugin.transform.jsonata.md | 9 +++++++++ .../main/resources/doc/io.kestra.plugin.transform.md | 2 ++ 3 files changed, 22 insertions(+) create mode 100644 plugin-transform-grok/src/main/resources/doc/io.kestra.plugin.transform.grok.md create mode 100644 plugin-transform-json/src/main/resources/doc/io.kestra.plugin.transform.jsonata.md diff --git a/plugin-transform-grok/src/main/resources/doc/io.kestra.plugin.transform.grok.md b/plugin-transform-grok/src/main/resources/doc/io.kestra.plugin.transform.grok.md new file mode 100644 index 0000000..10f7661 --- /dev/null +++ b/plugin-transform-grok/src/main/resources/doc/io.kestra.plugin.transform.grok.md @@ -0,0 +1,11 @@ +# How to use the Transform Grok plugin + +Parse unstructured text — log lines, error messages, raw event data — into structured fields using Grok patterns. + +## Tasks + +`TransformValue` applies one or more Grok patterns to a single string value passed via `from` and returns the captured named fields as a map. Use it to parse a single string already in your flow's variables. + +`TransformItems` reads a file from Kestra internal storage (passed as a `kestra://` URI via `from`), applies the pattern to each line, and writes the structured results back to storage. Use it for batch log parsing or event normalization. + +Both tasks accept `pattern` for a single Grok expression or `patterns` for a list of expressions tried in order — matching stops at the first successful pattern. Add custom pattern definitions with `patternDefinitions` (a map of name to regex) or point `patternsDir` at directories containing pattern files. By default only named capture groups are returned (`namedCapturesOnly: true`) and matching stops at the first successful pattern (`breakOnFirstMatch: true`). diff --git a/plugin-transform-json/src/main/resources/doc/io.kestra.plugin.transform.jsonata.md b/plugin-transform-json/src/main/resources/doc/io.kestra.plugin.transform.jsonata.md new file mode 100644 index 0000000..b264c00 --- /dev/null +++ b/plugin-transform-json/src/main/resources/doc/io.kestra.plugin.transform.jsonata.md @@ -0,0 +1,9 @@ +# How to use the Transform JSONata plugin + +Query and transform JSON data using [JSONata](https://jsonata.org/) expressions — a functional language for selecting, filtering, reshaping, and aggregating JSON structures. + +## Tasks + +`TransformValue` evaluates a JSONata `expression` against a single JSON string passed via `from` and returns the transformed result. Use it to reshape or extract values from a task output already in your flow. + +`TransformItems` reads a JSON or Ion file from Kestra internal storage (passed as a `kestra://` URI via `from`), evaluates the `expression` against each record, and writes the results back to storage. If the expression returns an array and `explodeArray` is `true` (the default), each array element is written as a separate record — set `explodeArray: false` to write the whole array as a single record instead. Use `TransformItems` for batch transformations over large datasets. diff --git a/plugin-transform-records/src/main/resources/doc/io.kestra.plugin.transform.md b/plugin-transform-records/src/main/resources/doc/io.kestra.plugin.transform.md index 24c3eaf..1d7b442 100644 --- a/plugin-transform-records/src/main/resources/doc/io.kestra.plugin.transform.md +++ b/plugin-transform-records/src/main/resources/doc/io.kestra.plugin.transform.md @@ -1,3 +1,5 @@ +# How to use the Transform plugin + These tasks let you reshape, filter, combine, flatten, and summarize structured data without writing custom code. They work both with in-memory records and with stored Ion files, so the same tasks can be used for small workflow variables and larger streamed datasets. ## Common Inputs And Outputs