Skip to main content

How Filter Works

This page describes the filter format used with totalumClient.crud.query().

If you are using deprecated methods like getRecords, getNestedData, getManyToManyReferencesRecords, or nestedFilter, see How Filter Works (Deprecated) for the old filter format.

Basic structure​

const result = await totalumClient.crud.query('your_table', {
    _filter: {
        property_name: "value"
    },
    _sort: { property_name: "asc" },   // "asc" or "desc"
    _limit: 50,
    _offset: 0,
});

How pagination works​

Use _limit to set the number of items per page and _offset to skip items. Default limit is 100.

// Page 1: items 0-49
{ _limit: 50, _offset: 0 }

// Page 2: items 50-99
{ _limit: 50, _offset: 50 }

How sorting works​

Use _sort with "asc" (ascending) or "desc" (descending):

{ _sort: { name: "asc" } }
{ _sort: { created_at: "desc" } }

Filter operators​

Filter by exact value (string, number, or date)​

{ _filter: { name: "John" } }
{ _filter: { age: 25 } }
{ _filter: { date: "2024-01-01T00:00:00.000Z" } }

Filter by partial string (regex)​

{ _filter: { name: { regex: "john", options: "i" } } }
// options: "i" = case insensitive

Filter by number range​

{ _filter: { price: { gte: 1, lte: 10 } } }

Filter by date range​

{ _filter: { date: { gte: "2024-01-01T00:00:00.000Z", lte: "2024-01-10T00:00:00.000Z" } } }

Filter by not equal to​

{ _filter: { status: { ne: "inactive" } } }

Filter by list (in / not in)​

{ _filter: { status: { in: ["active", "pending"] } } }
{ _filter: { status: { nin: ["deleted"] } } }

Filter by contains, startsWith, endsWith​

{ _filter: { name: { contains: "john" } } }
{ _filter: { name: { startsWith: "jo" } } }
{ _filter: { email: { endsWith: "@gmail.com" } } }

Filter by a table relation (One to Many)​

Use Case:

Imagine you have 2 tables, client and order. Each client can have multiple orders. You want to get all the orders of a specific client.

const result = await totalumClient.crud.query('order', {
    _filter: { client: "the_client_id" }
});

Combining filters​

AND condition (all must match)​

All properties at the top level of _filter are combined with AND:

{
    _filter: {
        status: "active",
        country: "Spain",
        age: { gte: 18 },
        name: { regex: "john", options: "i" },
        role: { ne: "admin" }
    }
}

OR condition (at least one must match)​

Use _or to combine conditions with OR:

{
    _filter: {
        _or: [
            { status: "active" },
            { status: "pending" },
            { age: { gte: 65 } }
        ]
    }
}

AND + OR combined​

{
    _filter: {
        country: "Spain",               // AND this
        _or: [
            { status: "active" },        // OR this
            { status: "pending" }         // OR this
        ]
    }
}

This filter will return the items where country is "Spain" AND status is "active" or "pending".

Full example​

const result = await totalumClient.crud.query('product', {
    _filter: {
        category: "electronics",
        price: { gte: 10, lte: 500 },
        name: { regex: "phone", options: "i" },
    },
    _sort: { price: "asc" },
    _limit: 20,
    _offset: 0,
});
const items = result.data;