github.com/Jeffail/benthos/v3@v3.65.0/website/docs/components/processors/branch.md (about)

     1  ---
     2  title: branch
     3  type: processor
     4  status: stable
     5  categories: ["Composition"]
     6  ---
     7  
     8  <!--
     9       THIS FILE IS AUTOGENERATED!
    10  
    11       To make changes please edit the contents of:
    12       lib/processor/branch.go
    13  -->
    14  
    15  import Tabs from '@theme/Tabs';
    16  import TabItem from '@theme/TabItem';
    17  
    18  
    19  The `branch` processor allows you to create a new request message via
    20  a [Bloblang mapping](/docs/guides/bloblang/about), execute a list of processors
    21  on the request messages, and, finally, map the result back into the source
    22  message using another mapping.
    23  
    24  ```yaml
    25  # Config fields, showing default values
    26  label: ""
    27  branch:
    28    request_map: ""
    29    processors: []
    30    result_map: ""
    31  ```
    32  
    33  This is useful for preserving the original message contents when using
    34  processors that would otherwise replace the entire contents.
    35  
    36  ### Metadata
    37  
    38  Metadata fields that are added to messages during branch processing will not be
    39  automatically copied into the resulting message. In order to do this you should
    40  explicitly declare in your `result_map` either a wholesale copy with
    41  `meta = meta()`, or selective copies with
    42  `meta foo = meta("bar")` and so on.
    43  
    44  ### Error Handling
    45  
    46  If the `request_map` fails the child processors will not be executed.
    47  If the child processors themselves result in an (uncaught) error then the
    48  `result_map` will not be executed. If the `result_map` fails
    49  the message will remain unchanged. Under any of these conditions standard
    50  [error handling methods](/docs/configuration/error_handling) can be used in
    51  order to filter, DLQ or recover the failed messages.
    52  
    53  ### Conditional Branching
    54  
    55  If the root of your request map is set to `deleted()` then the branch
    56  processors are skipped for the given message, this allows you to conditionally
    57  branch messages.
    58  
    59  ## Fields
    60  
    61  ### `request_map`
    62  
    63  A [Bloblang mapping](/docs/guides/bloblang/about) that describes how to create a request payload suitable for the child processors of this branch. If left empty then the branch will begin with an exact copy of the origin message (including metadata).
    64  
    65  
    66  Type: `string`  
    67  Default: `""`  
    68  
    69  ```yaml
    70  # Examples
    71  
    72  request_map: |-
    73    root = {
    74    	"id": this.doc.id,
    75    	"content": this.doc.body.text
    76    }
    77  
    78  request_map: |-
    79    root = if this.type == "foo" {
    80    	this.foo.request
    81    } else {
    82    	deleted()
    83    }
    84  ```
    85  
    86  ### `processors`
    87  
    88  A list of processors to apply to mapped requests. When processing message batches the resulting batch must match the size and ordering of the input batch, therefore filtering, grouping should not be performed within these processors.
    89  
    90  
    91  Type: `array`  
    92  Default: `[]`  
    93  
    94  ### `result_map`
    95  
    96  A [Bloblang mapping](/docs/guides/bloblang/about) that describes how the resulting messages from branched processing should be mapped back into the original payload. If left empty the origin message will remain unchanged (including metadata).
    97  
    98  
    99  Type: `string`  
   100  Default: `""`  
   101  
   102  ```yaml
   103  # Examples
   104  
   105  result_map: |-
   106    meta foo_code = meta("code")
   107    root.foo_result = this
   108  
   109  result_map: |-
   110    meta = meta()
   111    root.bar.body = this.body
   112    root.bar.id = this.user.id
   113  
   114  result_map: root.raw_result = content().string()
   115  
   116  result_map: |-
   117    root.enrichments.foo = if errored() {
   118    	throw(error())
   119    } else {
   120    	this
   121    }
   122  ```
   123  
   124  ## Examples
   125  
   126  <Tabs defaultValue="HTTP Request" values={[
   127  { label: 'HTTP Request', value: 'HTTP Request', },
   128  { label: 'Non Structured Results', value: 'Non Structured Results', },
   129  { label: 'Lambda Function', value: 'Lambda Function', },
   130  { label: 'Conditional Caching', value: 'Conditional Caching', },
   131  ]}>
   132  
   133  <TabItem value="HTTP Request">
   134  
   135  
   136  This example strips the request message into an empty body, grabs an HTTP
   137  payload, and places the result back into the original message at the path
   138  `image.pull_count`:
   139  
   140  ```yaml
   141  pipeline:
   142    processors:
   143      - branch:
   144          request_map: 'root = ""'
   145          processors:
   146            - http:
   147                url: https://hub.docker.com/v2/repositories/jeffail/benthos
   148                verb: GET
   149          result_map: root.image.pull_count = this.pull_count
   150  
   151  # Example input:  {"id":"foo","some":"pre-existing data"}
   152  # Example output: {"id":"foo","some":"pre-existing data","image":{"pull_count":1234}}
   153  ```
   154  
   155  </TabItem>
   156  <TabItem value="Non Structured Results">
   157  
   158  
   159  When the result of your branch processors is unstructured and you wish to simply set a resulting field to the raw output use the content function to obtain the raw bytes of the resulting message and then coerce it into your value type of choice:
   160  
   161  ```yaml
   162  pipeline:
   163    processors:
   164      - branch:
   165          request_map: 'root = this.document.id'
   166          processors:
   167            - cache:
   168                resource: descriptions_cache
   169                key: ${! content() }
   170                operator: get
   171          result_map: root.document.description = content().string()
   172  
   173  # Example input:  {"document":{"id":"foo","content":"hello world"}}
   174  # Example output: {"document":{"id":"foo","content":"hello world","description":"this is a cool doc"}}
   175  ```
   176  
   177  </TabItem>
   178  <TabItem value="Lambda Function">
   179  
   180  
   181  This example maps a new payload for triggering a lambda function with an ID and
   182  username from the original message, and the result of the lambda is discarded,
   183  meaning the original message is unchanged.
   184  
   185  ```yaml
   186  pipeline:
   187    processors:
   188      - branch:
   189          request_map: '{"id":this.doc.id,"username":this.user.name}'
   190          processors:
   191            - aws_lambda:
   192                function: trigger_user_update
   193  
   194  # Example input: {"doc":{"id":"foo","body":"hello world"},"user":{"name":"fooey"}}
   195  # Output matches the input, which is unchanged
   196  ```
   197  
   198  </TabItem>
   199  <TabItem value="Conditional Caching">
   200  
   201  
   202  This example caches a document by a message ID only when the type of the
   203  document is a foo:
   204  
   205  ```yaml
   206  pipeline:
   207    processors:
   208      - branch:
   209          request_map: |
   210            meta id = this.id
   211            root = if this.type == "foo" {
   212              this.document
   213            } else {
   214              deleted()
   215            }
   216          processors:
   217            - cache:
   218                resource: TODO
   219                operator: set
   220                key: ${! meta("id") }
   221                value: ${! content() }
   222  ```
   223  
   224  </TabItem>
   225  </Tabs>
   226  
   227