Media Database
Service URI - luna://com.webos.mediadb
Enables apps to store large media related datasets persistently.
The Media Database service enables apps to:
- Add objects
- Update objects
- Delete objects
- Query objects
- Manage access to objects within the database
Unlike the DB8 service, Media Database allows apps to manage large media datasets.
However, the usage method of Media Database is as same as Database (DB8). To learn about webOS Database (DB8) service and how to use it, see Database (DB8).
Methods
Method |
Description |
Supported in Emulator |
---|---|---|
batch | Enables apps to execute multiple database operations in one service request. | Yes |
del | Deletes the JSON data objects from the database. | Yes |
delKind | Deletes a kind from the database. | Yes |
find | Returns a set of objects that match the query specified in the query parameter. | Yes |
get | Retrieves JSON data objects by ids. | Yes |
merge | Updates the object properties in existing objects. | Yes |
put | Stores JSON data objects of a particular kind into the database. | Yes |
putKind | Registers a kind JSON object with the database. | Yes |
putPermissions | Enables other apps, or services to access the apps stored DB8 data. | Yes |
reserveIds |
Reserves a block of object ids. |
Yes |
search | Supports the ? operator which is used for full-text searching. | Yes |
watch | Watches for updates to the database that would change the results of a query. | Yes |
-
Open All
-
- batch
-
Description
Enables apps to execute multiple database operations in one service request. It allows only the following database operations:
- put
- get
- del
- find (without a watch)
- merge
Atomicity is NOT guaranteed across batched operations.
Syntax
batch(Object[] operations)Parameters
Name
Required
Type
Description
operations Required Object array The list of database operations to perform. Call Returns
Name
Required
Type
Description
BatchResponse Optional Object If the method succeeds, it will return BatchResponse object. ErrResponse Optional Object If the method fails, it will return ErrResponse object. Error Reference
Error Code
Error Message
Error Description
-3984 No required key: "method" The required database operations name is missing. -3984 No required key: "params" The required parameters for a database operation is missing. -3982 db: invalid operation in batch An incorrect or an unsupported database operation was specified in the operations parameter. Example
var request = webOS.service.request("luna://com.palm.db", { method: "batch", parameters: { "operations":[ { "method":"put", "params":{ "objects":[ { "_kind":"com.yourdomain.test:1", "sample":"sample1", "test":"test1" } ] } }, { "method":"merge", "params":{ "query":{ "from":"com.yourdomain.test:1", "where":[ { "prop":"sample", "op":"=", "val":"sample1" } ] }, "props":{ "sample":"sample2", "test": "test2" } } } ] }, onSuccess: function (inResponse) { console.log("The batch work is excuted"); console.log(JSON.stringify(inResponse); // To-Do something }, onFailure: function (inError) { console.log("Failed to execute the batch work"); console.log("[" + inError.errorCode + "]: " + inError.errorText); // To-Do something return; } });
Return Example
{ "responses": [ { "returnValue": true, "results": [ { "id": "JHd3Dg427oB", "rev": 21868 } ] }, { "count": 1, "returnValue": true } ], "returnValue": true }
See Also
- del
-
Description
Deletes the JSON data objects from the database. Apps can specify the objects as:
- a set of ids - this will return a PutResponse object
- a DB8 query - this will return a CountResponse object
Syntax
del([String[] ids][, Object query][, Boolean purge])Parameters
Name
Required
Type
Description
ids Optional String array An array of JSON object ids that you wish to delete. If you do not wish to specify JSON object ids, you must specify a query of in the query parameter. query Optional Object A query for a set of objects to be deleted. If you do not wish to specify a query, you must specify a list of JSON object ids in the ids parameter. purge Optional Boolean The default value is false.
- false: The target objects will only be marked for deletion. Objects marked for deletion can still be restored. They will be purged permanently only when an administrative purge operation is run.
- true : The target objects will be deleted permanently immediately.
Call Returns
Name
Required
Type
Description
PutResponse Optional Object When the method succeeds, and the objects to be deleted were specified as a list of JSON object ids, it will return PutResponse object. CountReponse Optional Object When the method succeeds, and the objects to be deleted were specified as a query, it will return CountResponse object. ErrResponse Optional Object If the method fails, it will return ErrResponse object. Error Reference
Error Code
Error Message
Error Description
-3963 db: permission denied The app does not have permission to delete the specified object. -3965 db: no index for query The query is referring to an index that does not exist for the specified kind. -3962 db: quota exceeded There is no space left on the device to complete this operation. It is recommended that the app should call the method again with purge set to true. Example
// Delete data with ID var request = webOS.service.request("luna://com.palm.db", { method: "del", parameters: { "ids" :["JHd3Dg427oB"] }, onSuccess: function (inResponse) { console.log("The " + inResponse.results.id "object is deleted"); // To-Do something }, onFailure: function (inError) { console.log("Failed to delete the obejct"); console.log("[" + inError.errorCode + "]: " + inError.errorText); // To-Do something return; } }); // Delete data with query // Delete all data object from com.yourdomain.test:1 kind var request = webOS.service.request("luna://com.palm.db", { method: "del", parameters: { "query" : { "from" : "com.yourdomain.test:1" } }, onSuccess: function (inResponse) { console.log("The " + inResponse.count "object(s) is(are) deleted"); // To-Do something }, onFailure: function (inError) { console.log("Failed to delete the obejct"); console.log("[" + inError.errorCode + "]: " + inError.errorText); // To-Do something return; } });
Return Example
// Result: Delete with ID { "returnValue": true, "results": [ { "id": "J8rBI6u7uh+" } ] } // Result: Delete with Query { "count": 11, "returnValue": true }
See Also
- delKind
-
Description
Deletes a kind from the database. Deleting a kind deletes ALL data objects of that kind.
Syntax
delKind(String id)Parameters
Name
Required
Type
Description
id Required String The id of kind the app wants to delete Call Returns
Name
Required
Type
Description
returnValue Required Boolean Flag that indicates success/failure of the request.
- true: Success
- false: Failure
errorCode Optional Number errorCode contains the error code if the method fails. The method will return errorCode only if it fails.
See the Error Codes Reference of this method for more details.
errorText Optional String errorText contains the error text if the method fails. The method will return errorText only if it fails.
See the Error Codes Reference of this method for more details.
Error Reference
Error Code
Error Message
Error Description
-3970 db: kind not registered The specified kind doesn't exist in the database. -3999 db: access denied The specified kind exists in the database, however the app does not have the delete permissions. Example
var request = webOS.service.request("luna://com.palm.db", { method: "delKind", parameters: { "id": "com.yourdomain.test:1" }, onSuccess: function (inResponse) { console.log("The kind is deleted"); // To-Do something }, onFailure: function (inError) { console.log("Failed to delete the kind"); console.log("[" + inError.errorCode + "]: " + inError.errorText); // To-Do something return; } });
See Also
- find
-
Description
Returns a set of objects that match the query specified in the query parameter.
The app can specify the number of results to return. However, if the app does not want to specify a limit, it can set the count parameter to true. This will cause the find method to return the total number of results returned in the FindResponse object.
The app can also request to be notified if any of the returned results from the query change in the future. In order to receive change notifications, set the watch parameter to true.
The find method supports the group by(distinct) clause enabling the app to get only unique objects and in the process removing duplicate objects from the results.Syntax
find(Object query[, Boolean count][, Boolean watch])Parameters
Name
Required
Type
Description
query Required Object DB8 query for retrieving results. count Optional Boolean The default value is false.
If the app did not specify a limit on the number of results to return, and wants to know the total number of results returned, the app should set the count parameter to true.
watch Optional Boolean The default value is false.
If an app wants to be notified about any change in the returned results, the app should set the watch parameter to true.
Call Returns
Name
Required
Type
Description
FindResponse Optional Object If the method succeeds, it will return the FindResponse object. NotificationResponse Optional Object If the watch parameter was set to true by the app, the find method will return the NotificationResponse object. ErrResponse Optional Object If the method fails, it will return the ErrResponse object. Error Reference
Error Code
Error Message
Error Description
-3970 db: kind not registered The specified kind is not registered in the database. -3978 db: invalid query The query syntax is correct, but contains misspelled commands or logical errors. -3965 db: no index for query The SELECT query contains field name(s) that do not exist for the selected kind. -3963 db: permission denied The specified kind exists in the database, however the app does not have permissions to read the data for the specified kind. Example
var request = webOS.service.request("luna://com.palm.db", { method: "find", parameters: { "query": { "from": "com.yourdomain.test:1", "where": [ { "prop":"sample", "op":"=", "val":"sample1" } ] } }, onSuccess: function (inResponse) { console.log( inResponse.results.length() + " object(s) is(are) found"); console.log( "Result: " + JSON.stringify(inResponse) ); // To-Do something }, onFailure: function (inError) { console.log("Failed to find the obejct with query"); console.log("[" + inError.errorCode + "]: " + inError.errorText); // To-Do something return; } });
Return Example
{ "returnValue": true, "results": [ { "_rev": 21873, "sample": "sample2", "test": "test2", "_id": "JHdxo18aqjZ", "_kind": "com.yourdomain.test:1" }, { "_rev": 21875, "sample": "sample2", "test": "test2", "_id": "JHdyO1clmYs", "_kind": "com.yourdomain.test:1" } ] }
See Also
- get
-
Description
Retrieves JSON data objects by ids. This is the fastest way to retrieve data.
Syntax
get(String[] ids)Parameters
Name
Required
Type
Description
ids Required String array Ids of the JSON data objects to retrieve. Call Returns
Name
Required
Type
Description
GetResponse Optional Object If the method succeeds, it will return the GetResponse object. ErrResponse Optional Object If the method fails, it will return the ErrResponse object. Error Reference
Error Code
Error Message
Error Description
-3999 db: access denied The specified object exists in the database, but the app does not have permissions to access the object. -3950 db: I/O error It is not possible to read from the database and that this is a critical error. Example
var request = webOS.service.request("luna://com.palm.db", { method: "get", parameters: { "ids" : ["J8rKTaBClIo"] }, onSuccess: function (inResponse) { console.log( inResponse.results.length() + " object(s) is(are) retrieved"); console.log( "Result: " + JSON.stringify(inResponse) ); // To-Do something }, onFailure: function (inError) { console.log("Failed to get the obejct(s)"); console.log("[" + inError.errorCode + "]: " + inError.errorText); // To-Do something return; } });
Return Example
{ "returnValue": true, "results": [ { "_rev": 21, "sample": "sample1", "test": "test1", "_id": "J8rKTaBClIo", "_kind": "com.yourdomain.test:1" } ] }
See Also
- merge
-
Description
Updates the object properties in existing objects.
The objects can be specified in one of the following ways:
- A query
- An array of IDs
Objects can be specified using a query (returns CountResponse) or array of IDs (returns PutResponse).
Syntax
merge([Object[] objects][, Object query][, Object props])Parameters
Name
Required
Type
Description
objects Optional Object array List of object ids, and the properties the app needs to merge. The objects parameter is required if the query parameter is not specified. query Optional Object Query specifying the set of object whose properties the app wants to update.
The query parameter is required if the object parameter is not specified.
props Optional Object The props parameter should specify the set of properties to be merged into the existing object(s) specified in the query parameter. If the app specifies the properties in the prop parameter, the query is required. Call Returns
Name
Required
Type
Description
PutResponse Optional Object If the objects parameter was specified, and the merge method succeeds, merge will return the PutResponse object. CountResponse Optional Object If the query parameter was specified, and the merge method succeeds, merge will return the CountResponse object. ErrResponse Optional Object If the merge method fails, it will return the ErrResponse object. Error Reference
Error Code
Error Message
Error Description
-3961 db: quota exceeded The app has exceeded its quota or there no free space is available on the device. -3963 db: permission denied The app does not have permission to modify the specified objects. -3965 db: no index for query The query contains a SELECT for object properties that do not have an index associated with them Example
// Update object with ids and values var request = webOS.service.request("luna://com.palm.db", { method: "merge", parameters: { "objects" : [ { "_id":"J8rKTaBClIo", "test":"test1", "sample":"sample_updated_value" } ] }, onSuccess: function (inResponse) { console.log( "The object(s) is(are) updated"); console.log( "Result: " + JSON.stringify(inResponse) ); // To-Do something }, onFailure: function (inError) { console.log("Failed to update the obejct(s)"); console.log("[" + inError.errorCode + "]: " + inError.errorText); // To-Do something return; } }); // Update data with query var request = webOS.service.request("luna://com.palm.db", { method: "merge", parameters: { "query":{ "from":"com.yourdomain.test:1", "where":[ { "prop":"sample", "op":"=", "val":"sample1" } ] }, "props":{ "sample":"sample_updated_value" } }, onSuccess: function (inResponse) { console.log( inResponse.count + " object(s) is(are) updated"); // To-Do something }, onFailure: function (inError) { console.log("Failed to update the obejct(s)"); console.log("[" + inError.errorCode + "]: " + inError.errorText); // To-Do something return; } });
Return Example
// Return: Update object with ids and values { "returnValue": true, "results": [ { "id": "J8rKTaBClIo", "rev": 23 } ] } // Return: Update data with query { "count": 2, "returnValue": true }
See Also
- put
-
Description
Stores JSON data objects of a particular kind into the database. The put method will:
- Assign an id field to each object, if it was not set
- Return the id and rev for each stored object,
Syntax
put(Object[] objects)Parameters
Name
Required
Type
Description
objects Required Object array List of JSON data objects of a particular kind that the app wants to store in the database. Call Returns
Name
Required
Type
Description
PutResponse Optional Object If the method succeeds, it will return PutResponse object. ErrResponse Optional Object If the method fails it will return ErrResponse object. Error Reference
Error Code
Error Message
Error Description
-3962 db: quota exceeded The app has exceeded its quota or there no free space is available on the device. -3970 db: kind not registered The kind for the specified object is not registered with the database. -3963 db: permission denided The app does not have permission to save objects of a specified kind. Example
var request = webOS.service.request("luna://com.palm.db", { method: "put", parameters: { "objects":[ { "_kind":"com.yourdomain.test:1", "sample":"sample1", "test":"test1" } ] }, onSuccess: function (inResponse) { console.log("The object(s) is(are) added"); console.log("Result: " + JSON.stringify(inResponse)); // To-Do something }, onFailure: function (inError) { console.log("Failed to add the obejct(s)"); console.log("[" + inError.errorCode + "]: " + inError.errorText); // To-Do something return; } });
Return Example
{ "returnValue": true, "results": [ { "id": "J8rTIa65u++", "rev": 27 } ] }
See Also
- putKind
-
Description
Registers a kind JSON object with the database.
Kind objects define the owner, and the indexes for a JSON data object. Indexes can be composed of single or multiple fields. When you create your index, be aware that queries can only return results that are indexed, and are contiguously ordered.
If your app or service wants to be notified only when a subset of an object's properties are updated, then you can use revision sets.
If your app or service creates objects that other apps or services need to access, then see the putPermissions method for more information.Syntax
putKind(String id, String owner[, Object schema][, Boolean sync][, String[] extends][, Object indexes][, Object[] revsets])Parameters
Name
Required
Type
Description
id Required String Id of the kindJSON object owner Required String Owner of the kind JSON object. Possible values:
- The service's bus address, or,
- The app's app ID
Only the owner has permission to modify the kind JSON object.
schema Optional Object JSON Syntax for data objects of a specific kind. If set, this kind's data objects are validated before being stored. For details refer to http://www.json.org/. sync Optional Boolean Not supported by this version of DB8.
The default value is false.
extends Optional String array List of the ids of kind parents indexes Optional Object Kind indexes revsets Optional Object array List of database revision sets Call Returns
Name
Required
Type
Description
returnValue Required Boolean Flag that indicates success/failure of the request.
- true: Success
- false: Failure
errorCode Optional Number errorCode contains the error code if the method fails. The method will return errorCode only if it fails.
See the Error Codes Reference of this method for more details.
errorText Optional String errorText contains the error text if the method fails. The method will return errorText only if it fails.
See the Error Codes Reference of this method for more details.
Error Reference
Error Code
Error Message
Error Description
-3981 db: invalid owner for kind The specified owner does not have permissions to add or modify the specified kind. -3962 db: quota exceeded App has exceeded its quota or does not have enough disk space available to create the specified kind. Example
var request = webOS.service.request("luna://com.palm.db", { method: "putKind", parameters: { "id": "com.yourdomain.test:1", "owner":"com.yourdomain.test", "indexes":[ { "name":"sample", "props":[ {"name":"sample"} ] }, { "name":"testsample", "props":[ {"name":"test"}, {"name":"sample"}] } ] }, onSuccess: function (inResponse) { console.log("The kind is created"); // To-Do something }, onFailure: function (inError) { console.log("Failed to create the kind"); console.log("[" + inError.errorCode + "]: " + inError.errorText); // To-Do something return; } });
See Also
- putPermissions
-
Description
Enables other apps, or services to access the apps stored DB8 data. The app can give permissions to access data objects of a particular kind.
Syntax
putPermissions(String type, String object, String caller, Object operations[, String create][, String read][, String update][, String delete])Parameters
Name
Required
Type
Description
type Required String Must be set to db.kind. object Required String The DB8 kind of the object for which the app wants to provide access. caller Required String The id of the app or service that the app is granting permission to access its data. operations Required Object Database operations the app is granting permissions for. create Optional String To grant create permission, set the value to allow. read Optional String To grant read permission, set the value to allow. update Optional String To grant update permission, set the value to allow. delete Optional String To grant delete permission, set the value to allow. Call Returns
Name
Required
Type
Description
returnValue Required Boolean Flag that indicates success/failure of the request.
- true: Success
- false: Failure
errorCode Optional Number errorCode contains the error code if the method fails. The method will return errorCode only if it fails.
See the Error Codes Reference of this method for more details.
errorText Optional String errorText contains the error text if the method fails. The method will return errorText only if it fails.
See the Error Codes Reference of this method for more details.
Error Reference
Error Code
Error Message
Error Description
-3999 db: access denied No permission to modify permission for a kind. Example
var request = webOS.service.request("luna://com.palm.db", { method: "putPermissions", parameters: { "permissions":[ { "operations":{ "read":"allow", "create":"allow", "update":"allow", "delete":"allow" }, "object":"com.yourdomain.test:1", "type":"db.kind", "caller":"com.yourdomain.testapp" } ] }, onSUccess: function (inResponse) { console.log("The permission(s) is(are) set"); // To-Do something }, onFailure: function (inError) { console.log("Failed to set the permission(s)"); console.log("[" + inError.errorCode + "]: " + inError.errorText); // To-Do something return; } });
See Also
- reserveIds
-
Description
Reserves a block of object ids.
Syntax
reserveIds(Number count)Parameters
Name
Required
Type
Description
count Required Number Number of Ids to reserve. Call Returns
Name
Required
Type
Description
ReserveIdsResponse Optional Object If the method succeeds it will return a ReserveIdsResponse object. ErrResponse Optional Object If the method fails, it will return a ErrResponse object. Error Reference
Error Code
Error Message
Error Description
-3968 db: malformed id The specified count contains invalid value. Example
var request = webOS.service.request("luna://com.palm.db", { method: "reserveIds", parameters: { "count": 3 }, onSuccess: function (inResponse) { console.log(inResponse.ids.length() + " object ID(s) is(are) reserved"); console.log("Result: " + JSON.stringify(inResponse) ); // To-Do something }, onFailure: function (inError) { console.log("Failed to reserve object IDs"); console.log("[" + inError.errorCode + "]: " + inError.errorText); // To-Do something return; } });
Example
{ "ids": [ "J9FJ12j0Usk", "J9FJ12j18hJ", "J9FJ12j1Mic" ], "returnValue": true }
See Also
- search
-
Description
Unlike the find method, the search method call supports the ? operator. The ? operator can be used for full-text searching. However, the search method is significantly slower, and should only be used for full-text type-down search. The search method should not be used for retrieving results that are going to be scrolled in a list.
The search method supports:
- Ordering by any property
- Distinct method to remove duplicate objects
- %% operator in filter to search in a substring
The search method has some limitations:- There must be an index for the field you are searching on.
- The search operation looks for words beginning with the search string.
Syntax
search(Object query[, Boolean watch])Parameters
Name
Required
Type
Description
query Required Object Query for search. watch Optional Boolean The default value is false.
If the app wants to be notified of any changes in the search results, it should set the watch parameter to true.
Call Returns
Name
Required
Type
Description
FindResponse Optional Object If the method succeeds, it will return the FindResponse object. NotificationResponse Optional Object If the method succeeds and the app had set the watch parameter to true, search will return the NotificationResponse object. ErrResponse Optional Object If the method fails, it will return a ErrResponse object. Error Reference
Error Code
Error Message
Error Description
-3987 db: invalid filter op An invalid operation was specified in the filter. -3978 db: invalid query There was a syntax error in the query. -3977 db: collations on property do not match The collation sequence of a property across different objects do not match. -3975 db: invalid combination of query operations The query syntax is correct, but contains logical errors. Example
var request = webOS.service.request("luna://com.palm.db", { method: "search", parameters: { "query":{ "from":"com.yourdomain.test:1", "where":[ { "prop":"sample", "op":"?", "val":"sample" } ] } }, onSuccess: function (inResponse) { console.log(inResponse.count + " objects is(are) returned."); console.log("Results: " + JSON.stringify(inResponse)); // To-Do something }, onFailure: function (inError) { console.log("Failed to search"); console.log("[" + inError.errorCode + "]: " + inError.errorText); // To-Do something return; } });
Return Example
{ "count": 4, "returnValue": true, "results": [ { "_rev": 22, "sample": "sample_updated_value", "test": "test1", "_id": "J8rKQDOvxdF", "_kind": "com.yourdomain.test:1" }, { "_rev": 23, "sample": "sample_updated_value", "test": "test1", "_id": "J8rKTaBClIo", "_kind": "com.yourdomain.test:1" }, { "_rev": 26, "sample": "sample1", "test": "test1", "_id": "J8rTH76hfcB", "_kind": "com.yourdomain.test:1" }, { "_rev": 27, "sample": "sample1", "test": "test1", "_id": "J8rTIa65u++", "_kind": "com.yourdomain.test:1" } ] }
See Also
- watch
-
Description
Watches for updates to the database that would change the results of a query.
Syntax
watch(Object query)Parameters
Name
Required
Type
Description
query Required Object Query whose results the app wants to watch. Call Returns
Name
Required
Type
Description
SuccessResponse Optional Object If DB8 has enough resources to add client into "watch stack" and the method succeeds, it will return the SuccessResponse object. NotificationResponse Optional Object If DB8 has enough resources to add into "watch stack" and DB8 found some record for query, it will return a NotificationResponse object. ErrResponse Optional Object If the method fails, it will return the ErrResponse object. Error Reference
Error Code
Error Message
Error Description
-3999 db: access denied The app does not have permissions to monitor the database. Example
var request = webOS.service.request("luna://com.palm.db", { method: "watch", parameters: { "query":{ "from":"com.yourdomain.test:1", "where":[ { "prop":"sample", "op":"=", "val":"sample1" } ] } }, onSuccess: function (inResponse) { console.log("The object, which is met specified criteria, was found."); // To-Do something }, onFailure: function (inError) { console.log("Failed to watch"); console.log("[" + inError.errorCode + "]: " + inError.errorText); // To-Do something return; } });
Return Example
{ "returnValue": true, "fired": true }
See Also
- Object
-
operation Object
Object used to represent a batch operation to run.
{ "method": string, "params": [] }
Name
Required
Type
Description
method
Required String Operation being requested. params
Required Any array Depends on the type of operation being requested. SuccessResponse Object
Indicates operation success or failure.
// Schema { "returnValue" : boolean } // Example { "returnValue": false }
Name
Required
Type
Description
returnValue Required Boolean Flag that indicates success/failure of the request.
- true: Success
- false: Failure
ErrResponse Object
Standard error response, containing operation success or failure flag, error code and error message.
{ "returnValue" : boolean, "errorCode" : int, "errorText" : string }
Name
Required
Type
Description
returnValue
Required
Boolean
Flag that indicates success/failure of the request.
-
true: Success
-
false: Failure
errorCode
Required
Number
Error code from the service. This property is available when request fails.
errorText
Required String Error message from the service. This property is available when request fails. Query Object
Defines a db8 query.
// Schema { "select" : string array, "from" : string, "where" : WhereClause array, "orderBy" : string, "desc" : boolean, "incDel" : boolean, "limit" : int, "page" : string } // Example { "select" : ["displayName", "state"], "from" : "com.mystuff.contacts:1", "where" : [{"prop":"state","op":"=","val":"CA"}], "orderBy" : "displayName", "desc" : true }
Name
Required
Type
Description
select Optional String array Array of property names to returnfrom Required String Name of kind to retrieve results fromwhere Optional Object array Array of clauses to testorderBy Optional String Order results on this propertydesc Optional Boolean If set to true, query results will be returned in a descending order.incDel Optional Boolean If set to true, the query results will include the deleted object.
Note: You can only request this if the incDel field was true when you created your indexes during a putKind operation. Otherwise, the query fails with a "no index for this query" message.
limit Optional Number Specifies maximum number of results to return (0-500). Default is 500page Optional String Page key returned by previous queryfilter Optional Object array Array of clauses - works only in the search method - identical to WhereClause. Can be used along with where to perform a range search. IndexClause Object
Used in the putKind method for creating kind object indexes. Note that indexes determine the type of queries your app can make. See Queries and Indexing for more information. Set the incDel flag to true if you want future queries to return marked as deleted objects. Objects are not completely deleted until an administrative purge operation takes place.
//Schema { "name" : string, "props" : IndexPropClause, "incDel" : boolean } //Example { "name" : "state", "props" : [{"name": "state"}], "incDel" : false }
Name
Required
Type
Description
name
Required
String
Index name
Required
Object array
Array of properties to index together
incDel
Optional Boolean If incDel is true, the query results will include the deleted object.
Note: You can only request this if the incDel field was true when you created your indexes during a putKind operation. Otherwise, the query fails with a "no index for this query" message.
IndexPropClause Object
Defines index property for IndexClause.
{ "name" : string, "collate" : string, "default" : any, "tokenize" : string, "type" : string }
Name
Required
Type
Description
collate
Optional
String
Indicates the string comparison routine used to order the index.
Must be one of the following:
-
default: Does binary comparison
-
primary: Compares base characters (for example, "a" < "b") without considering accents, case, or tone marks.
-
secondary: Accents in the characters are considered secondary differences (for example, "as" < "às" < "at"). Other differences between letters can also be considered secondary differences, depending on the language. A secondary difference is ignored when there is a primary difference anywhere in the strings.
-
tertiary: Upper and lower case differences in characters are distinguished at the tertiary level (for example, "ao" < "Ao" < "aò"). In addition, a variant of a letter differs from the base form on the tertiary level (such as "A" and "?"). A tertiary difference is ignored when there is a primary or secondary difference anywhere in the strings.
default
Optional
Any
Default value to set for this property at insertion time, if not present.
tokenize
Optional
String
Indicates if words in strings should be broken up, i.e., should "Hello World" become "Hello" and "World" for purposes of indexing.
Must be one of the following:
-
none: Does not tokenize.
-
default: Use the default for the locale (which may strip stop-words). Stop-words are common words that are stripped for purposes of indexing, i.e., "the", "a", "an", "is", etc.
-
all: Tokenizes all words.
type
Required String single or multi. Single property or multiple properties. RevSetClause Object
Defines a revision set—subset of an object's properties that your app can be notified about when one of the properties is modified. See Change Notification for more information.
{ "name" : string, "props" : RevSetPropClause array }
Name
Required
Type
Description
name
Required
String
Name of the revision set (unique to this kind).
Required Object array Array of properties to include in revision set. PutResponse Object
Indicates success of operation and returns id and rev fields for each object.
{ "returnValue" : boolean, "results" : PutResult }
Name
Required
Type
Description
returnValue
Required
Boolean
Flag that indicates success/failure of the request.
-
true: Success
-
false: Failure
Required Object array Array of objects containing the id and rev of each object that was put. PutResult Object
Contains id and rev fields in PutResponse for JSON data object.
{ "id" : any, "rev" : any }
Name
Required
Type
Description
id
Required
Any
ID of the object that was put.
rev
Required Any Object's revision ID. Every db8 object has this ID field. db8 maintains a global rev id counter that is incremented every time a db8 object is created or updated. CountResponse Object
Number of objects affected by operation.
{ "returnValue" : boolean, "count" : int }
Name
Required
Type
Description
returnValue
Required
Boolean
Flag that indicates success/failure of the request.
-
true: Success
-
false: Failure
count
Required Number Number of objects affected by operation. FindResponse Object
Response to a find objects operation.
{ "returnValue" : boolean, "results" : any, "count" : int, "next" : string }
Name
Required
Type
Description
returnValue
Required
Boolean
Flag that indicates success/failure of the request.
-
true: Success
-
false: Failure
results
Required
Any
Array of db8 kind data objects. What is returned depends on the query and what is stored.
count
Optional
Number
Number of results that would have been returned if a limit had not been specified.
next
Optional String Key to pass as query's "page" property when retrieving next page of results. NotificationResponse Object
Notifies caller of change in query results returned from a find method.
{ "returnValue" : boolean, "fired" : boolean }
Name
Required
Type
Description
returnValue
Optional
Boolean
Flag that indicates success/failure of the request.
-
true: Success
-
false: Failure
fired
Required Boolean Change notification flag GetResponse Object
Parameters for get objects operation response.
{ "returnValue" : boolean, "result" : any }
Name
Required
Type
Description
returnValue
Required
Boolean
Flag that indicates success/failure of the request.
-
true: Success
-
false: Failure
result
Required Object array Returns array of stored db8 data objects. BatchResponse Object
Response to batch operation.
{ "returnValue" : boolean, "responses" : any array }
Name
Required
Type
Description
returnValue
Required
Boolean
Flag that indicates success/failure of the request.
-
true: Success
-
false: Failure
responses
Required Array Array of responses for each of the operations in the batch. BatchOperation Object
Method and params for batch operation.
{ "method" : string, "params" : any }
Name
Required
Type
Description
method
Required
String
Database operation to perform.
Allowed values are:
-
del
-
find
-
get
-
merge
-
put
params
Required String List of parameters for the database operation. ReserveIdsResponse Object
Contains operation success or failure flag and array of reserved db8 IDs returned from reserveIds method.
{ "returnValue" : boolean, "ids" : string array }
Name
Required
Type
Description
returnValue
Required
Boolean
Flag that indicates success/failure of the request.
-
true: Success
-
false: Failure
ids
Optional String array Array of reserved IDs WhereClause Object
Defines a SQL-like JSON where clause for a db8 Query.
// Schema { "prop" : string, "op" : string, "val" : any, "collate" : string } // Example { "prop" : "state", "op" : "=", "val" : "CA" }
Name
Required
Type
Description
prop
Required
String
Name of property to test.
op
Required
String
Test operator. Must be one of the following: <, <=, =, >=, >, !=, %, ?, %% (less than, less than or equal, equals, greater than or equal, greater than, not equal, wildcard, and full-text) The % operator (aka - the prefix operator) will return all matches beginning with the value specified. The %% operator is used to locate substrings or partial string matches.
val
Required
Any
Value to test against.
collate
Optional String Indicates the string comparison routine used to order the results. See the collate field in the IndexPropClause data structure for more information. FilterClause Object
Definition of the Filter clause that is part of the Query object.
// Schema { "prop" : string, "op" : string, "val" : any, "collate" : string } // Example { "prop" : "state", "op" : "=", "val" : "CA" }
Name
Required
Type
Description
prop
Required
String
Name of property to test.
op
Required
String
Test operator. Must be one of the following: <, <=, =, >=, >, !=, ?, %, %% (less than, less than or equal, equals, greater than or equal, greater than, not equal, wildcard, full-text, and partial-text) The % operator (aka - the prefix operator) will return all matches beginning with the value specified. The %% operator is used to locate substrings or partial string matches.
val
Required
Any
Value to test against.
collate
Optional String Indicates the string comparison routine used to order the results. See the collate field in the IndexPropClause data structure for more information. RevSetPropClause Object
A property in a RevSetClause.
{ "name" : string, }
Name
Required
Type
Description
name
Required String Name of property to include in revision set.