Class: EntityQuery<T>

Defined in: src/query/entity-query.ts:31

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.

Type Parameters

T

T = any

Constructors

Constructor

new EntityQuery<T>(resourceName?): EntityQuery<T>

Defined in: src/query/entity-query.ts:94

Constructor. Most queries start from the static EntityQuery.from instead, which takes a registered entity class and so gives a typed query:

const query = EntityQuery.from(Customer);   // EntityQuery<Customer>

When a constructor is needed, supply the type argument. As with a type argument on EntityQuery.from(resourceName), nothing checks it against the resource name:

const query = new EntityQuery<Customer>("Customers");

Usually this constructor will be followed by calls to filtering, ordering or selection methods

const query = new EntityQuery<Customer>("Customers")
  .where("companyName", "startsWith", "C")
  .orderBy("region");

Parameters

resourceName?

string | Object

either a resource name or a serialized EntityQuery ( created by EntityQuery.toJSON)

Returns

EntityQuery<T>

Properties

dataService?

optional dataService?: DataService

Defined in: src/query/entity-query.ts:65

The DataService for this query. Read Only

entityManager?

optional entityManager?: EntityManager

Defined in: src/query/entity-query.ts:67

The EntityManager for this query. This may be null and can be set via the 'using' method.

expandClause?

optional expandClause?: ExpandClause

Defined in: src/query/entity-query.ts:46

The ExpandClause used by this query. Read Only

fromEntityType?

optional fromEntityType?: EntityType

Defined in: src/query/entity-query.ts:40

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. Read Only

inlineCountEnabled

inlineCountEnabled: boolean

Defined in: src/query/entity-query.ts:56

Whether an inline count is returned for this query. Read Only

noTrackingEnabled

noTrackingEnabled: boolean

Defined in: src/query/entity-query.ts:58

Whether entity tracking has been disabled for this query. Read Only

orderByClause?

optional orderByClause?: OrderByClause

Defined in: src/query/entity-query.ts:44

The OrderByClause used by this query. Read Only

parameters

parameters: Object

Defined in: src/query/entity-query.ts:54

Any additional parameters that were added to the query via the 'withParameters' method. Read Only

queryOptions?

optional queryOptions?: QueryOptions

Defined in: src/query/entity-query.ts:63

The QueryOptions for this query. Read Only

resourceName?

optional resourceName?: string

Defined in: src/query/entity-query.ts:36

The resource name used by this query. Read Only

resultEntityType

resultEntityType: string | EntityType

Defined in: src/query/entity-query.ts:70

The entityType that will be returned by this query. This property will only be set if the 'toType' method was called. Read Only

selectClause?

optional selectClause?: SelectClause

Defined in: src/query/entity-query.ts:48

The SelectClause used by this query. Read Only

skipCount?

optional skipCount?: number

Defined in: src/query/entity-query.ts:50

The number of entities to 'skip' for this query. Read Only

takeCount?

optional takeCount?: number

Defined in: src/query/entity-query.ts:52

The number of entities to 'take' for this query. Read Only

usePostEnabled

usePostEnabled: boolean

Defined in: src/query/entity-query.ts:60

Whether to send query as the body of a POST request. (Server needs to accomodate POST). Read Only

usesNameOnServer?

optional usesNameOnServer?: boolean

Defined in: src/query/entity-query.ts:72

Whether the query's property paths are the server's names, sent as written. Set by EntityQuery.useNameOnServer. Read Only

wherePredicate?

optional wherePredicate?: Predicate<any>

Defined in: src/query/entity-query.ts:42

The 'where' Predicate used by this query. Read Only

fromEntityNavigation

static fromEntityNavigation: (entity, navigationProperty) => EntityQuery<any>

Defined in: src/query/entity-query.ts:941

Creates an EntityQuery for the specified entity and NavigationProperty.

// 'employee' is a previously queried employee
const query = EntityQuery.fromEntityNavigation(employee, "orders");

will return a query for the "orders" of the specified 'employee'. The NavigationProperty itself may be passed instead of its name:

