---
title: WHERE
url: https://www.tines.com/docs/formulas/functions/where/
kind: formula-function
---

*[tines.com](https://www.tines.com/llms.txt) › [Docs](https://www.tines.com/docs/llms.txt) › [Formulas](https://www.tines.com/llm/docs/formulas.md) › [Functions](https://www.tines.com/llm/docs/formulas/functions.md)*

# WHERE

*[View on tines.com](https://www.tines.com/docs/formulas/functions/where/)*

Takes an array of objects, a path and a value (optional). The path can be a single key or a dot-separated series of keys. Returns a new array containing only the objects where the value at the key/path matches the provided value. If value is not provided, it returns an array containing only the objects where the value at the key/path is [present](https://www.tines.com/docs/formulas/functions/is-present).

If you try to pass NULL in for value, it will be treated as not provided, so you cannot use this function to check for NULL values. Instead, you can use [FILTER](https://www.tines.com/docs/formulas/functions/filter) to find NULL values like so:

`FILTER(data, LAMBDA(object, object["key"] = NULL))`. To return NULL when path has a value of NULL, set the `null_on_path_error` parameter to TRUE. `null_on_path_error` is FALSE by default.

**Categories:** Arrays, Objects

## Syntax

```
WHERE(array, path, [value], [null_on_path_error: FALSE])
```

## Examples

### Example 1

Input:

```json
{
  "staff": [
    {
      "name": "Alice",
      "department": "engineering"
    },
    {
      "name": "Bob",
      "department": "sales"
    },
    {
      "name": "Charlie",
      "department": "engineering"
    }
  ]
}
```

Formula:

```
WHERE(staff, "department", "engineering")
```

Output:

```json
[
  {
    "name": "Alice",
    "department": "engineering"
  },
  {
    "name": "Charlie",
    "department": "engineering"
  }
]
```

### Example 2

Input:

```json
{
  "staff": [
    {
      "name": "Alice",
      "department": {
        "name": "engineering",
        "role": "manager"
      }
    },
    {
      "name": "Bob",
      "department": {
        "name": "sales",
        "role": "assistant"
      }
    },
    {
      "name": "Charlie",
      "department": {
        "name": "sales",
        "role": "manager"
      }
    }
  ]
}
```

Formula:

```
WHERE(staff, "department.role", "manager")
```

Output:

```json
[
  {
    "name": "Alice",
    "department": {
      "name": "engineering",
      "role": "manager"
    }
  },
  {
    "name": "Charlie",
    "department": {
      "name": "sales",
      "role": "manager"
    }
  }
]
```

### Example 3: If 'value' isn't provided, return all objects where the path exists and the value at that path IS_PRESENT.

Input:

```json
{
  "staff": [
    {
      "name": "Alice",
      "department": {
        "name": "engineering",
        "role": "manager",
        "team": "AI"
      }
    },
    {
      "name": "Bob",
      "department": {
        "name": "sales",
        "role": "assistant",
        "team": "   "
      }
    },
    {
      "name": "Charlie"
    },
    {
      "name": "Denise",
      "department": {
        "name": "sales",
        "role": "manager"
      }
    }
  ]
}
```

Formula:

```
WHERE(data.staff, "department.team")
```

Output:

```json
[
  {
    "name": "Alice",
    "department": {
      "name": "engineering",
      "role": "manager",
      "team": "AI"
    }
  }
]
```

### Example 4: If 'path' is provided NULL and 'null_on_path_error' is provided TRUE, return NULL.

Input:

```json
{
  "staff": [
    {
      "name": "Alice",
      "department": {
        "name": "engineering",
        "role": "manager",
        "team": "AI"
      }
    }
  ]
}
```

Formula:

```
WHERE(data.staff, NULL, null_on_path_error: TRUE)
```

Output:

```json
"NULL"
```

## Sample actions

```json
{
  "standardLibVersion": "14",
  "actionRuntimeVersion": "3",
  "agents": [
    {
      "disabled": false,
      "name": "My Action 2",
      "description": null,
      "options": {
        "mode": "message_only",
        "loop": false,
        "payload": {
          "users": [
            {
              "name": "martin",
              "department": "Success",
              "location": "Dublin"
            },
            {
              "name": "bobby",
              "department": "Support",
              "location": "Utah"
            },
            {
              "name": "thomas",
              "department": "Success",
              "location": "Dublin"
            },
            {
              "name": "nick",
              "department": "Success",
              "location": "North Carolina"
            },
            {
              "name": "kelli",
              "department": "Marketing",
              "location": "Boston"
            }
          ]
        }
      },
      "position": {
        "x": 30,
        "y": 1290
      },
      "type": "eventTransformation",
      "timeSavedUnit": "minutes",
      "timeSavedValue": 0,
      "monitorAllEvents": false,
      "monitorFailures": false,
      "monitorNoEventsEmitted": null,
      "form": null
    },
    {
      "disabled": false,
      "name": "WHERE",
      "description": "You can read this: WHERE(my_action_2.users, 'location', my_action_1.location) as:\n\nGive me the result where My Action 2 has a location that matches My Action 1's location value",
      "options": {
        "mode": "message_only",
        "loop": false,
        "payload": {
          "Where": "=WHERE(my_action_2.users, 'location', my_action_1.location)"
        }
      },
      "position": {
        "x": 30,
        "y": 1380
      },
      "type": "eventTransformation",
      "timeSavedUnit": "minutes",
      "timeSavedValue": 0,
      "monitorAllEvents": false,
      "monitorFailures": false,
      "monitorNoEventsEmitted": null,
      "form": null
    },
    {
      "disabled": false,
      "name": "My Action 1",
      "description": null,
      "options": {
        "mode": "message_only",
        "loop": false,
        "payload": {
          "location": "Utah",
          "field_name": "location"
        }
      },
      "position": {
        "x": 30,
        "y": 1200
      },
      "type": "eventTransformation",
      "timeSavedUnit": "minutes",
      "timeSavedValue": 0,
      "monitorAllEvents": false,
      "monitorFailures": false,
      "monitorNoEventsEmitted": null,
      "form": null
    }
  ],
  "links": [
    {
      "sourceIdentifier": 0,
      "receiverIdentifier": 1
    },
    {
      "sourceIdentifier": 2,
      "receiverIdentifier": 0
    }
  ],
  "diagramNotes": []
}
```