Query & Filtering

Master advanced query techniques including filtering, searching, sorting, and pagination with powerful operators across all platforms.

Cocobase provides a comprehensive query system with support for complex filters, logical operators, and efficient pagination.

Overview

Build powerful queries with:

Comparison operators - Equal, not equal, greater than, less than
String operators - Contains, starts with, ends with, regex
List operators - In, not in
Logical operators - AND, OR, NOT combinations
Sorting - Order results by any field
Pagination - Limit and offset for large datasets
Query builder - Fluent, chainable API

Basic Filtering

Filter documents by field values with automatic type handling.

Equality Filters

JavaScript
Dart
Go
Python
HTTP

import { Cocobase } from 'cocobase';

const db = new Cocobase({ apiKey: 'your-api-key' });

// Simple equality
const activeUsers = await db.listDocuments('users', {
  filters: { status: 'active' }
});

// Multiple filters (AND logic)
const specificUsers = await db.listDocuments('users', {
  filters: {
    status: 'active',
    role: 'admin',
    verified: true
  }
});

import 'package:cocobase/cocobase.dart';

final db = Cocobase(CocobaseConfig(apiKey: 'your-api-key'));

// Simple equality
final activeUsers = await db.listDocuments('users', filters: {
  'status': 'active',
});

// Multiple filters (AND logic)
final specificUsers = await db.listDocuments('users', filters: {
  'status': 'active',
  'role': 'admin',
  'verified': true,
});

package main

import (
    "context"
    "github.com/lordace-coder/cocobase-go/cocobase"
)

func main() {
    client := cocobase.NewClient(cocobase.Config{
        APIKey: "your-api-key",
    })

    ctx := context.Background()

    // Simple equality
    query := cocobase.NewQuery().Where("status", "active")
    activeUsers, _ := client.ListDocuments(ctx, "users", query)

    // Multiple filters (AND logic)
    query = cocobase.NewQuery().
        Where("status", "active").
        Where("role", "admin").
        Where("verified", true)
    specificUsers, _ := client.ListDocuments(ctx, "users", query)
}

import requests

API_KEY = 'your-api-key'
BASE_URL = 'https://api.cocobase.cc'
headers = {'X-API-Key': API_KEY}

# Simple equality
params = {'status': 'active'}
response = requests.get(
    f'{BASE_URL}/collections/users/documents',
    headers=headers,
    params=params
)

# Multiple filters (AND logic)
params = {
    'status': 'active',
    'role': 'admin',
    'verified': 'true'
}
response = requests.get(
    f'{BASE_URL}/collections/users/documents',
    headers=headers,
    params=params
)

# Simple equality
curl "https://api.cocobase.cc/collections/users/documents?status=active" \
  -H "X-API-Key: your-api-key"

# Multiple filters (AND logic)
curl "https://api.cocobase.cc/collections/users/documents?status=active&role=admin&verified=true" \
  -H "X-API-Key: your-api-key"

Query Operators

Comparison Operators

Filter by numeric ranges and comparisons.

JavaScript
Dart
Go
Python
HTTP

// Greater than
const seniors = await db.listDocuments('users', {
  filters: { age_gt: 65 }
});

// Greater than or equal
const adults = await db.listDocuments('users', {
  filters: { age_gte: 18 }
});

// Less than
const minors = await db.listDocuments('users', {
  filters: { age_lt: 18 }
});

// Less than or equal
const eligible = await db.listDocuments('users', {
  filters: { age_lte: 65 }
});

// Not equal
const nonAdmins = await db.listDocuments('users', {
  filters: { role_ne: 'admin' }
});

// Between (range)
const midAge = await db.listDocuments('users', {
  filters: {
    age_gte: 25,
    age_lte: 40
  }
});

// Greater than
final seniors = await db.listDocuments('users', filters: {
  'age__gt': 65,
});

// Greater than or equal
final adults = await db.listDocuments('users',
  queryBuilder: QueryBuilder().whereGreaterThanOrEqual('age', 18)
);

// Less than
final minors = await db.listDocuments('users',
  queryBuilder: QueryBuilder().whereLessThan('age', 18)
);

// Less than or equal
final eligible = await db.listDocuments('users',
  queryBuilder: QueryBuilder().whereLessThanOrEqual('age', 65)
);

