---
title: Scopes
description: "Name a reusable part of a query, or narrow every query on a Model with a default scope."
seo:
  description: "Define named scopes on Active Record Models, call them on any Relation, narrow every query with a default scope, and leave it out with unscoped()."
---

## At a glance

| To                               | Write                                                                    |
| -------------------------------- | ------------------------------------------------------------------------ |
| declare a scope                  | `static published = this.scope((q) => q.whereNot({ … }))`                |
| declare one that takes arguments | `static publishedSince = this.scope((q, since: Date) => q.where({ … }))` |
| call it                          | `Post.published()`, or on any Relation: `Post.where(…).published()`      |
| narrow every query               | `static { this.defaultScope((q) => q.where({ isAvailable: true })) }`    |
| leave the default scope out      | `Product.unscoped()`                                                     |

## The Models

The examples use these Models, whose attributes come from their tables through the schema `active-record schema` generates:

```ts post.ts
import { gte } from "@forestfuture/active-record";
import { ApplicationRecord } from "./application-record";

export class Post extends ApplicationRecord {
  static published = this.scope((q) => q.whereNot({ publishedAt: null }));
  static publishedSince = this.scope((q, since: Date) => q.where({ publishedAt: gte(since) }));
}
```

```ts product.ts
import { ApplicationRecord } from "./application-record";

export class Product extends ApplicationRecord {
  static {
    this.defaultScope((q) => q.where({ isAvailable: true }));
  }
}
```

```ts schema.ts
// Generated by `active-record schema` from migrations/ — don't edit.
// schema: e9579b7b05ee

import { defineSchema, type TableAttributes } from "@forestfuture/active-record";
import { d1 } from "@forestfuture/active-record/d1";

/** posts — last changed by 0001_create_tables.sql */
export const posts = {
  id: { type: "string", null: false, generateId: true },
  title: { type: "string", null: false },
  publishedAt: "datetime",
} as const;

/** products — last changed by 0001_create_tables.sql */
export const products = {
  id: { type: "string", null: false, generateId: true },
  name: { type: "string", null: false },
  isAvailable: { type: "boolean", null: false },
} as const;

/** The database's adapter and binding, its tables (with their primary keys), and the Models built on them. */
export const schema = defineSchema({
  adapter: d1({ binding: "DB" }),
  tables: {
    posts: { attributes: posts, primaryKey: "id" },
    products: { attributes: products, primaryKey: "id" },
  },
  models: { Post: "posts", Product: "products" },
});

declare module "../models/post" {
  interface Post extends TableAttributes<typeof posts, (typeof Post)["attributes"]> {}
}

declare module "../models/product" {
  interface Product extends TableAttributes<typeof products, (typeof Product)["attributes"]> {}
}
```

```sql D1
CREATE TABLE posts (
  id TEXT PRIMARY KEY NOT NULL,
  title TEXT NOT NULL,
  published_at DATETIME
);
CREATE TABLE products (
  id TEXT PRIMARY KEY NOT NULL,
  name TEXT NOT NULL,
  is_available BOOLEAN NOT NULL
);
```

```sql Postgres
CREATE TABLE posts (
  id UUID PRIMARY KEY,
  title TEXT NOT NULL,
  published_at TIMESTAMPTZ
);
CREATE TABLE products (
  id UUID PRIMARY KEY,
  name TEXT NOT NULL,
  is_available BOOLEAN NOT NULL
);
```

## Defining scopes

Declare a scope as a static that receives the Relation, plus any arguments, and returns a narrower one:

```ts title="src/models/post.ts"
import { gte } from "@forestfuture/active-record";
import { ApplicationRecord } from "./application-record";

export class Post extends ApplicationRecord {
  static published = this.scope((q) => q.whereNot({ publishedAt: null }));
  static publishedSince = this.scope((q, since: Date) => q.where({ publishedAt: gte(since) }));
}
```

## Calling scopes

Call a scope as a static, or on any Relation of the Model:

```ts
import { Post } from "./models/post";

const published = await Post.published().toArray();
const thisYear = await Post.published().publishedSince(new Date("2026-01-01")).toArray();
const hellos = await Post.where({ title: "Hello" }).published().count(); // on any Relation
```

- Its arguments, and anything it computes such as `new Date()`, are evaluated when you call it.
- Scopes are inherited, including those on your app’s base class ([Shared behavior](/shared-behavior)). A subclass can replace one with `static override published = this.scope(…)`.
- A scope can’t reuse a Relation method’s name (`where`, `count`) or a Model static’s (`validates`, `scope`, `all`).
- Inside a scope, `q` has every Relation method but not the Model’s other scopes. Share logic between scopes with a plain function.

:::note
A scope whose body names its own class needs its type written out: `static roots: ScopeStatic<[]> = this.scope(…)`.
:::

An [enum](/enums#declaring-enums) gives its Model a scope for each name, and a `not…` scope: `Ticket.open()` and `Ticket.notOpen()`. Conditions take its names, one or a list: `Ticket.where({ status: ["open", "in_progress"] })`.

## Narrowing every query

Declare a default scope in the class’s `static {}` block, as `Product` does, to narrow every query on the Model:

```ts
import { Product } from "./models/product";

const listed = await Product.order({ name: "asc" }).toArray(); // available products only
const draft = Product.build({ name: "Pen" }); // isAvailable: true, from the default scope
```

- New records take its conditions’ values.
- It applies to everything that queries the Model: `find`, `count`, `updateAll`, `deleteAll`, its scopes, and associations that read it, preloads included.
- `reload`, uniqueness validation, and a record’s own `save` and `destroy` ignore it, since they work by primary key.
- `insert`, `insertAll`, `upsert`, and `upsertAll` write its conditions’ values over the values you give. `build` and `create` use the values you give.
- Several default scopes all apply. A subclass adds its own to its parent’s.
- An order in a default scope is the Relation’s order. `reorder` replaces it.
- `rewhere` replaces its condition on an attribute, and [`unscope`](/conditions#replacing-conditions) drops its parts.

## Leaving the default scope out

Start from `unscoped()` to leave the default scope out:

```ts
import { Product } from "./models/product";

const everything = await Product.unscoped().toArray(); // available or not
```

`unscoped()` is a Model static only. With a database you hold, call it inside [`withDatabase`](/connecting#using-the-requests-database).

:::warning[Default scopes hide records from associations too]
A default scope that hides soft-deleted records also hides them from every association. A comment on a deleted post then fails to save with “Post must exist”. And `dependent: "destroy"` leaves a deleted post’s comments behind. An upsert that updates a deleted post writes `deletedAt: null`, which brings the post back. It does this even when you pass a `deletedAt`. For soft deletes, use a named scope, such as `static kept = this.scope((q) => q.where({ deletedAt: null }))`, and call `Post.kept()` where deleted posts should stay hidden.
:::

> **Compared with Rails**
>
> `this.defaultScope` is Rails’ `default_scope`, applied the same way. `unscoped()` is only a static: Rails also has it on a Relation, where `Post.where(…).unscoped` drops every condition, the Relation’s own included. Rails’ block form, `Post.unscoped { … }`, and `all_queries: true` aren’t here.
