# cql

Learn how to evaluate a CQL query using a tag function.

This [tag function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#tagged_templates) evaluates a [CQL query](/reference/cql) on the server side.

> **Router compatibility**
>
> This function is only compatible with the [App Router](https://nextjs.org/docs/app), but you can alternatively use the [`evaluate`](evaluate) function.

Both the `cql` tag and the [`evaluate`](evaluate) function are similar in functionality. The main difference between them is that the `cql` tag automatically handles query interpolation for you, but it does not support specifying [options](evaluate#options-prop). So if you do not need to specify options or interpolation, you can use them interchangeably.

## Signature

This function has the following signature:

```ts
function cql<T extends JsonValue>(query: string): Promise<T>;
```

The result is a `Promise` that resolves to the result of the evaluation.

### Example

Here is a minimal example of how to use this function:

**JavaScript**

**Basic**

```jsx
import {cql} from '@croct/plug-next/server';

export function DocsLink() {
  const isDeveloper = cql`user's persona is 'developer'`;

  return (
    isDeveloper
      ? <a href="/docs">View docs</a>
      : <a href="/share">Share with your developer</a>
  );
}
```

**Interpolation**

```jsx
import {cql} from '@croct/plug-next/server';

export function DocsLink() {
  const roles = ['developer', 'engineer', 'cto', 'cio'];
  const isTechnical = cql`user's persona is in ${roles}`;

  return (
    isTechnical
      ? <a href="/docs">View docs</a>
      : <a href="/share">Share with your developer</a>
  );
}
```

**TypeScript**

**Basic**

```tsx
import type {ReactElement} from 'react';
import {cql} from '@croct/plug-next/server';

export function DocsLink(): ReactElement {
  const isDeveloper = cql<boolean>`user's persona is 'developer'`;

  return (
    isDeveloper
      ? <a href="/docs">View docs</a>
      : <a href="/share">Share with your developer</a>
  );
}
```

**interpolation**

```tsx
import type {ReactElement} from 'react';
import {cql} from '@croct/plug-next/server';

export function DocsLink(): ReactElement {
 const roles = ['developer', 'engineer', 'cto', 'cio'];
 const isTechnical = cql<boolean>`user's persona is in ${roles}`;

 return (
   isTechnical
     ? <a href="/docs">View docs</a>
     : <a href="/share">Share with your developer</a>
 );
}
```

## Parameters

The following list describes the supported parameters:

- `query`: `string`

  The [CQL query](/reference/cql) to evaluate, with a maximum length of 500 characters.