Chinese Documentation : Querying data

Icon

Methods of models in the AngularJS client have a different signature than those of the Node API. For more information, see AngularJS SDK API.

 

See also: See also: Querying related models.

Overview

A query is a read operation on models that returns a set of data or results.   You can query LoopBack models using a Node API and a REST API, using filters, as outlined in the following table.  Filters specify critera for the returned data set. The capabilities and options of the two APIs are the same–the only difference is the syntax used in HTTP requests versus Node function calls.  In both cases, LoopBack models return JSON.

QueryModel API (Node)REST API

Find all model instances using specified filters. 

 

find(filter, callback)

Where filter is a JSON object containing the query filters.

See Filters below.

 GET /modelName?filter...

See Model REST API - Find matching instances.

See Filters  below.

Find first model instance using specified filters.

findOne(filter, callback)

Where filter is a JSON object containing the query filters.

See Filters  below.

GET /modelName/findOne?filter...

See Model REST API - Find first instance

See Filters  below.

Find instance by ID.findById() 

GET /modelName/modelID

See Model REST API - Find instance by ID.

REVIEW COMMENT from Rand
Consider adding something like this http://docs.mongodb.org/manual/reference/sql-comparison/
Icon

A REST query must include the literal string "filter" in the URL query string. The Node API call does not include the literal string "filter" in the JSON.

LoopBack supports the following kinds of filters:

See Filters below for more information.

Examples

See additional examples of each kind of filter in the individual articles on filters (for example Where过滤器).

An example of using the find() method with both a where and a limit filter:

Account.find({where: {name: 'John'}, limit: 3}, function(err, accounts) { ... });

Equivalent using REST:

/accounts?filter[where][name]=John&filter[limit]=3

Filters

In both REST and Node API, you can use any number of filters to define a query.  The following table describes the filter types:

Filter typeTypeDescription
fieldsObject, Array, or String

Specify fields to include in or exclude from the response.

See fields(字段)过滤器.

includeString, Object, or Array

Include results from related models, for relations such as belongsTo and hasMany.

See Include(加载导航属性)过滤器.

limitNumber

Limit the number of instances to return.

See Limit(返回结果数限制)过滤器.

orderString

Specify sort order: ascending or descending.

See Order(排序)过滤器.

skip (offset)Number

Skip the specified number of instances.

See Skip过滤器.

whereObject

Specify search criteria; similar to a WHERE clause in SQL.

See Where过滤器.

REST syntax

Specify filters in the HTTP query string:

?filterfilterType=spec&filterType=spec....

See https://github.com/hapijs/qs for more details.

The number of filters that you can apply to a single request is limited only by the maximum URL length, which generally depends on the client used.

Icon

There is no equal sign after ?filter in the query string; for example
http://localhost:3000/api/books?filter[where][id]=1 

Node syntax

Specify filters as the first argument to find() and findOne()

{ filterType: spec, filterType: spec, ... }

There is no theoretical limit on the number of filters you can apply.

Where:

  • filterType is the filter: where, include, order, limit, skip, or fields.
  • spec is the specification of the filter: for example for a where filter, this is a logical condition that the results must match; for an include filter it specifies the related fields to include.

Using "stringified" JSON in REST queries

Instead of the standard REST syntax described above, you can also use "stringified JSON" in REST queries.  To do this, simply use the JSON specified for the Node syntax, as follows:

?filter={ Stringified-JSON } 

where Stringified-JSON is the stringified JSON from Node syntax.  However, in the JSON all text keys/strings must be enclosed in quotes (").

Icon

When using stringified JSON, you must use an equal sign after ?filter in the query string; for example
http://localhost:3000/api/books?filter={%22where%22:{%22id%22:2}} 

For example:

GET /api/activities/findOne?filter={"where":{"id":1234}}