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

     1  ---
     2  title: bloblang
     3  type: processor
     4  status: stable
     5  categories: ["Mapping","Parsing"]
     6  ---
     7  
     8  <!--
     9       THIS FILE IS AUTOGENERATED!
    10  
    11       To make changes please edit the contents of:
    12       lib/processor/bloblang.go
    13  -->
    14  
    15  import Tabs from '@theme/Tabs';
    16  import TabItem from '@theme/TabItem';
    17  
    18  
    19  Executes a [Bloblang](/docs/guides/bloblang/about) mapping on messages.
    20  
    21  ```yaml
    22  # Config fields, showing default values
    23  label: ""
    24  bloblang: ""
    25  ```
    26  
    27  Bloblang is a powerful language that enables a wide range of mapping, transformation and filtering tasks. For more information [check out the docs](/docs/guides/bloblang/about).
    28  
    29  If your mapping is large and you'd prefer for it to live in a separate file then you can execute a mapping directly from a file with the expression `from "<path>"`, where the path must be absolute, or relative from the location that Benthos is executed from.
    30  
    31  ## Examples
    32  
    33  <Tabs defaultValue="Mapping" values={[
    34  { label: 'Mapping', value: 'Mapping', },
    35  { label: 'More Mapping', value: 'More Mapping', },
    36  ]}>
    37  
    38  <TabItem value="Mapping">
    39  
    40  
    41  Given JSON documents containing an array of fans:
    42  
    43  ```json
    44  {
    45    "id":"foo",
    46    "description":"a show about foo",
    47    "fans":[
    48      {"name":"bev","obsession":0.57},
    49      {"name":"grace","obsession":0.21},
    50      {"name":"ali","obsession":0.89},
    51      {"name":"vic","obsession":0.43}
    52    ]
    53  }
    54  ```
    55  
    56  We can reduce the fans to only those with an obsession score above 0.5, giving us:
    57  
    58  ```json
    59  {
    60    "id":"foo",
    61    "description":"a show about foo",
    62    "fans":[
    63      {"name":"bev","obsession":0.57},
    64      {"name":"ali","obsession":0.89}
    65    ]
    66  }
    67  ```
    68  
    69  With the following config:
    70  
    71  ```yaml
    72  pipeline:
    73    processors:
    74    - bloblang: |
    75        root = this
    76        root.fans = this.fans.filter(fan -> fan.obsession > 0.5)
    77  ```
    78  
    79  </TabItem>
    80  <TabItem value="More Mapping">
    81  
    82  
    83  When receiving JSON documents of the form:
    84  
    85  ```json
    86  {
    87    "locations": [
    88      {"name": "Seattle", "state": "WA"},
    89      {"name": "New York", "state": "NY"},
    90      {"name": "Bellevue", "state": "WA"},
    91      {"name": "Olympia", "state": "WA"}
    92    ]
    93  }
    94  ```
    95  
    96  We could collapse the location names from the state of Washington into a field `Cities`:
    97  
    98  ```json
    99  {"Cities": "Bellevue, Olympia, Seattle"}
   100  ```
   101  
   102  With the following config:
   103  
   104  ```yaml
   105  pipeline:
   106    processors:
   107      - bloblang: |
   108          root.Cities = this.locations.
   109                          filter(loc -> loc.state == "WA").
   110                          map_each(loc -> loc.name).
   111                          sort().join(", ")
   112  ```
   113  
   114  </TabItem>
   115  </Tabs>
   116  
   117  ## Error Handling
   118  
   119  Bloblang mappings can fail, in which case the message remains unchanged, errors
   120  are logged, and the message is flagged as having failed, allowing you to use
   121  [standard processor error handling patterns](/docs/configuration/error_handling).
   122  
   123  However, Bloblang itself also provides powerful ways of ensuring your mappings
   124  do not fail by specifying desired fallback behaviour, which you can read about
   125  [in this section](/docs/guides/bloblang/about#error-handling).
   126