Collection/Search

◷ Reading Time: 15 minutes

Sequence Search

These pipes are applicable to a sequence of elements. Some of these pipes require a local name and predicate.

The local name is a name that will be used to reference an element in the sequence. A predicate is an Expression based on your parameters and the defined local name.

Let’s consider the following business objects:

NameAgeSex
Arash38Male
Parsa6Male
Pooya3Male
Shah3Female

These business objects are the basis of the examples provided here. Please note in the example expressions, people is the parameter name that references these business objects.

all

Determines whether all of the elements of a sequence satisfy a condition.

 |all (localName, predicate)
  • localName: Required
  • predicate: Required
  • return: Boolean

Example:

Sample:  people  |all (x, x.Sex == 'Female')

Result: false

any

Determines whether all of the elements of a sequence satisfy a condition.

 |any (localName, predicate)
  • localName: Optional
  • predicate: Optional (must follow localName)
  • return: Boolean

Example: Has any element with Female sex?

Sample: people |any (x, x.Sex == 'Female') 
Result: true

Example: Has any element at all?

Sample: people |any ()  
Result: true

contains

Determines whether a sequence contains a specified element. It checks for collection, sequence, enum flag and string.

 |contains (value)
  • value: Required
  • return: Boolean

Example:

Sample: people
        |select (x, x.Name)
        |contains ('arash')
Result: true

Example: String check

Sample: 'test 123'
        |contains ('123')
Result: true

toIndex

Creates a lookup index based on a key. Use [ and ] to access the data using a key. When the key is not found in the index, return null.

 |toIndex (localName, predicate)
  • localName: Required
  • predicate: This is used to create a key for the index. The key can be a single property or composite by using { and }.
Example:
b:= [{'Name':'a', 'Age': 23},{'Name':'b', 'Age': 33},{'Name':'c', 'Age': 43}]
b|toIndex(x,x.Name)

Result:
[
     {
         "Key" : "a",
         "Value" : {
             "Name" : "a",
             "Age" : 23
         }
     },
     {
         "Key" : "b",
         "Value" : {
             "Name" : "b",
             "Age" : 33
         }
     },
     {
         "Key" : "c",
         "Value" : {
             "Name" : "c",
             "Age" : 43
         }
     }
 ]

groupBy

Groups the elements of a sequence based on a key.

 |group (localName, predicate)
  • localName: Required
  • predicate: Required (key builder for groups) or list of properties of an element
  • return: Sequence of IGrouping elements

Example 1: Group people by gender (single property)

Sample: people |groupBy (x, x.Sex)
Result: Sequence of groups based on people gender (Sex property)

Example 2: Group people by gender and Age (by key function)

Sample: people |groupBy (x, key(x.Sex, x.Age))
Result: Sequence of groups based on people gender and age (Sex and Age property)

Example 3: Group people by gender and Age (by the list of properties)

Sample: people |groupBy (x, x.Sex, x.Age)
Result: Sequence of groups based on people gender and age (Sex and Age property)

groupIndexBy

Groups the elements of a sequence based on a key and then create an index based on the grouping key.

 |groupIndexBy (localName, predicate)
 Example:
b:= [{'Name':'a', 'Age': 23},{'Name':'b', 'Age': 33},{'Name':'c', 'Age': 43}]
b|groupIndexBy(x,x.Name)

Result:
[
     {
         "Key" : "a",
         "Value" : [
             {
                 "Name" : "a",
                 "Age" : 23
             }
         ]
     },
     {
         "Key" : "b",
         "Value" : [
             {
                 "Name" : "b",
                 "Age" : 33
             }
         ]
     },
     {
         "Key" : "c",
         "Value" : [
             {
                 "Name" : "c",
                 "Age" : 43
             }
         ]
     }
 ]

select

Projects each element of a sequence into a new form.

 |select (localName, predicate)
  • localName: Required
  • predicate: Required
  • return: Sequence of the projections

Example:

Sample: people|select (x, x.Name)

Result: a list of strings containing all the names ('Name' property of business objects)
Name
Arash
Parsa
Pooya
Shah

selectMany

Projects each element of a sequence to a list and flattens the resulting sequences into one sequence.

 |selectMany (localName, sequence)
  • localName: Required
  • sequence: Required
  • return: a flattened sequence of the projections