const ordersNavProp = employee.entityType.getNavigationProperty("orders");
const query = EntityQuery.fromEntityNavigation(employee, ordersNavProp);

Parameters

entity

Entity

The Entity whose navigation property will be queried.

navigationProperty

string | NavigationProperty

The NavigationProperty or name of the NavigationProperty to be queried.

Returns

EntityQuery<any>

Methods

execute()

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

It returns a promise:

const em = new EntityManager(serviceName);
const query = EntityQuery.from(Order).using(em);
const data = await query.execute();   // rejects if the query fails
const orders = data.results;          // Order[]

The callback and errorCallback arguments are deprecated. They still work, but the promise is the supported form and the callbacks will be removed in a future major version.

This method is the same as calling the EntityManager 'executeQuery' method.

const em = new EntityManager(serviceName);
const query = EntityQuery.from(Order);
const data = await em.executeQuery(query);
const orders = data.results;          // Order[]

Param

callback

Deprecated. Function called on success.

Param

errorCallback

Deprecated. Function called on failure.

Call Signature

execute(): Promise<QueryResult<T>>

Defined in: src/query/entity-query.ts:728

Returns

Promise<QueryResult<T>>

Call Signature

execute(callback?, errorCallback?): Promise<QueryResult<T>>

Defined in: src/query/entity-query.ts:730

Parameters

callback?

Callback

errorCallback?

ErrorCallback

Returns

Promise<QueryResult<T>>

Deprecated

Await the returned promise instead of passing callbacks.

executeCount()

executeCount(): Promise<number>

Defined in: src/query/entity-query.ts:791

Executes this query against the server and returns only the number of matching entities, without materializing any of them. Requires an EntityManager, set via EntityQuery.using.

const count = await EntityQuery.from(Order).where("freight", ">", 100).using(em).executeCount();

It is take(0).inlineCount(true) and reads inlineCount off the result, so the server must support inline count.

Returns

Promise<number>

executeLocally()

executeLocally(): T[]

Defined in: src/query/entity-query.ts:774

Executes this query against the local cache. This method requires that an EntityManager have been previously specified via the "using" method.

// assume em is an entityManager already filled with order entities;
const query = EntityQuery.from(Order).using(em);
const orders = query.executeLocally();   // Order[]

Note that calling this method is the same as calling EntityManager.executeQueryLocally.

Returns

T[]

expand()

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'.

const query = EntityQuery.from(Customer)
   .where("companyName", "startsWith", "C")
   .expand("orders");

will return the filtered customers each with its "orders" properties fully resolved. Multiple paths may be specified in an array

const query = EntityQuery.from(Order)
   .expand(["customer", "employee"]);

and nested property paths my be specified as well

const query = EntityQuery.from(Order)
   .expand(["customer", "orderDetails", "orderDetails.product"]);

The paths may also be separated by a ',' in a single string, "customer, employee", but those paths are not checked.

Param

propertyPaths

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.

Call Signature

expand(propertyPaths): EntityQuery<T>

Defined in: src/query/entity-query.ts:540

Parameters

propertyPaths

NavigationPath<T> | NavigationPath<T>[]

Returns

EntityQuery<T>

Call Signature

expand<P>(propertyPaths): EntityQuery<T>

Defined in: src/query/entity-query.ts:541

Type Parameters

P

P extends string

Parameters

propertyPaths

P extends `${string},${string}` ? P : string extends P ? P : never

Returns

EntityQuery<T>

Call Signature

expand<P>(propertyPaths): EntityQuery<T>

Defined in: src/query/entity-query.ts:542

Type Parameters

P

P extends string

Parameters

propertyPaths

string extends P ? P[] : never

Returns

EntityQuery<T>

Call Signature

expand(propertyPaths?): EntityQuery<T>

Defined in: src/query/entity-query.ts:543

Parameters

propertyPaths?

undefined

Returns

EntityQuery<T>

from()

from(resourceName): EntityQuery<T>

Defined in: src/query/entity-query.ts:135

Specifies the resource to query for this EntityQuery.

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

is the same as

const query = new EntityQuery("Customers");

For a typed query, use the static EntityQuery.from(Customer) instead.

Parameters

