Search Language

The search language enables you to retrieve a set of objects of any given combination of constraints. Interface will return all content of the given Model type that satisfy all the conditions you specify in the search language query. A basic query is made on a particular property of the Model you are searching, of the form:

• {property name}{query type}{matching string}

So in the case of

(label:over)

“label” is the property name, : is the query type and “over” is the matching string.

The basic concepts are the Query Types and the Set Operations. The Query Types provide a variety of ways to perform queries to retrieve a particular set of objects, and the Set Operations provide the means to combine those sets of objects in various ways into more specific sets of objects. The Query Types are:

• : (Loose) - Will match any substring of the given property
• ! (Strict) - Matches only the given value
• < (Less) - Only objects whose property is less than the given value
• > (Greater) - Same, but greater

For example, say you have created a Model named “Bicycle”, which has a short string type column “model,” and you want to find all Bicycles whose model contains the string ‘X’ returned as xml. The corresponding API call would be:

http://yourdomain.com/api/bicycle.xml?search=(model:X)

Most of this string is specifying the search context, but the query is the key point:

(model:X)

If you want all Bicycles whose model is exactly “Pangea,” use the strict Query Type:

(model!Pangea)

The Set Operations cluster queries into higher-order groups. The basic Set Operation syntax is as follows:

• {subquery}{set_operation}{subquery}

Notice this is still a query which could be used as a subquery in a larger query, so these operations can be nested infinitely. The Set Operations are one of three basic types:

• | (union) - Set Union
• @ (intersection) - Set Intersection
• ~ (difference) - Set Difference

In addition to these, there is also a grouping operator () that makes the operation’s precedence explicit. Out of these three operations any conceivable set operation can be specified. For example, find the XOR of two queries (the elements that are in one or the other but not both) with:

(queryA|queryB)~(queryA@queryB)

If you wanted to find all Bicycles whose model is “mountain” and whose height is greater than 53 cm:

(model!mountain@height>53)

Notice the conflation of logical AND with set intersection (only retaining the objects that occur in both sets). Likewise logical OR and set union (combining both sets). Difference is related to the logical operation AND NOT. The logical sense of the operation is used as a condition to include or exclude various objects in the resulting set.

There is also support for date and location queries. To find a group of items whose date is later than two days from now:

(date>2 days from now)

Or, earlier than two years ago:

(date<2 years ago)

For dates, there is also the general term ‘now’ which is always available.

(date!now)

For locations, if you have a location column named ‘loc’ you can find all locations within or beyond a certain radius of a given latitude and longitude with:

loc within 5mi of 47.332083,-111.937743

For all of the given queries, the property can follow any associations the object has by name. So if Bicycle belongs to Shop, and Shop has a column “City” you can find all Bicycles that belong to a Shop in Portland with:

(shop.city!Portland)

If you like that, but don’t want to include the Bicycles whose model has an ‘X’ in it:

(shop.city!Portland~model:X)

You like all those, but only want the Bicycles in a Shop in Portland without an ‘X’ in the model name that are taller than 53 cm :

(shop.city!Portland~model:X)@(height>53)

Have at it.