Show:

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.

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
)
Promise async

Executes this query. This method requires that an EntityManager has been previously specified via the "using" method.

Parameters:

  • callback Function

    Function called on success.

    successFunction([data])
    • [data] Object optional
      • results Array of Entity
      • query EntityQuery
        The original query
      • httpResponse HttpResponse
        The HttpResponse returned from the server.
      • inlineCount Integer
        Only 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 Function

    Function called on failure.

    failureFunction([error])
    • [error] Error optional

      Any error that occured wrapped into an Error object.

      • [query] optional
        The query that caused the error.
      • [httpResponse] HttpResponse optional
        The 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
)
EntityQuery chainable

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 String

    A 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
)
EntityQuery static chainable

This is a static version of the "from" method and it creates a 'base' entityQuery for the specified resource name.

Parameters:

  • resourceName String

    The resource to query.

Returns:

Example:

var query = EntityQuery.from("Customers");

is the same as

var query = new EntityQuery("Customers");

from

(
  • resourceName
)
EntityQuery chainable

Specifies the resource to query for this EntityQuery.

Parameters:

  • resourceName String

    The resource to query.

Returns:

Example:

var query = new EntityQuery()
    .from("Customers");

is the same as

var query = new EntityQuery("Customers");

fromEntities

(
  • entities
)
EntityQuery static chainable

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 Entity

    The 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
)
EntityQuery static chainable

Creates an EntityQuery for the specified EntityKey.

Parameters:

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);

fromEntityNavigation

(
  • entity
  • navigationProperty
)
EntityQuery static chainable

Creates an EntityQuery for the specified entity and NavigationProperty.

Parameters:

  • entity Entity

    The Entity whose navigation property will be queried.

  • navigationProperty NavigationProperty | String

    The NavigationProperty or name of the NavigationProperty to be queried.

Returns:

Example:

// 'employee' is a previously queried employee
var ordersNavProp = employee.entityType.getProperty("Orders");
var query = EntityQuery.fromEntityNavigation(employee, ordersNavProp);

will return a query for the "Orders" of the specified 'employee'.

inlineCount

(
  • enabled
)
EntityQuery chainable

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=true

    Whether 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
)
EntityQuery chainable

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=true

    Whether 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
)
EntityQuery chainable

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 String

    A 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
)
EntityQuery chainable

Returns a new query that orders the results of the query by property name in descending order.

Parameters:

  • propertyPaths String | Array of String

    A 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
)
EntityQuery chainable

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 String

    A 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
)
EntityQuery chainable

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 Number

    The 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
)
EntityQuery chainable

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 Number

    The 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
)
EntityQuery chainable

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 Number

    The 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
)
EntityQuery chainable

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 | EntityType

    The 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
)
EntityQuery chainable

Returns a copy of this EntityQuery with the specified EntityManager, DataService, JsonResultsAdapter, MergeStrategy or FetchStrategy applied.

Parameters:

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
)
EntityQuery chainable

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, value

    Can 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
)
EntityQuery chainable

Returns a new query that includes a collection of parameters to pass to the server.

Parameters:

  • parameters Object

    A 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

fromEntityType

EntityType

The entityType that is associated with the 'from' clause ( resourceName) of the query. This is only guaranteed to be be set AFTER the query has been executed because it depends on the MetadataStore associated with the EntityManager that the query was executed against. This value may be null if the entityType cannot be associated with a resourceName.

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

queryOptions

QueryOptions

The QueryOptions for this query.

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

wherePredicate

Predicate

The 'where' predicate used by this query.

readOnly