// Not equal
final nonAdmins = await db.listDocuments('users',
  queryBuilder: QueryBuilder().whereNotEqual('role', 'admin')
);

// Between (range)
final midAge = await db.listDocuments('users', filters: {
  'age__gte': 25,
  'age__lte': 40,
});

// Greater than
query := cocobase.NewQuery().GreaterThan("age", 65)
seniors, _ := client.ListDocuments(ctx, "users", query)

// Greater than or equal
query = cocobase.NewQuery().GreaterThanOrEqual("age", 18)
adults, _ := client.ListDocuments(ctx, "users", query)

// Less than
query = cocobase.NewQuery().LessThan("age", 18)
minors, _ := client.ListDocuments(ctx, "users", query)

// Less than or equal
query = cocobase.NewQuery().LessThanOrEqual("age", 65)
eligible, _ := client.ListDocuments(ctx, "users", query)

// Not equal
query = cocobase.NewQuery().NotEquals("role", "admin")
nonAdmins, _ := client.ListDocuments(ctx, "users", query)

// Between (range)
query = cocobase.NewQuery().Between("age", 25, 40)
midAge, _ := client.ListDocuments(ctx, "users", query)

# Greater than
params = {'age_gt': 65}
seniors = requests.get(
    f'{BASE_URL}/collections/users/documents',
    headers=headers,
    params=params
).json()

# Greater than or equal
params = {'age_gte': 18}
adults = requests.get(
    f'{BASE_URL}/collections/users/documents',
    headers=headers,
    params=params
).json()

# Less than
params = {'age_lt': 18}
minors = requests.get(
    f'{BASE_URL}/collections/users/documents',
    headers=headers,
    params=params
).json()

# Less than or equal
params = {'age_lte': 65}
eligible = requests.get(
    f'{BASE_URL}/collections/users/documents',
    headers=headers,
    params=params
).json()

# Not equal
params = {'role_ne': 'admin'}
non_admins = requests.get(
    f'{BASE_URL}/collections/users/documents',
    headers=headers,
    params=params
).json()

# Between (range)
params = {'age_gte': 25, 'age_lte': 40}
mid_age = requests.get(
    f'{BASE_URL}/collections/users/documents',
    headers=headers,
    params=params
).json()

# Greater than
curl "https://api.cocobase.cc/collections/users/documents?age_gt=65" \
  -H "X-API-Key: your-api-key"

# Greater than or equal
curl "https://api.cocobase.cc/collections/users/documents?age_gte=18" \
  -H "X-API-Key: your-api-key"

# Less than
curl "https://api.cocobase.cc/collections/users/documents?age_lt=18" \
  -H "X-API-Key: your-api-key"

# Less than or equal
curl "https://api.cocobase.cc/collections/users/documents?age_lte=65" \
  -H "X-API-Key: your-api-key"

# Not equal
curl "https://api.cocobase.cc/collections/users/documents?role_ne=admin" \
  -H "X-API-Key: your-api-key"

# Between (range)
curl "https://api.cocobase.cc/collections/users/documents?age_gte=25&age_lte=40" \
  -H "X-API-Key: your-api-key"

String Operators

Search and filter text fields with powerful string operations.

JavaScript
Dart
Go
Python
HTTP

// Contains (case-insensitive)
const johns = await db.listDocuments('users', {
  filters: { name_contains: 'john' }
});

// Starts with
const admins = await db.listDocuments('users', {
  filters: { email_startswith: 'admin' }
});

// Ends with
const gmailUsers = await db.listDocuments('users', {
  filters: { email_endswith: '@gmail.com' }
});

// Multiple string filters
const specific = await db.listDocuments('users', {
  filters: {
    name_contains: 'john',
    email_endswith: '@example.com'
  }
});

// Contains (case-insensitive)
final johns = await db.listDocuments('users',
  queryBuilder: QueryBuilder().whereContains('name', 'john')
);

// Starts with
final admins = await db.listDocuments('users',
  queryBuilder: QueryBuilder().whereStartsWith('email', 'admin')
);

// Ends with
final gmailUsers = await db.listDocuments('users',
  queryBuilder: QueryBuilder().whereEndsWith('email', '@gmail.com')
);

