Database

Service URI - luna://com.palm.db

Enables apps to store persistent data.

DB8 is an API for managing embedded JSON database. DB8 allows apps to store persistent data. DB8 provides various functions that allow entry, storage, and retrieval of large quantities of information as well as provides ways to manage how that information is organized.

It provides the following data management functions:

  • Add objects
  • Update objects
  • Delete objects
  • Query objects
  • Manage access to objects within the database

To learn about webOS Database (DB8) service and how to use it, see Database (DB8).

Methods

MethodDescriptionSupported in Emulator
batchEnables apps to execute multiple database operations in one service request.Yes
delDeletes the JSON data objects from the database.Yes
delKindDeletes a kind from the database.Yes
findReturns a set of objects that match the query specified in the query parameter.Yes
getRetrieves JSON data objects by IDs.Yes
mergeUpdates the object properties in existing objects.Yes
putStores JSON data objects of a particular kind into the database.Yes
putKindRegisters a kind with the database.Yes
putPermissionsEnables other apps or services to access the apps stored DB8 data.Yes
reserveIdsReserves a block of objects IDs.Yes
searchSupports the ? operator which is used for full-text searching.Yes
watchWatches for updates to the database that would change the results of a query.Yes

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.

Parameters

NameRequiredTypeDescription
operationsRequiredObject arrayThe list of database operations to perform.

Call returns

NameRequiredTypeDescription
BatchResponseOptionalObjectIf the method succeeds, it will return the BatchResponse object.
ErrResponseOptionalObjectIf the method fails, it will return the ErrResponse object.

Error reference

Error CodeError MessageError Description
-3984No required key: "method"The required database operations name is missing.
-3984No required key: "params"The required parameters for a database operation is missing.
-3982db: invalid operation in batchAn 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 executed');
    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
  • A DB8 query

Parameters

NameRequiredTypeDescription
idsOptionalString arrayAn 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 in the query parameter.
queryOptionalObjectA 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.
purgeOptionalBooleanThe 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

NameRequiredTypeDescription
PutResponseOptionalObjectWhen the method succeeds, and the objects to be deleted were specified as a list of JSON object ids, it will return a PutResponse object.
CountResponseOptionalObjectWhen the method succeeds, and the objects to be deleted were specified as a query, it will return a CountResponse object
ErrResponseOptionalObjectIf the method fails, it will return the ErrResponse object.

Error reference

Error CodeError MessageError Description
-3963db: permission deniedThe app does not have permission to delete the specified object.
-3965db: no index for queryThe query is referring to an index that does not exist for the specified kind.
-3962db: quota exceededThere 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 object');
    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 object');
    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.

Parameters

NameRequiredTypeDescription
idRequiredStringThe id of the kind that the app wants to delete.

Call returns

NameRequiredTypeDescription
returnValueRequiredBooleanFlag that indicates success/failure of the request.
  • true: Success
  • false: Failure
errorCodeOptionalNumbererrorCode 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.
errorTextOptionalStringerrorText 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 CodeError MessageError Description
-3970db: kind not registeredThe specified kind doesn't exist in the database.
-3999db: access deniedThe 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 group by(distinct) enabling the app to remove duplicate objects.

Parameters

NameRequiredTypeDescription
queryRequiredObjectDB8 query for retrieving results.
countOptionalBooleanThe default value of the count parameter 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.
watchOptionalBooleanThe default value of the watch parameter 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

NameRequiredTypeDescription
FindResponseOptionalObjectIf the find method succeeds, the find method returns the FindResponse object.
NotificationResponseOptionalObjectIf the watch parameter was set to true by the app, the find method returns the NotificationResponse object.
ErrResponseOptionalObjectIf the find method fails, it returns the ErrResponse object.

Error reference

Error CodeError MessageError Description
-3970db: kind not registeredThe specified kind is not registered in the database.
-3978db: invalid queryThe query syntax is correct, but contains misspelled commands or logical errors.
-3965db: no index for queryThe SELECT query contains field name(s) that do not exist for the selected kind.
-3963db: permission deniedThe 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 object 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.

Parameters

NameRequiredTypeDescription
idsRequiredString arrayIds of the JSON data objects to retrieve.

Call returns

NameRequiredTypeDescription
GetResponseOptionalObjectIf the method succeeds, it will return the GetResponse object.
ErrResponseOptionalObjectIf the method fails, it will return the ErrResponse object.

