提交 8ff9eedc 编写于 作者: A Annie_wang

update docs

Signed-off-by: NAnnie_wang <annie.wangli@huawei.com>
上级 7d18c4c3
......@@ -7,6 +7,8 @@ On the basis of the SQLite database, the relational database (RDB) allows you to
## Available APIs
For details about RDB APIs, see [Relational Database](../reference/apis/js-apis-data-rdb.md).
### Creating or Deleting an RDB Store
The following table describes the APIs available for creating and deleting an RDB store.
......@@ -15,10 +17,10 @@ The following table describes the APIs available for creating and deleting an RD
| API| Description|
| -------- | -------- |
|getRdbStore(config: StoreConfig, version: number, callback: AsyncCallback&lt;RdbStore&gt;): void | Obtains an RDB store. This method uses a callback to return the result. You can set parameters for the RDB store based on service requirements, and then call APIs to perform data operations.<br>- **config**: configuration of the RDB store.<br>- **version**: RDB version.<br>- **callback**: callback invoked to return the RDB store obtained.|
|getRdbStore(config: StoreConfig, version: number): Promise&lt;RdbStore&gt; | Obtains an RDB store. This method uses a promise to return the result. You can set parameters for the RDB store based on service requirements, and then call APIs to perform data operations.<br>- **config**: configuration of the RDB store.<br>- **version**: RDB version.|
|deleteRdbStore(name: string, callback: AsyncCallback&lt;void&gt;): void | Deletes an RDB store. This method uses a callback to return the result. <br>- **name**: RDB store to delete.<br>- **callback**: callback invoked to return the result.|
| deleteRdbStore(name: string): Promise&lt;void&gt; | Deletes an RDB store. This method uses a promise to return the result.<br>- **name**: RDB store to delete.|
|getRdbStore(context: Context, config: StoreConfig, version: number, callback: AsyncCallback&lt;RdbStore&gt;): void| Obtains an RDB store. This API uses a callback to return the result. You can set parameters for the RDB store based on service requirements, and then call APIs to perform data operations.<br>- **context**: context of the application or function.<br>- **config**: configuration of the RDB store.<br>- **version**: RDB version.<br>- **callback**: callback invoked to return the RDB store obtained.|
|getRdbStore(context: Context, config: StoreConfig, version: number): Promise&lt;RdbStore&gt; | Obtains an RDB store. This API uses a promise to return the result. You can set parameters for the RDB store based on service requirements, and then call APIs to perform data operations.<br>- **context**: context of the application or function.<br>- **config**: configuration of the RDB store.<br>- **version**: RDB version.|
|deleteRdbStore(context: Context, name: string, callback: AsyncCallback&lt;void&gt; ): void | Deletes an RDB store. This API uses a callback to return the result. <br>- **context**: context of the application or function.<br>- **name**: RDB store to delete.<br>- **callback**: callback invoked to return the result.|
| deleteRdbStore(context: Context, name: string): Promise&lt;void&gt; | Deletes an RDB store. This API uses a promise to return the result.<br>- **context**: context of the application or function.<br>- **name**: RDB store to delete.|
### Managing Data in an RDB Store
......@@ -32,8 +34,8 @@ The RDB provides APIs for inserting, deleting, updating, and querying data in th
| Class| API| Description|
| -------- | -------- | -------- |
| RdbStore | insert(name: string, values: ValuesBucket, callback: AsyncCallback&lt;number&gt;):void | Inserts a row of data into a table. This method uses a callback to return the result.<br>- **name**: name of the target table.<br>- **values**: data to be inserted into the table.<br>- **callback**: callback invoked to return the result. If the operation is successful, the row ID will be returned. Otherwise, **-1** will be returned.|
| RdbStore | insert(name: string, values: ValuesBucket): Promise&lt;number&gt; | Inserts a row of data into a table. This method uses a promise to return the result.<br>- **name**: name of the target table.<br>- **values**: data to be inserted into the table.|
| RdbStore | insert(table: string, values: ValuesBucket, callback: AsyncCallback&lt;number&gt;):void | Inserts a row of data into a table. This API uses a callback to return the result.<br>- **table**: name of the target table.<br>- **values**: data to be inserted into the table.<br>- **callback**: callback invoked to return the result. If the operation is successful, the row ID will be returned. Otherwise, **-1** will be returned.|
| RdbStore | insert(table: string, values: ValuesBucket): Promise&lt;number&gt; | Inserts a row of data into a table. This API uses a promise to return the result.<br>- **table**: name of the target table.<br>- **values**: data to be inserted into the table.|
- **Updating data**
......@@ -43,8 +45,8 @@ The RDB provides APIs for inserting, deleting, updating, and querying data in th
| Class| API| Description|
| -------- | -------- | -------- |
| RdbStore | update(values: ValuesBucket, rdbPredicates: RdbPredicates, callback: AsyncCallback&lt;number&gt;):void | Updates data in the RDB store based on the specified **RdbPredicates** object. This method uses a callback to return the result.<br>- **values**: data to update, which is stored in a **ValuesBucket**.<br>- **rdbPredicates**: conditions for updating data.<br>- **callback**: callback invoked to return the number of rows updated.|
| RdbStore | update(values: ValuesBucket, rdbPredicates: RdbPredicates): Promise\<number> | Updates data in the RDB store based on the specified **RdbPredicates** object. This method uses a promise to return the result.<br>- **values**: data to update, which is stored in a **ValuesBucket**.<br>- **rdbPredicates**: conditions for updating data.|
| RdbStore | update(values: ValuesBucket, predicates: RdbPredicates, callback: AsyncCallback&lt;number&gt;):void | Updates data in the RDB store based on the specified **RdbPredicates** object. This API uses a callback to return the result.<br>- **values**: data to update, which is stored in a **ValuesBucket**.<br>- **predicates**: conditions for updating data.<br>- **callback**: callback invoked to return the number of rows updated.|
| RdbStore | update(values: ValuesBucket, predicates: RdbPredicates): Promise&lt;number&gt; | Updates data in the RDB store based on the specified **RdbPredicates** object. This API uses a promise to return the result.<br>- **values**: data to update, which is stored in a **ValuesBucket**.<br>- **predicates**: conditions for updating data.|
- **Deleting data**
......@@ -54,8 +56,8 @@ The RDB provides APIs for inserting, deleting, updating, and querying data in th
| Class| API| Description|
| -------- | -------- | -------- |
| RdbStore | delete(rdbPredicates: RdbPredicates, callback: AsyncCallback&lt;number&gt;):void | Deletes data from the RDB store based on the specified **RdbPredicates** object. This method uses a callback to return the result.<br>- **rdbPredicates**: conditions for deleting data.<br>- **callback**: callback invoked to return the number of rows deleted.|
| RdbStore | delete(rdbPredicates: RdbPredicates): Promise\<number> | Deletes data from the RDB store based on the specified **RdbPredicates** object. This method uses a promise to return the result.<br>- **rdbPredicates**: conditions for deleting data.|
| RdbStore | delete(predicates: RdbPredicates, callback: AsyncCallback&lt;number&gt;):void | Deletes data from the database based on the specified **RdbPredicates** object. This API uses an asynchronous callback to return the result.<br>- **predicates**: conditions for deleting data.<br>- **callback**: callback invoked to return the number of rows updated.|
| RdbStore | delete(predicates: RdbPredicates): Promise&lt;number&gt; | Deletes data from the database based on the specified **RdbPredicates** object. This API uses a promise to return the result.<br>- **predicates**: conditions for deleting data.|
- **Querying data**
......@@ -68,10 +70,10 @@ The RDB provides APIs for inserting, deleting, updating, and querying data in th
| Class| API| Description|
| -------- | -------- | -------- |
| RdbStore | query(rdbPredicates: RdbPredicates, columns: Array, callback: AsyncCallback&lt;ResultSet&gt;): void | Queries data in the RDB store based on the specified **RdbPredicates** object. This method uses a callback to return the result.<br>- **rdbPredicates**: conditions for querying data.<br>- **columns**: columns to query. If this parameter is not specified, the query applies to all columns.<br>- **callback**: callback invoked to return the result. If the operation is successful, a **ResultSet** object will be returned.|
| RdbStore | query(rdbPredicates: RdbPredicates, columns: Array): Promise&lt;ResultSet&gt; | Queries data in the RDB store based on the specified **RdbPredicates** object. This method uses a promise to return the result.<br>- **rdbPredicates**: conditions for querying data.<br>- **columns**: columns to query. If this parameter is not specified, the query applies to all columns.|
| RdbStore | querySql(sql: string, bindArgs: Array&lt;ValueType&gt;, callback: AsyncCallback&lt;ResultSet&gt;):void | Queries data in the RDB store using the specified SQL statement. This method uses a callback to return the result.<br>- **sql**: SQL statement.<br>- **bindArgs**: arguments in the SQL statement.<br>- **callback**: callback invoked to return the result. If the operation is successful, a **ResultSet** object will be returned.|
| RdbStore | querySql(sql: string, bindArgs?: Array&lt;ValueType&gt;):Promise&lt;ResultSet&gt; | Queries data in the RDB store using the specified SQL statement. This method uses a promise to return the result.<br>- **sql**: SQL statement.<br>- **bindArgs**: arguments in the SQL statement.|
| RdbStore | query(predicates: RdbPredicates, columns: Array, callback: AsyncCallback&lt;ResultSet&gt;): void | Queries data in the RDB store based on the specified **RdbPredicates** object. This API uses a callback to return the result.<br>- **predicates**: conditions for querying data.<br>- **columns**: columns to query. If this parameter is not specified, the query applies to all columns.<br>- **callback**: callback invoked to return the result. If the operation is successful, a **ResultSet** object will be returned.|
| RdbStore | query(predicates: RdbPredicates, columns: Array): Promise&lt;ResultSet&gt; | Queries data in the RDB store based on the specified **RdbPredicates** object. This API uses a promise to return the result.<br>- **predicates**: conditions for querying data.<br>- **columns**: columns to query. If this parameter is not specified, the query applies to all columns.|
| RdbStore | querySql(sql: string, bindArgs: Array&lt;ValueType&gt;, callback: AsyncCallback&lt;ResultSet&gt;):void | Queries data in the RDB store using the specified SQL statement. This API uses a callback to return the result.<br>- **sql**: SQL statement.<br>- **bindArgs**: arguments in the SQL statement.<br>- **callback**: callback invoked to return the result. If the operation is successful, a **ResultSet** object will be returned.|
| RdbStore | querySql(sql: string, bindArgs?: Array&lt;ValueType&gt;):Promise&lt;ResultSet&gt; | Queries data in the RDB store using the specified SQL statement. This API uses a promise to return the result.<br>- **sql**: SQL statement.<br>- **bindArgs**: arguments in the SQL statement.|
### Using Predicates
......@@ -141,7 +143,7 @@ A result set can be regarded as a row of data in the queried results. It allows
### Setting Distributed Tables
>**CAUTION**<br>ohos.permission.DISTRIBUTED_DATASYNC is requied for using the **setDistributedTables**, **obtainDistributedTableName**, **sync**, **on**, and **off** APIs of **RdbStore**.
>**CAUTION**<br>ohos.permission.DISTRIBUTED_DATASYNC is required for using the **setDistributedTables**, **obtainDistributedTableName**, **sync**, **on**, and **off** APIs of **RdbStore**.
**Setting Distributed Tables**
......@@ -149,8 +151,8 @@ A result set can be regarded as a row of data in the queried results. It allows
| Class| API| Description|
| -------- | -------- | -------- |
| RdbStore | setDistributedTables(tables: Array\<string>, callback: AsyncCallback\<void>): void | Sets a list of distributed tables. This method uses a callback to return the result.<br>- **tables**: names of the distributed tables to set.<br>- **callback**: callback invoked to return the result.|
| RdbStore | setDistributedTables(tables: Array\<string>): Promise\<void> | Sets a list of distributed tables. This method uses a promise to return the result.<br>- **tables**: names of the distributed tables to set.|
| RdbStore | setDistributedTables(tables: Array\<string>, callback: AsyncCallback\<void>): void | Sets a list of distributed tables. This API uses a callback to return the result.<br>- **tables**: names of the distributed tables to set.<br>- **callback**: callback invoked to return the result.|
| RdbStore | setDistributedTables(tables: Array\<string>): Promise\<void> | Sets a list of distributed tables. This API uses a promise to return the result.<br>- **tables**: names of the distributed tables to set.|
**Obtaining the Distributed Table Name for a Remote Device**
......@@ -160,17 +162,17 @@ You can obtain the distributed table name for a remote device based on the local
| Class| API| Description|
| -------- | -------- | -------- |
| RdbStore | obtainDistributedTableName(device: string, table: string, callback: AsyncCallback\<string>): void | Obtains the distributed table name for a remote device based on the local table name. The distributed table name is used to query the RDB store of the remote device. This method uses a callback to return the result.<br>- **device**: remote device.<br>- **table**: local table name.<br>- **callback**: callback used to return the result. If the operation is successful, the distributed table name of the remote device will be returned. |
| RdbStore | obtainDistributedTableName(device: string, table: string): Promise\<string> | Obtains the distributed table name for a remote device based on the local table name. The distributed table name is used to query the RDB store of the remote device. This method uses a promise to return the result.<br>- **device**: remote device.<br>- **table**: local table name.|
| RdbStore | obtainDistributedTableName(device: string, table: string, callback: AsyncCallback\<string>): void | Obtains the distributed table name for a remote device based on the local table name. The distributed table name is required when the database of a remote device is queried. This API uses an asynchronous callback to return the result.<br>- **device**: remote device.<br>- **table**: local table name.<br>- **callback**: callback used to return the result. If the operation is successful, the distributed table name of the remote device will be returned. |
| RdbStore | obtainDistributedTableName(device: string, table: string): Promise\<string> | Obtains the distributed table name for a remote device based on the local table name. The distributed table name is used to query the RDB store of the remote device. This API uses a promise to return the result.<br>- **device**: remote device.<br>- **table**: local table name.|
**Synchronizing Data Between Devices**
**Table 10** APIs for synchronizing data between devices
**Table 10** APIs for cross-device data synchronization
| Class| API| Description|
| -------- | -------- | -------- |
| RdbStore | sync(mode: SyncMode, predicates: RdbPredicates, callback: AsyncCallback\<Array\<[string, number]>>): void | Synchronizes data between devices. This method uses a callback to return the result.<br>- **mode**: data synchronization mode. **SYNC\_MODE\_PUSH** means to push data from the local device to a remote device. **SYNC\_MODE\_PULL** means to pull data from a remote device to the local device.<br>- **predicates**: data and devices to be synchronized.<br>- **callback**: callback invoked to return the result. In the result, **string** indicates the device ID, and **number** indicates the synchronization status of each device. The value **0** indicates a success, and other values indicate a failure.|
| RdbStore | sync(mode: SyncMode, predicates: RdbPredicates): Promise\<Array\<[string, number]>> | Synchronizes data between devices. This method uses a promise to return the result.<br>- **mode**: data synchronization mode. **SYNC\_MODE\_PUSH** means to push data from the local device to a remote device. **SYNC\_MODE\_PULL** means to pull data from a remote device to the local device.<br>- **predicates**: data and devices to be synchronized. |
| RdbStore | sync(mode: SyncMode, predicates: RdbPredicates, callback: AsyncCallback\<Array\<[string, number]>>): void | Synchronizes data between devices. This API uses a callback to return the result.<br>- **mode**: data synchronization mode. **SYNC_MODE_PUSH** means to push data from the local device to a remote device. **SYNC_MODE_PULL** means to pull data from a remote device to the local device.<br>- **predicates**: data and devices to be synchronized.<br>- **callback**: callback invoked to return the result. In the result, **string** indicates the device ID, and **number** indicates the synchronization status of each device. The value **0** indicates a success, and other values indicate a failure.|
| RdbStore | sync(mode: SyncMode, predicates: RdbPredicates): Promise\<Array\<[string, number]>> | Synchronizes data between devices. This API uses a promise to return the result.<br>- **mode**: data synchronization mode. **SYNC_MODE_PUSH** means to push data from the local device to a remote device. **SYNC_MODE_PULL** means to pull data from a remote device to the local device.<br>- **predicates**: data and devices to be synchronized. |
**Registering an RDB Store Observer**
......@@ -178,7 +180,7 @@ You can obtain the distributed table name for a remote device based on the local
| Class| API| Description|
| -------- | -------- | -------- |
| RdbStore |on(event: 'dataChange', type: SubscribeType, observer: Callback\<Array\<string>>): void| Registers an observer for this RDB store to subscribe to distributed data changes. When data in the RDB store changes, a callback will be invoked to return the data changes.<br>- **type**: subscription type. **SUBSCRIBE\_TYPE\_REMOTE** means to subscribe to remote data changes.<br>- **observer**: observer that listens for data changes in the RDB store.|
| RdbStore |on(event: 'dataChange', type: SubscribeType, observer: Callback\<Array\<string>>): void| Registers an observer for this RDB store to subscribe to distributed data changes. When data in the RDB store changes, a callback will be invoked to return the data changes.<br>- **type**: subscription type. **SUBSCRIBE_TYPE_REMOTE** means to subscribe to remote data changes.<br>- **observer**: observer that listens for data changes in the RDB store.|
**Unregistering an RDB Store Observer**
......@@ -186,15 +188,37 @@ You can obtain the distributed table name for a remote device based on the local
| Class| API| Description|
| -------- | -------- | -------- |
| RdbStore |off(event:'dataChange', type: SubscribeType, observer: Callback\<Array\<string>>): void;| Unregisters the observer of the specified type for the RDB store. This API uses a callback to return the result.<br>- **type**: subscription type. **SUBSCRIBE\_TYPE\_REMOTE** means to subscribe to remote data changes.<br>- **observer**: observer to unregister.|
| RdbStore |off(event:'dataChange', type: SubscribeType, observer: Callback\<Array\<string>>): void;| Unregisters the observer of the specified type for the RDB store. This API uses a callback to return the result.<br>- **type**: subscription type. **SUBSCRIBE_TYPE_REMOTE** means to subscribe to remote data changes.<br>- **observer**: observer to unregister.|
### Backing Up and Restore an RDB Store
**Backing Up an RDB Store**
**Table 13** APIs for backing up an RDB store
| Class| API| Description|
| -------- | -------- | -------- |
| RdbStore |backup(destName:string, callback: AsyncCallback&lt;void&gt;):void| Backs up the RDB store with the specified name. This API uses an asynchronous callback to return the result.<br>- **destName**: name of the RDB backup file.<br>- **callback**: callback invoked to return the result.|
| RdbStore |backup(destName:string): Promise&lt;void&gt;| Backs up the RDB store with the specified name. This API uses a promise to return the result.<br>- **destName**: name of the RDB backup file.|
**Restoring an RDB Store**
**Table 14** APIs for restoring an RDB store
| Class| API| Description|
| -------- | -------- | -------- |
| RdbStore |restore(srcName:string, callback: AsyncCallback&lt;void&gt;):void| Restores an RDB store using the specified backup file. This API uses an asynchronous callback to return the result.<br>- **srcName**: name of the RDB backup file.<br>- **callback**: callback invoked to return the result.|
| RdbStore |restore(srcName:string): Promise&lt;void&gt;| Restores an RDB store using the specified backup file. This API uses a promise to return the result.<br>- **srcName**: name of the RDB backup file.|
## How to Develop
1. Create an RDB store.
1. Configure the RDB store attributes, including the RDB store name, storage mode, and whether read-only mode is used.
2. Initialize the table structure and related data in the RDB store.
3. Create the RDB store.
(1) Configure the RDB store attributes, including the RDB store name, storage mode, and whether read-only mode is used.
(2) Initialize the table structure and related data in the RDB store.
(3) Create an RDB store.
The sample code is as follows:
......@@ -203,15 +227,17 @@ You can obtain the distributed table name for a remote device based on the local
const CREATE_TABLE_TEST = "CREATE TABLE IF NOT EXISTS test (" + "id INTEGER PRIMARY KEY AUTOINCREMENT, " + "name TEXT NOT NULL, " + "age INTEGER, " + "salary REAL, " + "blobType BLOB)";
const STORE_CONFIG = {name: "rdbstore.db",}
data_rdb.getRdbStore(STORE_CONFIG, 1, function (err, rdbStore) {
data_rdb.getRdbStore(this.context, STORE_CONFIG, 1, function (err, rdbStore) {
rdbStore.executeSql(CREATE_TABLE_TEST)
console.info('create table done.')
})
```
2. Insert data.
1. Create a **ValuesBucket** to store the data you need to insert.
2. Call the **insert()** method to insert data into the RDB store.
(1) Create a **ValuesBucket** to store the data you need to insert.
(2) Call the **insert()** method to insert data into the RDB store.
The sample code is as follows:
......@@ -222,9 +248,12 @@ You can obtain the distributed table name for a remote device based on the local
```
3. Query data.
1. Create an **RdbPredicates** object to specify query conditions.
2. Call the **query()** method to query data.
3. Call the **ResultSet()** method to obtain the query result.
(1) Create an **RdbPredicates** object to specify query conditions.
(2) Call the query() API to query data.
(3) Call the resultSet() API to obtain the result.
The sample code is as follows:
......@@ -245,16 +274,20 @@ You can obtain the distributed table name for a remote device based on the local
4. Set the distributed tables to be synchronized.
1. Add the following permission to the permission configuration file:
(1) Add the following permission to the permission configuration file:
```js
"requestPermissions":
{
"name": "ohos.permission.DISTRIBUTED_DATASYNC"
}
```
2. Obtain the required permission.
3. Set the distributed tables.
4. Check whether the setting is successful.
(2) Obtain the application permissions.
(3) Set the distributed tables.
(4) Check whether the setting is successful.
The sample code is as follows:
......@@ -272,16 +305,19 @@ You can obtain the distributed table name for a remote device based on the local
```
5. Synchronize data across devices.
1. Constructs an **RdbPredicates** object to specify remote devices within the network to be synchronized.
2. Call the **sync()** method to synchronize data.
3. Check whether data synchronization is successful.
(1) Construct an **RdbPredicates** object to specify remote devices within the network to be synchronized.
(2) Call **rdbStore.sync()** to synchronize data.
(3) Check whether the data synchronization is successful.
The sample code is as follows:
```js
let predicate = new data_rdb.RdbPredicates('test')
predicate.inDevices(['12345678abcde'])
let promise = rdbStore.sync(rdb.SyncMode.SYNC_MODE_PUSH, predicate)
let promise = rdbStore.sync(data_rdb.SyncMode.SYNC_MODE_PUSH, predicate)
promise.then((result) => {
console.log('sync done.')
for (let i = 0; i < result.length; i++) {
......@@ -293,8 +329,10 @@ You can obtain the distributed table name for a remote device based on the local
```
6. Subscribe to distributed data.
1. Register an observer to listen for distributed data changes.
2. When data in the RDB store changes, a callback will be invoked to return the data changes.
(1) Register an observer to listen for distributed data changes.
(2) When data in the RDB store changes, a callback will be invoked to return the data changes.
The sample code is as follows:
......@@ -305,15 +343,17 @@ You can obtain the distributed table name for a remote device based on the local
}
}
try {
rdbStore.on('dataChange', rdb.SubscribeType.SUBSCRIBE_TYPE_REMOTE, storeObserver)
rdbStore.on('dataChange', data_rdb.SubscribeType.SUBSCRIBE_TYPE_REMOTE, storeObserver)
} catch (err) {
console.log('register observer failed')
}
```
7. Query data across devices.
1. Obtain the distributed table name for a remote device based on the local table name.
2. Call the **ResultSet()** method to obtain the query result.
(1) Obtain the distributed table name for a remote device based on the local table name.
(2) Call the resultSet() API to obtain the result.
The sample code is as follows:
......@@ -321,6 +361,32 @@ You can obtain the distributed table name for a remote device based on the local
let tableName = rdbStore.obtainDistributedTableName(deviceId, "test");
let resultSet = rdbStore.querySql("SELECT * FROM " + tableName)
```
8. Back up and restore an RDB store.
(1) Back up the current RDB store.
(2) Restore the RDB store using the backup file.
The sample code is as follows:
```js
let promiseBackup = rdbStore.backup("dbBackup.db")
promiseBackup.then(()=>{
console.info('Backup success.')
}).catch((err)=>{
console.info('Backup failed, err: ' + err)
})
```
```js
let promiseRestore = rdbStore.restore("dbBackup.db")
promiseRestore.then(()=>{
console.info('Restore success.')
}).catch((err)=>{
console.info('Restore failed, err: ' + err)
})
```
## Samples
The following samples are provided for you to better understand the RDB development:
- [`Rdb`: eTS RDB (API8)](https://gitee.com/openharmony/app_samples/tree/master/data/Rdb)
......
Markdown is supported
0% .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑!
想要评论请 注册