// Multiple string filters
final specific = await db.listDocuments('users',
  queryBuilder: QueryBuilder()
    .whereContains('name', 'john')
    .whereEndsWith('email', '@example.com')
);

// Contains (case-insensitive)
query := cocobase.NewQuery().Contains("name", "john")
johns, _ := client.ListDocuments(ctx, "users", query)

// Starts with
query = cocobase.NewQuery().StartsWith("email", "admin")
admins, _ := client.ListDocuments(ctx, "users", query)

// Ends with
query = cocobase.NewQuery().EndsWith("email", "@gmail.com")
gmailUsers, _ := client.ListDocuments(ctx, "users", query)

// Multiple string filters
query = cocobase.NewQuery().
    Contains("name", "john").
    EndsWith("email", "@example.com")
specific, _ := client.ListDocuments(ctx, "users", query)

# Contains (case-insensitive)
params = {'name_contains': 'john'}
johns = requests.get(
    f'{BASE_URL}/collections/users/documents',
    headers=headers,
    params=params
).json()

# Starts with
params = {'email_startswith': 'admin'}
admins = requests.get(
    f'{BASE_URL}/collections/users/documents',
    headers=headers,
    params=params
).json()

# Ends with
params = {'email_endswith': '@gmail.com'}
gmail_users = requests.get(
    f'{BASE_URL}/collections/users/documents',
    headers=headers,
    params=params
).json()

# Multiple string filters
params = {
    'name_contains': 'john',
    'email_endswith': '@example.com'
}
specific = requests.get(
    f'{BASE_URL}/collections/users/documents',
    headers=headers,
    params=params
).json()

# Contains (case-insensitive)
curl "https://api.cocobase.cc/collections/users/documents?name_contains=john" \
  -H "X-API-Key: your-api-key"

# Starts with
curl "https://api.cocobase.cc/collections/users/documents?email_startswith=admin" \
  -H "X-API-Key: your-api-key"

# Ends with
curl "https://api.cocobase.cc/collections/users/documents?email_endswith=@gmail.com" \
  -H "X-API-Key: your-api-key"

# Multiple string filters
curl "https://api.cocobase.cc/collections/users/documents?name_contains=john&email_endswith=@example.com" \
  -H "X-API-Key: your-api-key"

List Operators

Filter by multiple possible values.

JavaScript
Dart
Go
Python
HTTP

// In - match any of the values
const staff = await db.listDocuments('users', {
  filters: { role_in: 'admin,moderator,support' }
});

// Not in - exclude values
const active = await db.listDocuments('users', {
  filters: { status_notin: 'deleted,banned,suspended' }
});

// Array contains (for array fields)
const followers = await db.listDocuments('users', {
  filters: { 'followers_array_contains': 'user_123' }
});

// In - match any of the values
final staff = await db.listDocuments('users',
  queryBuilder: QueryBuilder().whereIn('role', 'admin,moderator,support')
);

// Not in - exclude values
final active = await db.listDocuments('users',
  queryBuilder: QueryBuilder().whereNotIn('status', 'deleted,banned,suspended')
);

// Using filter map
final staffAlt = await db.listDocuments('users', filters: {
  'role__in': 'admin,moderator,support',
});

// In - match any of the values
query := cocobase.NewQuery().In("role", "admin", "moderator", "support")
staff, _ := client.ListDocuments(ctx, "users", query)

// Not in - exclude values
query = cocobase.NewQuery().NotIn("status", "deleted", "banned", "suspended")
active, _ := client.ListDocuments(ctx, "users", query)

# In - match any of the values
params = {'role_in': 'admin,moderator,support'}
staff = requests.get(
    f'{BASE_URL}/collections/users/documents',
    headers=headers,
    params=params
).json()

# Not in - exclude values
params = {'status_notin': 'deleted,banned,suspended'}
active = requests.get(
    f'{BASE_URL}/collections/users/documents',
    headers=headers,
    params=params
).json()

# Array contains (for array fields)
params = {'followers_array_contains': 'user_123'}
followers = requests.get(
    f'{BASE_URL}/collections/users/documents',
    headers=headers,
    params=params
).json()

