voyageai-cli

# Sorting Sorting orders results by one or more fields. Results are sorted ascending by default; prefix field names with `-` for descending order. ## Basic Sorting Sort by a single field: ``` GET /users?sort=name ``` Returns users sorted by name (A-Z). Descending order: ``` GET /users?sort=-created_at ``` Returns users sorted by creation date (newest first). ## Multiple Sort Fields Combine multiple sort keys for secondary ordering: ``` GET /users?sort=-created_at,name ``` Sorts by creation date descending, then by name ascending. Secondary sorts break ties in primary sorts. ## Sortable Fields Not all fields are sortable. Documentation specifies which fields support sorting. Common sortable fields: - `name`, `email`, `title` (text fields) - `created_at`, `updated_at`, `timestamp` (date fields) - `status`, `role` (enum fields) - `price`, `count`, `score` (numeric fields) Attempting to sort by a non-sortable field returns 400 Bad Request. ## Indexed vs. Non-Indexed Sorting Sorting by indexed fields is fast. Sorting by non-indexed fields may be slow on large datasets. The database query planner uses available indexes to optimize sorts. For performance-critical sorts, ensure fields are indexed. See [Database Indexes](../database/indexes.md). ## Case-Sensitive Sorting Sorting is case-sensitive. Uppercase letters sort before lowercase in ASCII order: ``` A, B, Z, a, b, z ``` For case-insensitive sorting, use: ``` GET /users?sort=lower(name) // Function-based sorting (limited support) ``` Not all databases support function-based sorting; check your environment. ## Null Value Handling Null values in sort fields are typically placed last (for ascending) or first (for descending). Behavior varies by database. To control null placement explicitly (if supported): ``` GET /users?sort=name,_nulls_last ``` This is a future enhancement; currently nulls follow database defaults. ## Limiting Sort Keys Complex sorts with many keys may reduce performance. Limit secondary sorts to 2-3 fields maximum. ## Sort Order Consistency When paginating with sorting, always specify the same sort order in all requests: ``` Request 1: GET /users?page=1&sort=-created_at Request 2: GET /users?page=2&sort=-created_at ``` Omitting sort in page 2 reverts to default sort, causing inconsistent pagination. ## Dynamic Sorting API responses include available sort fields in response headers or metadata (future feature): ``` X-Sort-Available: name,-created_at,status,role ``` This helps clients discover sortable fields without reading documentation. ## Performance Considerations Sorting large datasets is expensive, especially for non-indexed fields. For better performance: 1. **Filter first**: Reduce dataset size before sorting 2. **Use pagination**: Never fetch entire unsorted dataset 3. **Index sort fields**: Ensure critical sort fields have indexes 4. **Limit sort complexity**: Use simple, single-field sorts when possible ## Default Sort Order If no sort is specified, results use the default sort order (usually `-created_at` for most collections). Some endpoints may have different defaults; check endpoint documentation. Override defaults explicitly to avoid surprises when defaults change.