Query evaluation

This guide provides practical examples of using the JavaScript SDK to evaluate CQL queries from your application.

Basic usage

The SDK provides an evaluate method that allows you to run CQL queries in real-time. This method returns a promise that resolves to the result of the evaluation.

For example, to check whether the current user is returning to your application you can use the following query:

import croct from '@croct/plug';

async function evaluate() {
  const returning = await croct.evaluate('user is returning');

  console.log('Is returning user?', returning);
}

The result of the evaluation is not restricted to boolean values. For example, you can use the following query to find out the location from which the user is accessing your application:

import croct from '@croct/plug';

async function evaluate() {
  const location = await croct.evaluate('location');

  console.log('User location:', location);
}

In this case, the result of the evaluation is a geographic location:

{
  "continent": "North America",
  "continentCode": "NA",
  "country": "United States",
  "countryCode": "US",
  "region": "New York",
  "regionCode": "NY",
  "state": "New York",
  "stateCode": "NY",
  "city": "Denver",
  "district": null,
  "timeZone": null
}

Fault tolerance

We recommend always handling errors when evaluating queries to protect your application from unexpected errors, downtime, and network failures.

You can achieve this by catching potential errors and providing a fallback value in case of error:

import croct from '@croct/plug';

async function evaluate() {
  const returning = await croct.evaluate('user is returning')
    .catch(() => false);

  console.log('Is returning user?', returning);
}

In this example, the returning variable is set to false if the evaluation fails, ensuring that the application continues to work as expected.

Context variables

In some cases, you may want to pass additional information that can be used by the query in the evaluation process.

For example, let's say you want to check whether the user is accessing your application from one of a list of countries. The SDK allows you to pass this information as an attribute to the query:

import croct from '@croct/plug';

async function evaluate() {
  const result = await croct.evaluate("context's countries include location's country", {
    attributes: {countries: ['United States', 'Canada', 'Mexico']},
  });

  console.log('Is one of the countries?', result);
}

Any attribute passed in the attributes option will be available in the query as a context variable.