# In - match any of the values
curl "https://api.cocobase.cc/collections/users/documents?role_in=admin,moderator,support" \
  -H "X-API-Key: your-api-key"

# Not in - exclude values
curl "https://api.cocobase.cc/collections/users/documents?status_notin=deleted,banned,suspended" \
  -H "X-API-Key: your-api-key"

# Array contains
curl "https://api.cocobase.cc/collections/users/documents?followers_array_contains=user_123" \
  -H "X-API-Key: your-api-key"

Logical Operators

Combine filters with AND and OR logic for complex queries.

OR Queries

JavaScript
Dart
Go
Python
HTTP

// Simple OR - match any condition
const users = await db.listDocuments('users', {
  filters: {
    '[or]role': 'admin',
    '[or]isPremium': true
  }
});

// Multi-field search
const searchResults = await db.listDocuments('users', {
  filters: {
    'name__or__email_contains': 'john'
  }
});

// Simple OR conditions
final users = await db.listDocuments('users',
  queryBuilder: QueryBuilder()
    .or()
      .where('role', 'admin')
      .where('isPremium', true)
    .done()
);

// Multi-field search
final searchResults = await db.listDocuments('users',
  queryBuilder: QueryBuilder()
    .searchInFields(['name', 'email', 'username'], 'john')
);

// Simple OR conditions
query := cocobase.NewQuery().
    Or().
        Where("role", "admin").
        Where("isPremium", true).
    Done()
users, _ := client.ListDocuments(ctx, "users", query)

// Multi-field search
query = cocobase.NewQuery().Search("john", "name", "email", "username")
searchResults, _ := client.ListDocuments(ctx, "users", query)

# Simple OR - match any condition
params = {
    '[or]role': 'admin',
    '[or]isPremium': 'true'
}
users = requests.get(
    f'{BASE_URL}/collections/users/documents',
    headers=headers,
    params=params
).json()

# Multi-field search
params = {'name__or__email_contains': 'john'}
search_results = requests.get(
    f'{BASE_URL}/collections/users/documents',
    headers=headers,
    params=params
).json()

# Simple OR - match any condition
curl "https://api.cocobase.cc/collections/users/documents?[or]role=admin&[or]isPremium=true" \
  -H "X-API-Key: your-api-key"

# Multi-field search
curl "https://api.cocobase.cc/collections/users/documents?name__or__email_contains=john" \
  -H "X-API-Key: your-api-key"

Complex Queries (AND + OR)

JavaScript
Dart
Go
Python
HTTP

// Active users who are (admin OR moderator)
const users = await db.listDocuments('users', {
  filters: {
    status: 'active',
    'role_in': 'admin,moderator'
  }
});

// Advanced: (Premium OR Verified) AND Active
const eligibleUsers = await db.listDocuments('users', {
  filters: {
    status: 'active',
    '[or:tier]isPremium': true,
    '[or:tier]isVerified': true
  }
});

// Active users who are (admin OR moderator)
final users = await db.listDocuments('users',
  queryBuilder: QueryBuilder()
    .where('status', 'active')
    .or()
      .where('role', 'admin')
      .where('role', 'moderator')
    .done()
);

// Named OR groups
final eligibleUsers = await db.listDocuments('users',
  queryBuilder: QueryBuilder()
    .where('status', 'active')
    .orGroup('tier')
      .where('isPremium', true)
      .where('isVerified', true)
    .done()
);

// Active users who are (admin OR moderator)
query := cocobase.NewQuery().
    Where("status", "active").
    Or().
        Where("role", "admin").
        Where("role", "moderator").
    Done()
users, _ := client.ListDocuments(ctx, "users", query)

// Named OR groups
query = cocobase.NewQuery().
    Where("status", "active").
    OrGroup("tier").
        Where("isPremium", true).
        Where("isVerified", true).
    Done()
eligibleUsers, _ := client.ListDocuments(ctx, "users", query)

# Active users who are (admin OR moderator)
params = {
    'status': 'active',
    '[or]role': 'admin',
    '[or]role': 'moderator'
}
users = requests.get(
    f'{BASE_URL}/collections/users/documents',
    headers=headers,
    params=params
).json()

