Query Predicates

In our Manage resources with the SDK module, we learned how to perform Create, Read, Update, and Delete (CRUD) operations on resources. We will build on this knowledge in this module and focus on how to query resources based on specific conditions.

Let’s take an example. Say you want to get the data on all customers in the age group 30 to 40 who reside in Berlin and have purchased products from a particular category in the last year. This is where query requests come in to help. By using API queries with appropriate predicates, you can retrieve a subset of data based on specific criteria. When used properly, queries can greatly enhance the performance and user experience of your application.

Query Predicates are a domain-specific language designed to define complex expressions for querying resources.

The syntax consists of field identifiers, operators, and values. Here's a breakdown of the syntax:

• Field identifiers: these reference specific fields within a resource. For example, totalPrice or customerEmail.
• Operators: these are used to compare the field identifier with a value. Common operators include =, !=, >, <, in, and contains.
• Values: these are the specific data points you're comparing the field identifiers against, such as a string, number, or boolean.

Here's an example of a Query Predicate that filters Customers in the gold Customer Group who were last updated after a certain date. The endpoint used is /customers:

where customerGroup(id="eb16f563-d9ca-4336-b9f3-64cce3b0123a") and lastModifiedAt>"2024-01-12T05:00:00.000Z"

Let’s break this Query Predicate down:

• customerGroup is the field identifier.
• eb16f563-d9ca-4336-b9f3-64cce3b0123a is the ID of the Customer Group we are looking for.
• and is a logical operator that combines multiple predicates.
• lastModifiedAt is the field identifier that references the date and time (UTC) the Customer was last updated.
• > is the operator that checks if the date is greater than the specified value.
• 2024-01-12T05:00:00.000Z is the date.

A predicate is a logical expression that evaluates to true or false and determines whether a resource is included in the query result.

The example above evaluates to true. If we wanted it to evaluate to false then we can change it by wrapping it in parentheses and adding a not to the beginning:

where not (customerGroup(id="eb16f563-d9ca-4336-b9f3-64cce3b0123a") and lastModifiedAt>"2024-01-12T05:00:00.000Z")

Now, this will return all Customers that belong to any Customer Group other than gold and that were last updated before 2024-01-12T05:00:00.000Z.

If we wanted to get Customers who are not assigned to a Customer Group, we would then use customerGroup is not defined.