voyageai-cli

# Filtering Filtering narrows results to specific criteria using query parameters. The platform supports flexible filter syntax for simple and complex queries. ## Basic Filtering Filter by a single field: ``` GET /users?filter[status]=active ``` Returns only users with `status` equal to "active". Multiple filters combine with AND logic: ``` GET /users?filter[status]=active&filter[role]=admin ``` Returns users with `status=active` AND `role=admin`. ## Comparison Operators Use operators for more complex filtering: ``` GET /events?filter[created_at][$gte]=2026-01-01 ``` Supported operators: - `$eq` - Equal (default if no operator specified) - `$ne` - Not equal - `$gt` - Greater than - `$gte` - Greater than or equal - `$lt` - Less than - `$lte` - Less than or equal - `$in` - In array - `$nin` - Not in array - `$exists` - Field exists (true) or is null (false) ## Range Queries Query ranges with multiple operators: ``` GET /products?filter[price][$gte]=10&filter[price][$lte]=100 ``` Returns products priced between $10 and $100 inclusive. ## String Matching **Exact match**: `filter[name]=John` **Partial match (contains)**: `filter[name][$contains]=ohn` (matches "John", "Johnson", etc.) **Case-insensitive**: `filter[name][$icontains]=JOHN` (matches "john", "John", "JOHN") **Regex**: `filter[email][$regex]=^[a-z]+@example\.com$` (limited to patterns for performance) ## Array Filtering Filter by array membership: ``` GET /users?filter[tags][$in]=vip,premium ``` Returns users with tags containing "vip" or "premium". Filter array length: ``` GET /users?filter[tags][$size]=3 ``` Returns users with exactly 3 tags. ## Nested Object Filtering For nested objects, use dot notation: ``` GET /orders?filter[user.status]=active ``` Filters by the `status` field inside the nested `user` object. ## Date and Time Filtering Dates can be specified in ISO 8601 format: ``` GET /events?filter[timestamp][$gte]=2026-02-01T00:00:00Z ``` Shorthand for day-only: ``` GET /events?filter[date][$gte]=2026-02-01 ``` Interpreted as 2026-02-01T00:00:00Z. Relative dates (future enhancement): ``` GET /events?filter[created_at][$gte]=now-7d ``` Not yet supported; use absolute dates instead. ## Boolean Filtering ``` GET /users?filter[verified]=true&filter[deleted]=false ``` ## Multiple OR Conditions OR logic uses separate filter arrays: ``` GET /users?filter[$or][0][status]=active&filter[$or][0][status]=pending ``` Returns users with `status` equal to "active" OR "pending". ## Filter Limits Filters are powerful but resource-intensive. Complex filters with >10 conditions or deep nesting may be slow. Use strategically and consider denormalization in your database schema. ## Full-Text Search For keyword-based search, use `search` parameter instead of filters: ``` GET /articles?search=kubernetes+deployment ``` This searches across multiple text fields efficiently using full-text indexes. ## Filter Performance Indexes are important for filter performance. Common filtered fields should be indexed. Check the [Schema Documentation](../database/schema-overview.md) for available indexes. Queries without indexes on filtered fields run slower, especially on large tables. Monitor slow query logs to identify missing indexes. ## Combining Filters with Pagination Filters reduce results before pagination: ``` GET /users?filter[status]=active&page=2&per_page=50 ``` The `total` count in pagination metadata reflects filtered results.