Understanding array data types

Introduction

We saw in the section on understanding the expressions template that most data objects in Cargo are contained inside JSON structures extracted from databases or APIs. The second most common data type that Cargo users encounter is the array.

It is important to understand how to handle arrays within Cargo workflows and data models as they requires a different syntax to be used inside Cargo expressions. Moreover, they are only compatible with specific methods that allow for data manipulation and transformation within an array.

Cargo's workflow editor normally provides options to handle either single JSON objects or only one specific element inside an array of objects. Where there is a need to 'loop' through all the elements of an array, the group node is used to iterate over each element in the array inside a 'sub-workflow'

What is an array?

In simple terms, an array is a data structure that stores a collection of elements, each identified by at least one index or key. Arrays are commonly used to store lists of data, such as a list of email addresses, a list of social media URLs, etc.

They're different to JSON objects in that they are not a single object containing key-value pairs, but rather a list of multiple elements that can be accessed by their index.

  "user": {
    "name": "John Doe",
    "firstName": "John",
    "lastName": "Doe",
    "address": {
        "street": "123 Main St",
        "city": "Anytown"
    },
}

    ...
        [
        "john.doe@example.com",
        "johndoe@anotherexample.com"
        ]

Notice how the JSON object contains key-value pairs, while the array contains a list of elements each identified by an index. What is an index? It is a number that represents the position of an element in an array.

For instance, in the array above, the first element is john.doe@example.com and hence has an index of 0. The second element is johndoe@anotherexample.com and has an index of 1. We use these indices to identify elements in the array, as we will see below.

Accessing array elements inside an expression

Imagine you have a start node like the one below, containing an array of email addresses associated with a user.

{
  "user": {
    "name": "John Doe",
    "firstName": "John",
    "lastName": "Doe",
    "address": {
      "street": "123 Main St",
      "city": "Anytown"
    },
    "emails": ["john.doe@example.com", "johndoe@anotherexample.com"]
  }
}

Adding square brackets in front of a reference to an array type of data object will permit access to elements inside the array.

Using the example start node above, let's zoom in onto the array containing two email addresses associated to John Doe that are nested in an array.

Should you want to loop over an entire array to process each of its elements, refer to this tutorial on using the group node in a workflow.

To access elements within this array, use square brackets with the index of the element you wish to access, like so:

{
  {
    nodes.start.user.emails[1];
  }
}

The index 1 is used because array indices start at 0, making 1 the second element, returning 'johndoe@anotherexample.com'.

Iteration

Arrays also support iteration, which enables you to traverse through each element, performing operations as needed.

Iteration can be achieved through methods like forEach(), map(), filter(), etc. providing a versatile toolset for data manipulation within node-based workflows.

In the example here, we take an example object below called 'companyInfo', which contains a property called 'socialMediaUrls'.

{
  "companyInfo": {
    "socialMediaUrls": [
      {
        "type": "LINKED_IN",
        "url": "http://www.linkedin.com/company/acmeinc",
        "followerCount": null
      },
      {
        "type": "TWITTER",
        "url": "http://www.twitter.com/acmeinc",
        "followerCount": 7260
      },
      {
        "type": "FACEBOOK",
        "url": "http://www.facebook.com/acmeincorporated",
        "followerCount": 2929
      }
    ]
  }
}

If we wanted to extract any occurrences of LinkedIn URLs from such an object, we would use an expression like the one below:

{
  {
    nodes.companyInfo.socialMediaUrls
      .filter((item) => item.type === "LINKED_IN")
      .map((item) => item.url)
      .join(", ");
  }
}

The expression above filters the array to find items where the type is 'LINKED_IN', maps over the filtered array to extract the URLs, and then joins them into a single string separated by commas.

Parsing string to arrays

In some cases, you may need to convert a string to an array. This can be achieved using the split method, which splits a string into an array of substrings based on a specified separator. For instance, if you have a string of comma-separated values, you can split it into an array using a comma as the separator.

{
  {
    "LinkedIn,Twitter,Facebook".split(",");
  }
}

The expression above converts the string ["LinkedIn", "Twitter", "Facebook"] to an array of strings, where each index contains one of the values.

Joining array elements into a string

Conversely, you may need to join an array of elements into a single string.

The join() method creates and returns a new string by concatenating all the elements in an array, separated by a specified separator string. If no separator is provided, the default separator is a comma.

For instance, if you want to join the URLs from the companyInfo object's socialMediaUrls array into a single string with each URL separated by a comma, you can use the join() method.

{
  {
    nodes.companyInfo.socialMediaUrls.map((social) => social.url).join(", ");
  }
}

The expression above extracts the URLs from the socialMediaUrls array and joins them into a single string, separated by a comma and a space. The resulting string for the example array above would be:

"http://www.linkedin.com/company/acmeinc, http://www.twitter.com/acmeinc, http://www.facebook.com/acmeincorporated"