daux.io/tmdocs/01_API/30_Filtering.md

3.6 KiB

To filter an api call, send the optional filter parameter. The filter parameter is a structured json object. Examples use the following terms:

  • field key - Is the key used to define the field in the config.
  • operator - Is the comparison to preform.
  • value - Is what we will compare the object value to.

Basic Structure

This is the most basic filter that can be preformed.

{
	"field key":  "value"
}

Example Call:

GET /collections/team?filter={"employment":"full"}

This will find all full time team members in the collection.

Advanced Structure

This structure allows more advanced control over operators used when filtering.

{
	"field key": {
		"operator": "value"
	}
}

Example Call:

GET /collections/team?filter={"employment": {"!=": "retired"}}

This will find all team members who are not retired in the collection.

Multiple Operators Structure

You can preform multiple comparision operations on the same field

{
	"field key": {
		"operator": "value",
		"operator2": "value2",
		"operatorx..": "valuex.."
	}
}

Example Call:

GET /collections/team?filter={"name": {"LIKE":"Justin%", "!=":"Justin Walsh"}}

This will find all team members who's names start with 'Justin' but are not 'Justin Walsh'.

Multiple Fields Structure

You can filter multiple fields by adding each field key to the object.

{
	"field key 1": "value",
	"field key 2": {
		"operator": "value"
	},
	"field key 3": {
		"operator": "value"
	}
}

Multiple Values Structure

When filtering, you can use an array instead of a string to match any of the values in the array.

{
	"employment": ["full", "part"],
	"name": {
		"LIKE": ["Justin%", "Brian%"]
	}
}

This will match all team members who are full or part time, and whose names starts with 'Justin' or 'Brian'.

Note: "employment": ["full", "part"] is equvalient to

"employment": {
	"=": ["full", "part"]
}

Nested Fields Structure

You can filter by nested fields in the object using a dot notation syntax as the field key in the filter. This syntax can be used to query deep into nested objects and arrays, including fields like the 'multi'.

{
	"address.zip": "58501"
}

This will filter the location field type by zip code, which is a nested field. This example is based on the sample config at the top of this guide.

AND/OR Fields Structure (Not Supported Yet)

This structure allows a very customized query including both -and and -or statments.

{
	"field key 3": {
		"operator": "value"
	},
	"-or": {
		"field key 1": "value",
		"-and": {
			"field key 2": {
				"operator": "value"
			},
			"field key 4": {
				"operator": "value"
			}
		}
	}
}

Supported Operators

Operator Description
= equal to
!= not equal to
> greater than
< less than
>= greater than or equal to
<= less than or equal to
LIKE case sensitive search, use '%' for wildcard
ILIKE case insensitive search, use '%' for wildcard
NOT LIKE inverse of 'LIKE'
NOT ILIKE inverse of 'ILIKE'

Notes

JSON Filtering

The JSON object used for the filter parameter must be url encoded when calling the api. Here are examples of how to url encode a json object or string in different languages.

php

$escaped_json = urlencode('{"name": {"LIKE":"Justin%", "!=":"Justin Walsh"}}');

javascript string

var escaped_json_from_string = escape('{"name": {"LIKE":"Justin%", "!=":"Justin Walsh"}}');

javascript object

var escaped_json_from_object = escape(JSON.stringify({"name": {"LIKE":"Justin%", "!=":"Justin Walsh"}}));