Filtering

Learn how to use api.vision's filtering capabilities to narrow down results and find exactly what you need.

Basic Filtering

To filter resources based on field values, simply add the field name as a query parameter:

GET /users?role=admin

This will return only users with the role set to "admin". You can combine multiple filters:

GET /users?role=admin&status=active

Multiple filters are combined with AND logic - all conditions must be met.

Operator Filtering

For more advanced filtering, api.vision supports various operators:

Operator	Description	Example
`_eq`	Equals (default)	`?status_eq=active` or `?status=active`
`_neq`	Not equals	`?status_neq=inactive`
`_gt`	Greater than	`?price_gt=100`
`_gte`	Greater than or equal	`?price_gte=100`
`_lt`	Less than	`?price_lt=100`
`_lte`	Less than or equal	`?price_lte=100`
`_like`	Contains substring (case-sensitive)	`?name_like=Smith`
`_ilike`	Contains substring (case-insensitive)	`?name_ilike=smith`
`_in`	In a list of values	`?status_in=active,pending`
`_nin`	Not in a list of values	`?status_nin=deleted,inactive`
`_exists`	Field exists (not null)	`?email_exists=true`
`_null`	Field is null	`?deleted_at_null=true`

Array Filtering

For array fields, api.vision provides specialized operators:

Operator	Description	Example
`_contains`	Array contains value	`?tags_contains=javascript`
`_containsAll`	Array contains all values	`?tags_containsAll=javascript,react`
`_containsAny`	Array contains any value	`?tags_containsAny=javascript,typescript`

Logical Operators

For complex filtering needs, api.vision supports logical operators:

AND Operator

Multiple filters are automatically combined with AND logic:

GET /products?category=electronics&price_gte=100&inStock=true

OR Operator

For OR logic, use the _or parameter with a list of conditions:

GET /products?_or=category:electronics,category:gadgets&price_gte=100

This fetches products where:

Category is "electronics" OR "gadgets", AND
Price is greater than or equal to 100

Filtering on Related Resources

You can filter on fields of related resources using dot notation:

GET /posts?author.role=admin

This fetches posts where the author's role is "admin". You can go multiple levels deep:

GET /comments?post.author.status=active

Advanced Example

GET /products?
  category_in=electronics,gadgets&
  price_gte=100&
  price_lte=1000&
  name_ilike=pro&
  _or=brand:apple,brand:samsung&
  rating_gte=4&
  inStock=true

This fetches products where:

Category is either "electronics" or "gadgets", AND
Price is between 100 and 1000, AND
Name contains "pro" (case-insensitive), AND
Brand is either "apple" OR "samsung", AND
Rating is at least 4, AND
Product is in stock

Performance Tip

While api.vision supports complex filtering, excessive filtering on large datasets can impact performance. When working with large datasets, consider using more targeted filters and pagination to improve response times.