# Named OR groups
params = {
    'status': 'active',
    '[or:tier]isPremium': 'true',
    '[or:tier]isVerified': 'true'
}
eligible_users = requests.get(
    f'{BASE_URL}/collections/users/documents',
    headers=headers,
    params=params
).json()

# Active users who are (admin OR moderator)
curl "https://api.cocobase.cc/collections/users/documents?status=active&[or]role=admin&[or]role=moderator" \
  -H "X-API-Key: your-api-key"

# Named OR groups
curl "https://api.cocobase.cc/collections/users/documents?status=active&[or:tier]isPremium=true&[or:tier]isVerified=true" \
  -H "X-API-Key: your-api-key"

Sorting

Order results by any field in ascending or descending order.

JavaScript
Dart
Go
Python
HTTP

// Sort ascending
const byName = await db.listDocuments('users', {
  orderBy: 'name',
  order: 'asc'
});

// Sort descending
const newest = await db.listDocuments('users', {
  orderBy: 'created_at',
  order: 'desc'
});

// Multiple sorts
const sorted = await db.listDocuments('users', {
  orderBy: 'role,name',
  order: 'asc'
});

// Sort ascending
final byName = await db.listDocuments('users',
  queryBuilder: QueryBuilder().orderByAsc('name')
);

// Sort descending
final newest = await db.listDocuments('users',
  queryBuilder: QueryBuilder().orderByDesc('created_at')
);

// Helper methods
final recent = await db.listDocuments('users',
  queryBuilder: QueryBuilder().recent()  // Shortcut for orderByDesc('created_at')
);

final oldest = await db.listDocuments('users',
  queryBuilder: QueryBuilder().oldest()  // Shortcut for orderByAsc('created_at')
);

// Sort ascending
query := cocobase.NewQuery().OrderByAsc("name")
byName, _ := client.ListDocuments(ctx, "users", query)

// Sort descending
query = cocobase.NewQuery().OrderByDesc("created_at")
newest, _ := client.ListDocuments(ctx, "users", query)

// Helper methods
query = cocobase.NewQuery().Recent()  // Shortcut for newest first
recent, _ := client.ListDocuments(ctx, "users", query)

query = cocobase.NewQuery().Oldest()  // Shortcut for oldest first
oldest, _ := client.ListDocuments(ctx, "users", query)

# Sort ascending
params = {'orderBy': 'name', 'order': 'asc'}
by_name = requests.get(
    f'{BASE_URL}/collections/users/documents',
    headers=headers,
    params=params
).json()

# Sort descending
params = {'orderBy': 'created_at', 'order': 'desc'}
newest = requests.get(
    f'{BASE_URL}/collections/users/documents',
    headers=headers,
    params=params
).json()

# Sort ascending
curl "https://api.cocobase.cc/collections/users/documents?orderBy=name&order=asc" \
  -H "X-API-Key: your-api-key"

# Sort descending
curl "https://api.cocobase.cc/collections/users/documents?orderBy=created_at&order=desc" \
  -H "X-API-Key: your-api-key"

Pagination

Efficiently handle large datasets with limit and offset.

JavaScript
Dart
Go
Python
HTTP

// Get first page (10 items)
const page1 = await db.listDocuments('users', {
  limit: 10,
  offset: 0
});

// Get next page
const page2 = await db.listDocuments('users', {
  limit: 10,
  offset: 10
});

// Helper function
async function getPage(pageNumber, pageSize = 10) {
  return db.listDocuments('users', {
    limit: pageSize,
    offset: (pageNumber - 1) * pageSize
  });
}

const page3 = await getPage(3);

// Get first page (10 items)
final page1 = await db.listDocuments('users',
  queryBuilder: QueryBuilder().limit(10).offset(0)
);

// Get next page
final page2 = await db.listDocuments('users',
  queryBuilder: QueryBuilder().limit(10).offset(10)
);

// Using skip and take aliases
final page3 = await db.listDocuments('users',
  queryBuilder: QueryBuilder().take(10).skip(20)
);

// Page helper
final page4 = await db.listDocuments('users',
  queryBuilder: QueryBuilder().page(4, 10)
);

// Get first page (10 items)
query := cocobase.NewQuery().Limit(10).Offset(0)
page1, _ := client.ListDocuments(ctx, "users", query)

