Cloudera Docs

Searching

Each of the following functions is used to search its subject for some value.

startsWith

Description: Returns true if the Subject starts with the String provided as the argument, false otherwise.

Subject Type: String

Arguments:

  • value : The value to search for

Return Type: Boolean

Examples: If the "filename" attribute has the value "a brand new filename.txt", then the Expression ${filename:startsWith('a brand')} will return true. ${filename:startsWith('A BRAND')} will return false. 
${filename:toUpper():startsWith('A
            BRAND')}
returns true.

endsWith

Description: Returns true if the Subject ends with the String provided as the argument, false otherwise.

Subject Type: String

Arguments:

  • value : The value to search for

Return Type: Boolean

Examples: If the "filename" attribute has the value "a brand new filename.txt", then the Expression ${filename:endsWith('txt')} will return true. ${filename:endsWith('TXT')} will return false. ${filename:toUpper():endsWith('TXT')} returns true.

contains

Description: Returns true if the Subject contains the value of the argument anywhere in the value.

Subject Type: String

Arguments:

  • value : The value to search for

Return Type: Boolean

Examples: If the "filename" attribute has the value "a brand new filename.txt", then the Expression ${filename:contains('new')} will return true. ${filename:contains('NEW')} will return false. ${filename:toUpper():contains('NEW')} returns true.

in

Description: Returns true if the Subject is matching one of the provided arguments.

Subject Type: String

Arguments:

  • value1 : First possible matching value

  • valueN : Nth possible matching value

Return Type: Boolean

Examples: If the "myEnum" attribute has the value "JOHN", then the Expression ${myEnum:in("PAUL", "JOHN", "MIKE")} will return true. ${myEnum:in("RED", "GREEN", "BLUE")} will return false.

find

Description: Returns true if the Subject contains any sequence of characters that matches the Regular Expression provided by the argument.

Subject Type: String

Arguments:

  • Regex : The Regular Expression (in the Java Pattern syntax) to match against the Subject

Return Type: Boolean

Examples:

If the "filename" attribute has the value "a brand new filename.txt", then the following Expressions will provide the following results:

Table 1. Table 15. find Examples
Expression Value
${filename:find('a [Bb]rand [Nn]ew')} true
${filename:find('Brand.*')} false
${filename:find('brand')} true

matches

Description: Returns true if the Subject exactly matches the Regular Expression provided by the argument.

Subject Type: String

Arguments:

  • Regex : The Regular Expression (in the Java Pattern syntax) to match against the Subject

Return Type: Boolean

Examples:

If the "filename" attribute has the value "a brand new filename.txt", then the following Expressions will provide the following results:

Table 2. Table 16. matches Examples
Expression Value
${filename:matches('a.*txt')} true
${filename:matches('brand')} false
${filename:matches('.brand.')} true

indexOf

Description: Returns the index of the first character in the Subject that matches the String value provided as an argument. If the argument is found multiple times within the Subject, the value returned is the starting index of the first occurrence. If the argument cannot be found in the Subject, returns -1. The index is zero-based. This means that if the search string is found at the beginning of the Subject, the value returned will be 0, not 1.

Subject Type: String

Arguments:

  • value : The value to search for in the Subject

Return Type: Number

Examples: If the "filename" attribute has the value "a brand new filename.txt", then the following Expressions will provide the following results:

Table 3. Table 17. indexOf Examples
Expression Value
${filename:indexOf('a.*txt')} -1
${filename:indexOf('.')} 20
${filename:indexOf('a')} 0
${filename:indexOf(' ')} 1

lastIndexOf

Description: Returns the index of the first character in the Subject that matches the String value provided as an argument. If the argument is found multiple times within the Subject, the value returned is the starting index of the last occurrence. If the argument cannot be found in the Subject, returns -1. The index is zero-based. This means that if the search string is found at the beginning of the Subject, the value returned will be 0, not 1.

Subject Type: String

Arguments:

  • value : The value to search for in the Subject

Return Type: Number

Examples: If the "filename" attribute has the value "a brand new filename.txt", then the following Expressions will provide the following results:

Table 4. Table 18. lastIndexOf Examples
Expression Value
${filename:lastIndexOf('a.*txt')} -1
${filename:lastIndexOf('.')} 20
${filename:lastIndexOf('a')} 17
${filename:lastIndexOf(' ')} 11

jsonPath

Description: The jsonPath function generates a string by evaluating the Subject as JSON and applying a JSON path expression. An empty string is generated if the Subject does not contain valid JSON, the jsonPath is invalid, or the path does not exist in the Subject. If the evaluation results in a scalar value, the string representation of scalar value is generated. Otherwise a string representation of the JSON result is generated. A JSON array of length 1 is special cased when [0] is a scalar, the string representation of [0] is generated.

Subject Type: String

Arguments: jsonPath : the JSON path expression used to evaluate the Subject.

Return Type: String

Examples: If the "myJson" attribute is

{
  "firstName": "John",
  "lastName": "Smith",
  "isAlive": true,
  "age": 25,
  "address": {
    "streetAddress": "21 2nd Street",
    "city": "New York",
    "state": "NY",
    "postalCode": "10021-3100"
  },
  "phoneNumbers": [
    {
      "type": "home",
      "number": "212 555-1234"
    },
    {
      "type": "office",
      "number": "646 555-4567"
    }
  ],
  "children": [],
  "spouse": null
}
Table 5. Table 19. jsonPath Examples
Expression Value
${myJson:jsonPath('$.firstName')} John
${myJson:jsonPath('$.address.postalCode')} 10021-3100
${myJson:jsonPath('$.phoneNumbers[?(@.type=="home")].number')} 212 555-1234
${myJson:jsonPath('$.phoneNumbers')} 
[{"type":"home","number":"212
                  555-1234"},{"type":"office","number":"646 555-4567"}]
${myJson:jsonPath('$.missing-path')} empty
${myJson:jsonPath('$.bad-json-path..')} exception bulletin

An empty subject value or a subject value with an invalid JSON document results in an exception bulletin.

jsonPathDelete

Description: The jsonPathDelete function deletes the specified JsonPath from a Subject JSON and returns string form of the updated JSON.

Subject Type: String

Arguments: jsonPath : the JSON path expression to delete from the Subject.

Return Type: String

Examples: If the "myJson" attribute is

{
  "firstName": "John",
  "lastName": "Smith",
  "isAlive": true,
  "age": 25,
  "address": {
    "streetAddress": "21 2nd Street",
    "city": "New York",
    "state": "NY",
    "postalCode": "10021-3100"
  },
  "phoneNumbers": [
    {
      "type": "home",
      "number": "212 555-1234"
    },
    {
      "type": "office",
      "number": "646 555-4567"
    }
  ],
  "children": [],
  "spouse": null
}
Table 6. Table 20. jsonPathDelete Examples
Expression Value
${myJson:jsonPathDelete('$.firstName')} 
{"lastName":"Smith","age":25,"address":{"streetAddress":"21 2nd
                  Street","city":"New
                  York","state":"NY","postalCode":"10021-3100"},"phoneNumbers":[{"type":"home","number":"212
                  555-1234"},{"type":"office","number":"646 555-4567"}]}
${myJson:jsonPathDelete('$.missing-path')} Returns original JSON document

An empty subject value or a subject value with an invalid JSON document results in an exception bulletin.

jsonPathAdd

Description: The jsonPathAdd function adds a scalar value to an array at the specified JsonPath on a Subject JSON and returns string form of the updated JSON. If the expression target element is a non-array, an empty string is returned and an exception is logged indicating the error. If the expression target element path is not in the JSON, the operation returns the original JSON without any modifications.

Subject Type: String

Arguments:

  • jsonPath : the JSON path expression to set value on the Subject.

  • value : the value expression to be added to the array at the specified path on Subject.

Return Type: String

Examples: If the "myJson" attribute is

{
     "firstName": "John",
     "lastName": "Smith",
     "age": 25,
     "voter" : true,
     "height" : 6.1,
     "address" : {
         "streetAddress": "21 2nd Street",
         "city": "New York",
         "state": "NY",
         "postalCode": "10021-3100"
     },
     "phoneNumbers": [
         {
             "type": "home",
             "number": "212 555-1234"
         },
         {
             "type": "office",
             "number": "646 555-4567"
         }
     ],
     "nicknames" : []
 }
Table 7. Table 21. jsonPathAdd Examples
Expression Value
${myJson:jsonPathAdd('$.nicknames', 'Jimmy')} 
{"firstName":"James", lastName":"Smith", "age":25, "voter":true,
                  "height":6.1, "address":{"streetAddress":"21 2nd Street", "city":"New
                  York", "state":"NY", "postalCode":"10021-3100"},
                  "phoneNumbers":[{"type":"home", "number":"212 555-1234"},
                  {"type":"office", "number":"646
                  555-4567"}],"nicknames":["Jimmy"]}
${myJson:jsonPathAdd('$.missingpath', 'Jimmy')} Returns original JSON document with no modifications
${myJson:jsonPathAdd('$.firstName', 'Jimmy')} empty

jsonPathSet

Description: The jsonPathSet function sets the value at the specified JsonPath on a Subject JSON and returns string form of the updated JSON.

Subject Type: String

Arguments:

  • jsonPath : the JSON path expression to set value on the Subject.

  • value : the value expression to be set on the specified path on Subject.

Return Type: String

Examples: If the "myJson" attribute is

{
     "firstName": "John",
     "lastName": "Smith",
     "age": 25,
     "voter" : true,
     "height" : 6.1,
     "address" : {
         "streetAddress": "21 2nd Street",
         "city": "New York",
         "state": "NY",
         "postalCode": "10021-3100"
     },
     "phoneNumbers": [
         {
             "type": "home",
             "number": "212 555-1234"
         },
         {
             "type": "office",
             "number": "646 555-4567"
         }
     ],
     "nicknames" : []
 }
Table 8. Table 22. jsonPathSet Examples
Expression Value
${myJson:jsonPathSet('$.firstName', 'James')} 
{"firstName":"James", lastName":"Smith", "age":25, "voter":true,
                  "height":6.1, "address":{"streetAddress":"21 2nd Street", "city":"New
                  York", "state":"NY", "postalCode":"10021-3100"},
                  "phoneNumbers":[{"type":"home", "number":"212 555-1234"},
                  {"type":"office", "number":"646 555-4567"}]}
${myJson:jsonPathSet('$.missingpath', 'James')} Returns original JSON document

An empty subject value or a subject value with an invalid JSON document results in an exception bulletin.

jsonPathPut

Description: The jsonPathPut function puts the key and scalar value at the specified JsonPath on a Subject JSON and returns string form of the updated JSON.

Subject Type: String

Arguments:

  • jsonPath : the JSON path expression to set value on the Subject.

  • value : the value expression to be set on the specified path on Subject.

  • key : the key expression with the associated value the specified path on Subject.

Return Type: String

Examples: If the "myJson" attribute is

{
     "firstName": "John",
     "lastName": "Smith",
     "age": 25,
     "voter" : true,
     "height" : 6.1,
     "address" : {
         "streetAddress": "21 2nd Street",
         "city": "New York",
         "state": "NY",
         "postalCode": "10021-3100"
     },
     "phoneNumbers": [
         {
             "type": "home",
             "number": "212 555-1234"
         },
         {
             "type": "office",
             "number": "646 555-4567"
         }
     ],
     "nicknames" : []
 }
Table 9. Table 23. jsonPathPut Examples
Expression Value
${myJson:jsonPathPut('$','middlename','Turon')} 
{"firstName":"James", lastName":"Smith", "middlename": "Turon",
                  "age":25, "voter":true, "height":6.1, "address":{"streetAddress":"21
                  2nd Street", "city":"New York", "state":"NY",
                  "postalCode":"10021-3100"}, "phoneNumbers":[{"type":"home",
                  "number":"212 555-1234"}, {"type":"office", "number":"646
                  555-4567"}]}

An empty subject value or a subject value with an invalid JSON document results in an exception bulletin.