query (search)

Collection.query(dbId, collectionName[, params][, token])

Queries (searches) are a list of objects from a specified collection.

Parameters

The method has the following parameters:

Argument

Description

Required

dbApiKey

String with database API key.

Yes.

collectionName

String with name of database collection.

Yes.

params

JSON object that contains request parameters:

criteria – JSON – queries the object that was built in accordance with the mongo querying documentation.
skip – integer – parameter indicating how many objects should be skipped before including objects into the response.

  • limit – integer – parameter indicating how many objects should be included in response.
    count – boolean – parameter indicating whether to include or not include the number of selected objects in the response;
    sort – string – list of fields names split by commas that indicate order of objects in response.
    include – string – parameter indicating whether the referenced object should or shouldn’t be included.
    proj* – JSON – projection object that was built in accordance with the documentation of mongo querying.

Yes.

token

String with user token or database Master key.

No. Only required if the collection is secured.

👍

Request Limitation

By default, 100 records are returned from the database.
To increase the query up to 1500 records, set the limit field in the params argument: var params = { limit:1500 }.

Response

A JSON object with a list of objects contained in the collection according to the request:

[{
   "_id":<object_id>,
   <colName>:<value>,
   "_createdAt":{"$date":<create_date>},
   "_updatedAt":{"$date":<update>}
}, 
...]

Examples

This example shows how to search in column lastName for Lee.

var dbApiKey = "c33010af-f263-4443-9897-c2ffaf522956";
var params = {};
params.criteria = {
   "lastName": {
      "$eq": "Lee"
   }
};
var result = Collection.query(dbApiKey, "Student", params);
[
    {
        "major": {
            "name": "English"
        },
        "isTransferStudent": true,
        "courses": [
            300,
            305
        ],
        "lastName": "Lee",
        "firstName": "Anna",
        "_id": "57a52796e4b03647ddae32a5",
        "_updatedAt": {
            "$date": "2016-08-08T19:11:36.301Z"
        },
        "toAddress": {
            "collName": "Address",
            "_id": "57a5199be4b03647ddae3297"
        },
        "_createdAt": {
            "$date": "2016-08-05T23:56:06.051Z"
        }
    },
    {
        "isTransferStudent": true,
        "_updatedAt": {
            "$date": "2016-08-08T20:46:23.833Z"
        },
        "toAddress": {
            "collName": "Address",
            "_id": "57a52992e4b03647ddae32a8"
        },
        "lastName": "Lee",
        "courses": [
            100,
            101
        ],
        "firstName": "Sarah",
        "_id": "57a8ed82e4b081a83615fc33",
        "major": {
            "name": "Chemistry"
        },
        "_createdAt": {
            "$date": "2016-08-08T20:37:22.486Z"
        }
    }
]
The following examples is the same as the first one but now with a session token:
var user = DatabaseUser.login("c33010af-f263-4443-9897-c2ffaf522956", "admin", "123");

var dbApiKey = "c33010af-f263-4443-9897-c2ffaf522956";
var params = {};
params.criteria = {
   "lastName": {
      "$eq": "Lee"
   }
};
var result = Collection.query(dbApiKey, "Student", params, user.sesssionToken);
[
    {
        "major": {
            "name": "English"
        },
        "isTransferStudent": true,
        "courses": [
            300,
            305
        ],
        "lastName": "Lee",
        "firstName": "Anna",
        "_id": "57a52796e4b03647ddae32a5",
        "_updatedAt": {
            "$date": "2016-08-08T19:11:36.301Z"
        },
        "toAddress": {
            "collName": "Address",
            "_id": "57a5199be4b03647ddae3297"
        },
        "_createdAt": {
            "$date": "2016-08-05T23:56:06.051Z"
        }
    },
    {
        "isTransferStudent": true,
        "_updatedAt": {
            "$date": "2016-08-08T20:46:23.833Z"
        },
        "toAddress": {
            "collName": "Address",
            "_id": "57a52992e4b03647ddae32a8"
        },
        "lastName": "Lee",
        "courses": [
            100,
            101
        ],
        "firstName": "Sarah",
        "_id": "57a8ed82e4b081a83615fc33",
        "major": {
            "name": "Chemistry"
        },
        "_createdAt": {
            "$date": "2016-08-08T20:37:22.486Z"
        }
    }
]
This example shows how to count the number of objects in a collection:
var dbApiKey = "c33010af-f263-4443-9897-c2ffaf522956";
var result = Collection.query(dbApiKey, "Student", {"count": 1});
[
    {
        "count": 20
    }
]
This example shows how to search by the built-in _updatedAt column:

var dbApiKey = "c33010af-f263-4443-9897-c2ffaf522956";
var now = new Date ();
var params = {};
params.criteria = {
   "_updatedAt": {
      "$lt":  {$date: now.toISOString()} 
   }
};
var result = Collection.query(dbApiKey, "Goods", params);
Apperyio.response.success(result, "application/json");
// Returns all objects updated before 'now'.

You can also use the built-in _createdAt column the same way.

The following examples hows how to search by a custom field of Date type. Note that the syntax is slightly different than when using the built-in date columns.

📘

ISO Format

When using one of the built-in data types in a query (_createdAt, _updatedAt), the date value must be formatted in ISO format. When using a custom column with Date type, using ISO format is not required.

var dbApiKey = "c33010af-f263-4443-9897-c2ffaf522956";
var params = {};
params.criteria = {
  "startTime": {
    "$gt": "2016-12-31 00:00:00.000"
  }
};
var result = Collection.query(dbApiKey, "Goods", params);
Apperyio.response.success(result, "application/json");
// Returns all items where startTime is greater than Dec 31, 2016
The following examples uses two date columns:
var dbApiKey = "c33010af-f263-4443-9897-c2ffaf522956";
var params = {};
params.criteria = {
  "$and": [{
    "startTime": {
      "$gt": "2016-12-31 00:00:00.000"
    }
  }, {
    "endTime": {
      "$lt": "2017-02-01 00:00:00.000"
    }
  }]
};
var result = Collection.query(dbApiKey, "Goods", params);
Apperyio.response.success(result, "application/json");
// Returns all items where time is between December 31, 2016 and February 1, 2017