resourceName

string

The resource to query.

Returns

EntityQuery<T>

inlineCount()

inlineCount(enabled?): EntityQuery<T>

Defined in: src/query/entity-query.ts:619

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.

const query = EntityQuery.from(Customer)
   .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.

Parameters

enabled?

boolean

(default = true) Whether or not inlineCount capability should be enabled. If this parameter is omitted, true is assumed.

Returns

EntityQuery<T>

noTracking()

noTracking(enabled?): EntityQuery<T>

Defined in: src/query/entity-query.ts:654

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.

const query = EntityQuery.from(Customer)
    .take(20)
    .orderBy("companyName")
    .noTracking(true);

Parameters

enabled?

boolean

(default = true) Whether or not the noTracking capability should be enabled. If this parameter is omitted, true is assumed.

Returns

EntityQuery<T>

orderBy()

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. OrderBy clauses may be chained.

const query = EntityQuery.from(Customer)
   .orderBy("companyName");

or to sort across multiple properties

const query = EntityQuery.from(Customer)
   .orderBy(["region", "companyName"]);

A comma-separated string, "region, companyName", is also accepted, but its paths are not checked.

Nested property paths are also supported

const query = EntityQuery.from(Product)
   .orderBy("category.categoryName");

Sorting in descending order is supported via the addition of ' desc' to the end of any property path.

const query = EntityQuery.from(Customer)
   .orderBy("companyName desc");

const query = EntityQuery.from(Customer)
   .orderBy(["region desc", "companyName desc"]);

Param

propertyPaths

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.

Param

isDescending

If specified, overrides all of the embedded 'desc' tags in the previously specified property paths.

Call Signature

orderBy(propertyPaths, isDescending?): EntityQuery<T>

Defined in: src/query/entity-query.ts:357

Parameters

propertyPaths

OrderByPath<T> | OrderByPath<T>[]

isDescending?

boolean

Returns

EntityQuery<T>

Call Signature

orderBy<P>(propertyPaths, isDescending?): EntityQuery<T>

Defined in: src/query/entity-query.ts:361

Type Parameters

P

P extends string

Parameters

propertyPaths

P extends `${string},${string}` ? P : string extends P ? P : never

isDescending?

boolean

Returns

EntityQuery<T>

Call Signature

orderBy(propertyPaths?, isDescending?): EntityQuery<T>

Defined in: src/query/entity-query.ts:363

Parameters

propertyPaths?

undefined

isDescending?

boolean

Returns

EntityQuery<T>

Call Signature

orderBy<P>(propertyPaths, isDescending?): EntityQuery<T>

Defined in: src/query/entity-query.ts:364

Type Parameters

P

P extends string

Parameters

propertyPaths

string extends P ? P[] : never

isDescending?

boolean

Returns

EntityQuery<T>

orderByDesc()

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

const query = EntityQuery.from(Customer)
   .orderByDesc("companyName");

or to sort across multiple properties

const query = EntityQuery.from(Customer)
   .orderByDesc(["region", "companyName"]);

Nested property paths are also supported

const query = EntityQuery.from(Product)
   .orderByDesc("category.categoryName");

Param

propertyPaths

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.

Call Signature

orderByDesc(propertyPaths): EntityQuery<T>

Defined in: src/query/entity-query.ts:413

Parameters

propertyPaths

OrderByPath<T> | OrderByPath<T>[]

Returns

EntityQuery<T>

Call Signature

orderByDesc<P>(propertyPaths): EntityQuery<T>

Defined in: src/query/entity-query.ts:415

Type Parameters

P

P extends string

Parameters

propertyPaths

P extends `${string},${string}` ? P : string extends P ? P : never

Returns

EntityQuery<T>

Call Signature

orderByDesc<P>(propertyPaths): EntityQuery<T>

Defined in: src/query/entity-query.ts:416

Type Parameters

P

P extends string

Parameters

propertyPaths

string extends P ? P[] : never

Returns

EntityQuery<T>

select()

Call Signature

select(propertyPaths): EntityQuery<any>

Defined in: src/query/entity-query.ts:483

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'.

