Appearance
Search
The search endpoint is another CRUD endpoint
GET /api/ClassName
Search results will be encapsulated with some additional metadata
json
{
"status": 200,
"message": "OK",
"payload":
{
"results":[ ... result values ... ],
"total": 110,
"offset": 0
}
}
Search queries will automatically be limited to the session's access control.
Special fields
The search API contains a few special fields
Search limiters
Field | Function | Type | Example |
---|---|---|---|
limit | The max number of results to return | number | (default=25) |
offset | Offset the returned list of values | number | (default=0) |
sortby | Column name to sort by | string | (default=id SQL Server only) |
sortbyorder | Sort by direction | string | up / asc or down / desc |
Metadata fields
Regardless of the objects structure there are a few fields that are always avilable
Field | Function | Type |
---|---|---|
id | The identifier | string |
displayName | A string value that describes the items name | string |
dateMade | date record was made | epoch long with milliseconds |
dateUpdated | date record was updated | epoch long with milliseconds |
path | the access control paths this object it located in (this can be suppressed) | string |
Simple search queries
The search endpoint can contain filter criteria to limit results of a search. These take the form of standard url parameters
eg:
/api/ClassName?category=sports
The key of the parameter must correspond to a column name of the class. By default the operation used on the search is an equal to.
Operators
The query can be augmented with prefixes to change the operation
Prefix | Operation | Example |
---|---|---|
none | Equals | category=Sports Category must equal 'Sports' (case sensitive) |
~ | Contains | name=~star name contains with word 'star' somewhere in it (case insensitive) |
> | Greater Than | age= >20 age must be more than 20 (numeric and date fields only) |
< | Less Than | age=<20 age must be less than 20 (numeric and date fields only) |
>= | Greater Than or equal | age= >=20 age must be more than or equals to 20 (numeric and date fields only) |
<= | Less Than or equal | age=<=20 age must be less than or equals to 20 (numeric and date fields only) |
! | Not | category=!~sports category must not contain the word sports |
Note that operators need to be URL encoded. so age=<=20 will need to be age=%3C%3D20
Sets
pipe delimited values are treated as sets eg: select all where category = sports or arts or tv
/api/ClassName?category=sports|tv|arts
Multiple criteria are permitted, the criteria are always joined with an AND conjunction
Complex Queries
As of: v 3.3.0
Complex queries allow a greater level of control over conjunctions and order execution. A complex query is sent as a JSON encoded parameter called query or simply q.
js
{or:[
{and:[
{gender:{eq:"male"}},
{name:{in:["Star Wars","Harry Potter"]}}
]},
{and:[
{age:{gt:20}},
{age:{lt:40}},
{not:{state:{eq:"NSW"}}},
]}
]}
Expression will read
sql
WHERE (gander = 'male' AND name in ('Star Wars','Harry Potter')) OR (age > 20 AND age < 40 AND state = 'NSW' )
Operators
The query can be augmented with prefixes to change the operation
Operators | Operation | Sample |
---|---|---|
eq | Equals | {name:{eq:"John"}} |
like | Contains | {name:{like:"John"}} |
in | Contains | {name:{in:["John","Kate"]}} |
gt | Greater Than^ | {age:{gt:20}} |
lt | Less Than^ | {date:{lt:1724761129000}} |
ge | Greater Than or equal^ | {age:{ge:20}} |
le | Less Than or equal^ | {date:{le:1724761129000}} |
not | Not | {not:{date:{le:1724761129000}}} |
and | AND conjunction | {and:[{name:{eq:"John"}},{age:{gt:20}} ]} |
or | OR Conjunction | {or:[{name:{eq:"John"}},{age:{gt:20}} ]} |
^ Numeric and date fields only