Class: SC.Query

Extends SC.Copyable, SC.Freezable, SC.Object.

This class permits you to perform queries on your data store or a remote data store. Here is a simple example of a local (see below) query,

query = SC.Query.create({
  conditions: "firstName = 'Johnny' AND lastName = 'Cash'"
});

This query, when used with the store, will return all records which have record attributes of firstName equal to 'Johnny' and lastName equal to 'Cash'. To use the query with the store simple pass it to find like so,

records = MyApp.store.find(query);

In this example, records will be an SC.RecordArray array containing all matching records. The amazing feature of record arrays backed by local queries is that they update automatically whenever the records in the store change. This means that once we've run the query once, any time data is loaded or unloaded from the store, the results of the query (i.e. records) will update automatically. This allows for truly powerful and dynamic uses, such as having a list of filtered results that continually updates instantly as data pages in or out in the background.

To limit the query to a record type of MyApp.MyModel, you can specify the type as a property of the query like this,

query = SC.Query.create({
  conditions: "firstName = 'Johnny' AND lastName = 'Cash'",
  recordType: MyApp.MyModel
});

Calling find() like above will now return only records of type MyApp.MyModel. It is recommended to limit your query to a record type, since the query will have to look for matching records in the whole store if no record type is given.

You can also give an order for local queries, which the resulting records will use,

query = SC.Query.create({
  conditions: "firstName = 'Johnny' AND lastName = 'Cash'",
  recordType: MyApp.MyModel,
  orderBy: "lastName, year DESC"
});

The default order direction is ascending. You can change it to descending by writing 'DESC' behind the property name as was done in the example above. If no order is given, or records are equal in respect to a given order, records will be ordered by their storeKeys which increment depending on load order.

Note, you can check if a certain record matches the query by calling query.contains(record).

Local vs. Remote Queries

The default type for queries is 'local', but there is another type we can use called 'remote'. The distinction between local and remote queries is a common tripping point for new SproutCore developers, but hopefully the following description helps keep it clear. The terms local and remote refer to the location of the data where the query is performed and by whom. A local query will be run by the client against the store of data within the client, while a remote query will be run on by the server against some remote store of data. This seems simple enough, but it can lead to a few misconceptions.

The first misconception is that local queries don't ever result in a call to a server. This is not the case; when a local query is first used with the store it will generally result in a call to the server, but whether or not it does depends on your store's data source. Keep this in mind, local queries only run against the data loaded in the client's store. If the client store is empty, the results of the query will be empty even though there may be thousands of matching records on a server somewhere. That's why when a query is first used, the store will look for a data source that implements the fetch(store, query) method. Your data source can then decide whether additional data should be loaded into the store first in order to better fulfill the query.

This is entirely up to your client/server implementation, but a common use case is to have a general query trigger the load of a large set of data and then any more specific queries will only run against what was already loaded. For more details, @see SC.DataSource.prototype.fetch. So to recap, local queries are passed to the data source fetch method the first time they are used so that the data source has a chance to load additional data that the query may need.

Once we get past the first misconception; local queries are actually pretty easy to understand and to work with. We run the queries, get the resulting record array and watch as the results almost magically update as the data in the client changes. Local queries are the default type, and typically we will use local queries almost exclusively in SproutCore apps. So why do we have a remote type?

In a previous paragraph, we considered how a local query would be empty if the local store was empty even though there may be thousands of matching records on a server. Well what if there were millions of records on the server? When dealing with extremely large datasets, it's not feasible to load all of the records into the client so that the client can run a query against them. This is the role of the 'remote' type. Remote queries are not actually "run" by the client at all, which is the next misconception; you cannot run a remote query.

This misconception is another way of saying that you can't set conditions or order on a remote query. The 'remote' SC.Query type is simply a reflection of some database query that was run against a data store somewhere outside of the client. For example, say we want to still find all the records on the server with firstName equal to 'Johnny' and lastName equal to 'Cash', but now there are millions of records. This type of query is best left to a MySQL or other database on a server and thus the server will have exposed an API endpoint that will return the results of such a search when passed some search terms.