// Get next page
query = cocobase.NewQuery().Limit(10).Offset(10)
page2, _ := client.ListDocuments(ctx, "users", query)

// Page helper
query = cocobase.NewQuery().Page(3, 10)
page3, _ := client.ListDocuments(ctx, "users", query)

# Get first page (10 items)
params = {'limit': 10, 'offset': 0}
page1 = requests.get(
    f'{BASE_URL}/collections/users/documents',
    headers=headers,
    params=params
).json()

# Get next page
params = {'limit': 10, 'offset': 10}
page2 = requests.get(
    f'{BASE_URL}/collections/users/documents',
    headers=headers,
    params=params
).json()

# Helper function
def get_page(page_number, page_size=10):
    params = {
        'limit': page_size,
        'offset': (page_number - 1) * page_size
    }
    return requests.get(
        f'{BASE_URL}/collections/users/documents',
        headers=headers,
        params=params
    ).json()

page3 = get_page(3)

# Get first page (10 items)
curl "https://api.cocobase.cc/collections/users/documents?limit=10&offset=0" \
  -H "X-API-Key: your-api-key"

# Get next page
curl "https://api.cocobase.cc/collections/users/documents?limit=10&offset=10" \
  -H "X-API-Key: your-api-key"

# Page 3
curl "https://api.cocobase.cc/collections/users/documents?limit=10&offset=20" \
  -H "X-API-Key: your-api-key"

Query Builder Pattern

Use fluent, chainable APIs for complex queries.

JavaScript
Dart
Go
Python
HTTP

// Not directly supported in JS SDK - use filters object
const users = await db.listDocuments('users', {
  filters: {
    status: 'active',
    age_gte: 18,
    role_in: 'admin,moderator'
  },
  orderBy: 'created_at',
  order: 'desc',
  limit: 20
});

// Fluent query builder
final users = await db.listDocuments('users',
  queryBuilder: QueryBuilder()
    .where('status', 'active')
    .whereGreaterThanOrEqual('age', 18)
    .whereIn('role', 'admin,moderator')
    .orderByDesc('created_at')
    .limit(20)
);

// Complex query with OR
final results = await db.listDocuments('users',
  queryBuilder: QueryBuilder()
    .where('status', 'active')
    .or()
      .whereGreaterThan('score', 100)
      .where('isPremium', true)
    .done()
    .recent()
    .limit(50)
);

// Fluent query builder
query := cocobase.NewQuery().
    Where("status", "active").
    GreaterThanOrEqual("age", 18).
    In("role", "admin", "moderator").
    OrderByDesc("created_at").
    Limit(20)

users, _ := client.ListDocuments(ctx, "users", query)

// Complex query with OR
query = cocobase.NewQuery().
    Where("status", "active").
    Or().
        GreaterThan("score", 100).
        Where("isPremium", true).
    Done().
    Recent().
    Limit(50)

results, _ := client.ListDocuments(ctx, "users", query)

# Build query params programmatically
def build_query(**kwargs):
    params = {}
    if 'status' in kwargs:
        params['status'] = kwargs['status']
    if 'min_age' in kwargs:
        params['age_gte'] = kwargs['min_age']
    if 'roles' in kwargs:
        params['role_in'] = ','.join(kwargs['roles'])
    if 'order_by' in kwargs:
        params['orderBy'] = kwargs['order_by']
        params['order'] = kwargs.get('order', 'asc')
    if 'limit' in kwargs:
        params['limit'] = kwargs['limit']
    return params

# Usage
params = build_query(
    status='active',
    min_age=18,
    roles=['admin', 'moderator'],
    order_by='created_at',
    order='desc',
    limit=20
)

users = requests.get(
    f'{BASE_URL}/collections/users/documents',
    headers=headers,
    params=params
).json()

# All parameters in URL
curl "https://api.cocobase.cc/collections/users/documents?status=active&age_gte=18&role_in=admin,moderator&orderBy=created_at&order=desc&limit=20" \
  -H "X-API-Key: your-api-key"

Real-World Examples

E-commerce Product Search

JavaScript
Dart
Go
Python
HTTP

