Filters API - NocoDB

Overview

Filters allow you to define conditions for displaying records in views. NocoDB supports complex filter logic with groups, multiple conditions, and various comparison operators.

Comparison Operators

Filters support a wide range of comparison operators:

Equality & Comparison

eq - Equals
neq - Not equals
gt - Greater than
gte - Greater than or equal
lt - Less than
lte - Less than or equal

Text Operators

like - Contains
nlike - Does not contain

List Operators

in - Is in list
allof - All of (multi-select)
anyof - Any of (multi-select)
nallof - Not all of
nanyof - Not any of

Null Operators

null - Is null
notnull - Is not null
empty - Is empty
notempty - Is not empty
blank - Is blank (null or empty)
notblank - Is not blank

Boolean Operators

checked - Is checked (checkbox)
notchecked - Is not checked

Special Operators

is - Is (exact match)
isnot - Is not
btw - Between
nbtw - Not between
isWithin - Is within (date/time)

Comparison Sub-Operators

For date/time filters, use sub-operators:

today, tomorrow, yesterday
oneWeekAgo, oneWeekFromNow
oneMonthAgo, oneMonthFromNow
daysAgo, daysFromNow
exactDate
pastWeek, pastMonth, pastYear
nextWeek, nextMonth, nextYear
nextNumberOfDays, pastNumberOfDays

List View Filters

Retrieve all filters for a specific view.

curl -X GET "https://app.nocodb.com/api/v1/db/meta/views/{viewId}/filters" \
  -H "xc-token: YOUR_API_TOKEN"

Path Parameters

viewId

string

required

Unique identifier for the view

Query Parameters

includeAllFilters

boolean

Include all filters, including nested group filters

Response

list

array

Array of filter objects

list[].id

string

Unique filter identifier

list[].fk_view_id

string

Foreign key to the view

list[].fk_column_id

string

Foreign key to the column being filtered

list[].comparison_op

string

Comparison operator (e.g., “eq”, “like”, “gt”)

list[].value

any

Filter value to compare against

list[].logical_op

string

Logical operator: and, or, or not

list[].is_group

boolean

Whether this filter is a group

list[].children

array

Nested filters (only for groups)

Create Filter

Add a new filter to a view.

curl -X POST "https://app.nocodb.com/api/v1/db/meta/views/{viewId}/filters" \
  -H "xc-token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "comparison_op": "eq",
    "fk_column_id": "cl_d7ah9n2qfupgys",
    "value": "Active",
    "logical_op": "and"
  }'

Path Parameters

viewId

string

required

Unique identifier for the view

Request Body

fk_column_id

string

required

Column ID to filter on

comparison_op

string

required

Comparison operator (see Comparison Operators)

value

any

Value to compare against (can be null for some operators)

logical_op

string

Logical operator: and (default), or, or not

comparison_sub_op

string

Sub-operator for date/time filters (see Comparison Sub-Operators)

fk_parent_id

string

Parent filter group ID (for nested filters)

is_group

boolean

Whether this filter is a group (default: false)

Example: Text Filter

curl -X POST "https://app.nocodb.com/api/v1/db/meta/views/vw_abc123/filters" \
  -H "xc-token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "fk_column_id": "cl_name123",
    "comparison_op": "like",
    "value": "John",
    "logical_op": "and"
  }'

Example: Date Filter with Sub-Operator

curl -X POST "https://app.nocodb.com/api/v1/db/meta/views/vw_abc123/filters" \
  -H "xc-token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "fk_column_id": "cl_created_at",
    "comparison_op": "isWithin",
    "comparison_sub_op": "pastWeek",
    "logical_op": "and"
  }'

Example: Number Filter

curl -X POST "https://app.nocodb.com/api/v1/db/meta/views/vw_abc123/filters" \
  -H "xc-token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "fk_column_id": "cl_price",
    "comparison_op": "gte",
    "value": 100,
    "logical_op": "and"
  }'

Get Filter

Retrieve a specific filter by its ID.

curl -X GET "https://app.nocodb.com/api/v1/db/meta/filters/{filterId}" \
  -H "xc-token: YOUR_API_TOKEN"

Path Parameters

filterId

string

required

Unique identifier for the filter

Update Filter

Modify an existing filter.

curl -X PATCH "https://app.nocodb.com/api/v1/db/meta/filters/{filterId}" \
  -H "xc-token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "comparison_op": "neq",
    "value": "Inactive"
  }'

Path Parameters

filterId

string

required

Unique identifier for the filter

Request Body

Accepts the same parameters as Create Filter. Only include fields you want to update.

comparison_op

string

New comparison operator

value

any

New filter value

logical_op

string

New logical operator

enabled

boolean

Enable or disable the filter (disabled filters are skipped)

Delete Filter

Remove a filter from a view.

curl -X DELETE "https://app.nocodb.com/api/v1/db/meta/filters/{filterId}" \
  -H "xc-token: YOUR_API_TOKEN"