Simple data properties can be projected

const query = EntityQuery.from(Customer)
    .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

const query = EntityQuery.from(Customer)
   .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:

const query = EntityQuery.from(Customer)
   .where("companyName", "startsWith", "C")
   .select("companyName, orders");

As well as projections involving nested property paths

const query = EntityQuery.from(Order)
   .where("customer.companyName", "startsWith", "C")
   .select("customer.companyName, customer, orderDate");

The projected query is an EntityQuery<any>: its results are no longer entities of the queried type.

Parameters

propertyPaths

SelectPath<T> | SelectPath<T>[]

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

EntityQuery<any>

Call Signature

select<P>(propertyPaths): EntityQuery<any>

Defined in: src/query/entity-query.ts:486

Simple data properties can be projected

const query = EntityQuery.from(Customer)
    .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

const query = EntityQuery.from(Customer)
   .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:

const query = EntityQuery.from(Customer)
   .where("companyName", "startsWith", "C")
   .select("companyName, orders");

As well as projections involving nested property paths

const query = EntityQuery.from(Order)
   .where("customer.companyName", "startsWith", "C")
   .select("customer.companyName, customer, orderDate");

The projected query is an EntityQuery<any>: its results are no longer entities of the queried type.

Type Parameters

P

P extends string

Parameters

propertyPaths

P extends `${string},${string}` ? P : string extends P ? P : never

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

EntityQuery<any>

Call Signature

select(propertyPaths?): EntityQuery<any>

Defined in: src/query/entity-query.ts:487

Simple data properties can be projected

const query = EntityQuery.from(Customer)
    .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

const query = EntityQuery.from(Customer)
   .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:

const query = EntityQuery.from(Customer)
   .where("companyName", "startsWith", "C")
   .select("companyName, orders");

As well as projections involving nested property paths

const query = EntityQuery.from(Order)
   .where("customer.companyName", "startsWith", "C")
   .select("customer.companyName, customer, orderDate");

The projected query is an EntityQuery<any>: its results are no longer entities of the queried type.

Parameters

propertyPaths?

undefined

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

EntityQuery<any>

Call Signature

select<P>(propertyPaths): EntityQuery<any>

Defined in: src/query/entity-query.ts:488

Simple data properties can be projected

const query = EntityQuery.from(Customer)
    .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

const query = EntityQuery.from(Customer)
   .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:

const query = EntityQuery.from(Customer)
   .where("companyName", "startsWith", "C")
   .select("companyName, orders");

As well as projections involving nested property paths

const query = EntityQuery.from(Order)
   .where("customer.companyName", "startsWith", "C")
   .select("customer.companyName, customer, orderDate");

The projected query is an EntityQuery<any>: its results are no longer entities of the queried type.

Type Parameters

P

P extends string

Parameters

propertyPaths

string extends P ? P[] : never

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

EntityQuery<any>

skip()

skip(count?): EntityQuery<T>

Defined in: src/query/entity-query.ts:506

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.

const query = EntityQuery.from(Customer)
  .where("companyName", "startsWith", "C")
  .skip(5);

Parameters

count?

number

The number of entities to skip over. If omitted or null any existing skip count on the query is removed.

Returns

EntityQuery<T>

take()

take(count?): EntityQuery<T>

Defined in: src/query/entity-query.ts:535

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.

const query = EntityQuery.from(Customer)
   .take(5);

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

EntityQuery<T>

toJSON()

toJSON(): Record<string, any>

Defined in: src/query/entity-query.ts:805

Returns the serializable form of this query: its resource name, clauses, parameters and options, with client property names. JSON.stringify calls it, and passing the parsed JSON to the EntityQuery constructor recreates the query. The EntityManager and DataService are not included.

Returns

Record<string, any>

top()

top(count?): EntityQuery<T>

Defined in: src/query/entity-query.ts:521

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.

const query = EntityQuery.from(Customer)
   .top(5);

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

EntityQuery<T>

toType()

Call Signature

toType<U>(entityCtor): EntityQuery<U>

Defined in: src/query/entity-query.ts:207

