EntityQuery Class
An EntityQuery instance is used to query entities either from a remote datasource or from a local EntityManager.
EntityQueries are immutable - this means that all EntityQuery methods that return an EntityQuery actually create a new EntityQuery. This means that EntityQueries can be 'modified' without affecting any current instances.
Item Index
Methods
- <ctor> EntityQuery
- execute
- executeLocally
- expand
- from static
- from
- fromEntities static
- fromEntityKey static
- fromEntityNavigation static
- inlineCount
- noTracking
- orderBy
- orderByDesc
- select
- skip
- take
- top
- toType
- using
- where
- withParameters
Methods
<ctor> EntityQuery
-
[resourceName]
Parameters:
-
[resourceName]
String optional
Example:
var query = new EntityQuery("Customers")
Usually this constructor will be followed by calls to filtering, ordering or selection methods
var query = new EntityQuery("Customers")
.where("CompanyName", "startsWith", "C")
.orderBy("Region");
execute
-
callback
-
errorCallback
Executes this query. This method requires that an EntityManager has been previously specified via the "using" method.
Parameters:
-
callback
FunctionFunction called on success.
successFunction([data])
-
[data]
Object optional-
results
Array of Entity -
query
EntityQueryThe original query -
httpResponse
HttpResponseThe HttpResponse returned from the server. -
inlineCount
IntegerOnly available if 'inlineCount(true)' was applied to the query. Returns the count of items that would have been returned by the query before applying any skip or take operators, but after any filter/where predicates would have been applied.
-
-
-
errorCallback
FunctionFunction called on failure.
failureFunction([error])
-
[error]
Error optionalAny error that occured wrapped into an Error object.
-
[query]
optionalThe query that caused the error. -
[httpResponse]
HttpResponse optionalThe raw XMLHttpRequest returned from the server.
-
-
Returns:
Example:
This method can be called using a 'promises' syntax ( recommended)
var em = new EntityManager(serviceName);
var query = new EntityQuery("Orders").using(em);
query.execute()
.then( function(data) {
... query results processed here
}).fail( function(err) {
... query failure processed here
});
or with callbacks
var em = new EntityManager(serviceName);
var query = new EntityQuery("Orders").using(em);
query.execute(
function(data) {
var orders = data.results;
... query results processed here
},
function(err) {
... query failure processed here
});
Either way this method is the same as calling the EntityManager 'execute' method.
var em = new EntityManager(serviceName);
var query = new EntityQuery("Orders");
em.executeQuery(query)
.then( function(data) {
var orders = data.results;
... query results processed here
}).fail( function(err) {
... query failure processed here
});
executeLocally
()
Executes this query against the local cache. This method requires that an EntityManager have been previously specified via the "using" method.
Example:
// assume em is an entityManager already filled with order entities;
var query = new EntityQuery("Orders").using(em);
var orders = query.executeLocally();
Note that calling this method is the same as calling executeQueryLocally.
expand
-
propertyPaths
Returns a new query that will return related entities nested within its results. The expand method allows you to identify related entities, via navigation property names such that a graph of entities may be retrieved with a single request. Any filtering occurs before the results are 'expanded'.
Parameters:
-
propertyPaths
String | Array of StringA comma-separated list of navigation property names or an array of navigation property names. Each Navigation Property name can be followed by a '.' and another navigation property name to enable identifying a multi-level relationship. If 'propertyPaths' is either null or omitted then any existing 'expand' clause on the query is removed.
Returns:
Example:
var query = new EntityQuery("Customers")
.where("CompanyName", "startsWith", "C")
.expand("Orders");
will return the filtered customers each with its "Orders" properties fully resolved. Multiple paths may be specified by separating the paths by a ','
var query = new EntityQuery("Orders")
.expand("Customer, Employee")
and nested property paths my be specified as well
var query = new EntityQuery("Orders")
.expand("Customer, OrderDetails, OrderDetails.Product")
from
-
resourceName
This is a static version of the "from" method and it creates a 'base' entityQuery for the specified resource name.
Parameters:
-
resourceName
StringThe resource to query.
Returns:
Example:
var query = EntityQuery.from("Customers");
is the same as
var query = new EntityQuery("Customers");
from
-
resourceName
Specifies the resource to query for this EntityQuery.
Parameters:
-
resourceName
StringThe resource to query.
Returns:
Example:
var query = new EntityQuery()
.from("Customers");
is the same as
var query = new EntityQuery("Customers");
fromEntities
-
entities
Static method tht creates an EntityQuery that will allow 'requerying' an entity or a collection of entities by primary key. This can be useful to force a requery of selected entities, or to restrict an existing collection of entities according to some filter.
Parameters:
-
entities
Entity | Array of EntityThe entities for which we want to create an EntityQuery.
Returns:
Example:
// assuming 'customers' is an array of 'Customer' entities retrieved earlier.
var customersQuery = EntityQuery.fromEntities(customers);
The resulting query can, of course, be extended
// assuming 'customers' is an array of 'Customer' entities retrieved earlier.
var customersQuery = EntityQuery.fromEntities(customers)
.where("Region", FilterQueryOp.NotEquals, null);
Single entities can requeried as well.
// assuming 'customer' is a 'Customer' entity retrieved earlier.
var customerQuery = EntityQuery.fromEntities(customer);
will create a query that will return an array containing a single customer entity.
fromEntityKey
-
entityKey
Creates an EntityQuery for the specified EntityKey.
Returns:
Example:
var empType = metadataStore.getEntityType("Employee");
var entityKey = new EntityKey(empType, 1);
var query = EntityQuery.fromEntityKey(entityKey);
or
// 'employee' is a previously queried employee
var entityKey = employee.entityAspect.getKey();
var query = EntityQuery.fromEntityKey(entityKey);
inlineCount
-
enabled
Returns a query with the 'inlineCount' capability either enabled or disabled. With 'inlineCount' enabled, an additional 'inlineCount' property will be returned with the query results that will contain the number of entities that would have been returned by this query with only the 'where'/'filter' clauses applied, i.e. without any 'skip'/'take' operators applied. For local queries this clause is ignored.
Parameters:
-
enabled
Boolean=trueWhether or not inlineCount capability should be enabled. If this parameter is omitted, true is assumed.
Returns:
Example:
var query = new EntityQuery("Customers")
.take(20)
.orderBy("CompanyName")
.inlineCount(true);
will return the first 20 customers as well as a count of all of the customers in the remote store.
noTracking
-
enabled
Returns a query with the 'noTracking' capability either enabled or disabled. With 'noTracking' enabled, the results of this query will not be coerced into entities but will instead look like raw javascript projections. i.e. simple javascript objects.
Parameters:
-
enabled
Boolean=trueWhether or not the noTracking capability should be enabled. If this parameter is omitted, true is assumed.
Returns:
Example:
var query = new EntityQuery("Customers")
.take(20)
.orderBy("CompanyName")
.noTracking(true);
orderBy
-
propertyPaths
Returns a new query that orders the results of the query by property name. By default sorting occurs is ascending order, but sorting in descending order is supported as well.
Parameters:
-
propertyPaths
String | Array of StringA comma-separated (',') string of property paths or an array of property paths. Each property path can optionally end with " desc" to force a descending sort order. If 'propertyPaths' is either null or omitted then all ordering is removed.
Returns:
Example:
var query = new EntityQuery("Customers")
.orderBy("CompanyName");
or to sort across multiple properties
var query = new EntityQuery("Customers")
.orderBy("Region, CompanyName");
Nested property paths are also supported
var query = new EntityQuery("Products")
.orderBy("Category.CategoryName");
Sorting in descending order is supported via the addition of ' desc' to the end of any property path.
var query = new EntityQuery("Customers")
.orderBy("CompanyName desc");
or
var query = new EntityQuery("Customers")
.orderBy("Region desc, CompanyName desc");
orderByDesc
-
propertyPaths
Returns a new query that orders the results of the query by property name in descending order.
Parameters:
-
propertyPaths
String | Array of StringA comma-separated (',') string of property paths or an array of property paths. If 'propertyPaths' is either null or omitted then all ordering is removed.
Returns:
Example:
var query = new EntityQuery("Customers")
.orderByDesc("CompanyName");
or to sort across multiple properties
var query = new EntityQuery("Customers")
.orderByDesc("Region, CompanyName");
Nested property paths are also supported
var query = new EntityQuery("Products")
.orderByDesc("Category.CategoryName");
select
-
propertyPaths
Returns a new query that selects a list of properties from the results of the original query and returns the values of just these properties. This will be referred to as a projection. If the result of this selection "projection" contains entities, these entities will automatically be added to EntityManager's cache and will be made 'observable'. Any simple properties, i.e. strings, numbers or dates within a projection will not be cached are will NOT be made 'observable'.
Parameters:
-
propertyPaths
String | Array of StringA comma-separated (',') string of property paths or an array of property paths. If 'propertyPaths' is either null or omitted then any existing projection on the query is removed.
Returns:
Example:
Simple data properties can be projected
var query = new EntityQuery("Customers")
.where("CompanyName", "startsWith", "C")
.select("CompanyName");
This will return an array of objects each with a single "CompanyName" property of type string. A similar query could return a navigation property instead
var query = new EntityQuery("Customers")
.where("CompanyName", "startsWith", "C")
.select("Orders");
where the result would be an array of objects each with a single "Orders" property that would itself be an array of "Order" entities. Composite projections are also possible:
var query = new EntityQuery("Customers")
.where("CompanyName", "startsWith", "C")
.select("CompanyName, Orders");
As well as projections involving nested property paths
var query = EntityQuery("Orders")
.where("Customer.CompanyName", "startsWith", "C")
.select("Customer.CompanyName, Customer, OrderDate");
skip
-
count
Returns a new query that skips the specified number of entities when returning results. Any existing 'skip' can be cleared by calling 'skip' with no arguments.
Parameters:
-
count
NumberThe number of entities to return. If omitted or null any existing skip count on the query is removed.
Returns:
Example:
var query = new EntityQuery("Customers")
.where("CompanyName", "startsWith", "C")
.skip(5);
take
-
count
Returns a new query that returns only the specified number of entities when returning results - Same as 'top'.
Any existing take can be cleared by calling take with no arguments.
Parameters:
-
count
NumberThe number of entities to return. If 'count' is either null or omitted then any existing 'take' count on the query is removed.
Returns:
Example:
var query = new EntityQuery("Customers")
.take(5);
top
-
count
Returns a new query that returns only the specified number of entities when returning results. - Same as 'take'. Any existing 'top' can be cleared by calling 'top' with no arguments.
Parameters:
-
count
NumberThe number of entities to return. If 'count' is either null or omitted then any existing 'top' count on the query is removed.
Returns:
Example:
var query = new EntityQuery("Customers")
.top(5);
toType
-
entityType
Specifies the top level EntityType that this query will return. Only needed when a query returns a json result that does not include type information.
Parameters:
-
entityType
String | EntityTypeThe top level entityType that this query will return. This method is only needed when a query returns a json result that does not include type information. If the json result consists of more than a simple entity or array of entities, consider using a JsonResultsAdapter instead.
Returns:
Example:
var query = new EntityQuery()
.from("MyCustomMethod")
.toType("Customer")
using
-
obj
Returns a copy of this EntityQuery with the specified EntityManager, DataService, JsonResultsAdapter, MergeStrategy or FetchStrategy applied.
Parameters:
-
obj
EntityManager | QueryOptions | DataService | MergeStrategy | FetchStrategy | JsonResultsAdapter | Config objectThe object to update in creating a new EntityQuery from an existing one.
Returns:
Example:
'using' can be used to return a new query with a specified EntityManager.
var em = new EntityManager(serviceName);
var query = new EntityQuery("Orders")
.using(em);
or with a specified MergeStrategy
var em = new EntityManager(serviceName);
var query = new EntityQuery("Orders")
.using(MergeStrategy.PreserveChanges);
or with a specified FetchStrategy
var em = new EntityManager(serviceName);
var query = new EntityQuery("Orders")
.using(FetchStrategy.FromLocalCache);
where
-
predicate
Returns a new query with an added filter criteria. Can be called multiple times which means to 'and' with any existing Predicate.
Parameters:
-
predicate
Predicate | Property | Property path, operator, valueCan be either
a single Predicate
or the parameters to create a 'simple' Predicate
- a property name, a property path with '.' as path seperators or a property expression {String}
- an operator {FilterQueryOp|String} Either a FilterQueryOp or it's string representation. Case is ignored
when if a string is provided and any string that matches one of the FilterQueryOp aliases will be accepted.
- a value {Object} - This will be treated as either a property expression or a literal depending on context. In general,
if the value can be interpreted as a property expression it will be, otherwise it will be treated as a literal. In most cases this works well, but you can also force the interpretation by making the value argument itself an object with a 'value' property and an 'isLiteral' property set to either true or false. Breeze also tries to infer the dataType of any literal based on context, if this fails you can force this inference by making the value argument an object with a 'value' property and a 'dataType'property set to one of the breeze.DataType enumeration instances.
- or a null or undefined ( this causes any existing where clause to be removed)
Returns:
Example:
var query = new EntityQuery("Customers")
.where("CompanyName", "startsWith", "C");
This can also be expressed using an explicit FilterQueryOp as
var query = new EntityQuery("Customers")
.where("CompanyName", FilterQueryOp.StartsWith, "C");
or a preconstructed Predicate may be used
var pred = new Predicate("CompanyName", FilterQueryOp.StartsWith, "C");
var query = new EntityQuery("Customers")
.where(pred);
Predicates are often useful when you want to combine multiple conditions in a single filter, such as
var pred = Predicate.create("CompanyName", "startswith", "C").and("Region", FilterQueryOp.Equals, null);
var query = new EntityQuery("Customers")
.where(pred);
More complicated queries can make use of nested property paths
var query = new EntityQuery("Products")
.where("Category.CategoryName", "startswith", "S");
or OData functions - A list of valid OData functions can be found within the Predicate documentation.
var query = new EntityQuery("Customers")
.where("toLower(CompanyName)", "startsWith", "c");
or to be even more baroque
var query = new EntityQuery("Customers")
.where("toUpper(substring(CompanyName, 1, 2))", FilterQueryOp.Equals, "OM");
withParameters
-
parameters
Returns a new query that includes a collection of parameters to pass to the server.
Parameters:
-
parameters
ObjectA parameters object where the keys are the parameter names and the values are the parameter values.
Returns:
Example:
var query = EntityQuery.from("EmployeesFilteredByCountryAndBirthdate")
.withParameters({ BirthDate: "1/1/1960", Country: "USA" });
will call the 'EmployeesFilteredByCountryAndBirthdate' method on the server and pass in 2 parameters. This query will be uri encoded as
{serviceApi}/EmployeesFilteredByCountryAndBirthdate?birthDate=1%2F1%2F1960&country=USA
Parameters may also be mixed in with other query criteria.
var query = EntityQuery.from("EmployeesFilteredByCountryAndBirthdate")
.withParameters({ BirthDate: "1/1/1960", Country: "USA" })
.where("LastName", "startsWith", "S")
.orderBy("BirthDate");
Properties
entityManager
EntityManager
The EntityManager for this query. This may be null and can be set via the 'using' method.
readOnly
orderByClause
OrderByClause
The OrderByClause used by this query.
readOnly
parameters
Object
Any additional parameters that were added to the query via the 'withParameters' method.
readOnly
resourceName
String
The resource name used by this query.
readOnly
resultEntityType
EntityType
The entityType that will be returned by this query. This property will only be set if the 'toType' method was called.
readOnly
skipCount
Integer
The number of entities to 'skip' for this query.
readOnly
takeCount
Integer
The number of entities to 'take' for this query.
readOnly