Example:

Sample: people |selectMany (x, x.Emails)
Result: a list of strings containing all emails of all people

apply

Executes a set of expressions on all elements of a sequence.

 |apply (localName, predicates)
  • localName: mandatory
  • predicates: comma-separated list of expressions based on localName

Example:

Sample: people |apply (x, x.Email=null, x.Age=0)
Result: on the list of people it sets Email to null and sets Age to 0.

forEach

Check apply

firstOrDefault

Returns the first item in the sequence or a null value. When a predicate is defined, the first item that matches will be returned.

 |firstOrDefault (localName, predicates)
  • localName: Optional
  • predicate: Optional
  • return: an element from sequence or null.
Sample: people |firstOrDefault (x, x.Age lt 3)
Result: The first person has the Age less than 3

first

Check firstOrDefault

lastOrDefault

Returns the last item in the sequence or a null value. When a predicate is defined, the last item that matches will be returned.

 |lastOrDefault (localName, predicate)
  • localName: Optional
  • predicate: Optional
  • return: an element from sequence or null.
Sample: people |lastOrDefault (x, x.Age gt 3)
Result: The last person has the Age greater than 3

distinct

Finds distinct elements from a list

 |distinct ()
  • return: an element from sequence or null.

Example:

Student = ["Sarah","Alex","Emma","Emma","Sarah"]
Student|distinct()

Result: [
     "Sarah",
     "Alex",
     "Emma"
 ]

last

Check lastOrDefault

where

Filters sequence based on a condition.

 |where (localName, predicate)
  • localName: Required
  • predicate: Required
  • return: Sequence that matches the predicate

Example:

Sample: people |where (x, x.Age == 3)
Result: A sequence of business objects that has all the people with the Age of 3
NameAgeSex
Pooya3Male
Shah3Female

take

Returns the first n elements of a sequence.

 |take (count)
  • count: Required (Length of the elements to be returned)
  • return: Sequence

Example:

Sample: people |take (2)
Result: A list that contains the first two elements of the business objects list.
NameAgeSex
Arash38Male
Parsa6Male

skip

Bypasses a specified number of elements in a sequence and then returns the remaining ones.

 |skip (count)
  • count: Required
  • return: Sequence

Example:

Sample: people |skip (2)
Result: Sequence containing 2 elements that is excluding the first two elements of the original list
NameAgeSex
Pooya3Male
Shah3Female

union

Produces the set union of two sequences.

 |union (second)
  • second: Mandatory (address of the second set)
  • return: Sequence (collection)

Example: Let’s consider the following two sets

a = [ 1, 2, 3, 4, 5, 9, 12 ]
b = [ 3, 5, 7, 8, 9 ]
Sample: a |union (b)
Result: [ 1, 2, 3, 4, 5, 7, 8, 9, 12 ]

intersect

Produces the set intersection of two sequences by using the default equality comparer to compare values.

 |intersect (second)
  • second: Mandatory (address of the second set)
  • return: Sequence (collection)

Example: Let’s consider the following two sets

a = [ 1, 2, 3, 4, 5, 9, 12 ]
b = [ 3, 5, 7, 8, 9 ]
Sample: a |intersect (b)
Result: [ 3, 5, 9 ]

except

Produces the set difference of two sequences.

 |except (second)
  • second: Mandatory (address of the second set)
  • return: Sequence (collection)
Example: 

a = [ 1, 2, 3, 4, 5, 9, 12 ]
b = [ 3, 5, 7, 8, 9 ]

a|except (b) 

Result: [ 1, 2, 4, 12 ]

toList

Returns a sequence of characters as a list from a given string.

value |toList ()
  • value (String): Value to be converted into a list (Mandatory)
Example: 'hello'|toList () 
Result: ["h", "e", "l", "l", "o"]

filter

Check where

exists

Checks whether a given list is empty and returns a boolean value.

list |exists ()
  • list: List to be checked whether it is contains any values (Mandatory)
Example: []|exists()
Result: False
Example: [1,2,3]|exists()
Result: True

minus

Shows the difference between the two lists.

a |minus (b)

Example: Let’s consider the following set

