# useEvaluation

Learn how to evaluate a CQL query using composables.

This composable evaluates a [CQL query](/reference/cql) in real-time and returns the result, serving as the imperative equivalent of the [`<Personalization>`](/reference/sdk/vue/api/components/personalization) component.

## Signature

This composable has the following signature:

```ts
function useEvaluation<T extends JsonValue>(
    query: MaybeRefOrGetter<string>,
    options?: MaybeRefOrGetter<UseEvaluationOptions>,
): UseEvaluationResult<T>;
```

Where `UseEvaluationResult<T>` is:

```ts
type UseEvaluationResult<T> = {
    data: ShallowRef<T | undefined>;
    isLoading: Ref<boolean>;
    error: Ref<Error | null>;
};
```

## Example

Here is an example of how to use this composable:

**JavaScript**

```vue
<script setup>
import {useEvaluation} from '@croct/plug-vue';

const {data: isDeveloper} = useEvaluation("user's persona is 'developer'");
</script>

<template>
  <a v-if="isDeveloper" href="/docs">View docs</a>
  <a v-else href="/share">Share with your developer</a>
</template>
```

**TypeScript**

```vue
<script setup lang="ts">
import {useEvaluation} from '@croct/plug-vue';

const {data: isDeveloper} = useEvaluation<boolean>("user's persona is 'developer'");
</script>

<template>
  <a v-if="isDeveloper" href="/docs">View docs</a>
  <a v-else href="/share">Share with your developer</a>
</template>
```

## Parameters

- `query`: `string`

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

- `options`: `object` (optional)

  The evaluation options. Accepts a `MaybeRefOrGetter` for reactivity.

  - `initial`: `JSON` (optional)

    An initial value to use while loading the actual result.

    This value is required for server-side rendering. For client-side rendering, not specifying this value will cause the `data` ref to be `undefined` and `isLoading` to be `true` until the evaluation completes.

  - `fallback`: `JSON` (optional)

    A fallback value to use in case of an error.

    If not specified, the `error` ref will contain the error and `data` will remain `undefined`.

  - `expiration`: `number` (optional) (default: 60000)

    The cache expiration time in milliseconds, extended on every render.

    If negative, the cache never expires. By default, the cache expires after 60 seconds.

    The SDK caches the result to prevent network requests on concurrent renders and re-renders.

  - `cacheKey`: `string` (optional)

    A unique key to identify the cache entry.

    By default, the cache key is a hash of the query and attributes. To force re-evaluation even if the query and attributes are the same, provide a unique cache key.

  - `staleWhileLoading`: `boolean` (optional) (default: false)

    Whether to use the previous result while re-evaluating the new value.

    By default, the composable sets `data` to `undefined` and `isLoading` to `true` while evaluating.

    If this option is enabled, the behavior changes as follows:

    - On the first render, it either returns the initial value or sets `isLoading` to `true` while evaluating the query.
    - If the cache key or any other property that affects the result changes, it returns the previous result while re-evaluating the query.
    - When the new result is available, it updates `data` with the new value.

  - `timeout`: `number` (optional)

    The maximum fetch time in milliseconds.

    Once reached, the SDK will abort the request and reject the promise with a timeout error.

  - `attributes`: `object` (optional)

    The map of attributes to inject in the evaluation context.

    The attributes can be referenced in audience conditions using the [`context`](/reference/cql/context#evaluation) variable. For example, suppose you pass the following attributes:

    ```json
    {cities: ["New York", "San Francisco"]}
    ```

    You can then reference them in queries like:

    ```cql
    context's cities include location's cityName
    ```

    For more information, see [Context variables](../../content-rendering#context-variables).

    The following restrictions apply to the attributes:

    - Up to 30 entries and 5 levels deep
    - Keys can be either numbers or non-empty strings with a maximum length of 50 characters
    - Values can be null, numbers, booleans, strings (up to 50 characters), or nested maps
    - Nested maps follow the same constraints for keys and values

## Return

The return is a reactive object with the following properties:

- `data`: `ShallowRef<T | undefined>`

  A shallow ref containing the evaluation result, or `undefined` while loading.

- `isLoading`: `Ref<boolean>`

  A ref indicating whether the evaluation is currently in progress.

- `error`: `Ref<Error | null>`

  A ref containing the error if the evaluation failed, or `null` otherwise.