Error reference

Error CodeError MessageError Description
-3999db: access deniedThe specified object exists in the database, but the app does not have permissions to access the object.
-3950db: I/O errorIt 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 object(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).

Parameters

NameRequiredTypeDescription
objectsOptionalObject arrayThe objects parameter is an array of objects, and each object will have an id and key/value pairs that represent the object properties that the app needs to merge. The objects parameter is required if the query parameter is not specified.
queryOptionalObjectQuery object specifying the set of objects whose properties the app wants to update.
The query parameter is required if the objects parameter is not specified.
propsOptionalObjectThe props parameter is an object with key/value pairs that 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

NameRequiredTypeDescription
PutResponseOptionalObjectIf the objects parameter was specified, and the method succeeds, it will return the PutResponse object.
CountResponseOptionalObjectIf the parameter was specified, and the merge method succeeds, it will return the CountResponse object.
ErrResponseOptionalObjectIf the method fails, it will return the ErrResponse object.

Error reference

Error CodeError MessageError Description
-3961db: quota exceededThe app has exceeded its quota or there no free space is available on the device.
-3963db: permission deniedThe app does not have permission to modify the specified objects.
-3965db: no index for queryThe 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 object(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 object(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

Parameters

NameRequiredTypeDescription
objectsRequiredObject arrayList of JSON data objects of a particular kind that the app wants to store in the database.

Call returns

NameRequiredTypeDescription
PutResponseOptionalObjectIf the method succeeds, it will return PutResponse object.
ErrResponseOptionalObjectIf the method fails, it will return ErrResponse object.

Error reference

Error CodeError MessageError Description
-3962db: quota exceededThe app has exceeded its quota or there no free space is available on the device.
-3970db: kind not registeredThe kind for the specified object is not registered with the database.
-3963db: permission deniedThe 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 object(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 with the database.
Kinds define the owner, and the indexes for a JSON data object. Indexes can be composed of single or multiple properties. 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 is 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.

Parameters

NameRequiredTypeDescription
idRequiredStringId of the kind.
ownerRequiredStringOwner of the kind. Possible values:
  • The service's bus address, or
  • The app's app ID
Only the owner has permission to modify the kind.
privateOptionalBooleanThe private parameter is available on webOS TV 3.0 or later.
  • true: When the app is uninstalled, the kind is also removed.
  • false (default): When the app is uninstalled, the kind is not removed.
schemaOptionalObjectIf you define the schema, you must put the valid data that conforms to the schema format. For more information about the schema, see Schema Enforcement.
syncOptionalBooleanEnables apps to enable backing up and restoring specific kinds of objects.
The default value for the parameter is false.
If the app wants to enable backing up and restoring objects to LG servers on a daily basis, the app should set sync to true.
If the user moves to another device, the saved app data can be restored.
extendsOptionalString arrayList of the ids of kind parents.
indexesOptionalObjectThe kind indexes.
revsetsOptionalObject arrayList of database revision sets.

Call returns

NameRequiredTypeDescription
returnValueRequiredBooleanFlag that indicates success/failure of the request.
  • true: Success
  • false: Failure
errorCodeOptionalNumbererrorCode 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.
errorTextOptionalStringerrorText 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 CodeError MessageError Description
-3981db: invalid owner for kindThe specified owner does not have permissions to add or modify the specified kind.
-3962db: quota exceededApp 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',
    private: true,
    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.

Parameters

NameRequiredTypeDescription
typeRequiredStringMust be set to db.kind.
objectRequiredStringThe DB8 kind of the object for which the app wants to provide access.
callerRequiredStringThe id of the app or service that the app is granting permission to access its data.
operationsRequiredObjectDatabase operations the app is granting permissions for.
createOptionalStringTo grant create permission, set the create parameter to allow.
readOptionalStringTo grant read permission, set the read parameter to allow.
updateOptionalStringTo grant update permission, set the update parameter to allow.
deleteOptionalStringTo grant delete permission, set the delete parameter to allow.

Call returns

NameRequiredTypeDescription
returnValueRequiredBooleanFlag that indicates success/failure of the request.
  • true: Success
  • false: Failure
errorCodeOptionalNumbererrorCode 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.
errorTextOptionalStringerrorText 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 CodeError MessageError Description
-3999db: access deniedThe app cannot modify the permissions of the specified 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.

Parameters

NameRequiredTypeDescription
countRequiredNumberNumber of Ids to reserve.

Call returns

NameRequiredTypeDescription
ReserveIdsResponseOptionalObjectIf the method succeeds it will return ReserveIdsResponse object.
ErrResponseOptionalObjectIf the method fails, it will return ErrResponse object.

Error reference

Error CodeError MessageError Description
-3968db: malformed idThe specified count contains an 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;
  },
});

