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
- 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:
-
callbackFunctionFunction called on success.
successFunction([data])-
[data]Object optional-
resultsArray of Entity -
queryEntityQueryThe original query -
XHRXMLHttpRequestThe raw XMLHttpRequest returned from the server. -
inlineCountIntegerOnly 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.
-
-
-
errorCallbackFunctionFunction called on failure.
failureFunction([error])-
[error]Error optionalAny error that occured wrapped into an Error object.
-
[query]optionalThe query that caused the error. -
[XHR]XMLHttpRequest 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:
-
propertyPathsString | 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
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:
-
resourceNameStringThe 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:
-
resourceNameStringThe 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:
-
entitiesEntity | 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:
-
enabledBoolean=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.
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:
-
propertyPathsString | 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.
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:
-
propertyPathsString | Array of StringA comma-separated (',') string of property paths or an array of property paths.
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:
-
propertyPathsString | Array of StringA comma-separated (',') string of property paths or an array of property paths.
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.
Parameters:
-
countNumberThe number of entities to return. If omitted this clears the
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'
Parameters:
-
countNumberThe number of entities to return.
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'.
Parameters:
-
countNumberThe number of entities to return.
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:
-
entityTypeString | 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:
-
objEntityManager | 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:
-
predicatePredicate | 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 setting the next parameter 'valueIsLiteral' to true.
- an optional [valueIsLiteral] {Boolean} parameter - Used to force the 'value' parameter to be treated as a literal - otherwise this will be inferred based on the context.
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:
-
parametersObjectA 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 'EmployeesFilteredByCountryAndBirthdata' 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
skipCount
Integer
The number of entities to 'skip' for this query.
readOnly
takeCount
Integer
The number of entities to 'take' for this query.
readOnly
