Advanced FQL expressions in Postman Flows
With the recent launch of Postman Flows, more and more people around the world are starting to create and experiment, familiarizing themselves with the capabilities it unlocks.
From extract-transform-load (ETL) use cases to business dashboards, Postman Flows offers a completely new take on how APIs can enable business processes without the need for complex coding and cumbersome application development.
A key capability within Flows that is empowering these rapid development efforts to be so effective is the use of Flows Query Language (FQL) within the Evaluate block.
FQL is the expression language built into Flows that can manipulate and aggregate data sourced from API requests and other blocks, or data created within the flows themselves. The result of the FQL expression can then be passed to other blocks to be used in subsequent API requests or output directly to the user.
The following is a set of nine examples showing how to slowly create more and more sophisticated expressions using sample data and the Evaluate block in Postman Flows.
To help you get hands-on, these examples are also available in the Flows – Advanced FQL Scripts public workspace for you to fork and build upon.
Example 1: Using aggregations
Users are able to use any of the built-in functions (e.g., $sum
, $avg
, $min
, or $max
) to perform simple aggregations on lists of numbers.
The example below performs a simple sum of the list of numbers provided:
Aggregations form the foundation of the calculations that users are likely to perform to summarize and analyze data within Flows.
Example 2: Using variables
While multiple Evaluate blocks can be chained together, it’s sometimes useful to have access to variable information within FQL. Variables can be set by using the := syntax.
The example below performs two aggregations, a sum of the list of numbers and an average of the list of numbers. It then adds the two numbers together to produce the final result:
The last expression is implicitly returned as output from the Evaluate block. A return statement is not required.
Note: for variables to work, the FQL expression must be wrapped in parentheses.
Example 3: Using array functions
In some cases, users may want to perform a calculation or operation on each element of an array (or list). Flows offers several common functions that users can utilize (e.g., $count
, $filter
, $reduce
, and $map
) that will help perform these operations.
The example below filters the given list of numbers for any that have a 0 remainder when divided by 2 (modulus). Only 1 number meets the criteria and this is what is returned:
Example 4: Combining variables and array functions
For more sophisticated calculations, it may be necessary to combine variables and array functions. You can assign the result of an array function just as you would any other function.
This example iterates through the numbers list and squares each of the values, creating a new list. It then sums the total of the new list:
Example 5: Working with records
More complicated datasets are modeled using the Record type in Flows. Records are key/value pairs where the values could be almost any data type. JSON objects are considered records when being evaluated in Postman Flows.
Users can use dot notation to select values from the keys within a record:
Example 6: Aggregating data from an array of records
Data is often returned from API endpoints as an array of JSON objects. FQL makes it simple to perform calculations and aggregations across the whole dataset in a single step.
The below example sums the total field from each record in the list with a single expression:
Example 7: Using query filters on arrays of records
The previous example looked at a field on each record. It is sometimes useful to only select a subset of the records in a list. For this, users can use query filters.
The below example shows how a query filter can be used to only select records where the status field is equal to CLOSED, and then sum the resulting costs:
Example 8: Transformation to a new JSON object
Users will often want to transform JSON from one format to another in order to prepare data to be used in a subsequent API call. FQL and the Evaluate block make this process extremely simple.
The example below takes a Record object and transforms this into a completely new JSON format, whilst at the same time performing sum aggregations on the filtered data within. In this case, the new JSON object has the sum totals of orders with the status OPEN and CLOSED:
Example 9: Summarizing based on dates
Extending upon the previous example where we wanted to summarize cost by status, in the instance where we have a date field in our records, we can instead use that for the summarization.
The example below shows a list of records that have a cost and a date field. The goal here is to sum the costs by each month across all of the records.
To achieve this, we need to break the problem down into three parts:
- Convert the dates into the required format (yyyy-MM)
- Sort the dates into ascending order
- Sum the costs for each date
With some small modifications, this evaluation can then be used to power a bar or line chart representing some very useful information from a business user perspective.
Note: Dates in Flows are currently represented as UNIX timestamps (millis from epoch). The $fromMillis
and $toMillis
functions are provided to convert these dates into more readable formats.
As you can see, FQL in Flows in combination with the Evaluate block provides some extremely powerful functionality to aggregate, manipulate, and summarize data from your APIs.
For more information about FQL, see the Introduction to FQL Learning Center page, and for more information on Postman Flows, see the Flows Overview page.
Postman Flows is available now on Postman Free and Professional plans. Tell us in a comment below how Flows and FQL are helping you and your organization today.
What do you think about this topic? Tell us in a comment below.