Note
This API has been available since API level 11.
This API has been available since API level 11.
com.webos.service.db
API Summary
Enables apps to store persistent data.
Overview of the API
DB8 is a user-space service that provides access to the webOS database. Access to the database APIs is provided over the luna-service bus.
Formally, a database refers to a set of related objects and the way it is structured or organized. Access to these objects is usually provided by a luna API that allows applications to interact with the database and one with another. It also provides access to the objects in the database (although there may be restrictions that grant or limit access to particular data). DB8 provides various functions that allow to enter, store, and retrieve large volumes of information as well as provides the interface to manage how that information is organized.
Designing a Database:
The first task of a database designer is to produce a conceptual model that reflects the structure of data as it is going to be stored in a database. A common approach to this is to develop a Kind that implements the relevant data structures within the database.
Example of Kind creation:
# luna-send -n 1 luna://com.webos.service.db/putKind '{
"id":"com.webos.service.test:1",
"owner":"com.webos.service.test",
"indexes":[
{
"name":"sample",
"props":[
{
"name":"sample"
}
]
},
{
"name":"testsample",
"props":[
{
"name":"test"
},
{
"name":"sample"
}
]
}
]
}'
In the example above, we create a Kind with an ID: "com.webos.service.test:1" (this is similar to a schema name).
The owner of this Kind service is com.webos.service.test. The owner of a Kind has permissions to calculate quotas, grant permissions to modify or delete a Kind, grant permissions to other services for Kind data, and so on.
We have also specified two indexes for the Kind. An index is a data structure that allows data retrieval operations on a database at the cost of additional writes and storage space to maintain the index data structure. Indexes are used to quickly locate data without having to search every row in a database every time a database is accessed. Indexes are created using one or more columns of a database object, providing the basis for both rapid random searches and efficient access of ordered records.
The number after the colon in the ID is the Kind Revision number. When a service updates a Kind, the service should increment its revision number to indicate that the schema has changed.
Philosopher's stone (objects):
DB8 operates with objects. Objects have fields. Every object that is stored within DB8 always has an ID and a revision.
An object ID uniquely identifies an object within a database. The object ID does not repeat within a database.
Object revisions:
Object revision is a number, that determines "version of an object in the database". This number is required to avoid collisions when two or more services simultaneously try to update an object at the same time.
For all new objects, the database will append a _rev field, which indicates the object revision. By default, the database will set object revision _rev field to Database Revision (Number, that atomically increments on any database modification).
If an object already exists in the database, the database engine will automatically increment the object revision number on each successful put/merge API call for this object.
Explanation by example: com.webos.service.test and com.webos.service.othertest applications have access for read/write to Kind com.webos.service.test:1. Both applications, at the same time, read an object from com.webos.service.test:1 kind object with ID ++JZk1sXYW7lCdqU and revision 777.
Both applications execute a merge command like the following:
# luna-send -n 1 luna://com.webos.service.db/merge '{
"objects":[
{
"_id":"++JZk1sXYW7lCdqU",
"_rev":777,
"_kind":"com.webos.service.test:1",
"sample":"I am new sample value"
}
]
}'
Following is the merge call response, that will be received by one of the applications - (may be com.webos.service.test or com.webos.service.othertest, depends who is more lucky):
{
"returnValue":true,
"results":[
{
"id":"++JZk1sXYW7lCdqU",
"rev":778 <--- See, the database increments the revision after a successful object update!
}
]}
The other application will get the following error:
{
"returnValue":false,
"errorCode":-3961,
"errorText":"db: revision mismatch - expected 778, got 777"
}
This error indicates that someone else has already updated this object. After receiving this error, the application MUST execute the get method to get the object again with a new _rev, and then try to re-execute the merge query.
Create:
To store an object in the database, a client can use the put method.
Complexity guaranteed for a put API call is log(n).
# luna-send -n 1 luna://com.webos.service.db/put '{
"objects":[
{
"_kind":"com.webos.service.test:1",
"sample":"sample1",
"test":"test1",
"name":"max"
}
]
}'
Update (replace):
The put method updates an object. Update by default will replace the database object with the new one (in other words, if a new object does not have some fields that were present in the old database object, those old database fields will be removed)
As an example, consider the following object in a database:
{
"_kind":"com.webos.service.test:1",
"_id":"JZR3hyjVyB3",
"_rev":12,
"name":"MAX",
"sample":"sample777",
"test":"test777"
}
And the following luna call is made:
# luna-send -n 1 -m com.webos.service.configurator luna://com.webos.service.db/put '{
"objects":[
{
"_kind":"com.webos.service.test:1",
"_id":"JZR3hyjVyB3",
"_rev":12,
"sample":"sample777"
}
]
}'
If the call is successful, the database will contain:
{
"_rev": 13,
"sample": "sample777",
"_id": "JZR3hyjVyB3",
"_kind": "com.webos.service.test:1"
}
Update (Merge):
Sometimes a service does not need to replace an object in the database, but simply needs to add a field to a database object. For this type of update, a client can call the merge method instead of the put method.
For example, if we have an object:
{
"_kind":"com.webos.service.test:1",
"_id":"JZR3hyjVyB3",
"_rev":12,
"name":"MAX",
"sample":"sample777",
"test":"test777"
}
And the following luna call is made:
# luna-send -n 1 -m com.webos.service.configurator luna://com.webos.service.db/merge '{
"objects":[
{
"_kind":"com.webos.service.test:1",
"_id":"JZR3hyjVyB3",
"_rev":12,
"sername":"Super Hero!!!"
}
]
}'
If the call is successful, the database will contain:
{
"_kind":"com.webos.service.test:1",
"_id":"JZR3hyjVyB3",
"_rev":13,
"name":"MAX",
"sername":"Super Hero!!!",
"sample":"sample777",
"test":"test777"
}
Trick with put/merge and object revision:
The _rev object field shows the revision number of an object. But what happens if an application wants to track updates to specific field/fields? DB8 can do that.
The application should modify the Kind and add revSets.
Revision set (revSets) is a set of object field names, that the database should track for changes. If the tracked field(s) are modified, the database will increment the number.
# luna-send -n 1 -f luna://com.webos.service.db/putKind '{
"id":"com.webos.service.test:2",
"owner":"com.webos.service.test",
"indexes":[
{
"name":"field1",
"props":[
{
"name":"field1"
}
]
},
{
"name":"field2",
"props":[
{
"name":"field2"
}
]
},
{
"name":"field12",
"props":[
{
"name":"field1"
},
{
"name":"field2"
}
]
},
{
"name":"field21",
"props":[
{
"name":"field2"
},
{
"name":"field1"
}
]
}
],
"revSets":[
{
"name":"field1_rev",
"props":[
{
"name":"field1"
}
]
}
]
}'
The above modification to the Kind tells DB8 to do the following:
- Add the field1_rev field to each object
- Increase its value when the field1 object is modified.
The default value of field1_rev will be the same as object _rev.
Example:
Lets create a new object:
# luna-send -n 1 luna://com.webos.service.db/put '{
"objects":[
{
"_kind":"com.webos.service.test:1",
"field1":"a",
"field2":"a"
}
]
}'
In the database, the object will be stored as:
{
"field1_rev":408,
"_rev":408,
"field1":"a",
"field2":"a",
"_id":"++JZlENT5FkVcjy3",
"_kind":"com.webos.service.test:1"
}
The database then adds the field1_rev field to the object.
When an application updates field1, DB8 will automatically increment the field1_rev field:
# luna-send -n 1 luna://com.webos.service.db/merge '{
"objects":[
{
"_id":"++JZlENT5FkVcjy3",
"_kind":"com.webos.service.test:2",
"_rev":408,
"field1":"Join to dark DB8 side, Luke!"
}
]
}'
The database will contain:
{
"field1_rev":409,
"_rev":409,
"field1":"Join to dark DB8 side, Luke!",
"field2":"c",
"_id":"++JZlENT5FkVcjy3",
"_kind":"com.webos.service.test:2"
}
Now, if we update the field2 only, the database will not increment the field1_rev field, as it does not track updates to field2.
# luna-send -n 1luna://com.webos.service.db/merge '{
"objects":[
{
"_id":"++JZlENT5FkVcjy3",
"_kind":"com.webos.service.test:2",
"_rev":409,
"field2":"Lalala"
}
]
}'
The database will contain:
{
"field1_rev":409,
"_rev":410,
"field1":"Join to dark DB8 side, Luke!",
"field2":"Lalala",
"_id":"++JZlENT5FkVcjy3",
"_kind":"com.webos.service.test:2"
}
Queries:
DB8 guarantees complexity for all CRUD (create, read, update, delete) API calls.
To retrieve data, a client can call either the get or the find method.
- The get method provides the ability to get an object by the object id.
Complexity guaranteed for get API call is log(n) - The find method provides the ability to get objects by condition. The find query must use the index fields of an object for searching.
Complexity guaranteed for the find API call is log(n) - The search method provides the ability to get objects by condition. The search Query uses any object field for searching.
Complexity guaranteed for the search API call is n.
It may not be clear, why the find method does not allow operations, like filter or sub-string search. Think about it this way: DB8 always guarantees complexity for all of its API calls without exception. An operation like the filter can search by object fields that do not have indexes. In other words, DB8 would have to iterate over n objects to process the resulting set. However, since DB8 guarantees a complexity of log(n) to the find call, it does not allow the filtering operation.
Some quick examples for find (with collate and limit):
# luna-send -n 1 luna://com.webos.service.db/find '{
"query":{
"from":"com.webos.service.test:1",
"where":[
{
"prop":"sample",
"op":"=",
"val":"test1"
}
],
"limit":1
}
}'
Quick example for search:
# luna-send -n 1 luna://com.webos.service.db/search '{
"query":{
"from":"com.webos.service.test:1",
"where":[
{
"prop":"name",
"op":"=",
"val":"max"
}
],
"limit":1
}
}'
Pages:
Processing of result sets that contain a lot of objects (thousands, millions, etc) can consume all available memory. Assume that a database has 1 million objects and we need to build a JSON representation of those objects on a target system that has only 1M of free RAM. How can that be achieved? To handle such a scenario, DB8 will output result sets by pages. Each page will have a limit on the maximum number of objects it can contain. If an application does not specify a limit in find/search, DB8 will add a default limit. On most platforms, the default limit value is 500 objects per page, but this can be reconfigured.
For example, we retrieve data from a DB8 database on a Tamagochi device (each page will contain only two objects):
# luna-send -f -n 1 luna://com.webos.service.db/find '{
"query":{
"from":"com.webos.service.test:1",
"limit":2
}
}'
DB8 response:
{
"next":"1lg403dPJY4mHMCDHJd9+F",
"returnValue":true,
"results":[
{
"name":"max",
"_rev":3,
"sample":"sample1",
"test":"test1",
"_id":"JZQjZfgzFPw",
"_kind":"com.webos.service.test:1"
},
{
"name":"max",
"_rev":8,
"sample":"sample1",
"test":"test1",
"_id":"JZR1rIsNIJJ",
"_kind":"com.webos.service.test:1"
}
]
}
The next parameter in the response indicates the ID of the next page in the result data set (internally, DB8 interprets this id as a very tricky offset). To get the next object in the result data set, execute query with a page parameter:
# luna-send -f -n 1 luna://com.webos.service.db/find '{
"query":{
"from":"com.webos.service.test:1",
"limit":2,
"page":"1lg403dPJY4mHMCDHJd9+F"
}
}'
And DB8 will response with next 2 objects and id of the next page:
{
"next":"1lg403dPJYCcTLdLTJ7n+F",
"returnValue":true,
"results":[
{
"name":"max",
"_rev":9,
"sample":"sample2",
"test":"test2",
"_id":"JZR1vy_Lb8c",
"_kind":"com.webos.service.test:1"
},
{
"sername":"Super Hero!!!",
"_rev":15,
"sample":"sample777",
"_id":"JZR3hyjVyB3",
"_kind":"com.webos.service.test:1"
}
]
}
If DB8 does not have any objects in the result set and the last retrieved page contains the final objects from the result set, DB8 will not provide the next parameter in the response.
Complex Queries:
For this section we are using the following test Kind:
# luna-send -n 1 -a com.webos.service.configurator luna://com.webos.service.db/putKind '{
"id":"com.webos.service.test:1",
"owner":"com.webos.service.test",
"indexes":[
{
"name":"field1",
"props":[
{
"name":"field1"
}
]
},
{
"name":"field2",
"props":[
{
"name":"field2"
}
]
},
{
"name":"field12",
"props":[
{
"name":"field1"
},
{
"name":"field2"
}
]
}
]
}'
Example database set for this documentation section:
| field1 | field2 |
|---|---|
| a | a |
| a | b |
| b | a |
| b | b |
For test queries, we use these put API calls:
# luna-send -n 1 luna://com.webos.service.db/put '{
"objects":[
{
"_kind":"com.webos.service.test:1",
"field1":"a",
"field2":"a"
},
{
"_kind":"com.webos.service.test:1",
"field1":"a",
"field2":"b"
},
{
"_kind":"com.webos.service.test:1",
"field1":"b",
"field2":"a"
},
{
"_kind":"com.webos.service.test:1",
"field1":"b",
"field2":"b"
}
]
}'
In the Queries section you can find how to create an index for one field and execute some trivial queries, like:
"where":[{"prop":"field1","op":"=", "val":"a" }
If an application developer tries to search using two fields at the same time:
"where":[{"prop":"field1","op":"=", "val":"a" }, {"prop":"field2","op":"=","val":"b"}]
DB8 will return "Sorry, I don't know such index". This error is returned because the DB8 Planner is not very intelligent and will never try to guess the index.
An application developer should provide complex indexes for such complex quires. To get an object using 2 fields (third object from example set):
(field1 == b) && (field2 == a)
The client should provide the Kind for such index like following:
{"name":"field12","props":[ {"name": "field1"}, {"name" : "field2"}] }
(See at top of this documentation section for full luna comand for kind creation.)
After modification of the Kind, an application can execute a query like this:
# luna-send -n 1 -f luna://com.webos.service.db/find '{
"query":{
"from":"com.webos.service.test:1",
"where":[
{
"prop":"field1",
"op":"=",
"val":"a"
},
{
"prop":"field2",
"op":"=",
"val":"b"
}
]
}
}'
Complex Queries Tricks:
Imagine, that an application developer extends a Kind with a complex index like the one below, and then tries to execute it:
(field1 < b) && (field2 == b)
# luna-send -n 1 -f luna://com.webos.service.db/find '{
"query":{
"from":"com.webos.service.test:1",
"where":[
{
"prop":"field1",
"op":"<",
"val":"a"
},
{
"prop":"field2",
"op":"=",
"val":"b"
}
]
}
}'
DB8 will return "Index not found", even if you have created a complex index for field1 and field2. In the example below, the index has the name field12.
To work around this, you should also create a reverse index field21:
{"name":"field21","props":[ {"name": "field2"}, {"name" : "field1"}] }
# luna-send -n 1 luna://com.webos.service.db/putKind '{
"id":"com.webos.service.test:1",
"owner":"com.webos.service.test",
"indexes":[
{
"name":"field1",
"props":[
{
"name":"field1"
}
]
},
{
"name":"field2",
"props":[
{
"name":"field2"
}
]
},
{
"name":"field12",
"props":[
{
"name":"field1"
},
{
"name":"field2"
}
]
},
{
"name":"field21",
"props":[
{
"name":"field2"
},
{
"name":"field1"
}
]
}
]
}'
After such a tricky index creation, DB8 can successfully search for data.
Watch:
Sometimes a client may want to be notified about an object in a database that satisfies some condition. For this, the client can use the watch method.
Example:
# luna-send -i -m com.webos.service.configurator luna://com.webos.service.db/watch '{
"query":{
"from":"com.webos.service.test:1",
"where":[
{
"prop":"processed",
"op":"=",
"val":false
}
]
},
"subscribe":true
}'
If no object exists with the field processed=false for Kind com.webos.service.test:1, the client will be blocked in the watch method. The watch will be unblocked when an object that satisfies a query will appear in a database. In the example above, the database will have an object for com.webos.service.test:1 with field processed=false (if someone will insert object or modify field for an existing object).
Note about blocking: For a blocking watch API call, the caller cannot do anything until the watch API call returns. It is very similar to system calls blocks.
Example of watch response, when it is unblocked:
{
"returnValue": true,
"fired": true
}
The fired param in the response informs the client that DB8 contains one or more objects that satisfy the watch query and that the client can retrieve those objects.
Sample workflow for the watch method:
Assume that you are developing a chat application.
The chat application creates a DB8 Kind com.chat.messages:1
The chat application will have 2 independent threads: A UI thread that shows messages and a reader thread, that receives messages from the network.
- Phase: Application startup
UI thread reads all objects from com.chat.messages:1 Kind and shows the messages to the end-user. - Phase: UI Blocks till new message arrive
UI thread calls DB8 watch method with the query: processed=false. If the database does not have such objects, the UI thread is blocked in the watch API call. - Phase: reader thread receives a new message
The reader thread receives messages over the network, stores those messages into com.chat.messages:1 with set field processed=false. - Phase: UI thread unblocked
The Database unblocks watch API call (UI thread was blocked in watch API call on step 2), the UI executes the query find with parameter processed=false - Phase: UI thread processes the new message
For each new object in the result set, the UI thread shows those object to the end-user. To indicate, that each new object was processed and shown to the end-user by the UI, UI thread set field processed=false and merge each object into the database. - Phase: UI thread is blocked again
UI go to step 2.
Collation:
Information is displayed in sorted order to enable users to easily find the items they are looking for. However, users of different languages might have very different expectations of what a "sorted" list should look like. Not only does the alphabetical order vary from one language to another, but it also can vary from document to document within the same language. For example, phone book ordering might be different than dictionary ordering. String comparison is one of the basic functions most applications require, and yet implementations often do not match local conventions. Collation provides string comparison capability with support for appropriate sort orderings for each of the locales needed by a client.
Collation rule:
A RuleBasedCollator is built from a rule string that changes the sort order of some characters and strings relative to the default order. An empty string (or one with only white space and comments) results in a collator that behaves like the root collator.
Customization is specified via a string containing a set of rules. ICU implements the (CLDR). For more details see LDML collation rule syntax.
Each rule contains a string of ordered characters that starts with an anchor point or a reset value. For example, "&a < g", places "g" after "a" and before "b", and the "a" does not change place. This rule has the following sorting consequences:
| Without rule | With rule |
|---|---|
| apple | apple |
| Abernathy | Abernathy |
| bird | green |
| Boston | bird |
| green | Boston |
| Graham | Graham |
Note: Only the word that starts with "g" has changed place. All the words sorted after "a" and "A" are sorted after "g".
This is a non-complex example of a custom rule. Custom rules consist of zero or more rules and zero or more options. There must be at least one rule or at least one option. The rule syntax is discussed in more detail in the following sections.
Note: The custom rules override the UCA ordering. In addition, if a character is reordered, it automatically reorders any other equivalent characters. For example, if the rule "&e<a" is used to reorder "a" in the list, "á" is also greater than "é".
Syntax:
The following table summarizes the basic syntax necessary for most usages:
| Symbol | Example | Description |
|---|---|---|
| < | a < b | Identifies a primary (base letter) difference between "a" and "b". |
| << | a << ä | Signifies a secondary (accent) difference between "a" and "ä". |
| <<< | a <<< A | Identifies a tertiary difference between "a" and "A". |
| <<<< | か<<<<カ | Identifies a quaternary difference between "か" and "カ". (New in ICU 53.) ICU permits up to three quaternary relations in a row (except for intervening "=" identity relations). |
| = | x = y | Signifies no difference between "x" and "y". |
| & | &Z | Instructs ICU to reset at this letter. These rules will be relative to this letter from here on, but will not affect the position of Z itself. |
For more information, see:
Collation can be specified in the putKind or the find method.
Example of using collator with putKind - set default collation for kind:
# luna-send -n 1 luna://com.webos.service.db/putKind '{
"id":"com.webos.service.test:1",
"owner":"com.webos.service.test",
"indexes":[
{
"name":"sample",
"props":[
{
"name":"sample"
}
]
},
{
"name":"testsample",
"props":[
{
"name":"test"
},
{
"name":"sample"
}
]
}
],
"collation":"secondary"
}'
Internally, DB8 processes strings via ICU. All ICU documentation about strings somewhat applies to DB8 string processing.
Permissions:
DB8 is the central storage for applications. Every application can not only store/retrieve data by itself, but it can also share and interact with other applications.
The application can share kind and grant permissions for any CRUD operator. For more information, see putPermissions method.
Quotas:
The function of quotas is to allocate limited disk space in a reasonable way for the target device. Those limits are set by product developers via DB8 configuration files.
In other words, quotas limit the amount of disk space that can be used by a certain application. Every process can see its quota usage by using the quotaStats method.
Encoding:
When the DB8 daemon starts, it uses UTF8 en_US.en_US encoding which is its default encoding.
DB8 subscribes for com.webos.service.systemservice/getPreferences '{ "keys" : "locale"}' . If the systemservice does not exist on the platform or returns an error, DB8 will continue use UTF8 en_US.en_US encoding by default.
Disk Storage Logic:
When DB8 starts, it creates 2 activities in Activity Manager:
- Scheduled space check
- Garbage collector (purge)
Activity for space check will check for available storage space. If the free storage space is too low, DB8 will reject all new CRUD API calls with quota exceeded error. If the storage has enough free space, then on the next scheduled space check DB8 will continue to process CRUD API calls.
Garbage collector:
By default, DB8 does not remove objects from its database, it only marks it for future delete. DB8 use this logic, as an update operation takes less resources compared with delete. Physical objects are removed when processed by the DB8 garbage collector.
The garbage collector can be called in 2 ways: by ActivityManager or directly by service.
On startup, DB8 dynamically registers an activity to call the garbage collector.
If the client wants to delete an object and immediately free storage space, the client can specify the purge option in the del method. The del API call with the purge parameter can be potentially slow.
Complexity for garbage collector: m*log(n), where m - count of objects marked for removal.
Error handling:
If DB8 cannot process method calls (internal error, bad params, no resources, etc) it always returns an error in the following format:
- returnValue - If an error occurs, it will contain false
- errorCode - Code that indicates the cause of the error
- errorText - Text representation of the error code
Error codes and descriptions are provided for each method call. For example, if the client calls the load method with a bad parameter:
# luna-send -n 1 -f -m com.webos.service.configurator luna://com.webos.service.db/load '{"path" : "/tmp/dump.json" }'
{
"returnValue": false,
"errorCode": 2,
"errorText": "No such file or directory"
}
The above response indicates, that:
- returnValue: false - method call failed
- errorCode: 2 - See the load method for more details on error code 2
- errorText: No such file or directory - A quick textual explanation of the error
Basic API functions:
It provides the following data management functions:
- Add objects
- Update objects
- Delete objects
- Query objects
- Manage access to objects within the database
Methods
batch
ACG: database.operation
- Added:
API level 11
Description
The batch method 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
Name | Required | Type | Description |
|---|---|---|---|
| operations | Required | Object array: BatchOperation | The operations parameter contains the list of database operations to perform. |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| batchResponse | Optional | Object: BatchResponse | If DB8 modifies any record, status of the executing batch will be returned in a BatchResponse object |
| errorCode | Optional | Number | The error code for the failed operation. |
| errorText | Optional | String | Indicates the reason for the failure of the operation. See the "Error Codes" section of this method for details. |
| returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
Error Codes Reference
Error Code | Error Text | Error Description |
|---|---|---|
| -3984 | No required key: "method" | This message implies that the required database operations name is missing. |
| -3984 | No required key: "params" | This message implies that the required parameters for a database operation are missing. |
| -3982 | db: invalid operation in batch | This message implies that an incorrect or an unsupported database operation was specified in the operations parameter. |
Example
Example code
# luna-send -n 1 -f -a com.webos.service.test luna://com.webos.service.db/batch '{
"operations":[
{
"method":"put",
"params":{
"objects":[
{
"_kind":"com.webos.service.test:1",
"sample":"sample1",
"test":"test1"
}
]
}
},
{
"method":"merge",
"params":{
"query":{
"from":"com.webos.service.test:1",
"where":[
{
"prop":"sample",
"op":"=",
"val":"sample1"
}
]
},
"props":{
"sample":"sample2",
"test":"test2"
}
}
}
]
}'
Response:
{
"responses":[
{
"returnValue":true,
"results":[
{
"id":"J8qx+EwdBs7",
"rev":2
}
]
},
{
"count":1,
"returnValue":true
}
],
"returnValue":true
}
cancelSearch
ACG: database.operation
- Added:
API level 11
Description
Stops the search operation mid-way.
This method can be used when the search operation takes a long time to return results or required to search with another keyword without waiting for previous search results. It is not applicable to situations where the search method returns results immediately.
Note: For this method to work, the search() API must be configured with the 'cancelable' parameter set to 'true'.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| taskId | Required | String | Unique identifier of the search operation. Obtained using the search() API. |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
| errorCode | Optional | Number | The error code for the failed operation. |
| errorText | Optional | String | Indicates the reason for the failure of the operation. See the "Error Codes" section of this method for details. |
Error Codes Reference
Error Code | Error Text | Error Description |
|---|---|---|
| -3984 | db: find_bKkNbX job does not exist | When there is no active search or when the search is already completed. |
Example
Example code
# luna-send -n 1 -f luna://com.webos.service.db/cancelSearch '{"taskId": "find_sEhKeU"}'
Response:
{
"returnValue":true
}
compact
ACG: database.management
- Added:
API level 11
Description
The compact method invokes the low level garbage collector. When DB8 executes a del operation without Purge:True param, it only marks the object as to be deleted. The object will be removed by DB8, when the garbage collector is called. To call the garbage collector manually, the client can call the compact method.
This command is implemented only for the LevelDB and Sandwich engine.
Parameters
None
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
| errorCode | Optional | Number | The error code for the failed operation. |
| errorText | Optional | String | Indicates the reason for the failure of the operation. See the "Error Codes" section of this method for details. |
Error Codes Reference
Error Code | Error Text | Error Description |
|---|---|---|
| -3997 | db: corrupt database | This message implies that some part of the database is logically corrupted. |
| -3988 | db: backup file is full | This message implies that the storage does not have free space. |
Example
Example code
# luna-send -n 1 -f luna://com.webos.service.db/compact '{}'
Response:
{
"returnValue":true
}
del
ACG: database.operation
- Added:
API level 11
Description
The del method deletes JSON data objects from the database.
Apps can specify the objects to be deleted by providing:
- a set of IDs to be deleted
- a DB8 query
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| ids | Optional | String array | The ids parameter contains 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 in the query parameter. |
| query | Optional | Object: Query | The query parameter contains 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 of the purge parameter is false.
|
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| results | Optional | Object array: Results | When the del method succeeds, and the objects to be deleted were specified as a list of JSON object ids, the del method will return a list of deleted ids. |
| count | Optional | Number | When the del method succeeds, and the objects to be deleted were specified as a query, the del method will return a count of deleted objects. |
| returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
| errorCode | Optional | Number | The error code for the failed operation. |
| errorText | Optional | String | Indicates the reason for the failure of the operation. See the "Error Codes" section of this method for details. |
Error Codes Reference
Error Code | Error Text | Error Description |
|---|---|---|
| -3965 | db: no index for query | This message implies that the query is referring to an index that does not exist for the specified kind. |
| -3963 | db: permission denied | This message implies that the app does not have permission to delete the specified object. |
| -3962 | db: quota exceeded | This message implies that 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
Example code
Example 1: Using ID
# luna-send -n 1 -f luna://com.webos.service.db/del '{"ids" :["J8rBI6u7uh+"]}'
Response:
{
"returnValue":true,
"results":[
{
"id":"J8rBI6u7uh+"
}
]
}
Example 2: Using query
# luna-send -n 1 -f -a com.webos.service.test luna://com.webos.service.db/del '{"query" : { "from" : "com.webos.service.test:1"}}'
Response:
{
"count":11,
"returnValue":true
}
delKind
ACG: database.operation
- Added:
API level 11
Description
The delKind method deletes a Kind from the database. Deleting a Kind deletes ALL data objects of that Kind.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| id | Required | String | The id parameter contains the id of the kind the app wants to delete. |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
| errorCode | Optional | Number | The error code for the failed operation. |
| errorText | Optional | String | Indicates the reason for the failure of the operation. See the "Error Codes" section of this method for details. |
Error Codes Reference
Error Code | Error Text | Error Description |
|---|---|---|
| -3999 | db: access denied | This message implies that the specified kind exists in the database, however the app does not have the delete permissions. |
| -3970 | db: kind not registered | This message implies that the specified kind doesn't exist in the database. |
Example
Example code
# luna-send -n 1 -f -a com.webos.service.configurator luna://com.webos.service.db/delKind '{"id" : "com.webos.service.test:1"}'
Response:
{
"returnValue":true
}
dump
ACG: database.management
- Added:
API level 11
Description
Backs up a database. The file created by the dump method typically contains JSON statements to recreate all of the Kinds and data of the database from which they have been dumped.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| path | Required | String | Path to the dump file |
| incDel | Optional | Boolean | If true, also include deleted objects. |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| count | Required | Number | The total number of objects stored if the dump method succeeds. |
| returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
| errorCode | Optional | Number | The error code for the failed operation. |
| errorText | Optional | String | Indicates the reason for the failure of the operation. See the "Error Codes" section of this method for details. |
Error Codes Reference
Error Code | Error Text | Error Description |
|---|---|---|
| -3998 | db: backup file is full | This message implies that there is insufficient space to create a backup file or that the backup file size exceeds COUNT limit. |
Example
Example code
# luna-send -n 1 -f -a com.webos.service.configurator luna://com.webos.service.db/dump '{"path":"/tmp/dump.json"}'
Response:
{
"count":0,
"returnValue":true
}
find
ACG: database.operation
- Added:
API level 11
Description
The find method 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.
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 distinct groups enabling the app to remove duplicate objects.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| query | Required | Object: Query | DB8 query for retrieving results. |
| count | Optional | Boolean | The 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. |
| watch | Optional | Boolean | The 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. |
| subscribe | Optional | Boolean | Subscription is enabled if true. |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| results | Required | Object array | 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. |
| fired | Optional | Boolean | Change notification flag. Note: Returned only if the watch parameter is set to true by the app. |
| returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
| errorCode | Optional | Number | The error code for the failed operation. |
| errorText | Optional | String | Indicates the reason for the failure of the operation. See the "Error Codes" section of this method for details. |
Error Codes Reference
Error Code | Error Text | Error Description |
|---|---|---|
| -3978 | db: invalid query | This message implies that the query syntax is correct, but contains misspelled commands or logical errors. |
| -3970 | db: kind not registered | This message implies that the specified kind is not registered in the database. |
| -3965 | db: no index for query | This message implies that the SELECT query contains field name(s) that do not exist for the selected kind. |
| -3963 | db: permission denied | This message implies that the specified kind exists in the database, however the app does not have permissions to read the data for the specified kind. |
Example
Example code
Note: Should execute putKind, put APIs before calling find API. To get the below result, 2 entries should be added using put API.
# luna-send -n 1 -f -a com.webos.service.test luna://com.webos.service.db/find '{
"query":{
"from":"com.webos.service.test:1",
"where":[
{
"prop":"sample",
"op":"=",
"val":"sample1"
}
]
}
}'
Response:
{
"returnValue":true,
"results":[
{
"_rev":19,
"sample":"sample1",
"test":"test1",
"_id":"J8rKQDOvxdF",
"_kind":"com.webos.service.test:1"
},
{
"_rev":21,
"sample":"sample1",
"test":"test1",
"_id":"J8rKTaBClIo",
"_kind":"com.webos.service.test:1"
}
]
}
get
ACG: database.operation
- Added:
API level 11
Description
The get method retrieves JSON data objects by ids. This is the fastest way to retrieve data.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| ids | Required | String array | Ids of the JSON data objects to retrieve. |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| results | Required | Object array | Returns an array of stored db8 data objects. |
| returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
| errorCode | Optional | Number | The error code for the failed operation. |
| errorText | Optional | String | Indicates the reason for the failure of the operation. See the "Error Codes" section of this method for details. |
Error Codes Reference
Error Code | Error Text | Error Description |
|---|---|---|
| -3999 | db: access denied | This message implies that the specified object exists in the database, but the app does not have permissions to access the object. |
| -3950 | db: I/O error | This message implies that it is not possible to read from the database and that this is a critical error. |
Example
Example code
# luna-send -n 1 -f luna://com.webos.service.db/get '{"ids" : ["J8rKTaBClIo"]}'
Response:
{
"returnValue":true,
"results":[
{
"_rev":21,
"sample":"sample1",
"test":"test1",
"_id":"J8rKTaBClIo",
"_kind":"com.webos.service.test:1"
}
]
}
getProfile
ACG: database.profiling
- Added:
API level 11
Description
Get profiling data for applications. Profile data includes the queries made and related information such as request time and response time.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| application | Optional | String | Name of application for which to get profile data.
|
| query | Optional | Object: Query | Additional filters for retrieving profile data. |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | Indicates the status of the operation.
|
| results | Optional | Object array | If the method succeeds, the relevant details are returned in the response. |
| errorCode | Optional | Number | Indicates the error code for the failed operation. |
| errorText | Optional | String | Indicates the reason for the failure of the operation. See the "Error Codes" section of this method for details. |
Error Codes Reference
Error Code | Error Text | Error Description |
|---|---|---|
| -3978 | db: invalid query | The query syntax is correct but contains misspelled commands or logical errors. |
| -3970 | db: kind not registered | The specified kind is not registered in the database. |
| -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, but the app does not have permissions to read the data for the specified kind. |
| -3947 | db: profiling feature is not supported | DB8 profiling feature is not supported. |
| -3946 | db: profiling not enabled for this application | Application profiling is disabled. Enable it by using the "profile" method. |
| 22 | "invalid parameters: caller='com.palm.configurator' error='invalid type for property 'query'' | When Invalid Parameters are passed. |
Example
Example code
Example 1: Get profile data for application "com.webos.service.test:3"
# luna-send -n 1 -a com.webos.service.test:3 luna://com.webos.service.db/getProfile '{ }' -f
Response:
{
"returnValue": true,
"results": [
{
"memory_info": "%MEM=1.01, VSS=70104, RSS=7888, SHR=6264",
"application": "com.webos.service.test:3",
"category": "/",
"method": "get",
"_rev": 5366,
"payload": {
"ids": [
"J8rKTaBClIo"
]
},
"_kind": "com.webos.service.test:3.profile:1",
"_id": "+++11eN6jck",
"time": "0.083334"
},
{
"memory_info": "%MEM=1.01, VSS=70104, RSS=7888, SHR=6264",
"application": "com.webos.service.test:3",
"category": "/",
"method": "put",
"_rev": 5368,
"payload": {
"objects": [
{
"sample": "sample1",
"test": "test1",
"_id": "14f9",
"_kind": "com.webos.service.tes:3t.profile:1"
}
]
},
"_kind": "com.webos.service.test:3.profile:1",
"_id": "+++19DpixTc",
"time": "0.066458"
},
{
"_rev": 5370,
"sample": "sample1",
"test": "test1",
"_id": "+++1BZDmwCg",
"_kind": "com.webos.service.test:3.profile:1"
},
{
"memory_info": "%MEM=1.01, VSS=70104, RSS=7888, SHR=6264",
"application": "com.webos.service.test:3",
"category": "/",
"method": "put",
"_rev": 5371,
"payload": {
"objects": [
{
"sample": "sample1",
"test": "test1",
"_id": "14fc",
"_kind": "com.webos.service.test:3.profile:1"
}
]
},
"_kind": "com.webos.service.test:3.profile:1",
"_id": "+++1BZHnhrV",
"time": "0.321958"
}
]
}
Example 2: Get profile data for an application for only get commands.
# luna-send -n 1 -a com.webos.service.test:3 luna://com.webos.service.db/getProfile '{
"application":"com.webos.service.test:3",
"query":{
"where":[
{
"prop":"method",
"op":"=",
"val":"get"
}
]
}
}' -f
Response:
{
"returnValue": true,
"results": [
{
"memory_info": "%MEM=1.01, VSS=70104, RSS=7888, SHR=6264",
"application": "com.webos.service.test:3",
"category": "/",
"method": "get",
"_rev": 5366,
"payload": {
"ids": [
"J8rKTaBClIo"
]
},
"_kind": "com.webos.service.test:3.profile:1",
"_id": "+++11eN6jck",
"time": "0.083334"
}
]
}
internal/postBackup
ACG: database.management
- Added:
API level 23
Description
An internal DB8 method that is called when a backup operation has been completed.
Parameters
None
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | If the internal/postBackup method succeeds, returnValue will contain true. If the internal/postBackup method fails, returnValue will contain false. The postBackup method may fail because of:
|
| errorCode | Optional | Number | The error code for the failed operation. |
| errorText | Optional | String | Indicates the reason for the failure of the operation. |
Error Codes Reference
Error Code | Error Text | Error Description |
|---|---|---|
| -1990 | json: error parsing prop name at 1:2 | invalid json format input parameter. |
| -1989 | json: unexpected char at 1:9 | invalid json format input parameter. |
Example
Example scenario
# luna-send -n 1 -a com.webos.service.configurator -f luna://com.webos.service.db/internal/postBackup '{}'
Response:
{
"returnValue": true
}
Example scenario
# luna-send -n 1 -a com.webos.service.configurator -f luna://com.webos.service.db/internal/postBackup '{"Test":db}'
Response:
{
"errorCode": -1989,
"errorText": "json: unexpected char at 1:9",
"returnValue": false
}
Example scenario
# luna-send -n 1 -a com.webos.service.configurator -f luna://com.webos.service.db/internal/postBackup '{123:123}'
Response:
{
"errorCode": -1990,
"errorText": "json: error parsing prop name at 1:2",
"returnValue": false
}
internal/postRestore
ACG: database.management
- Added:
API level 21
Description
An internal DB8 method that is called when the database finishes a restore process.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| tempDir | Required | String | Directory where the JSON dump file is stored. |
| files | Required | String array | List of files to load from tempDir |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | If the <internal/postRestore> method succeeds, returnValue will contain true. If the <internal/postRestore> method fails, returnValue will contain false. The <internal/postRestore> method may fail because of:
|
Example
None
internal/preBackup
ACG: database.management
- Added:
API level 21
Description
Invoked when an internal webOS service wants to restore a database from a backup file.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| tempDir | Required | String | Directory where the JSON dump files are stored. |
| maxTempBytes | Required | Number | Maximum size allowed for the dump file. |
| incrementalKey | Optional | Object | Provides list of revisions to be dumped |
| deletedRev | Optional | Number (int32_t) | Deleted revision value that increase after operation |
| rev | Optional | Number (int32_t) | revision value that increase after operation |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| files | Required | Object array | List of files that were created by the dump method. |
| returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
| full | Optional | Boolean | If pre-backup is full, then returns true. Else, false. |
| warnings | Optional | Number (int32_t) | Number of warnings during pre-backup operation. |
| description | Optional | String | Pre-backup operation identifier. |
| incrementalKey | Optional | Object: Query | Incremental key revision number for pre-backup operation. |
| version | Optional | Number (int32_t) | Pre-backup version for a given operation. |
Example
Example code
# luna-send -n 1 -m com.webos.service.configurator -f luna://com.webos.service.db/internal/preBackup '{
"tempDir": "/tmp/",
"maxTempBytes" : 777 ,
"incrementalKey" : {
"deletedRev" : 1,
"rev" : 1
}
}'
Response:
{
"returnValue":true,
"description":"incremental=1",
"warnings":0,
"files":[
"backup-1457026101363953.json"
],
"full":false,
"incrementalKey":{
"rev":4675
},
"version":8
}
internal/preRestore
ACG: database.management
- Added:
API level 21
Description
Used by the webOS service to correctly respond to a database restore command. This method must be called before restoring a database.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| version | Required | String | version is the database version that is to be restored. |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| proceed | Required | Boolean | proceed will contain true if the database revision is greater than the verison key provided in the version parameter. |
| returnValue | Required | Boolean | If the internal/preRestore method succeeds, returnValue will contain true. If the internal/preRestore method fails, returnValue will contain false. The internal/preRestore method may fail because of:
|
Example
None
internal/releaseAdminProfile
ACG: database.management
- Added:
API level 21
Description
For applications whose profiling is controlled by admin-privileged applications, this method relinquishes the profiling control from admin-privilged applications. The 3rd-party application can then control its own its own profiling.
Background: Once an admin-privileged application has enabled/disabled profiling for a 3rd-party application, then only admin-privileged applications can control the profiling for that application.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| application | Optional | String | Name of application for which admin permission must be relinquished.
|
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
| errorCode | Optional | Number | The error code for the failed operation. |
| errorText | Optional | String | Indicates the reason for the failure of the operation. See the "Error Codes" section of this method for details. |
Error Codes Reference
Error Code | Error Text | Error Description |
|---|---|---|
| -3999 | db: access denied | The caller application does not have admin permission. |
| -3946 | db: profiling not enabled for this application | Application profiling is disabled. Enable it by using the "profile" method. |
Example
Example code
Example 1: Admin-privileged application (com.webos.service.configurator) relinquishes its control over profiling for all 3rd-party applications.
# luna-send -n 1 -a com.webos.service.configurator luna://com.webos.service.db/internal/releaseAdminProfile '{"application":"*"}' -f
Example 2: Admin-privileged application (com.webos.service.configurator) relinquishes its control over profiling for the "com.webos.testApp" 3rd-party application.
# luna-send -n 1 -a com.webos.service.configurator luna://com.webos.service.db/internal/releaseAdminProfile '{"application":"com.webos.testApp"}' -f
internal/scheduledPurge
ACG: database.management
- Added:
API level 21
Description
An internal DB8 private method, used by activityManager. Activity manager periodically calls the DB8 garbage collector to remove data that has been marked for deletion.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| $activity | Required | Object: activity | $activity contain information about active ActivityManager job |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean |
The method may fail because of provided wrong $activity parameter |
Example
Example code
Step 1: Create an activity using ActivityManager
# luna-send -n 1 -f luna://com.webos.service.activitymanager/create '{
"activity":{
"name":"basicactivity",
"description":"Test create",
"type":{
"foreground":true
}
},
"start":true,
"subscribe":true
}'
Response:
{
"subscribed":true,
"activityId":87,
"returnValue":true
}
Step 2: Call sheduledPurge API
# luna-send -a com.webos.service.configurator -n 1 luna://com.webos.service.db/internal/scheduledPurge '{
"$activity": {"activityId": 87}
}'
Response:
{
"returnValue":true
}
internal/scheduledSpaceCheck
ACG: database.management
- Added:
API level 21
Description
An internal DB8 callback method, that is called by the Activity Manager for checking available disk space.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| $activity | Required | Object | Id of created activity by activity manager. |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | If the scheduledSpaceCheck method succeeds, returnValue will contain true. If the scheduledSpaceCheck method fails, returnValue will contain false. The scheduledSpaceCheck method may fail because of:
|
Example
None
internal/spaceCheck
ACG: database.management
- Added:
API level 21
Description
An internal DB8 private method, used by webOS private services. Services can subscribe for the spaceCheck method and get notifications when DB8 reaches soft and hard disk space limits.
Parameters
None
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| severity | Required | String | The level of severity reached. Can have one of the following values: none, warning, critical |
| bytesUsed | Required | Number | The number of bytes used in the partition |
| bytesAvailable | Required | Number | The number of bytes avaiable for db8 |
| path | Required | String | Path to the current active database |
Example
None
listActiveMedia
ACG: database.operation
- Added:
API level 21
Description
Returns a list of active attached media, and shards.
Parameters
None
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | If the listActiveMedia method succeeds, returnValue will contain true.
|
| media | Required | Object: media | List of active devices and their associated shards |
Example
Example code
# luna-send -f -n 1 luna://com.webos.mediadb/listActiveMedia '{}'
Response (When one media device is active):
{
"count":1,
"returnValue":true,
"media":[
{
"deviceId":"323031333032535030303739303230313132323230_1",
"mountPath":"/var/run/db8/mountpoints//174B7C9",
"deviceUri":"/tmp/usb/sda/sda1",
"shardId":"+MHrmF"
}
]
}
load
ACG: database.management
- Added:
API level 11
Description
Restores a database from a dumped JSON file.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| path | Required | String | The complete path of the JSON dump file. For example: /tmp/dump.json |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| count | Required | Number | Count of objects loaded from the dump file |
| returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
| errorCode | Optional | Number | The error code for the failed operation. |
| errorText | Optional | String | Indicates the reason for the failure of the operation. See the "Error Codes" section of this method for details. |
Error Codes Reference
Error Code | Error Text | Error Description |
|---|---|---|
| -987 | path too long | This message implies that the path provided for the dump file is too long |
| 2 | No such file or directory | File specified in path parameter not found or DB8 doesn't have permissions to read it |
Example
Example code
# luna-send -n 1 -f luna://com.webos.service.db/load '{"path": "/tmp/dump.json"}'
Response:
{
"count":0,
"returnValue":true
}
merge
ACG: database.operation
- Added:
API level 11
Description
The merge method updates the properties of existing objects.
The objects can be specified in one of the following ways:
- A query
- An array of IDs
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| objects | Optional | Object array | The object parameter is an array of objects, each object will have an id and key/value pairs that represent the object properties the app needs to merge. The objects parameter is required if the query parameter is not specified. |
| query | Optional | Object: Query | The query parameter is a Query object specifying the set of objects 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 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. |
| ignoreMissing | Optional | Boolean | Ignore if any key is missing |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| results | Optional | Object array: Results | If the objects parameter was specified, and the merge method succeeds, merge will return the ids and revisions of the updated object. |
| count | Optional | Number | If the query parameter was specified, and the merge method succeeds, merge will return the count of updated objects. |
| returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
| errorCode | Optional | Number | The error code for the failed operation. |
| errorText | Optional | String | Indicates the reason for the failure of the operation. See the "Error Codes" section of this method for details. |
Error Codes Reference
Error Code | Error Text | Error Description |
|---|---|---|
| -3965 | db: no index for query | This message implies that the query contains a SELECT for object properties that do not have an index associated with them. |
| -3963 | db: permission denied | This message implies that the app does not have permission to modify the specified objects. |
| -3961 | db: quota exceeded | This message implies that the app has exceeded its quota or there is no free space available on the device. |
Example
Example code
Example 1: How to update similar objects
# luna-send -n 1 -f -a com.webos.service.configurator luna://com.webos.service.db/merge '{
"objects":[
{
"_id":"J8rKTaBClIo",
"test":"test1",
"sample":"sample_updated_value"
}
]
}'
Response:
{
"returnValue":true,
"results":[
{
"id":"J8rKTaBClIo",
"rev":23
}
]
}
Example 2: How to update in all object with filed "sample" and value "sample1" to value "sample_updated_value"
# luna-send -n 1 -f -a com.webos.service.configurator luna://com.webos.service.db/merge '{
"query":{
"from":"com.webos.service.test:1",
"where":[
{
"prop":"sample",
"op":"=",
"val":"sample1"
}
]
},
"props":{
"sample":"sample_updated_value"
}
}'
Response:
{
"count":2,
"returnValue":true
}
mergePut
ACG: database.operation
- Added:
API level 11
Description
The mergePut method updates the properties of existing objects. If an object doesn't exist, a new one will be created in the database.
The object to be updated can be specified in one of the following ways:
- A query
- An array of IDs
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| objects | Optional | Object array | The object parameter is an array of objects, each object will have an id and key/value pairs that represent the object properties the app needs to merge. This is required if the query parameter is not specified. |
| query | Optional | Object: Query | The query parameter is a Query object specifying the set of objects 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 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
Name | Required | Type | Description |
|---|---|---|---|
| results | Optional | Object array: Results | If the objects parameter was specified, and the merge method succeeds, merge will return the ids and revisions of the updated object. |
| count | Optional | Number | If the query parameter was specified, and the merge method succeeds, merge will return the count of updated objects. |
| returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
| errorCode | Optional | Number | The error code for the failed operation. |
| errorText | Optional | String | Indicates the reason for the failure of the operation. See the "Error Codes" section of this method for details. |
Error Codes Reference
Error Code | Error Text | Error Description |
|---|---|---|
| -3965 | db: no index for query | This message implies that the query contains a SELECT for object properties that do not have an index associated with them. |
| -3963 | db: permission denied | This message implies that the app does not have permission to modify the specified objects. |
| -3961 | db: quota exceeded | This message implies that the app has exceeded its quota or there is no free space available on the device. |
Example
Example code
Example 1: How to an insert object, if it doesn't exist in the database
# luna-send -n 1 -f -a com.webos.service.configurator luna://com.webos.service.db/mergePut '{
"objects":[
{
"_id":"J8rKTaBClIo",
"test":"test1",
"sample":"sample_updated_value"
}
]
}'
Response:
{
"returnValue":true,
"results":[
{
"id":"J8rKTaBClIo",
"rev":23
}
]
}
profile
ACG: database.profiling
- Added:
API level 11
Description
Enables or disables DB8 profiling for an application. When enabled, profiling data is stored for the application.
You can enable DB8 profiling using one of the following approaches:
- Self enabling: In this approach, the 3rd-party application enables profiling on itself (see example 1).
- Enable profiling using admin-privileged applications: In the approach, an admin-privileged application controls DB8 profiling for 3rd-party applications. Use this approach when you want the admin to control the profiling of 3rd-party applications. You can choose to enable profiling for a single application or for all 3rd-party applications. See example 2 and 3.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| enable | Optional | Boolean | Status of DB8 profiling. Possible values: TRUE, FALSE Default value: TRUE |
| application | Optional | String | Name of application to be profiled.
|
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
| errorCode | Optional | Number | The error code for the failed operation. |
| errorText | Optional | String | Indicates the reason for the failure of the operation. See the "Error Codes" section of this method for details. |
Error Codes Reference
Error Code | Error Text | Error Description |
|---|---|---|
| -3963 | db: permission denied | The application does not have permission to enable/disable profiles for other applications. |
| -3947 | db: profiling feature is not supported | Profiling feature is not supported. |
| -3945 | db: profiling restricted by admin for this application | Profiling restricted by admin for this application. |
Example
Example code
Example 1: 3rd-party application "com.webos.testApp" enables profiling for itself.
# luna-send -f -a com.webos.testApp -n 1 luna://com.webos.service.db/profile '{"enable":true}'
Example 2: Admin-privileged application (com.webos.service.configurator) enables profiling for all 3rd-party applications.
# luna-send -n 1 -a com.webos.service.configurator luna://com.webos.service.db/profile '{"enable":true, "application":"*"}'
Example 3: Admin-privileged application (com.webos.service.configurator) enables profiling for the "com.webos.testApp" 3rd-party application.
# luna-send -n 1 -a com.webos.service.configurator luna://com.webos.service.db/profile '{"enable":true, "application":"com.webos.testApp"}'
purge
ACG: database.operation
- Added:
API level 11
Description
The purge method invokes the garbage collector. The purge method will:
- Remove all objects that were marked for deletion
- Perform a space check, and remove all temporary data
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| window | Optional | Number (int32_t) | purge window size |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | If the purge method succeeds, returnValue will contain true.
|
| count | Required | Number | count contains the total number of objects that were permanently deleted by the purge method. |
Example
Example code
Note: Should execute putKind, put, del (to delete some of entries added using put) APIs before calling purge API
# luna-send -n 1 -f -a com.palm.configurator luna://com.webos.service.db/purge '{}'
Response:
{
"count":0,
"returnValue":true
}
purgeStatus
ACG: database.operation
- Added:
API level 11
Description
The purgeStatus method returns the status of the last run purge command. If the last run purge command was successful, the objects were permanently deleted, and the purgeStatus method will return the updated database revision number.
Parameters
None
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | If the purgeStatus method succeeds, returnValue will contain true. If the purgeStatus method fails, returnValue will contain false. |
| rev | Required | Number | If the purgeStatus method is successful, rev will contain the updated database revision number. If the purgeStatus method fails, rev will contain database revision number before the purge. |
Example
Example code
Note: Should execute purge API before purgeStatus, refer purge API
#luna-send -n 1 -f -a com.palm.configurator luna://com.webos.service.db/purgeStatus '{}'
Response:
{
"rev": -1,
"returnValue": true
}
put
ACG: database.operation
- Added:
API level 11
Description
The put method 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
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. |
| shardId | Optional | String | Id of shard info |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| results | Required | Object array: Results | If the object was inserted, results will contain id and revision of the inserted object |
| returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
| errorCode | Optional | Number | The error code for the failed operation. |
| errorText | Optional | String | Indicates the reason for the failure of the operation. See the "Error Codes" section of this method for details. |
Error Codes Reference
Error Code | Error Text | Error Description |
|---|---|---|
| -3970 | db: kind not registered | This message implies that the kind for the specified object is not registered with the database. |
| -3963 | db: permission denied | This message implies that the app does not have permission to save objects of a specified kind. |
| -3962 | db: quota exceeded | This message implies that the app has exceeded its quota or there is no free space available on the device. |
Example
Example code
# luna-send -n 1 -f -a com.webos.service.configurator luna://com.webos.service.db/put '{
"objects":[
{
"_kind":"com.webos.service.test:1",
"sample":"sample1",
"test":"test1"
}
]
}'
Response:
{
"returnValue":true,
"results":[
{
"id":"J8rTIa65u++",
"rev":27
}
]
}
putKind
ACG: database.operation
- Added:
API level 11
Description
The putKind method 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 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.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| id | Required | String | Id of the kind to be registered with the database. |
| owner | Required | String | Owner of the kind. Only the owner has permission to modify the kind. Depending on whether service/app ID is provided, use one of the following:
|
| 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://json-schema.org/documentation.html |
| sync | Optional | Boolean | The sync parameter allows apps to enable backing up and restoring specific kinds of objects. The default value for the sync parameter is false. If the user moves to another device, the saved app data can be restored. |
| extends | Optional | String array | List of ids of parent kinds from which the kind has been derived. |
| indexes | Optional | Object: IndexClause | The indexes parameter contains indexes for the kind. |
| revsets | Optional | Object array: RevSetClause | List of database revision sets. |
| private | Optional | Boolean | Enable private data for putKind |
| assignId | Optional | Boolean | Enable assign id for putKind if true |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
| errorCode | Optional | Number | The error code for the failed operation. |
| errorText | Optional | String | Indicates the reason for the failure of the operation. See the "Error Codes" section of this method for details. |
Error Codes Reference
Error Code | Error Text | Error Description |
|---|---|---|
| -3981 | db: invalid owner for kind | This message implies that the specified owner does not have permissions to add or modify the specified kind. |
| -3962 | db: quota exceeded | This message implies that app has exceeded its quota or does not have enough disk space available to create the specified kind. |
Example
Example code
# luna-send -n 1 -f -a com.webos.service.test luna://com.webos.service.db/putKind '{
"id":"com.webos.service.test:1",
"owner":"com.webos.service.test",
"indexes":[
{
"name":"sample",
"props":[
{
"name":"sample"
}
]
},
{
"name":"testsample",
"props":[
{
"name":"test"
},
{
"name":"sample"
}
]
}
]
}'
Response:
{
"returnValue":true
}
putPermissions
ACG: database.operation
- Added:
API level 11
Description
The putPermissions method enables other apps or services to access an app's stored DB8 data. The app can give permissions to access data objects of a specific Kind.
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: operation | Database operations the app is granting permissions for. |
| create | Optional | String | To grant create permission, set the create parameter to allow. |
| read | Optional | String | To grant read permission, set the read parameter to allow. |
| update | Optional | String | To grant update permission, set the update parameter to allow. |
| delete | Optional | String | To grant delete permission, set the delete parameter to allow. |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
| errorCode | Optional | Number | The error code for the failed operation. |
| errorText | Optional | String | Indicates the reason for the failure of the operation. See the "Error Codes" section of this method for details. |
Error Codes Reference
Error Code | Error Text | Error Description |
|---|---|---|
| -3999 | db: access denied | This message implies that the app cannot modify the permissions of the specified kind. |
Example
Example code
# luna-send -n 1 -f -a com.webos.service.test luna://com.webos.service.db/putPermissions '{
"permissions":[
{
"operations":{
"read":"allow",
"create":"allow",
"update":"allow",
"delete":"allow"
},
"object":"com.webos.service.test:1",
"type":"db.kind",
"caller":"com.webos.service.testapp"
}
]
}'
Response:
{
"returnValue":true
}
putQuotas
ACG: database.management
- Added:
API level 11
Description
The putQuotas method provides the ability to update a quota's current service limits at runtime. This service is used by private webOS services to increase/decrease quotas for critical webOS services.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| quotas | Required | Object array: putQuotas | List of quotas |
| owner | Optional | String | Name of service |
| size | Optional | Number (int32_t) | quota size in bytes |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | If the putQuotas method succeeds, returnValue will contain true. If the putQuotas method fails, returnValue will contain false. The putQuotas method may fail because of:
|
Example
Example code
# luna-send -f -n 1 -a com.webos.service.configurator luna://com.webos.service.db/putQuotas '{
"quotas":[
{
"owner":"com.test",
"size":1000000
}
]
}'
Response:
{
"returnValue":true
}
And after executing of this command, quotas will be:
# luna-send -f -n 1 -a com.webos.service.configurator luna://com.webos.service.db/quotaStats '{}'
Response:
{
"returnValue":true,
"results":{
"com.test":{
"size":1000000,
"used":0
}
}
}
quotaStats
ACG: database.management
- Added:
API level 11
Description
The quotaStats method returns information about a service's used limits.
Parameters
None
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
| results | Required | Object: quotaStatsResult | Returns information about a service's quota. |
Example
Example code
# luna-send -n 1 -f -a com.palm.configurator luna://com.webos.service.db/quotaStats '{}'
Response:
{
"returnValue":true,
"results":{
"*":{
"size":10485760,
"used":1371
},
"com.webos.*":{
"size":10485760,
"used":0
},
"com.webos.testapp":{
"size":52428800,
"used":0
}
}
}
removeAppData
ACG: database.operation
- Added:
API level 11
Description
The removeAppData method removes all data associated with the given owner. In other words, the method removes all Kinds that have specified owner.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| owners | Required | String array | Owner(s) of kinds to delete. Kinds having given owners will be removed from the database. |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
| errorCode | Optional | String | The error code for the failed operation. |
| errorText | Optional | String | Indicates the reason for the failure of the operation. See the "Error Codes" section of this method for details. |
Error Codes Reference
Error Code | Error Text | Error Description |
|---|---|---|
| -3980 | db: invalid owner for kind | The value specified in owners input parameter is invalid or Kinds associated with the owners do not exist. |
Example
Example code
# luna-send -n 1 luna://com.webos.service.db/removeAppData '{"owners" : [ "com.webos.service.test:1" ]}'
Response:
{
"returnValue":true
}
reserveIds
ACG: database.operation
- Added:
API level 11
Description
When a client service creates objects that have references between each other, the service can ask the database through the reserveIds method to regenerate ids of objects. The client service can use such ids as objects, and DB8 will use those ids when objects are inserted into the database.
By default, DB8 configured to reserve maximum [0:1000] ids, but this limit can vary depending on the platform.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| count | Required | Number | Number of Ids to reserve. |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| ids | Required | String array | Array of reserved db8 IDs. |
| returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
| errorCode | Optional | Number | The error code for the failed operation. |
| errorText | Optional | String | Indicates the reason for the failure of the operation. See the "Error Codes" section of this method for details. |
Error Codes Reference
Error Code | Error Text | Error Description |
|---|---|---|
| -3968 | db: malformed id | This message implies that the specified count contains an invalid value. |
| -3967 | cannot reserve more than 1000 ids | Client tries to reserve too many object ids. By default, DB8 is configured to reserve maximum [0:1000] ids, but this limit can vary depending on the platform. |
Example
Example code
# luna-send -i -f luna://com.webos.service.db/reserveIds '{ "count" : 3 }'
Response:
{
"ids":[
"J9FJ12j0Usk",
"J9FJ12j18hJ",
"J9FJ12j1Mic"
],
"returnValue":true
}
search
ACG: database.operation
- Added:
API level 11
Description
Unlike the find method, the search method supports the "?" (question mark) 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 sub-string.
- Canceling the search mid-way (using the 'cancelable' parameter).
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
Name | Required | Type | Description |
|---|---|---|---|
| query | Required | Object: Query | Query for search. |
| watch | Optional | Boolean | Indicates if the app must be notified of any changes in the search results. This notification is sent only once (the first time when there is a change in the result). Possible values are:
Default value: false Note: The 'watch' and 'subscribe' parameters must not be used in the same call. |
| subscribe | Optional | Boolean | Subscribe to get notified when there are changes in search results. Possible values are:
Note:
|
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| results | Required | Object array | Returns an array of objects if the search() method succeeds. What is returned depends on the query and what is stored. |
| count | Required | Number | The number of objects returned in the results array. |
| returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
| errorCode | Optional | Number | The error code for the failed operation. |
| errorText | Optional | String | Indicates the reason for the failure of the operation. See the "Error Codes" section of this method for details. |
| taskId | Optional | String | Unique identifier of the search operation (only when 'cancelable' is set to true). |
Subscription Returns
Name | Required | Type | Description |
|---|---|---|---|
| results | Required | Object array | Returns an array of objects if the search() method succeeds. What is returned depends on the query and what is stored. |
| count | Required | Number | The number of objects returned in the results array. |
| returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
| errorCode | Optional | Number | The error code for the failed operation. |
| errorText | Optional | String | Indicates the reason for the failure of the operation. See the "Error Codes" section of this method for details. |
| taskId | Optional | String | Unique identifier of the search operation (only when 'cancelable' is set to true). |
Error Codes Reference
Error Code | Error Text | Error Description |
|---|---|---|
| -986 | db : 'cancelable' property must be used with 'subscribe' | 'subscribe' parameter is mandatory when 'cancelable' parameter is passed to search() method. |
| -992 | db : cannot use both 'watch' and 'cancelable' simultaneously | The 'watch' and 'cancelable' parameters must not be used in the same call. |
| -3987 | db: invalid filter op | This message implies that an invalid operation was specified in the filter. |
| -3978 | db: invalid query | This message implies that there was a syntax error in the query. |
| -3977 | db: collations on property do not match | This message implies that the collation sequence of a property across different objects do not match. |
| -3975 | db: invalid combination of query operations | This message implies that the query syntax is correct, but contains logical errors. |
Example
Example code
# luna-send -n 1 -f -a com.webos.service.test luna://com.webos.service.db/search '{
"query":{
"from":"com.webos.service.test:1",
"where":[
{
"prop":"sample",
"op":"?",
"val":"sample"
}
]
}
}'
Response:
{
"count":4,
"returnValue":true,
"results":[
{
"_rev":22,
"sample":"sample_updated_value",
"test":"test1",
"_id":"J8rKQDOvxdF",
"_kind":"com.webos.service.test:1"
},
{
"_rev":23,
"sample":"sample_updated_value",
"test":"test1",
"_id":"J8rKTaBClIo",
"_kind":"com.webos.service.test:1"
},
{
"_rev":26,
"sample":"sample1",
"test":"test1",
"_id":"J8rTH76hfcB",
"_kind":"com.webos.service.test:1"
},
{
"_rev":27,
"sample":"sample1",
"test":"test1",
"_id":"J8rTIa65u++",
"_kind":"com.webos.service.test:1"
}
]
}
setShardMode
ACG: database.operation
- Added:
API level 21
Description
Marks an external media as transient for the specified DB8 shard Id. This means that all data, relative to the shard, are not required by any application and will be removed by garbage collector. In other words, marking shard as transient will wipe all data from the shard on the nearest garbage collector call.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| shardId | Required | String | Base64 encoded id of shard |
| transient | Required | Boolean | Mark shard as transient. Service can mark shard as not transient. If garbage collector didn't run, all data relative to shard, will not be removed. |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
| errorCode | Optional | Number | The error code for the failed operation. |
| errorText | Optional | String | Indicates the reason for the failure of the operation. See the "Error Codes" section of this method for details. |
Error Codes Reference
Error Code | Error Text | Error Description |
|---|---|---|
| 1 | Invalid Parameters | This message implies that the client did not pass the correct shardId. |
| 100 | Invalid Shard ID | This message implies that the Shard ID was specified, but malformed |
Example
Example code
# luna-send -f -n 1 luna://com.webos.mediadb/setShardMode '{ "shardId" : "+MHrmF", "transient" : true }'
Response:
{
"returnValue":true
}
shardInfo
ACG: database.operation
- Added:
API level 21
Description
Retrieves the state of a shard, like shard activity, associated media devices, mount point.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| shardId | Required | String | Base64 encoded shard Id for which information is to be retrieved. |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
| isActive | Required | Boolean | Will return true, If media device attached
The method may fail because of one of the error conditions described in the Error Codes Reference of this method. See the Error Code Reference for more information. |
| isTransient | Required | Boolean | True, if the shard is marked as transient
The method may fail because of one of the error conditions described in the Error Codes Reference of this method. See the Error Code Reference for more information. |
| shardId | Required | String | Will return base64 of shardId |
| deviceId | Required | String | Return UUID of device, associated with shard. |
| deviceName | Required | String | Will return the symbolic name of a device. For example, name of flash card or external hdd |
| deviceUri | Required | String | The physical device path. For example: /tmp/usb/sda/sda1 |
| mountPath | Required | String | Mount path of device |
| errorCode | Optional | Number | The error code for the failed operation. |
| errorText | Optional | String | Indicates the reason for the failure of the operation. See the "Error Codes" section of this method for details. |
Error Codes Reference
Error Code | Error Text | Error Description |
|---|---|---|
| 1 | Invalid Parameters | This message implies that the client specified the shardId, but it is malformed. |
| 100 | Invalid Shard ID | This message implies that the registered shard is not found in db8. |
Example
Example code
# luna-send -f -n 1 luna://com.webos.mediadb/shardInfo '{ "shardId" : "+MHrmF"}'
Response:
{
"deviceUri":"/tmp/usb/sda/sda1",
"deviceName":"A:",
"deviceId":"323031333032535030303739303230313132323230_1",
"returnValue":true,
"shardId":"+MHrmF",
"mountPath":"/var/run/db8/mountpoints//174B7C9",
"isTransient":false,
"isActive":true
}
Response (if shard is disabled):
{
"errorCode": -3958,
"returnValue": false,
"errorText": "db: sharding disabled"
}
shardKind
ACG: database.operation
Retired
- Added:
API level 23 - Deprecated:
API level 23 - Retired:
API level 23
Description
Requests whether an external media supports a specific kind, by providing the DB8 short ID and the Kind.
shardKind method call is deprecated and will always return isSupported: TRUE.
For physical shards, sharding is available for any kind and so the shardKind call is no longer useful.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| shardId | Required | String | base64 encoded shard ID |
| kind | Required | String | Id of kind |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| isSupported | Required | Boolean | Return true, if shard id is registered for _kind
The method may fail because of one of the error conditions described in the Error Codes Reference of this method. See the Error Code Reference for more information. |
| shardId | Required | String | Base64 encoded shard ID (same, as passed in params) |
| kind | Required | String | associated shards _kind (same, as passed into params) |
| errorCode | Optional | Number | The error code for the failed operation. |
| errorText | Optional | String | Indicates the reason for the failure of the operation. See the "Error Codes" section of this method for details. |
| returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
Example
Example code
Note: shards disabled
# luna-send -f -n 1 luna://com.webos.mediadb/shardKind '{ "shardId" : "+MHrmF"}'
Response (if shards disabled):
{
"errorCode": -3958,
"returnValue": false,
"errorText": "db: sharding disabled"
}
stats
ACG: database.profiling
- Added:
API level 11
Description
The stats method returns detailed information about the storage space used by every service.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| kind | Optional | String | Identifier of kind |
| verify | Optional | Boolean | Verify kindkey if it is true |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
| results | Required | Object array: statsKindResult | Information about resource usage per kind. |
Example
Example code
# luna-send -n 1 -f luna://com.webos.service.db/stats '{}'
Response:
{
"returnValue":true,
"results":{
"com.webos.service.test:1":{
"indexes":{
"barfoo":{
"size":0,
"delmisses":0,
"count":0
},
"foo":{
"size":0,
"delmisses":0,
"count":0
},
"_id":{
"size":0,
"delmisses":0,
"count":0
}
},
"objects":{
"size":0,
"count":0
}
}
}
}
watch
ACG: database.operation
- Added:
API level 11
Description
The watch method watches for updates to the database that would change the results of a query.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| query | Required | Object: Query | Query whose results the app wants to watch. |
| subscribe | Optional | Boolean | subscription is enabled if it true |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| fired | Required | Boolean | If the watch method found any object by query, fired will contain true. Fired will never return false. |
| returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
| errorCode | Optional | Number | The error code for the failed operation. |
| errorText | Optional | String | Indicates the reason for the failure of the operation. See the "Error Codes" section of this method for details. |
Error Codes Reference
Error Code | Error Text | Error Description |
|---|---|---|
| -3999 | db: access denied | This message implies that the app does not have permissions to monitor the database. |
Example
Example code
# luna-send -i -f -a com.webos.service.configurator luna://com.webos.service.db/watch '{
"query":{
"from":"com.webos.service.test:1",
"where":[
{
"prop":"sample",
"op":"=",
"val":"sample1"
}
]
}
}'
Response: When object is found with such criteria
{
"returnValue":true,
"fired":true
}
Objects
BatchOperation
Method and params for batch operation.
Name | Required | Type | Description |
|---|---|---|---|
| method | Required | String | Database operation to perform. Allowed values are:
|
| params | Required | String | List of parameters for the database operation. |
BatchResponse
Response to batch operation.
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean |
The method may fail because of one of the error conditions described in the Error Codes Reference table of this method. See the Error Code Reference table for more information. |
| responses | Required | Array | Array of responses for each of the operations in the batch. |
| 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. |
FilterClause
Definition of the Filter clause that is part of the Query object.
Name | Required | Type | Description |
|---|---|---|---|
| prop | Required | String | Name of property to test. |
| op | Required | String | Test operator. Must be one of the following:
|
| 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. |
IndexClause
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.
Name | Required | Type | Description |
|---|---|---|---|
| name | Required | String | Index name |
| props | Required | Object array: IndexPropClause | Array of properties to index together. |
| incDel | Optional | Boolean | To display query results with deleted objects, set incDel to true. The default value of incDel is false. 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
Defines index property for IndexClause
Name | Required | Type | Description |
|---|---|---|---|
| name | Required | String | Name of property being indexed. |
| collate | Optional | String | Indicates the string comparison routine used to order the index. Must be one of the following:
|
| 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:
|
| type | Required | String | "single" or "multi". Single property or multiple properties. |
Query
Defines a db8 query.
Name | Required | Type | Description |
|---|---|---|---|
| select | Optional | String array | Array of property names to return. |
| from | Required | String | Name of kind to retrieve results from. |
| where | Optional | Object array: WhereClause | Array of clauses to test. |
| orderBy | Optional | String | Order results on this property. |
| desc | Optional | Boolean | To display query results in descending order, set desc to true. The default value of desc is false. |
| incDel | Optional | Boolean | To display query results with deleted objects, set incDel to true. The default value of incDel is false. 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 500 |
| page | Optional | String | Page key returned by previous query. |
| filter | Optional | Object array: FilterClause | Array of clauses - works only in the search method - identical to WhereClause. Can be used along with where to perform a range search. |
Results
Contains "id" and "rev" fields for the JSON data object.
Name | Required | Type | Description |
|---|---|---|---|
| id | Required | Any | ID of the object. |
| 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. |
RevSetClause
Defines a revision set - subset of an object's properties that your app can be notified about when one of the properties is modified.
Name | Required | Type | Description |
|---|---|---|---|
| name | Required | String | Name of the revision set (unique to this kind). |
| props | Required | Object array: RevSetPropClause | Array of properties to include in revision set. |
RevSetPropClause
A property in a RevSetClause.
Name | Required | Type | Description |
|---|---|---|---|
| name | Required | String | Name of property to include in revision set. |
WhereClause
Defines a SQL-like JSON where clause for a db8 Query.
Name | Required | Type | Description |
|---|---|---|---|
| prop | Required | String | Name of property to test. |
| op | Required | String | Test operator. Must be one of the following:
|
| 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. |
activity
Information about registered Activity in ActivityManager for calling DB8 internal/scheduledPurge API call.
Name | Required | Type | Description |
|---|---|---|---|
| activityId | Required | Number | ID of Activity, that registered in ActivityManager |
media
List of media devices, registered by db8.
Name | Required | Type | Description |
|---|---|---|---|
| deviceId | Required | String | UUID of device |
| deviceUri | Required | String | The physical device path. For example: /tmp/usb/sda/sda1 |
| mountPath | Required | String | Path to device mount point |
| shardId | Required | String | Base64 encoded Id of shard |
operation
Object used to represent a batch operation to run.
Note: This object has different format as target. Following object example is for the target.
Name | Required | Type | Description |
|---|---|---|---|
| method | Required | String | operation being requested. |
| params | Required | Any array | Params will depend on the type of operation being requested. |
putQuotas
Represent Kind owner and maximum allowed DB8 storage usage.
Name | Required | Type | Description |
|---|---|---|---|
| owner | Required | String | Name of service |
| size | Required | Number | Size in bytes of allowed quota |
quotaStatsResult
Information about used quotas.
Name | Required | Type | Description |
|---|---|---|---|
| size | Required | Number | Size of quotas in bytes |
| used | Required | Number | Used quotas by service in bytes |
statsKindResult
Information about kind usage.
Name | Required | Type | Description |
|---|---|---|---|
| indexes | Required | String | Statistic for each index, created for kind |
| _id | Required | String | Statistic for each id, created for kind |
| objects | Required | String | Statistic about objects, relative to kind |