Path Parameters

filterId

string

required

Unique identifier for the filter to delete

Filter Groups

Filter groups allow you to create complex filter logic with nested conditions.

curl -X POST "https://app.nocodb.com/api/v1/db/meta/views/{viewId}/filters" \
  -H "xc-token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "is_group": true,
    "logical_op": "or"
  }'

is_group

boolean

required

Set to true to create a filter group

logical_op

string

required

Logical operator for combining filters in the group: and or or

Add Filter to Group

Once you have a group, add filters to it using the fk_parent_id:

curl -X POST "https://app.nocodb.com/api/v1/db/meta/views/{viewId}/filters" \
  -H "xc-token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "fk_parent_id": "fi_group123",
    "fk_column_id": "cl_status",
    "comparison_op": "eq",
    "value": "Active",
    "logical_op": "and"
  }'

List Group Children

Retrieve all filters within a group.

curl -X GET "https://app.nocodb.com/api/v1/db/meta/filters/{filterGroupId}/children" \
  -H "xc-token: YOUR_API_TOKEN"

filterGroupId

string

required

Unique identifier for the filter group

Example: Complex Filter Logic

Create a filter group with OR logic for multiple conditions:

# 1. Create the group
curl -X POST "https://app.nocodb.com/api/v1/db/meta/views/vw_abc123/filters" \
  -H "xc-token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"is_group": true, "logical_op": "or"}'

# Response: {"id": "fi_group789"}

# 2. Add first condition to group
curl -X POST "https://app.nocodb.com/api/v1/db/meta/views/vw_abc123/filters" \
  -H "xc-token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "fk_parent_id": "fi_group789",
    "fk_column_id": "cl_status",
    "comparison_op": "eq",
    "value": "Active"
  }'

# 3. Add second condition to group
curl -X POST "https://app.nocodb.com/api/v1/db/meta/views/vw_abc123/filters" \
  -H "xc-token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "fk_parent_id": "fi_group789",
    "fk_column_id": "cl_priority",
    "comparison_op": "eq",
    "value": "High"
  }'

This creates: (Status = "Active" OR Priority = "High")

Hook Filters

Filters can also be applied to webhooks to control when they trigger.

Create Hook Filter

curl -X POST "https://app.nocodb.com/api/v1/db/meta/hooks/{hookId}/filters" \
  -H "xc-token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "comparison_op": "eq",
    "fk_column_id": "cl_status",
    "value": "Completed",
    "logical_op": "and"
  }'

hookId

string

required

Unique identifier for the webhook

List Hook Filters

curl -X GET "https://app.nocodb.com/api/v1/db/meta/hooks/{hookId}/filters" \
  -H "xc-token: YOUR_API_TOKEN"

Logical Operators

Combine multiple filters using logical operators:

AND Logic

{
  "logical_op": "and"
}

All conditions must be true.

OR Logic

{
  "logical_op": "or"
}

At least one condition must be true.

NOT Logic

{
  "logical_op": "not"
}

Negates the condition.

Filter Best Practices

Performance: Keep filter conditions simple and indexed when possible. Complex nested groups can impact query performance.

Order: Filters are evaluated in order. Place more restrictive filters first to improve performance.

Testing: Use the enabled field to temporarily disable filters without deleting them.

Filter changes take effect immediately and apply to all users viewing the same view (unless using personal lock type).

​Overview

​Comparison Operators

​Equality & Comparison

​Text Operators

​List Operators

​Null Operators

​Boolean Operators

​Special Operators

​Comparison Sub-Operators

​List View Filters

​Path Parameters

​Query Parameters

​Response

​Create Filter

​Path Parameters

​Request Body

​Example: Text Filter

​Example: Date Filter with Sub-Operator

​Example: Number Filter

​Get Filter

​Path Parameters

​Update Filter

​Path Parameters

​Request Body

​Delete Filter

​Path Parameters

​Filter Groups

​Create Filter Group

​Add Filter to Group

​List Group Children

​Example: Complex Filter Logic

​Hook Filters

​Create Hook Filter

​List Hook Filters

​Logical Operators

​AND Logic

​OR Logic

​NOT Logic

​Filter Best Practices

Overview

Comparison Operators

Equality & Comparison

Text Operators

List Operators

Null Operators

Boolean Operators

Special Operators

Comparison Sub-Operators

List View Filters

Path Parameters

Query Parameters

Response

Create Filter

Path Parameters

Request Body

Example: Text Filter

Example: Date Filter with Sub-Operator

Example: Number Filter

Get Filter

Path Parameters

Update Filter

Path Parameters

Request Body

Delete Filter

Path Parameters

Filter Groups

Create Filter Group

Add Filter to Group

List Group Children

Example: Complex Filter Logic

Hook Filters

Create Hook Filter

List Hook Filters

Logical Operators

AND Logic

OR Logic

NOT Logic

Filter Best Practices