async function searchProducts(searchTerm, minPrice, maxPrice, category) {
  return await db.listDocuments('products', {
    filters: {
      name_contains: searchTerm,
      price_gte: minPrice,
      price_lte: maxPrice,
      category: category,
      inStock: true
    },
    orderBy: 'popularity',
    order: 'desc',
    limit: 24
  });
}

const laptops = await searchProducts('laptop', 500, 2000, 'electronics');

Future<List<Document>> searchProducts({
  required String searchTerm,
  required double minPrice,
  required double maxPrice,
  required String category,
}) async {
  return await db.listDocuments('products',
    queryBuilder: QueryBuilder()
      .whereContains('name', searchTerm)
      .whereGreaterThanOrEqual('price', minPrice)
      .whereLessThanOrEqual('price', maxPrice)
      .where('category', category)
      .where('inStock', true)
      .orderByDesc('popularity')
      .limit(24)
  );
}

final laptops = await searchProducts(
  searchTerm: 'laptop',
  minPrice: 500,
  maxPrice: 2000,
  category: 'electronics',
);

func searchProducts(client *cocobase.Client, searchTerm string, minPrice, maxPrice float64, category string) ([]cocobase.Document, error) {
    query := cocobase.NewQuery().
        Contains("name", searchTerm).
        Between("price", minPrice, maxPrice).
        Where("category", category).
        Where("inStock", true).
        OrderByDesc("popularity").
        Limit(24)

    return client.ListDocuments(ctx, "products", query)
}

laptops, _ := searchProducts(client, "laptop", 500, 2000, "electronics")

def search_products(search_term, min_price, max_price, category):
    params = {
        'name_contains': search_term,
        'price_gte': min_price,
        'price_lte': max_price,
        'category': category,
        'inStock': 'true',
        'orderBy': 'popularity',
        'order': 'desc',
        'limit': 24
    }

    response = requests.get(
        f'{BASE_URL}/collections/products/documents',
        headers=headers,
        params=params
    )
    return response.json()

laptops = search_products('laptop', 500, 2000, 'electronics')

curl "https://api.cocobase.cc/collections/products/documents?name_contains=laptop&price_gte=500&price_lte=2000&category=electronics&inStock=true&orderBy=popularity&order=desc&limit=24" \
  -H "X-API-Key: your-api-key"

JavaScript
Dart
Go
Python
HTTP

async function getUserFeed(userId, page = 1) {
  return await db.listDocuments('posts', {
    filters: {
      '[or]author_id': userId,
      '[or]followers_array_contains': userId,
      status: 'published'
    },
    orderBy: 'created_at',
    order: 'desc',
    limit: 20,
    offset: (page - 1) * 20
  });
}

const myFeed = await getUserFeed('user-123');

Future<List<Document>> getUserFeed(String userId, {int page = 1}) async {
  return await db.listDocuments('posts',
    queryBuilder: QueryBuilder()
      .or()
        .where('author_id', userId)
        .where('followers_array_contains', userId)
      .done()
      .where('status', 'published')
      .orderByDesc('created_at')
      .limit(20)
      .offset((page - 1) * 20)
  );
}

final myFeed = await getUserFeed('user-123');

func getUserFeed(client *cocobase.Client, userID string, page int) ([]cocobase.Document, error) {
    query := cocobase.NewQuery().
        Or().
            Where("author_id", userID).
            Where("followers_array_contains", userID).
        Done().
        Where("status", "published").
        Recent().
        Page(page, 20)

    return client.ListDocuments(ctx, "posts", query)
}

myFeed, _ := getUserFeed(client, "user-123", 1)

def get_user_feed(user_id, page=1):
    params = {
        '[or]author_id': user_id,
        '[or]followers_array_contains': user_id,
        'status': 'published',
        'orderBy': 'created_at',
        'order': 'desc',
        'limit': 20,
        'offset': (page - 1) * 20
    }

    response = requests.get(
        f'{BASE_URL}/collections/posts/documents',
        headers=headers,
        params=params
    )
    return response.json()

my_feed = get_user_feed('user-123')

curl "https://api.cocobase.cc/collections/posts/documents?%5Bor%5Dauthor_id=user-123&%5Bor%5Dfollowers_array_contains=user-123&status=published&orderBy=created_at&order=desc&limit=20&offset=0" \
  -H "X-API-Key: your-api-key"

