Filtering Records

Filtering Records - Simple and Advanced

Learn how to filter records using the Tadabase REST API, from simple single-condition filters to complex nested queries with multiple conditions.

HTTP Methods for Filtering

You can filter records using either GET or POST methods:

Simple Filter (Single Condition)

Filter records with a single condition.

POST Request (Recommended)

POST /api/v1/data-tables/{tableId}/records

Headers:
  X-Tadabase-App-id: your_app_id
  X-Tadabase-App-Key: your_app_key
  X-Tadabase-App-Secret: your_app_secret
  Content-Type: application/json

Body:
{
  "filters": {
    "condition": "AND",
    "items": [
      {
        "field_id": "status",
        "operator": "is",
        "val": "Active"
      }
    ]
  },
  "page": 1,
  "limit": 50
}

This returns all records where status equals "Active".

GET Request (Alternative)

GET /api/v1/data-tables/{tableId}/records?filters[items][0][field_id]=status&filters[items][0][operator]=is&filters[items][0][val]=Active

Multiple Conditions (AND)

Filter records that match ALL conditions.

POST /api/v1/data-tables/{tableId}/records

Content-Type: application/json

{
  "filters": {
    "condition": "AND",
    "items": [
      {
        "field_id": "status",
        "operator": "is",
        "val": "Active"
      },
      {
        "field_id": "age",
        "operator": "higher than",
        "val": 25
      },
      {
        "field_id": "email",
        "operator": "contains",
        "val": "@example.com"
      }
    ]
  }
}

Returns records where:

• Status is "Active" AND
• Age is greater than 25 AND
• Email contains "@example.com"

Multiple Conditions (OR)

Filter records that match ANY condition.

{
  "filters": {
    "condition": "any",
    "items": [
      {
        "field_id": "status",
        "operator": "is",
        "val": "Active"
      },
      {
        "field_id": "status",
        "operator": "is",
        "val": "Pending"
      }
    ]
  }
}

Returns records where status is either "Active" OR "Pending".

Complex Nested Filters

Combine AND and OR logic using nested groups with the child array.

{
  "filters": {
    "condition": "AND",
    "items": [
      {
        "field_id": "status",
        "operator": "is",
        "val": "Active"
      }
    ],
    "child": [
      {
        "condition": "any",
        "items": [
          {
            "field_id": "email",
            "operator": "contains",
            "val": "@example.com"
          },
          {
            "field_id": "email",
            "operator": "contains",
            "val": "@test.com"
          }
        ]
      }
    ]
  }
}

Returns records where:

• Status is "Active" AND
• (Email contains "@example.com" OR Email contains "@test.com")

Complete Operator Reference

Text Field Operators

Numeric Field Operators

{
  "filters": {
    "condition": "AND",
    "items": [
      {
        "field_id": "price",
        "operator": "higher than or equal to",
        "val": 100
      },
      {
        "field_id": "price",
        "operator": "lower than or equal to",
        "val": 1000
      }
    ]
  }
}

Date and Date/Time Field Operators

Boolean and Checkbox Operators

User and Authentication Operators

These operators require bearer token authentication to work correctly.

Join (Connection) Field Operators

Field Identifiers

The field_id parameter accepts either:

• Field IDs: The internal field ID like field_40
• Field Slugs: The slug name assigned to the field

Sub-Field Syntax

For complex field types (Name, Address), reference sub-fields using a hyphen:

{
  "field_id": "full_name-first",
  "operator": "contains",
  "val": "John"
}

Common sub-fields:

• Name: -title, -first, -middle, -last
• Address: -address, -address2, -city, -state, -zip, -country

Date Filtering Examples

Exact Date

{
  "field_id": "created_at",
  "operator": "is",
  "val": "2024-01-27"
}

Date Range (Between Two Dates)

Use two conditions with AND logic:

{
  "filters": {
    "condition": "AND",
    "items": [
      {
        "field_id": "created_at",
        "operator": "is on or after",
        "val": "2024-01-01"
      },
      {
        "field_id": "created_at",
        "operator": "is on or before",
        "val": "2024-01-31"
      }
    ]
  }
}

After Specific Date

{
  "field_id": "created_at",
  "operator": "is after",
  "val": "2024-01-01"
}

Before Specific Date

{
  "field_id": "created_at",
  "operator": "is before",
  "val": "2024-12-31"
}

Important Warnings

Debugging Filter Issues

If your filters aren't working as expected:

1. Verify field IDs: Use GET /api/v1/data-tables/{tableId}/fields to list all valid field IDs
2. Check parameter names: Use operator (not condition) in filter items
3. Check value parameter: Use val (not value) for filter values
4. Ensure field exists: The field must actually exist in the data table
5. Use field ID or slug: Not the display name
6. Test simple first: Start with a single-filter query before adding complexity
7. Check response: Look at total_items to see if filters are working

Complete Working Examples

Example 1: Active customers from specific domains

POST /api/v1/data-tables/lGArg7rmR6/records

Content-Type: application/json

{
  "filters": {
    "condition": "AND",
    "items": [
      {
        "field_id": "status",
        "operator": "is",
        "val": "Active"
      }
    ],
    "child": [
      {
        "condition": "any",
        "items": [
          {
            "field_id": "email",
            "operator": "ends with",
            "val": "@example.com"
          },
          {
            "field_id": "email",
            "operator": "ends with",
            "val": "@test.com"
          }
        ]
      }
    ]
  },
  "limit": 50,
  "order": "created_at",
  "order_by": "desc"
}

Example 2: Orders in price range with recent dates

{
  "filters": {
    "condition": "AND",
    "items": [
      {
        "field_id": "total_amount",
        "operator": "higher than or equal to",
        "val": 100
      },
      {
        "field_id": "total_amount",
        "operator": "lower than or equal to",
        "val": 1000
      },
      {
        "field_id": "order_date",
        "operator": "is on or after",
        "val": "2024-01-01"
      },
      {
        "field_id": "status",
        "operator": "is not",
        "val": "Cancelled"
      }
    ]
  }
}

JavaScript Example

async function filterRecords(tableId, filters) {
  const response = await fetch(
    `https://api.tadabase.io/api/v1/data-tables/${tableId}/records`,
    {
      method: 'POST',
      headers: {
        'X-Tadabase-App-id': 'your_app_id',
        'X-Tadabase-App-Key': 'your_app_key',
        'X-Tadabase-App-Secret': 'your_app_secret',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ filters })
    }
  );

  const data = await response.json();
  return data.items;
}

// Usage
const filters = {
  condition: "AND",
  items: [
    {
      field_id: "status",
      operator: "is",
      val: "Active"
    },
    {
      field_id: "age",
      operator: "higher than",
      val: 18
    }
  ]
};

const records = await filterRecords('lGArg7rmR6', filters);
console.log(records);

Next Steps

Master sorting and pagination to complete your data retrieval skills:

→ Sorting and Pagination

Learn how to sort results and efficiently paginate through large datasets.