Return example

{
  "ids": [
      "J9FJ12j0Usk",
      "J9FJ12j18hJ",
      "J9FJ12j1Mic"
  ],
  "returnValue": true
}

See also

Description

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 a 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 the 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.

Parameters

NameRequiredTypeDescription
queryRequiredObjectQuery for search.
watchOptionalBooleanThe default value of the watch parameter 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

NameRequiredTypeDescription
FindResponseOptionalObjectIf the method succeeds, it will return the FindResponse object.
NotificationResponseOptionalObjectIf the method succeeds and the app had set the watch parameter to true, the search will return the NotificationResponse object.
ErrResponseOptionalObjectIf the method fails, it will return a ErrResponse object.

Error reference

Error CodeError MessageError Description
-3987db: invalid filter opAn invalid operation was specified in the filter.
-3978db: invalid queryThere was a syntax error in the query.
-3977db: collations on property do not matchThe collation sequence of a property across different objects do not match.
-3975db: invalid combination of query operationsThe 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',
        },
      ],
    },
  },
  onComplete: 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.

Parameters

NameRequiredTypeDescription
queryRequiredObjectQuery whose results the app wants to watch.

Call returns

NameRequiredTypeDescription
SuccessResponseOptionalObjectIf DB8 have enough resources to add client into "watch stack" and the watch method succeeds, it will return the SuccessResponse object.
NotificationResponseOptionalObjectIf DB8 have enough resources to add into "watch stack" and DB8 found some record for the query, it will return a NotificationResponse object.
ErrResponseOptionalObjectIf the method fails, it will return ErrResponse object.

Error reference

Error CodeError MessageError Description
-3999db: access deniedThe 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

BatchOperation object

The object for batch operation.

{
  "method" : string,
  "params" : any
}
NameRequiredTypeDescription
methodRequiredStringDatabase operation to perform.
Allowed values are:
  • del
  • find
  • get
  • merge
  • put
paramsRequiredStringList of parameters for the database operation.

BatchResponse object

Response to batch operation.

{
  "returnValue": boolean,
  "responses"  : any array
}
NameRequiredTypeDescription
returnValueRequiredBooleanFlag that indicates success/failure of the request.
  • true: Success
  • false: Failure
responsesRequiredArrayArray of responses for each of the operations in the batch

ErrResponse object

Standard error response, containing operation success or failure flag, error code and error message.

{
  "returnValue": boolean,
  "errorCode"  : int,
  "errorText"  : string
}
NameRequiredTypeDescription
returnValueRequiredBooleanFlag that indicates success/failure of the request.
  • true: Success
  • false: Failure
If the method fails, the method will return an error message and error message description in errorCode and errorText fields respectively.
errorCodeRequiredNumberNumeric error code.
errorTextRequiredStringError message from the service. This property is available when a 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
}
NameRequiredTypeDescription
selectOptionalString arrayArray of property names to return.
fromRequiredStringName of the kind to retrieve results from.
where OptionalObject arrayArray of clauses to test.
orderByOptionalStringOrder results on this property.
descOptionalBooleanIf set to true, query results will be returned in a descending order.
incDelOptionalBooleanIf 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.
limitOptionalNumberSpecifies the maximum number of results to return (0-500). The default is 500.
pageOptionalStringPage key returned by the previous query.
filterOptionalObject arrayArray of clauses - works only in the search method - identical to WhereClause. Can be used along with where to perform a range search.

putResponse object

Indicates success of the operation and returns id and rev fields for each object.

{
  "returnValue" : boolean,
  "results"     : PutResult
} 
NameRequiredTypeDescription
returnValueRequiredBooleanFlag that indicates success/failure of the request.
  • true: Success
  • false: Failure
resultsRequiredObject arrayArray of objects containing the id and rev of each object that was put.