Best Practices

1. Use Specific Filters

Filter on the server, not the client. This reduces bandwidth and improves performance.

// ✓ Good: Filter on server
const users = await db.listDocuments('users', {
  filters: { status: 'active', age_gte: 18 }
});

// ✗ Bad: Fetch all, filter client-side
const allUsers = await db.listDocuments('users');
const filtered = allUsers.filter(u => u.status === 'active' && u.age >= 18);

2. Always Use Pagination

Never fetch all documents at once. Use limit and offset for better performance.

// ✓ Good: Paginated
const users = await db.listDocuments('users', {
  limit: 50,
  offset: 0
});

// ✗ Bad: No limit
const allUsers = await db.listDocuments('users');

3. Index Frequently Queried Fields

Contact support to add indexes for fields you query often for better performance.

4. Combine Filters Efficiently

Order filters from most to least selective for optimal query planning.

// ✓ Good: Most selective first
filters: {
  id: 'specific-id',        // Very selective
  email: 'user@example.com', // Selective
  status: 'active'          // Less selective
}

5. Use Query Builder for Complex Queries

For complex queries with OR logic, use the query builder pattern.

// ✓ Good: Clear structure
final users = await db.listDocuments('users',
  queryBuilder: QueryBuilder()
    .where('status', 'active')
    .or()
      .where('isPremium', true)
      .where('isVerified', true)
    .done()
    .recent()
);

Operator Reference

Comparison Operators

Operator	Suffix	Description	Example
Equal	(none)	Exact match	`status=active`
Not Equal	`_ne`	Not equal to	`role_ne=admin`
Greater	`_gt`	Greater than	`age_gt=18`
Gte	`_gte`	Greater than or equal	`age_gte=18`
Less	`_lt`	Less than	`age_lt=65`
Lte	`_lte`	Less than or equal	`age_lte=65`

String Operators

Operator	Suffix	Description	Example
Contains	`_contains`	Substring	`name_contains=john`
Starts	`_startswith`	Starts with	`email_startswith=admin`
Ends	`_endswith`	Ends with	`email_endswith=@gmail.com`

List Operators

Operator	Suffix	Description	Example
In	`_in`	Match any	`role_in=admin,moderator`
Not In	`_notin`	Exclude values	`status_notin=deleted,banned`
Contains	`_array_contains`	Array contains	`tags_array_contains=featured`

Next Steps

CRUD Operations

Learn the basics of creating, reading, updating, deleting

Real-time Updates

Subscribe to live filtered query results

Relationships

Populate related documents in queries

Authentication

Query authenticated user collections

Getting Started

Core Concepts

Data & Querying

Cloud Functions

Hooks

Realtime & Multiplayer

Storage

Auth & Security

Guides

SDK Reference

API Reference

Query & Filtering

Query & Filtering

Overview

Basic Filtering

Equality Filters

Query Operators

Comparison Operators

String Operators

List Operators

Logical Operators

OR Queries

Complex Queries (AND + OR)

Sorting

Query Builder Pattern

Real-World Examples

E-commerce Product Search

Best Practices

Operator Reference

Comparison Operators

String Operators

List Operators

Next Steps

CRUD Operations

Real-time Updates

Relationships

Authentication

​Query & Filtering

​Overview

​Basic Filtering

​Equality Filters

​Query Operators

​Comparison Operators

​String Operators

​List Operators

​Logical Operators

​OR Queries

​Complex Queries (AND + OR)

​Sorting

​Pagination

​Query Builder Pattern

​Real-World Examples

​E-commerce Product Search

​Social Feed with Filters

​Best Practices

​Operator Reference

​Comparison Operators

​String Operators

​List Operators

​Next Steps

CRUD Operations

Real-time Updates

Relationships

Authentication

Query & Filtering

Overview

Basic Filtering

Equality Filters

Query Operators

Comparison Operators

String Operators

List Operators

Logical Operators

OR Queries

Complex Queries (AND + OR)

Sorting

Pagination

Query Builder Pattern

Real-World Examples

E-commerce Product Search

Social Feed with Filters

Best Practices

Operator Reference

Comparison Operators

String Operators

List Operators

Next Steps