Filtering

When you use a field as an input to a list action, Keel generates a structured query input for that field. Instead of passing a plain value, you pass an object with one or more operators that describe how to filter.

model Product {
  fields {
    name Text
    price Decimal
    releaseDate Date
  }
  actions {
    list listProducts(name?, price?, releaseDate?)
  }
}

// POST /api/json/listProducts
{
  "where": {
    "name": { "contains": "Widget" },
    "price": { "greaterThan": 10.00 },
    "releaseDate": { "after": "2024-01-01" }
  }
}

Each field type has its own set of available operators. All operators are optional, and when multiple are provided they are AND'd together. The full set of operators for each type is documented below.

Text

Text fields (including Markdown) support exact matching, partial matching, and set membership.

// Find products with "Pro" in the name, excluding a specific one
{
  "name": {
    "contains": "Pro",
    "notEquals": "Pro Max Legacy"
  }
}

Number

Number fields support exact matching, comparison, and set membership.

// Find products with stock between 10 and 100
{
  "stock": {
    "greaterThanOrEquals": 10,
    "lessThanOrEquals": 100
  }
}

Decimal

Decimal fields support the same operators as Number.

Boolean

Boolean fields support equality checks only.

// Find all active products
{
  "isActive": {
    "equals": true
  }
}

Date

Date fields support exact matching, range comparisons, and relative date expressions. Values are in ISO 8601 format (YYYY-MM-DD).

// Find orders placed in Q1 2024
{
  "orderDate": {
    "onOrAfter": "2024-01-01",
    "before": "2024-04-01"
  }
}

Relative date expressions

The beforeRelative, afterRelative, and equalsRelative operators accept a string expression in the following format:

    attribute   value  complete          period
       v          v       v                 v
{this/next/last} {x}? {complete}? {minute/hour/day/week/month/year}

There are also a few shorthands:

Timestamp

Timestamp fields support range comparisons and relative expressions. Values are in ISO 8601 format with time (YYYY-MM-DDTHH:mm:ss.sssZ).

// Find records created in the last 7 days
{
  "createdAt": {
    "afterRelative": "last 7 days"
  }
}

Duration

Duration fields support exact matching and comparisons. Values are in ISO 8601 duration format (opens in a new tab) (e.g. P1D for one day, PT2H30M for two hours and thirty minutes).

// Find tasks with estimated time under 2 hours
{
  "estimatedTime": {
    "lessThan": "PT2H"
  }
}

ID

ID fields support exact matching and set membership.

Enum

Enum fields support exact matching and set membership. Values are the enum member names as strings.

enum Status {
  Draft
  Published
  Archived
}
 
model Post {
  fields {
    status Status
  }
  actions {
    list listPosts(status?)
  }
}

// Find posts that are either Draft or Published
{
  "where": {
    "status": {
      "oneOf": ["Draft", "Published"]
    }
  }
}

Null checks

For fields that are optional in your schema, the equals and notEquals operators accept null. This lets you filter for records where a field has or has not been set.

model Task {
  fields {
    completedAt Timestamp?
  }
  actions {
    list listTasks(completedAt?)
  }
}

{
  "where": {
    "completedAt": {
      "equals": null
    }
  }
}

Array fields

When a field is an array type (e.g. Text[], Number[]), the query input has a different structure. At the top level you can check if the entire array exactly matches or doesn't match a set of values. You can also use any and all to filter based on individual elements.

The operators available inside any and all are the same as those for the corresponding scalar type, except that equals and notEquals inside any/all are not nullable, and oneOf is not available.

model Product {
  fields {
    tags Text[]
    scores Number[]
  }
  actions {
    list listProducts(tags?, scores?)
  }
}

// Find products where any tag contains "sale"
// and all scores are greater than 80
{
  "where": {
    "tags": {
      "any": {
        "equals": "sale"
      }
    },
    "scores": {
      "all": {
        "greaterThan": 80
      }
    }
  }
}

Non-filterable types

The following field types cannot be used as inputs to list actions and do not have query inputs:

• Secret — encrypted fields
• Password — hashed fields
• File — binary file fields
• Vector — embedding vectors