General advices

• The following relational operators are allowed: ==, >, <, >=,

• All queries may extended using the or or and operators

• You can limit the result size with the limit operator, followed by a number defining the max result size like limit 10. Please pay attention that the limit operator must be the very last one in your query!

• Every query can be limited system-wide to return a maximum number of entries. You can change the limit by setting the property maxResults in the apiomat.yaml for your installation. In YAMBAS 3.1.3 and later, this is set to unlimited (0) by default! In versions < 3.1.3, it is set to 1000 by default.

• Paging is also possible using the offset operator; querying with offset 5 would return all matching results but cut off the first five results.

• If you use limit and offset together than please pay attention to the order! For example: firstname startswith "J" offset 5 limit 4 means: “Give me all firstnames starts with a “J” from the 5th entry and limit the result by 4 entries”

• You can query list sizes using the size operator: myList size 0 will return results with an empty myList list

• You can query null values using null as value, like: attributeName == null

• You can provide an ordering by using order by myAttributeName, where myAttributeName is an attribute of the class you are querying

• Ascending order is standard. Add DESC keyword to your order statement to sort results descending (e.g. lastName == null order by createdAt DESC)

• Always use double quotes (“) instead of single quotes (‘)!

Numbers and Texts

Querying for number or text attributes follows a very straightforward SQL syntax. Imagine
you have a textual attribute named “firstname” and a numbered one named “age”:

• firstname=="John" will return all objects with exact firstname “John”

• firstname startswith "John" will return all objects where the firstname starts with “John”

• firstname like "oh" will return all objects where the firstname contains “oh”, e.g. “John”

• age==24 will return all objects with exact age of 24

• age!=24 will return all objects with exact age other than 24

• age>24 will return all objects with exact age larger than 24

• age<=24 will return all objects with exact age younger than or exactly 24

• age>24 and age<30 will return all objects with exact ages older than 24 but younger than 30

Dates

Querying for dates follows the syntax of numbers and texts; you just have to pass the date as a long value, denoting the milliseconds since the standard base time known as the epoch, namely January 1st 1970, 00:00:00 GMT. To divide between numbers and a date, simply wrap the number into date (..), like birthdate > date(1347600117535)
Please make sure you use the 13 digit timestamp (milliseconds)!

IDs

All of your stored class instances (objects) get an unique ID assigned on server. You can find that at the very end of the class instance href. If you want to query a specific class instance, you can also use this ID in a query in a very equal syntax as used for dates:
id == id(5052cd9444ae23a741ca76b2)

Locations

Querying for locations is also very simple; you can query objects in a specific radius using within or nearest objects of a point using near. Imagine ‘loc’ is your location attribute:

• loc within [51.3, 12.3, 10.0] will return all objects within a radius of 10 kilometers of a point with latitude 51.3 and longitude 12.3, without a specific sort order

• loc near [51.3, 12.3,] will return all objects near a point with latitude 51.3 and longitude 12.3, sorted by distance to the queried point

• loc near [51.3, 12.3,] limit 10 will return at most 10 objects near a point with latitude latitude 51.3 and longitude 12.3, sorted by distance to the queried point

As seen in the examples, when using "within" or "near", you need to provide the data in the order [lat, long].

Also note that queries using near will return at most 100 results for performance reasons.

When using "within", you cannot order the results by distance to the searched point. When adding an "order by" to the query, you can order by other attributes.
When using "near", the results are automatically ordered by distance to the searched point, but when you add an "order by" to the query, the distance order will be overwritten.

All values have to be dot-separated floating point numbers.

Please pay attention that location queries can not be used with and/or concatenation. Instead, you can use the keyword filter to filter your locational results afterwards like follows:
loc near [11.5,50.0] filter firstname=="John" and lastname=="doe"
In the filter part, the following operations are permitted:
==, !=, >, <, >=

References

Querying references is also very straightforward. Imagine your class contains a Place, which can have a list of Users as attribute name users, denoting the users which currently are at that location. Now you want to find the place and find people older than 30. Just start a query on places:

users.age > 30

You can concatenate as much as you like, for example your class may also have a city and country; query country like:

city.places.users.age > 30

Collections

A collection of strings can be accessed like a single string.

attendeeUserNames=="John" will return all objects with the “John” as an element in the collection

Maps

Values of keys of a map can be accessed with map.key == "value".

Thus, the query preferences.food == "Pasta" returns every object which has the key "food" stored in the map "preferences" and associated with the value "Pasta".

Note that this condition is case-sensitive. If you want to conduct a case-insensitive search, use the 'like' key word instead of "==" as follows:

preferences.food like "Pasta"