Again, this is entirely up to your client/server configuration, but the way it is handled by the data source is nearly identical to how local queries will be handled. In both situations, the data source is passed the query the first time it is run and when the data source is done it calls the same method on the store, dataSourceDidFetchQuery. In both situations too, any data that the data source receives should be loaded into the client store using loadRecords. However, because there may be lots of other data in the client store, the 'remote' query must also be told which records pertain to it and in what order, which is done by passing the store keys of the new data also to dataSourceDidFetchQuery.

So to recap, use 'local' queries to filter the data currently in the client store and use 'remote' queries to represent results filtered by a remote server. Both may be used by a data source to load data from a server.

SproutCore Query Language

Features of the query language:

Primitives:

• record properties
• null, undefined
• true, false
• numbers (integers and floats)
• strings (double or single quoted)

Parameters:

• %@ (wild card)
• {parameterName} (named parameter)

Wild cards are used to identify parameters by the order in which they appear in the query string. Named parameters can be used when tracking the order becomes difficult. Both types of parameters can be used by giving the parameters as a property to your query object:

yourQuery.parameters = yourParameters

where yourParameters should have one of the following formats: for wild cards: [firstParam,secondParam,thirdParam] for named params: {name1: param1, mane2: parma2}

You cannot use both types of parameters in a single query!

Operators:

• =
• !=
• <
• <=
• >
• >=
• BEGINS_WITH -- (checks if a string starts with another one)
• ENDS_WITH -- (checks if a string ends with another one)
• CONTAINS -- (checks if a string contains another one, or if an object is in an array)
• MATCHES -- (checks if a string is matched by a regexp, you will have to use a parameter to insert the regexp)
• ANY -- (checks if the thing on its left is contained in the array on its right, you will have to use a parameter to insert the array)
• TYPE_IS -- (unary operator expecting a string containing the name of a Model class on its right side, only records of this type will match)

Boolean Operators:

• AND
• OR
• NOT

Parenthesis for grouping:

• ( and )

Adding Your Own Query Handlers

You can extend the query language with your own operators by calling:

SC.Query.registerQueryExtension('your_operator', your_operator_definition);

See details below. As well you can provide your own comparison functions to control ordering of specific record properties like this:

SC.Query.registerComparison(property_name, comparison_for_this_property);

Defined in: query.js

Since:

SproutCore 1.0

Field Summary

Class Methods

• build(location, recordType, conditions, parameters)
• compareStoreKeys(storeKey1, storeKey2, storeKey1, storeKey2)
• containsRecords(query, records, store)
• local(recordType, properties, oldParameters)
• orderStoreKeys(storeKeys, query, store)
• registerComparison(name, custom)
• registerQueryExtension(tokenName, token)
• remote(recordType, properties, oldParameters)
• storeKeyFor(query)

Instance Methods

• buildOrder(orderOp)
• buildTokenTree(tokenList, treeLogic)
• compare(record1, record2)
• contains(record, parameters)
• containsRecordTypes(types)
• expandedRecordTypes()
• isLocal()
• isRemote()
• parse()
• queryWithScope(recordArray)
• tokenizeString(inputString, grammar)
• toString()

var people = SC.Query.local(Ab.Person);
var peopleAndCompanies = SC.Query.local([Ab.Person, Ab.Company]);

var people = SC.Query.local('Ab.Person');
var peopleAndCompanies = SC.Query.local('Ab.Person Ab.Company'.w());

var allRecords = SC.Query.local(SC.Record);

var married = SC.Query.local(Ab.Person, "isMarried=YES");
var married = SC.Query.local(Ab.Person, "isMarried=%@", [YES]);
var married = SC.Query.local(Ab.Person, "isMarried={married}", {
  married: YES
});

var orderedPeople = SC.Query.local(Ab.Person, { orderBy: "firstName" });

// Show all the accounts with a value greater than 100.
query = SC.Query.local(MyApp.Account, {
  conditions: 'value > {amt}',
  parameters: { amt: 100 },
  orderBy: 'value DESC'
});

// The data source can alter its remote request using the value of
// `query.beginsWith`.
query = SC.Query.remote(MyApp.Person, { beginsWith: 'T' });

tree.evaluate(record, parameters)