My awesome application

# Query evaluation Learn how to evaluate queries in real-time. This guide provides practical examples of using the JavaScript SDK to evaluate [CQL queries](/reference/cql/introduction) from your application. ## Basic usage The SDK provides an [`evaluate`](api/plug/evaluate) method that allows you to run [CQL queries](/reference/cql/introduction) 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: **Boolean query** **JavaScript** ```js import croct from '@croct/plug'; async function evaluate() { const returning = await croct.evaluate('user is returning'); console.log('Is returning user?', returning); } ``` **TypeScript** ```ts import croct from '@croct/plug'; async function evaluate(): Promise { const returning = await croct.evaluate('user is returning'); console.log('Is returning user?', returning); } ``` **HTML** ```html My awesome application ``` 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: **Location query** **JavaScript** ```js import croct from '@croct/plug'; async function evaluate() { const location = await croct.evaluate('location'); console.log('User location:', location); } ``` **TypeScript** ```ts import croct from '@croct/plug'; async function evaluate(): Promise { const location = await croct.evaluate('location'); console.log('User location:', location); } ``` **HTML** ```html My awesome application ``` In this case, the result of the evaluation is a [geographic location](/reference/cql/data-types/location/location): **Query result** ```json { "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 } ``` *In the browser version of this page, this example is evaluated live for the visitor.* ## 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: **Fail-safe evaluation** **JavaScript** ```js import croct from '@croct/plug'; async function evaluate() { const returning = await croct.evaluate('user is returning') .catch(() => false); console.log('Is returning user?', returning); } ``` **TypeScript** ```ts import croct from '@croct/plug'; async function evaluate(): Promise { const returning = await croct.evaluate('user is returning') .catch(() => false); console.log('Is returning user?', returning); } ``` **HTML** ```html My awesome application ``` 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: **Evaluation with external context** **JavaScript** ```js import croct from '@croct/plug'; async function evaluate() { const result = await croct.evaluate("context's countries include location's countryName", { attributes: {countries: ['United States', 'Canada', 'Mexico']}, }); console.log('Is one of the countries?', result); } ``` **TypeScript** ```ts import croct from '@croct/plug'; async function evaluate(): Promise { const result = await croct.evaluate("context's countries include location's countryName", { attributes: {countries: ['United States', 'Canada', 'Mexico']}, }); console.log('Is one of the countries?', result); } ``` **HTML** ```html My awesome application ``` Any attribute passed in the [`attributes`](api/plug/evaluate#options-attributes-prop) option will be available in the query as a [`context`](/reference/cql/data-types/web/web-context) variable. ## Explore - [CQL reference](/reference/cql/expressions/basics): Learn how to write queries using the CQL language. - [Evaluate method](api/plug/evaluate): Explore the method documentation and available options.