# Criteria

### Overview

The **Criteria** object is a commonly used model within the **Clear API** for defining complex filter rules. It is used when generating reports as well as searching across various resources. 

A criteria is a recursively nested JSON object composed of branches of conditions, it takes the following base form:

```javascript
{
    "COMPARATOR": [
        { FIELD },
        "VALUE"
    ]
}
```

The root *key* of a Criteria object is known as a **Comparator**, and the *value* will always be an Array of **values** to compare. This object is known as an **Operation**, and the power of the Criteria object comes in its ability to combine multiple operations together.

```javascript
{
    and: [
        {
            "COMPARATOR": [
                { FIELD },
                "VALUE"
            ]
        },
        {
            "COMPARATOR": [
                { FIELD },
                "VALUE"
            ]
        }
    ]
}
```

 At its most simplest, a criteria could simply be matching on a single field:

```javascript
{
    "=": [
        { type: "attribute", key: "Country" },
        "Australia"
    ]
}
```

When used in Actor search, the above criteria will return all actors with a `Country` attribute matching `Australia`.

However, more advanced examples permit deep nesting to build infinitely complex filter rules:

```javascript
{
    and: [
        { "=": [
            { type: "attribute", key: "Country" },
            "Australia"
        ] },
        { or: [
            { "=": [
                { type: "attribute", key: "Department" },
                "Marketing"
            ] },
            { "!=": [
                { type: "attribute", key: "Job Title" },
                "*Manager"
            ] }
        ] }
    ]
}
```

When used in Actor search, the above criteria will return all actors who meet the following conditions:

* The actor must contain a `Country` attribute of `Australia`, **AND**;
* The actor must match any of the following:
  * The actor must contain a `Department` attribute of `Marketing`, **OR;**
  * The actor must not contain a `Job Title` attribute ending in `Manager`

### Reference

#### Comparators

| Key          | Description                                                                                                                        |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| `and`        | All operations in the Array must be met for the filter to match.                                                                   |
| `or`         | Any operation in the Array must be met for the filter to match.                                                                    |
| `=`          | The resource field must match any of the values in the Array.                                                                      |
| `!=`         | The resource field must not match any of the values in the Array.                                                                  |
| `<`          | The resource field must be less than the second value in the Array.                                                                |
| `<=`         | The resource field must be less than or equal to the second value in the Array.                                                    |
| `>`          | The resource field must be greater than the second value in the Array.                                                             |
| `>=`         | The resource field must be great or equal to the second value in the Array.                                                        |
| `><`         | The resource field must be between the first and second values in the Array (non-inclusive).                                       |
| `<>`         | The resource field must be less than the first value in the Array and greater than the second value in                             |
| `exists`     | A value for the resource field must exist.                                                                                         |
| `!exists`    | A value for the resource field must not exist.                                                                                     |
| `belongsTo`  | Used with the **Actors** resource and **Groups** field, indicates the Groups field must contain the second value in the Array.     |
| `!belongsTo` | Used with the **Actors** resource and **Groups** field, indicates the Groups field must not contain the second value in the Array. |

#### Values

| Resource  | Field | Example            |
| --------- | ----- | ------------------ |
| **Actor** | Name  | `{ type: "name" }` |