One of the most useful aspects of using local queries is that you can dynamically specify your conditions using a rich SQL-like languages called SCQL (SproutCore Query Language).  SCQL implements enough grammar to support basic conditions.  Much like the ‘WHERE’ clause in traditional SQL.  In addition to the basic conditions, SCQL allows you to insert named and unnamed wildcards that will be substituted with parameters later on.  You can also register your own comparison operations if needed.

Basic Grammar

An SCQL statement simply lists a set of comparison, optionally grouped by parenthesis.  Comparisons are processed from left to right unless parenthesis get in the way.  For example, this would be a simple SCQL statement:

firstName = “John”

You can join multiple comparisons using the AND or OR operators.  You should wrap each comparison in parenthesis:

((firstName = “John”) OR (firstName = “Jane”) AND (lastName = “Doe”))

Property Keys

For simple comparisons, the value on the left hand side is almost always a key name that would be found on the matching record.  Note that this key is for the record not the data hash.  This means if you remap a key name you should use the remapped name.  Likewise, you can use computed properties for comparison here as well.

For example, the comparison:

fullName = “John Doe”

would find all records whose “fullName” property is “John Doe”, even if fullName is actually computed from firstName and lastName.

Simple Values

The right hand side of a simple comparison is usually a simple value.  The value may be a string (surrounded in quotes), boolean (written as true/false or YES/NO without quotes), or a number. 

firstName = “John” // string

isActive = YES  // boolean

birthyear = 1979 // number

Wildcards

You can use one of two wildcard methods any place you would normally use a simple value.  Wildcards will be substituted with a parameter from the query’s “parameters” property when the search is actually performed.

Wildcards can be either named or positional.  Named wildcards are strings wrapped in curly brackets “{}”.  Positional wildcards simply use the string “%@”.    You should use either named wildcards or positional wildcards in statement, but not both.  

// named wildcards

var q = SC.Query.local(MyApp.Contact, “firstName = {name}”, { name: “John” });

// positional wildcards

var q = SC.Query.local(MyApp.Contact, “firstName = %@”, [“John”]);

If you use named wildcards, the “parameters” property on the query MUST be a hash with same-named properties to substitute in.  If you use positional wildcards, the “parameters” property MUST be an array of values.  They will be substituted in from left to right.

Note that arrays, hashes, and objects cannot be expressed directly in SCQL.  You MUST use wildcards instead to use these values.

Available Comparisons 

SC.Query comes with the following basic comparisons built in:

In addition, SC.Query supports AND, OR, and NOT logical operators.

Implementation Details

SC.Query uses a simple parse tree to evaluate your SCQL.  It first tokenizes your query string, then maps each token to a handler function.  This creates a tree of functions that are simply executed in order from left to right to evaluate the final results.  This parsing is only done once when your query is created, so it is really fast.

Registering Your Own Comparison Operators

TODO: Finish this section.  Any takers?

Moving On

Learn about Nested Stores »

Back to DataStore Programming Guide Home »