> Documentation index: https://firebase.google.com/docs/firestore/llms.txt

While Pipeline operations offer a rich set of
features, the Rules engine is restricted to recognizing comparison (e.g. `>`) and logical (e.g. `or`) filters to ensure
constraint satisfiability and security.

## Supported Filter Expressions

For Pipeline operations to be constrained to the bounds set by your rules, it must use
logical and comparison operators against constants. The following filter types
are recognized by the Rules engine:

- Comparisons: `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `in`, `arrayContains`.
- Logical: `and`, `or`.

Here are some examples:

- `where(eq("foo", 2))`
- `where(lt("foo", 2))`
- `documents("/user/1", "/user/2").where(...)`

> [!NOTE]
> **Note:** Complex expressions, such as arithmetic within a filter (For example, `where(eq("foo" * 2, 10))`) or string functions like `strContains`, are not recognized for constraining queries.

## Request Properties

You can continue to use the
[`request`](https://firebase.google.com/docs/reference/rules/rules.firestore.Request.md.txt)
object to validate authentication and query context, though some properties
available in standard queries are not supported in Pipeline operations.

### Supported properties

The new engine continues to support the following properties:

- `request.auth`: Access user uid and token data.
- `request.method`: Identifies the operation (For example, `get`, `list`).
- `request.path`: The path of the resource being accessed.
- `request.time`: The server-side timestamp of the request.

### Unsupported properties

The `request.query` properties such as `limit`, `offset`, and `orderBy` are
unsupported for Pipeline operations rule checks due to the complexity of determining these
values in multi-stage queries.

## Pipeline stage handling and permissions

There are different pipeline stages that map to specific granular operations in
security rules:

- `allow list` permissions: Triggered by `collection()`, `collectionGroup()`, and `database()` stages.
- `allow get` permissions: Triggered by the `documents()` stage, which is treated similarly to a batch `get` operation.
- `allow create` permissions: Triggered by `insert()` stages, and `upsert()` stages when creating new documents.
- `allow update` permissions: Triggered by `update()` stages, and `upsert()` stages when updating existing documents.
- `allow delete` permissions: Triggered by `delete()` stages.
- `allow write` permissions: Applies to all DML operations (`insert()`, `update()`, `upsert()`, and `delete()`).
- Literals stage: The `literals()` stage does not read from the database but can incur costs. To prevent abuse, it must be paired with another stage (like `collection()`) that can be verified by rules.

## Field modification stages

Rules only operate on stored data and not derived values. If a pipeline includes
stages that modify fields (For example,
[`add_fields(...)`](https://firebase.google.com/docs/firestore/pipelines/stages/transformation/add-fields.md.txt),
[`replace_with(...)`](https://firebase.google.com/docs/firestore/pipelines/stages/transformation/replace-with.md.txt),
[`select(...)`](https://firebase.google.com/docs/firestore/pipelines/stages/transformation/select.md.txt),
[`remove_fields(...)`](https://firebase.google.com/docs/firestore/pipelines/stages/transformation/remove-fields.md.txt)),
the Rules engine stops applying filter constraints after that stage is
encountered. To ensure that rules works as expected, position your filter stages
(i.e. `where`) before any stages that can modify the original stored documents.

For example, take the following security rule:

    match /databases/{database}/documents {
      match /cities/{city} {
        // Allow the user to read data if the document has the 'visibility'
        // field set to 'public'
        allow read: if resource.data.visibility == 'public';
      }
    }

Denied: This rule rejects the following pipeline because the `addFields` stage
occurs before filtering to documents where `visibility` is `public`:

```javascript
const results = await db.pipeline()
  .collection("/cities")
  // Filters after a modification stage are ignored by Rules.
  .addFields(constant(1000).as("population"))
  .where(eq(field("visibility"), constant("public")))
  .execute();
```

Allowed: This rule allows the following
pipeline because the `where(eq(field("visibility"), constant("public")))` stage
occurs before any modification stages:

```javascript
const results = await db.pipeline()
  .collection("/cities")
  .where(eq(field("visibility"), constant("public")))
  .addFields(constant(1000).as("population"))
  .execute();
```

## Data manipulation language stages and security rules

When executing Data manipulation language (DML) stages (`insert()`, `update()`,
`upsert()`, and `delete()`), Security Rules evaluate permissions differently
than for read queries:

- **Per-document rule evaluation**: Unlike read pipelines, which require filter expressions up front to constrain the query at planning time, DML operations evaluate security rules against each individual document mutation.
- **Rule variables** :
  - `request.resource`: Contains the proposed document data for `insert()`, `update()`, and `upsert()` operations.
  - `resource`: Contains the current document data stored in the database prior to modification (available for `update()`, `delete()`, and `upsert()` of existing documents).

### System limits and execution behavior with DML

When running DML operations with Security Rules, keep the following
system limits and execution behaviors in mind:

#### The 20-lookup limit on `get()` and `exists()`

Firebase Security Rules allows a maximum of 20 document lookups (`get()` or
`exists()`) across an entire request.

When a DML pipeline runs outside of an explicit transaction,
Cloud Firestore processes document writes in batches. Because each
batch executes in its own transaction and documents might be modified
concurrently between batches, security rules and document lookups are
re-evaluated for **each write batch**.

Even if your security rules evaluate against a single static document
(for example, checking whether a user is an administrator):

    rules_version = '2';
    service cloud.firestore {
      match /databases/{database}/documents {
        match /posts/{postId} {
          allow write: if get(/databases/$(database)/documents/users/$(request.auth.uid)).data.isAdmin == true;
        }
      }
    }

Each write batch of 10 documents performs a lookup. As a result, after writing
all possible documents, the 20-lookup limit for the request is reached,
and the pipeline fails with a `PERMISSION_DENIED` error. In addition, each
lookup performed per write batch incurs its own read billing.

> [!TIP]
> **Tip:** To avoid hitting the 20-lookup limit on bulk DML operations, use [Custom Claims](https://firebase.google.com/docs/auth/admin/custom-claims.md.txt) on Firebase Authentication tokens (for example, `request.auth.token.isAdmin == true`) instead of `get()` or `exists()` lookups. Custom claims are validated in memory directly from the authentication token, avoiding document reads and lookup limits entirely.

#### Partial success and `PERMISSION_DENIED`

When executing outside of a transaction, DML operations commit writes in
sequential batches. If a batch fails---either because a document fails a rule
condition or because the 20-lookup limit is exceeded---the pipeline halts and
returns a `PERMISSION_DENIED` error.

However, **batches that were already committed are not rolled back**. The
database remains in a partially updated state. Because the client receives an
error without a list of modified documents, you must query your data to inspect
which writes succeeded.

> [!TIP]
> **Tip:** If your workload requires all-or-nothing execution, run the DML pipeline within an explicit user transaction (for example, using `runTransaction` and `transaction.execute(pipeline)`). In a transaction, all operations either commit together or roll back completely on error. Note that transactions are subject to Firestore Enterprise edition transaction limits.

#### Diagnosing rule failures with Cloud Audit Logs

For security reasons, client-facing `PERMISSION_DENIED` errors don't disclose
which security rule condition failed or whether the 20-lookup limit was reached.

To diagnose rule evaluation failures, project administrators can inspect
Cloud Audit Logs in the Google Cloud console (under **Firestore** \>
**Monitoring** or in **Logs Explorer** ) to view detailed `EvaluationError`
entries.