Specifies the top level type this query will return, as a registered constructor. The query then carries that type, so its results are typed - and because the constructor is resolved through metadata, this is checked, unlike a type argument on EntityQuery.from:

const query = EntityQuery.from("CustomersAndOrders").toType(Customer);   // EntityQuery<Customer>

Type Parameters

U

U extends Entity

Parameters

entityCtor

() => U

A constructor registered for the EntityType this query will return.

Returns

EntityQuery<U>

Call Signature

toType(entityType): EntityQuery<any>

Defined in: src/query/entity-query.ts:220

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, or when using a resource name that is not associated to an EntityType.

const query = EntityQuery.from("MyCustomMethod")
  .toType("Customer");

Passing the registered class instead, as in toType(Customer), also types the query.

Parameters

entityType

string | EntityType

The top level EntityType that this query will return.

Returns

EntityQuery<any>

useNameOnServer()

useNameOnServer(usesNameOnServer?): EntityQuery<T>

Defined in: src/query/entity-query.ts:637

Returns a query whose property paths are the server's names rather than the client's, so Breeze sends them as written instead of translating them with the MetadataStore's naming convention.

EntityQuery.from('Customers').where('CompanyName', 'startsWith', 'A').useNameOnServer();

The query is built from a resource name because a typed query, EntityQuery.from(Customer), checks its paths against the client's names and would reject 'CompanyName'. Only the query sent to the server is affected: run against the cache, a query works on the client's objects and needs the client's names.

Parameters

usesNameOnServer?

boolean

(default = true)

Returns

EntityQuery<T>

usePost()

usePost(enabled?): EntityQuery<T>

Defined in: src/query/entity-query.ts:673

Returns a query with the usePost capability either enabled or disabled. With usePost enabled, the query is sent as a POST request (instead of GET) and the query expression will be sent as JSON in the body of the post. Note that the server must be able to parse the body of the request; otherwise the query expression will be ignored.

const query = EntityQuery.from(Order)
    .where("freight", "gt", 100)
    .usePost(true);

results in a POST request to {host}/{path}/Orders with body {"where": {"Freight":{"gt":100}}}

Parameters

enabled?

boolean

(default = true) Whether or not usePost should be enabled. If this parameter is omitted, true is assumed.

Returns

EntityQuery<T>

using()

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

// 'using' can be used to return a new query with a specified EntityManager.
const em = new EntityManager(serviceName);
const query = EntityQuery.from(Order)
  .using(em);

or with a specified MergeStrategy

const query = EntityQuery.from(Order)
  .using(MergeStrategy.PreserveChanges);

or with a specified FetchStrategy

const query = EntityQuery.from(Order)
  .using(FetchStrategy.FromLocalCache);

Param

obj

The object to update in creating a new EntityQuery from an existing one.

Call Signature

using(obj): EntityQuery<T>

Defined in: src/query/entity-query.ts:679

Parameters

obj

EntityManager

Returns

EntityQuery<T>

Call Signature

using(obj): EntityQuery<T>

Defined in: src/query/entity-query.ts:680

Parameters

obj

DataService

Returns

EntityQuery<T>

Call Signature

using(obj): EntityQuery<T>

Defined in: src/query/entity-query.ts:681

Parameters

obj

JsonResultsAdapter

Returns

EntityQuery<T>

Call Signature

using(obj): EntityQuery<T>

Defined in: src/query/entity-query.ts:682

Parameters

obj

QueryOptions

Returns

EntityQuery<T>

Call Signature

using(obj): EntityQuery<T>

Defined in: src/query/entity-query.ts:683

Parameters

obj

MergeStrategy

Returns

EntityQuery<T>

Call Signature

using(obj): EntityQuery<T>

Defined in: src/query/entity-query.ts:684

Parameters

obj

FetchStrategy

Returns

EntityQuery<T>

where()

Returns a new query with an added filter criteria; Can be called multiple times which means to 'and' with any existing Predicate or can be called with null to clear all predicates.

const query = EntityQuery.from(Customer)
    .where("companyName", "startsWith", "C");

or in object form

const query = EntityQuery.from(Customer)
    .where({ companyName: { startsWith: "C" } });