countResponse object

The number of objects affected by the operation.

{
  "returnValue" : boolean,
  "count"       : int
}
NameRequiredTypeDescription
returnValueRequiredBooleanFlag that indicates success/failure of the request.
  • true: Success
  • false: Failure
countRequiredNumberArray of objects containing the id and rev of each object that was put.

FindResponse object

Response to a find objects operation.

{
  "returnValue" : boolean,
  "results"     : any,
  "count"       : int,
  "next"        : string
}
NameRequiredTypeDescription
returnValueRequiredBooleanFlag that indicates success/failure of the request.
  • true: Success
  • false: Failure
resultsRequiredAnyArray of DB8 kind data objects. What is returned depends on the query and what is stored.
countOptionalNumberNumber of results that would have been returned if a limit had not been specified.
nextOptionalStringKey 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" call.

{
  "returnValue" : boolean,
  "fired"       : boolean
}
NameRequiredTypeDescription
returnValueOptionalBooleanFlag that indicates success/failure of the request.
  • true: Success
  • false: Failure
firedRequiredBooleanChange notification flag.

GetResponse object

Parameters for get objects operation response.

{
  "returnValue" : boolean,
  "results"     : any
}
NameRequiredTypeDescription
returnValueRequiredBooleanFlag that indicates success/failure of the request.
  • true: Success
  • false: Failure
resultsRequiredObject arrayReturns array of stored DB8 data objects.

IndexClause object

Used in the putKind call 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
}
NameRequiredTypeDescription
nameRequiredStringIndex name
propsRequiredObject arrayArray of properties to index together.
incDelOptionalBooleanIf 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.

RevSetClause object

Defines a revision set- a 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.

// Schema
{
  "name"  : string,
  "props" : RevSetPropClause array
}
NameRequiredTypeDescription
nameRequiredStringName of the revision set (unique to this kind).
propsRequiredObject arrayArray of properties to include in revision set.

operation object

The object used to represent a batch operation to run.
(This object has the different format as a product. Following object example is for TV product).

{
  "method" : string,
  "params" : []
}
NameRequiredTypeDescription
methodRequiredStringOperation being requested.
paramsRequiredAny arrayParams will depend on the type of operation being requested

ReserveIdsResponse object

Contains operation success or failure flag and the array of reserved db8 IDs returned from "reserveIds" call.

{
  "returnValue" : boolean,
  "ids"         : string array
}
NameRequiredTypeDescription
returnValueRequiredBooleanFlag that indicates success/failure of the request.
  • true: Success
  • false: Failure
idsOptionalString arrayArray of reserved IDs.

SuccessResponse object

Indicates operation success or failure.

// Schema
{
  "returnValue"  : boolean
}

// Example
{
  "returnValue": false
}
NameRequiredTypeDescription
returnValueRequiredBooleanFlag that indicates success/failure of the request.
  • true: Success
  • false: Failure

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"
}
NameRequiredTypeDescription
propRequiredStringName of property to test.
opRequiredStringTest 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.
valRequiredAnyValue to test against.
collateOptionalStringIndicates 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"
}
NameRequiredTypeDescription
propRequiredStringName of property to test.
opRequiredStringTest 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.
valRequiredAnyValue to test against.
collateOptionalStringIndicates the string comparison routine used to order the results. See the collate field in the IndexPropClause data structure for more information.

PutResult object

Contains "id" and "rev" fields in PutResponse for JSON data object.

// Schema
{
  "id"    : any,
  "rev"   : any
} 
NameRequiredTypeDescription
idRequiredAnyID of the object that was put.
revRequiredAnyObject'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.

IndexPropClause object

Defines index property for IndexClause.

// Schema
{
  "name"     : string,
  "collate"  : string,
  "default"  : any,
  "tokenize" : string,
  "type"     : string
}
NameRequiredTypeDescription
nameRequiredStringName of property being indexed.
collateRequiredStringIndicates 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.
defaultOptionalAnyDefault value to set for this property at insertion time, if not present.
tokenizeOptionalStringIndicates 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.
typeRequiredStringsingle or multi. Single property or multiple properties.

RevSetPropClause object

Object for RevSetPropClause.

{
  "name"     : string
}
NameRequiredTypeDescription
nameRequiredStringName of property to include in revision set.
No Headings