Data

Provides a client-side api to the server-side Data module. The data module is a simple interface to the Mongo database. For more complex data handling, you must provide an api on the server-side.

get

Get a data object from the Mongo database.

core.data.get(data_params, listener)

Parameters

Name	Description	Type	Required
data_params	The data parameters for the call.	Table	Y
listener	The api listener callback function.	Function	Y

Data Params

Name	Description	Type	Required
source	The data source to run against.	String	Y
query	A query table or string id.	Table or String	Y
db	A specific database. Default: "_app".	String	N

Event Response

On success, the result will hold the data object as a table.

Example

local function apiListener( evt )
  if evt.error then
    print(evt.error)
  else
    core.debug(evt.result) -- result holds the data object
  end
end

core.data.get({source="users", query="id1234"}, apiListener)

Multiple Objects

To retrieve multiple data objects, see the getPage method.

save

Create a new, or update an existing, data object and save it in the Mongo database.

core.data.save(data_params, listener)

Parameters

Name	Description	Type	Required
data_params	The data parameters for the call.	Table	Y
listener	The api listener callback function.	Function	Y

Data Params

Name	Description	Type	Required
source	The data source to run against.	String	Y
data	A data object to save.	Table	Y
db	A specific database. Default: "_app".	String	N

Event Response

On success, the result will contain the id of the newly created object as a string.

Example

Saving a new data object

Warning

Do not add an _id key to the object, it will be generated automatically on the server-side.

local dataObj = {
  name = "Sally",
  age = 32,
  active = true,
  colors = {"blue", "gold"}
}

local function apiListener( evt )
  if evt.error then
    print(evt.error)
  else
    print(evt.result) --the object id
  end
end

core.data.save({source="users", data=dataObj}, apiListener)

Updating an existing object

Info

To update an existing object, first retrieve it using core.data.get.

local obj = --an object from core.data.get

obj.score = 200 --add or update key value

local function apiListener( evt )
  --listener code (see above)
end

core.data.save({source="users", data=obj}, apiListener)

Warning

Do not change the _id key in the object you wish to update.

delete

Delete a data object from the Mongo database.

core.data.delete(data_params, listener)

Parameters

Name	Description	Type	Required
data_params	The data parameters for the call.	Table	Y
listener	The api listener callback function.	Function	Y

Data Params

Name	Description	Type	Required
source	The data source to run against.	String	Y
id	The data object id string.	String	Y
db	A specific database. Default: "_app".	String	N

Object IDs

You can get an object id from any data object. See the core.data.get example above.

Event Response

On success, the result will be true.

Example

local function apiListener( evt )
  if evt.error then
    print(evt.error)
  else
    print("deleted")
  end
end

core.data.delete({source="users", id="id1234"}, apiListener)

Special Note

While passing an id string is the most consistent way to delete an object, you can also pass the entire object to the id key. Example: {source = "users", id = obj}. The object must contain a valid _id field for this to work.

Pagination

getPage

Get multiple data objects from the Mongo database based on a specific criteria.

core.data.getPage(data_params, listener)

Parameters

Name	Description	Type	Required
data_params	The data parameters for the call.	Table	Y
listener	The api listener callback function.	Function	Y

Data Params

Name	Description	Default	Type	Required
source	The data source to run against.	none	String	Y
page	The page number to return.	none	Number	Y
perPage	The number of objects per page.	20	Number	N
sort	Sort constant or sorting table.	core.ASC	Const or Table	N
query	Specialized query table.	{ } (all records)	Table	N
db	Specify a different database.	"_app"	String	N

Sort Constants

Enum	Description
core.ASC	Sort in an ascending order.
core.DESC	Sort in a descending order.

Event Response

On success, the result will hold a table array of data objects.

Example

local params = {
  source = "users",
  page = 1,
  perPage = 10
}

local function apiListener( evt )
  if evt.error then
    print(evt.error)
  else
    --evt.result holds array of objects
    for i=1, #evt.result do
      print(evt.result[i]._id)
    end
  end
end

core.data.getPage(params, apiListener)

Network Timeout

Though rare, very large workloads may cause the Corona client to throw a network timeout error before you receive a reponse from the server. In these cases you can add a timeout parameter to the data_params table.

The Corona default network timeout is 30 seconds. This is an optional parameter.

Example

local function apiListener( evt )
  ...
end

core.data.get({source="users", query="id1234", timeout=60}, apiListener)