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