This can also be expressed using an explicit FilterQueryOp (the operator is then not checked against the property's type) as

const query = EntityQuery.from(Customer)
    .where("companyName", FilterQueryOp.StartsWith, "C");

or a preconstructed Predicate may be used

const p = Predicate.for(Customer);
const query = EntityQuery.from(Customer).where(p("companyName", "startsWith", "C"));

Predicates are often useful when you want to combine multiple conditions in a single filter, such as

const pred = p("companyName", "startsWith", "C").and(p("region", "eq", null));
const query = EntityQuery.from(Customer)
    .where(pred);

More complicated queries can make use of nested property paths

const query = EntityQuery.from(Product)
    .where("category.categoryName", "startsWith", "S");

or query functions - A list of valid functions can be found within the Predicate documentation.

const query = EntityQuery.from(Customer)
    .where("toLower(companyName)", "startsWith", "c");

or to be even more baroque

const query = EntityQuery.from(Customer)
    .where("toUpper(substring(companyName, 1, 2))", FilterQueryOp.Equals, "OM");

Param

predicate

Can be either

a single Predicate
the parameters to create a 'simple' Predicate
- a property name, a property path with '.' as path seperators or a property expression
- an operator - 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 DataType enumeration instances.
a null or undefined ( this causes any existing where clause to be removed)

Call Signature

where<P>(collection, quantifier, predicate): EntityQuery<T>

Defined in: src/query/entity-query.ts:236

Type Parameters

P

P extends string

Parameters

collection

P

quantifier

QuantifierOp | FilterQueryOp

predicate

Predicate<CollectionElement<T, P>>

Returns

EntityQuery<T>

Call Signature

where(collection, quantifier, property, quantifier2, predicate): EntityQuery<T>

Defined in: src/query/entity-query.ts:238

Parameters

collection

CollectionPath<T>

quantifier

QuantifierOp | FilterQueryOp

property

string

quantifier2

QuantifierOp | FilterQueryOp

predicate

Predicate

Returns

EntityQuery<T>

Call Signature

where(predicate): EntityQuery<T>

Defined in: src/query/entity-query.ts:244

Parameters

predicate

WhereObject<T>

Returns

EntityQuery<T>

Call Signature

where(predicate?): EntityQuery<T>

Defined in: src/query/entity-query.ts:245

Parameters

predicate?

Predicate<T>

Returns

EntityQuery<T>

Call Signature

where<O>(property, operator, value): EntityQuery<T>

Defined in: src/query/entity-query.ts:251

Type Parameters

O

O extends string

Parameters

property

PropertyPath<T>

operator

string extends O ? O : never

value

any

Returns

EntityQuery<T>

Call Signature

where<P>(property, operator, value): EntityQuery<T>

Defined in: src/query/entity-query.ts:253

Type Parameters

P

P extends string

Parameters

property

P extends `${string}(${string})` ? P : string extends P ? P : never

operator

string | FilterQueryOp

value

any

Returns

EntityQuery<T>

Call Signature

where<P>(collection, quantifier, property, operator, value): EntityQuery<T>

Defined in: src/query/entity-query.ts:255

Type Parameters

P

P extends string

Parameters

collection

string extends P ? P : never

quantifier

string | FilterQueryOp

property

string

operator

string | FilterQueryOp

value

any

Returns

EntityQuery<T>

Call Signature

where<P2>(collection, quantifier, property, operator, value): EntityQuery<T>

Defined in: src/query/entity-query.ts:258

Type Parameters

P2

P2 extends string

Parameters

collection

CollectionPath<T>

quantifier

string | FilterQueryOp

property

string extends P2 ? P2 : never

operator

string | FilterQueryOp

value

any

Returns

EntityQuery<T>

Call Signature

where<O2>(collection, quantifier, property, operator, value): EntityQuery<T>

Defined in: src/query/entity-query.ts:261

Type Parameters

O2

O2 extends string

Parameters

operator

string extends O2 ? O2 : never

value

any

Returns

EntityQuery<T>

Call Signature

where(property, filterop, property2, filterop2, property3, filterop3, value): EntityQuery<T>

Defined in: src/query/entity-query.ts:264

Parameters

property

string

filterop

string

property2

string

filterop2

string

property3

string

filterop3

string

value

any

Returns

EntityQuery<T>

Call Signature

where(anArray): EntityQuery<T>

Defined in: src/query/entity-query.ts:265

Parameters

anArray

RecursiveArray<string | number | FilterQueryOp | Predicate<any>>

Returns

EntityQuery<T>

Call Signature

where<P, O>(property, operator, value): EntityQuery<T>

Defined in: src/query/entity-query.ts:270

Type Parameters

P

P extends string

O

O extends EqualityOps | ComparisonOps | StringOps | FilterQueryOp | "in"

Parameters

property

P

operator

O

value

FilterValueFor<T, PropertyValue<T, P>, O>

Returns

EntityQuery<T>

Call Signature

where<P, P2, O2>(collection, quantifier, property, operator, value): EntityQuery<T>

Defined in: src/query/entity-query.ts:272

Type Parameters

P

P extends string

P2

P2 extends string

O2

O2 extends EqualityOps | ComparisonOps | StringOps | FilterQueryOp | "in"

Parameters

collection

P

quantifier

QuantifierOp

property

P2

operator

O2

value

FilterValueFor<CollectionElement<T, P>, PropertyValue<CollectionElement<T, P>, P2>, O2>

Returns

EntityQuery<T>

withParameters()

withParameters(parameters): EntityQuery<T>

Defined in: src/query/entity-query.ts:600

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

const query = EntityQuery.from("EmployeesFilteredByCountryAndBirthdate")
   .toType(Employee)
   .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.

const query = EntityQuery.from("EmployeesFilteredByCountryAndBirthdate")
   .toType(Employee)
   .withParameters({ birthDate: "1/1/1960", country: "USA" })
   .where("lastName", "startsWith", "S")
   .orderBy("birthDate");

Parameters

parameters

Object

A parameters object where the keys are the parameter names and the values are the parameter values.

Returns

EntityQuery<T>

from()

Call Signature

static from<U>(entityCtor): EntityQuery<U>

Defined in: src/query/entity-query.ts:157

Creates a 'base' entityQuery, either for a registered entity class or for a resource name.

Given a class, the resource name comes from the metadata and the query carries the type, so the results are typed:

const query = EntityQuery.from(Customer);            // EntityQuery<Customer>
const custs = (await query.using(em).execute()).results;   // Customer[]

The class must be registered with MetadataStore.registerEntityTypeCtor; that is what tells Breeze which type it stands for, and an unregistered class throws.

A resource name may be given instead; see the other signature.

Type Parameters

U

U extends Entity

Parameters

entityCtor

() => U

A constructor registered for the EntityType to query.

Returns

EntityQuery<U>

Call Signature

static from<U>(resourceName): EntityQuery<U>

Defined in: src/query/entity-query.ts:183

Creates a 'base' entityQuery for the specified resource name. Prefer passing a registered entity class, as in EntityQuery.from(Customer), which gives a typed query.

Given a resource name, the query is untyped, as it always was:

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

is the same as

const query = new EntityQuery("Customers");

A type argument may be supplied with a resource name, for a projection or a named server query that no entity class describes. Nothing checks it against the resource - it is an assertion, not a guarantee, and EntityQuery.from<Customer>("Orders") compiles:

const query = EntityQuery.from<CustomerDto>("CompanyNamesAndIds");

U is the caller's claim about what the resource returns; nothing checks it against the name. It defaults to any, so from("Customers") behaves exactly as it always has.

Type Parameters

U

U = any

Parameters

resourceName

string

The resource to query.

Returns

EntityQuery<U>

fromEntities()

Static method that 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.

Works for a single entity or an array of entities of the SAME type. Does not work for an array of entities of different types.

// assuming 'customers' is an array of 'Customer' entities retrieved earlier.
const customersQuery = EntityQuery.fromEntities(customers);   // EntityQuery<Customer>

The resulting query can, of course, be extended

// assuming 'customers' is an array of 'Customer' entities retrieved earlier.
const customersQuery = EntityQuery.fromEntities(customers)
  .where("region", "ne", null);

Single entities can requeried as well.

// assuming 'customer' is a 'Customer' entity retrieved earlier.
const customerQuery = EntityQuery.fromEntities(customer);

will create a query that will return an array containing a single customer entity.

Param

entities

The entities for which we want to create an EntityQuery.

Call Signature

static fromEntities<U>(entity): EntityQuery<QueriedAs<U>>

Defined in: src/query/entity-query.ts:848

Type Parameters

U

U extends Entity

Parameters

entity

U

Returns

EntityQuery<QueriedAs<U>>

Call Signature

static fromEntities<U>(entities): EntityQuery<QueriedAs<U>>

Defined in: src/query/entity-query.ts:849

Type Parameters

U

U extends Entity

Parameters

entities

U[]

Returns

EntityQuery<QueriedAs<U>>

fromEntityKey()

static fromEntityKey(entityKey): EntityQuery<any>

Defined in: src/query/entity-query.ts:917

Creates an EntityQuery for the specified EntityKey.

const entityKey = new EntityKey(Employee, 1);
const query = EntityQuery.fromEntityKey(entityKey);

// 'employee' is a previously queried employee
const entityKey = employee.entityAspect.getKey();
const query = EntityQuery.fromEntityKey(entityKey);

Parameters

entityKey

EntityKey

The EntityKey for which a query will be created.

Returns

EntityQuery<any>

promises

Class: EntityQuery<T> ​

Type Parameters ​

T ​

Constructors ​

Constructor ​

Parameters ​

resourceName? ​

Returns ​

Properties ​

dataService? ​

entityManager? ​

expandClause? ​

fromEntityType? ​

inlineCountEnabled ​

noTrackingEnabled ​

orderByClause? ​

parameters ​

queryOptions? ​

resourceName? ​

resultEntityType ​

selectClause? ​

skipCount? ​

takeCount? ​

usePostEnabled ​

usesNameOnServer? ​

wherePredicate? ​

fromEntityNavigation ​

Parameters ​

entity ​

navigationProperty ​

Returns ​

Methods ​

execute() ​

Param ​

Param ​

Call Signature ​

Returns ​

Call Signature ​

Parameters ​

callback? ​

errorCallback? ​

Returns ​

Deprecated ​

executeCount() ​

Returns ​

executeLocally() ​

Returns ​

expand() ​

Param ​

Call Signature ​

Parameters ​

propertyPaths ​

Returns ​

Call Signature ​

Type Parameters ​

P ​

Parameters ​

propertyPaths ​

Returns ​

Call Signature ​

Type Parameters ​

P ​

Parameters ​

propertyPaths ​

Returns ​

Call Signature ​

Parameters ​

propertyPaths? ​

Returns ​

from() ​

Parameters ​

resourceName ​

Returns ​

inlineCount() ​

Parameters ​

enabled? ​

Returns ​

noTracking() ​

Parameters ​

Class: EntityQuery<T>

Type Parameters

T

Constructors

Constructor

Parameters

resourceName?

Returns

Properties

dataService?

entityManager?

expandClause?

fromEntityType?

inlineCountEnabled

noTrackingEnabled

orderByClause?

parameters

queryOptions?

resourceName?

resultEntityType

selectClause?

skipCount?

takeCount?

usePostEnabled

usesNameOnServer?

wherePredicate?

fromEntityNavigation

Parameters

entity

navigationProperty

Returns

Methods

execute()

Param

Param

Call Signature

Returns

Call Signature

Parameters

callback?

errorCallback?

Returns

Deprecated

executeCount()

Returns

executeLocally()

Returns

expand()

Param

Call Signature

Parameters

propertyPaths

Returns

Call Signature

Type Parameters

P

Parameters

propertyPaths

Returns

Call Signature

Type Parameters

P

Parameters

propertyPaths

Returns

Call Signature

Parameters

propertyPaths?

Returns

from()

Parameters

resourceName

Returns

inlineCount()

Parameters

enabled?

Returns

noTracking()

Parameters

enabled?