a = [1, 2, 5, 4, 3]
b = [1, 7]
Sample: b |minus(a)
Result: 7 

difference

Shows the difference between the two lists.

a |difference (b)

Example: Let’s consider the following set

a = [1, 2, 5, 4, 3]
b = [1, 7]
Sample: b |difference(a)
Result: 7 

min

Shows the minimum value of a list.

value |min ()

Example: Let’s consider the following set

a = [1, 2, 5, 4, 3]
Sample: a |min()
Result: 1 

max

Shows the maximum value of a list.

value |max ()

Example: Let’s consider the following set

a = [1, 2, 5, 4, 3]
Sample: a |max()
Result: 5 

avg

Shows the average value of a list.

value |avg ()

Example: Let’s consider the following set

a = [1, 2, 5, 4, 3]
Sample: a |avg()
Result: 3

sum

Use this monad operator to compute the sum of numeric values in a sequence.

value |sum (localName, predicate)
  • localName: optional
  • predicate: optional
  • return: numeric value

in

Determines whether a sequence contains a specified element.

value |in (sequence)
  • sequence: Required
  • value: Required
Example: "VIC" |in ("VIC","SA","NT")

key

Key is available as both function and monad. It creates an object to build a key. Key creates a structure of name and value.

 |key (expression1, expression2, expression3...)

Note expression1, expression2, expression3… can be simply a valid Expression or these can have the following format:

propertyName: expression

In this case, the object will have set property names. This option is available only for the key monad, not as a function.

Example 1: Group people by gender and Age and select Sex

Sample: people 
        |groupBy (x, key(x.Sex, x.Age))
        |select (s, s.Key.Sex)
Result: Sequence of groups based on people gender and age (Sex and Age property)

Example 2: key with custom property name

Sample: people 
        |select (x, x)
        |key (Gender: person.Sex, FirstName: person.Name)
Result: Sequence of new objects that each have (Gender and FirstName property)

keys

Keys is available as a function. It returns the keys from a dictionary.

 keys (parameter)
  • parameter: Parameter name of the dictionary

Example: Retrieve the student names from a dictionary

Students = {"Sam":15,"Alex":13,"Diana":12} 

Sample: keys(Students)

Result: The list of student names

[
     "Sam",
     "Alex",
     "Diana"
 ]

tuple

Creates a key based on multiple values combination. i.e. Composite Key.

 |tuple (arg1, arg2, arg3...)

Note the maximum number of accepted arguments is 8.

The result of the key is an object with a maximum of 8 properties

Item1, Item2, Item3,... Item8 

This corresponds to the argument that was passed to a key.

Example 2: Group people by gender and Age and select Sex

Sample: people 
        |groupBy (x, tuple(x.Sex, x.Age))
        |select (s, s.Key.Item1)
Result: Sequence of groups based on people gender and age (Sex and Age property)

In this example, Item1 is referring to x.Sex values and similarly Item2 will refer to x.Age.

query

Query a given attribute using JSONPath

JSONObject |query (JSONPath)
  • JSONObject: Mandatory (Variable name of the JSON object)
  • JSONPath: Mandatory  (JSONPath expression)

Use the following JSONPath syntax elements to search for data in a collection/ JSON object.

JSONPath syntaxDescription
$the root object/element
. or []child operator
..recursive descent
*wildcard. All objects/elements regardless their names.
[,]Union operator in XPath results in a combination of node sets. JSONPath allows alternate names or array indices as a set.

Examples:
studentInfo JSON object has the following attributes.

{
     "Classroom": {
         "Student": [
         {
             "Subject": "Maths",
             "Score": 98
         },
         {
             "Subject": "Physics",
             "Score": 95
         },
         {
             "Subject": "Biology",
             "Score": 86
         }
         ]
     }
 }

Example 1: If you want to get all the scores of the student,

Sample: studentInfo|query("$..Score")

Result: 
[
     98,
     95,
     86
 ]

This will search for any tag named Score in the JSON and return the values.

Example 2: If you want to get all the scores of the students under Classroom,

Sample: studentInfo|query("Classroom..Score")

Result: 
[
     98,
     95,
     86
 ]

This will search for any tag named Score under Classroom.

For further information, go to this link.

Updated on January 14, 2021

Was this article helpful?

Related Articles