diff --git a/en/application-dev/database/database-mdds-guidelines.md b/en/application-dev/database/database-mdds-guidelines.md index dd1594215a10d1c93c9825444253484ed8956e05..e6995db8bf2eed90111952d8104bb458b2dafe51 100644 --- a/en/application-dev/database/database-mdds-guidelines.md +++ b/en/application-dev/database/database-mdds-guidelines.md @@ -6,6 +6,7 @@ The Distributed Data Service (DDS) implements synchronization of application dat ## Available APIs + For details about the APIs related to distributed data, see [Distributed Data Management](../reference/apis/js-apis-distributed-data.md). @@ -13,13 +14,13 @@ For details about the APIs related to distributed data, see [Distributed Data Ma | API | Description | | ------------------------------------------------------------ | ----------------------------------------------- | -| createKVManager(config:KVManagerConfig,callback:AsyncCallback<KVManager>):void
createKVManager(config:KVManagerConfig):Promise<KVManager> | Creates a **KVManager** object for database management.| -| getKVStore<TextendsKVStore>(storeId:string,options:Options,callback:AsyncCallback<T>):void
getKVStore<TextendsKVStore>(storeId:string,options:Options):Promise<T> | Obtains a KV store with the specified **Options** and **storeId**.| -| put(key:string,value:Uint8Array\|string\|number\|boolean,callback:AsyncCallback<void>):void
put(key:string,value:Uint8Array\|string\|number\|boolean):Promise<void> | Inserts and updates data. | -| delete(key:string,callback:AsyncCallback<void>):void
delete(key:string):Promise<void> | Deletes data. | -| get(key:string,callback:AsyncCallback<Uint8Array\|string\|boolean\|number>):void
get(key:string):Promise<Uint8Array\|string\|boolean\|number> | Queries data. | -| on(event:'dataChange',type:SubscribeType,observer:Callback<ChangeNotification>):void
on(event:'syncComplete',syncCallback:Callback<Array<[string,number]>>):void | Subscribes to data changes in the KV store. | -| sync(deviceIdList:string[],mode:SyncMode,allowedDelayMs?:number):void | Triggers database synchronization in manual mode. | +| createKVManager(config: KVManagerConfig, callback: AsyncCallback<KVManager>): void
createKVManager(config: KVManagerConfig): Promise<KVManager> | Creates a **KVManager** object for database management.| +| getKVStore<TextendsKVStore>(storeId: string, options: Options, callback: AsyncCallback<T>): void
getKVStore<TextendsKVStore>(storeId: string, options: Options): Promise<T> | Obtains a KV store with the specified **Options** and **storeId**.| +| put(key: string, value: Uint8Array\|string\|number\|boolean, callback: AsyncCallback<void>): void
put(key: string, value: Uint8Array\|string\|number\|boolean): Promise<void> | Inserts and updates data. | +| delete(key: string, callback: AsyncCallback<void>): void
delete(key: string): Promise<void> | Deletes data. | +| get(key: string, callback: AsyncCallback<Uint8Array\|string\|boolean\|number>): void
get(key: string): Promise<Uint8Array\|string\|boolean\|number> | Queries data. | +| on(event: 'dataChange', type: SubscribeType, observer: Callback<ChangeNotification>): void
on(event: 'syncComplete', syncCallback: Callback<Array<[string,number]>>): void | Subscribes to data changes in the KV store. | +| sync(deviceIdList: string[], mode: SyncMode, allowedDelayMs?: number): void | Triggers database synchronization in manual mode. | @@ -29,19 +30,50 @@ For details about the APIs related to distributed data, see [Distributed Data Ma The following uses a single KV store as an example to describe the development procedure. 1. Import the distributed data module. + ```js import distributedData from '@ohos.data.distributedData'; ``` +2. Apply for the required permission if data synchronization is required. -2. Create a **KvManager** instance based on the specified **KvManagerConfig** object. - - (1) Create a **KvManagerConfig** object based on the application context. + You need to configure the request permission in the **config.json** file. The sample code is as follows: + + ```json + { + "module": { + "reqPermissions": [ + { + "name": "ohos.permission.DISTRIBUTED_DATASYNC" + } + ] + } + } + ``` + This permission must also be granted by the user when the application is started for the first time. The sample code is as follows: + + ```js + import featureAbility from '@ohos.ability.featureAbility'; + + function grantPermission() { + console.info('grantPermission'); + let context = featureAbility.getContext(); + context.requestPermissionsFromUser(['ohos.permission.DISTRIBUTED_DATASYNC'], 666, function (result) { + console.info(`result.requestCode=${result.requestCode}`) + + }) + console.info('end grantPermission'); + } + + grantPermission(); + ``` + +3. Create a **KvManager** instance based on the specified **KvManagerConfig** object. + + 1. Create a **kvManagerConfig** object based on the application context. + 2. Create a **kvManager** instance. - (2) Create a **KvManager** instance. - The sample code is as follows: - - ``` + ```js let kvManager; try { const kvManagerConfig = { @@ -63,13 +95,11 @@ The following uses a single KV store as an example to describe the development p console.log("An unexpected error occurred. Error:" + e); } ``` - - -3. Create and obtain a single KV store. - (1) Declare the ID of the single KV store to create. +4. Create and obtain a single KV store. - (2) Create a single KV store. You are advised to disable automatic synchronization (**autoSync:false**) and call **sync** when a synchronization is required. + 1. Declare the ID of the single KV store to create. + 2. Create a single KV store. You are advised to disable automatic synchronization (`autoSync:false`) and call `sync` when a synchronization is required. The sample code is as follows: ```js @@ -99,8 +129,9 @@ The following uses a single KV store as an example to describe the development p > **NOTE** > > For data synchronization between networked devices, you are advised to open the distributed KV store during application startup to obtain the database handle. With this database handle (`kvStore` in this example), you can perform operations, such as inserting data into the KV store, without creating the KV store repeatedly during the lifecycle of the handle. + +5. Subscribe to changes in the distributed data. -4. Subscribe to changes in the distributed data.
The following is the sample code for subscribing to the data changes of a single KV store: ```js kvStore.on('dataChange', distributedData.SubscribeType.SUBSCRIBE_TYPE_ALL, function (data) { @@ -108,11 +139,10 @@ The following uses a single KV store as an example to describe the development p }); ``` -5. Write data to the single KV store. +6. Write data to the single KV store. - (1) Construct the key and value to be written into the single KV store. - - (2) Write key-value pairs into the single KV store. + 1. Construct the `Key` and `Value` to be written into the single KV store. + 2. Write key-value pairs into the single KV store. The following is the sample code for writing key-value pairs of the string type into the single KV store: @@ -132,11 +162,10 @@ The following uses a single KV store as an example to describe the development p } ``` -6. Query data in the single KV store. - - (1) Construct the key to be queried from the single KV store. +7. Query data in the single KV store. - (2) Query data from the single KV store. + 1. Construct the `Key` to be queried from the single KV store. + 2. Query data from the single KV store. The following is the sample code for querying data of the string type from the single KV store: ```js @@ -158,7 +187,8 @@ The following uses a single KV store as an example to describe the development p } ``` -7. Synchronize data to other devices.
+8. Synchronize data to other devices. + Select the devices in the same network and the synchronization mode to synchronize data. > **NOTE** diff --git a/en/application-dev/database/database-relational-guidelines.md b/en/application-dev/database/database-relational-guidelines.md index 688835122445f6800d83a76fa0633b0be64f385c..7d4ded2757229593c6220a51f92d5b972c3b5a13 100644 --- a/en/application-dev/database/database-relational-guidelines.md +++ b/en/application-dev/database/database-relational-guidelines.md @@ -16,8 +16,8 @@ The table below describes the APIs available for creating and deleting an RDB st | API| Description| | -------- | -------- | -|getRdbStore(config:StoreConfig,version:number):Promise<RdbStore> | 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 call APIs to perform data operations.
- **config**: configuration of the RDB store.
- **version**: version of the RDB store.| -| deleteRdbStore(name:string):Promise<void> | Deletes an RDB store. This API uses a promise to return the result.
- **name**: name of the RDB store to delete.| +|getRdbStore(config: StoreConfig, version: number): Promise<RdbStore> | 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 call APIs to perform data operations.
- **config**: configuration of the RDB store.
- **version**: version of the RDB store.| +| deleteRdbStore(name: string): Promise<void> | Deletes an RDB store. This API uses a promise to return the result.
- **name**: name of the RDB store to delete.| ### Managing Data in an RDB Store @@ -31,7 +31,7 @@ The **RDB** module provides APIs for inserting, deleting, updating, and querying | Class| API| Description| | -------- | -------- | -------- | - | RdbStore | insert(name:string,values:ValuesBucket):Promise<number> | Inserts a row of data into a table. This API uses a promise to return the result.
If the operation is successful, the row ID will be returned; otherwise, **-1** will be returned.
- **name**: name of the target table.
- **values**: data to be inserted into the table.| + | RdbStore | insert(name: string, values: ValuesBucket): Promise<number> | Inserts a row of data into a table. This API uses a promise to return the result.
If the operation is successful, the row ID will be returned; otherwise, **-1** will be returned.
- **name**: name of the target table.
- **values**: data to be inserted into the table.| - **Updating Data** @@ -41,7 +41,7 @@ The **RDB** module provides APIs for inserting, deleting, updating, and querying | Class| API| Description| | -------- | -------- | -------- | - | RdbStore | update(values:ValuesBucket,rdbPredicates:RdbPredicates):Promise\ | Updates data based on the specified **RdbPredicates** object. This API uses a promise to return the result.
Return value: number of rows updated.
- **values**: data to update, which is stored in **ValuesBucket**.
- **rdbPredicates**: conditions for updating data.| + | RdbStore | update(values: ValuesBucket, rdbPredicates: RdbPredicates): Promise\ | Updates data based on the specified **RdbPredicates** object. This API uses a promise to return the result.
Return value: number of rows updated.
- **values**: data to update, which is stored in **ValuesBucket**.
- **rdbPredicates**: conditions for updating data.| - **Deleting Data** @@ -51,7 +51,7 @@ The **RDB** module provides APIs for inserting, deleting, updating, and querying | Class| API| Description| | -------- | -------- | -------- | - | RdbStore | delete(rdbPredicates:RdbPredicates):Promise\ | Deletes data from the RDB store based on the specified **RdbPredicates** object. This API uses a promise to return the result.
Return value: number of rows updated.
- **rdbPredicates**: conditions for deleting data.| + | RdbStore | delete(rdbPredicates: RdbPredicates): Promise\ | Deletes data from the RDB store based on the specified **RdbPredicates** object. This API uses a promise to return the result.
Return value: number of rows updated.
- **rdbPredicates**: conditions for deleting data.| - **Querying data** @@ -64,8 +64,8 @@ The **RDB** module provides APIs for inserting, deleting, updating, and querying | Class| API| Description| | -------- | -------- | -------- | - | RdbStore | query(rdbPredicates:RdbPredicates,columns:Array):Promise<ResultSet> | Queries data from the RDB store based on specified conditions. This API uses a promise to return the result.
- **rdbPredicates**: conditions for querying data.
- **columns**: columns to query. If this parameter is not specified, the query applies to all columns.| - | RdbStore | querySql(sql:string,bindArgs?:Array<ValueType>):Promise<ResultSet> | Queries data using the specified SQL statement. This API uses a promise to return the result.
- **sql**: SQL statement.
- **bindArgs**: arguments in the SQL statement.| + | RdbStore | query(rdbPredicates: RdbPredicates, columns: Array): Promise<ResultSet> | Queries data from the RDB store based on specified conditions. This API uses a promise to return the result.
- **rdbPredicates**: conditions for querying data.
- **columns**: columns to query. If this parameter is not specified, the query applies to all columns.| + | RdbStore | querySql(sql: string, bindArgs?: Array<ValueType>): Promise<ResultSet> | Queries data using the specified SQL statement. This API uses a promise to return the result.
- **sql**: SQL statement.
- **bindArgs**: arguments in the SQL statement.| ### Using Predicates @@ -77,11 +77,11 @@ The table below lists common predicates. For more information about predicates, | Class| API| Description| | -------- | -------- | -------- | -| RdbPredicates | equalTo(field:string,value:ValueType):RdbPredicates | Sets an **RdbPredicates** object to match the field with data type **ValueType** and value equal to the specified value.
- **field**: column name in the database table.
- **value**: value to match the **RdbPredicates**.
- **RdbPredicates**: **RdbPredicates** object created.| -| RdbPredicates | notEqualTo(field:string,value:ValueType):RdbPredicates | Sets an **RdbPredicates** object to match the field with data type **ValueType** and value not equal to the specified value.
- **field**: column name in the database table.
- **value**: value to match the **RdbPredicates**.
- **RdbPredicates**: **RdbPredicates** object created.| -| RdbPredicates | or():RdbPredicates | Adds the OR condition to the **RdbPredicates** object.
- **RdbPredicates**: **RdbPredicates** with the OR condition.| -| RdbPredicates | and():RdbPredicates | Adds the AND condition to the **RdbPredicates** object.
- **RdbPredicates**: **RdbPredicates** with the AND condition.| -| RdbPredicates | contains(field:string,value:string):RdbPredicats | Sets an **RdbPredicates** object to match a string that contains the specified value.
- **field**: column name in the database table.
- **value**: value to match the **RdbPredicates**.
- **RdbPredicates**: **RdbPredicates** object created.| +| RdbPredicates | equalTo(field: string, value: ValueType): RdbPredicates | Sets an **RdbPredicates** object to match the field with data type **ValueType** and value equal to the specified value.
- **field**: column name in the database table.
- **value**: value to match the **RdbPredicates**.
- **RdbPredicates**: **RdbPredicates** object created.| +| RdbPredicates | notEqualTo(field: string, value: ValueType): RdbPredicates | Sets an **RdbPredicates** object to match the field with data type **ValueType** and value not equal to the specified value.
- **field**: column name in the database table.
- **value**: value to match the **RdbPredicates**.
- **RdbPredicates**: **RdbPredicates** object created.| +| RdbPredicates | or(): RdbPredicates | Adds the OR condition to the **RdbPredicates** object.
- **RdbPredicates**: **RdbPredicates** with the OR condition.| +| RdbPredicates | and(): RdbPredicates | Adds the AND condition to the **RdbPredicates** object.
- **RdbPredicates**: **RdbPredicates** with the AND condition.| +| RdbPredicates | contains(field: string, value: string): RdbPredicats | Sets an **RdbPredicates** object to match a string that contains the specified value.
- **field**: column name in the database table.
- **value**: value to match the **RdbPredicates**.
- **RdbPredicates**: **RdbPredicates** object created.| ### Using the Result Set @@ -97,12 +97,12 @@ For details about how to use result set APIs, see [Result Set](../reference/apis | Class| API| Description| | -------- | -------- | -------- | -| ResultSet | goToFirstRow():boolean | Moves to the first row of the result set.| -| ResultSet | getString(columnIndex:number):string | Obtains the value in the form of a string based on the specified column and current row.| -| ResultSet | getBlob(columnIndex:number):Uint8Array | Obtains the value in the form of a byte array based on the specified column and the current row.| -| ResultSet | getDouble(columnIndex:number):number | Obtains the value in the form of double based on the specified column and current row.| -| ResultSet | getLong(columnIndex:number):number | Obtains the value in the form of a long integer based on the specified column and current row. | -| ResultSet | close():void | Closes the result set.| +| ResultSet | goToFirstRow(): boolean | Moves to the first row of the result set.| +| ResultSet | getString(columnIndex:number): string | Obtains the value in the form of a string based on the specified column and current row.| +| ResultSet | getBlob(columnIndex:number): Uint8Array | Obtains the value in the form of a byte array based on the specified column and the current row.| +| ResultSet | getDouble(columnIndex:number): number | Obtains the value in the form of double based on the specified column and current row.| +| ResultSet | getLong(columnIndex:number): number | Obtains the value in the form of a long integer based on the specified column and current row. | +| ResultSet | close(): void | Closes the result set.| @@ -148,7 +148,7 @@ 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>): void;| Unregisters the observer of the specified type for the RDB store. This API uses a callback to return the result.
- **type**: subscription type. **SUBSCRIBE_TYPE_REMOTE** means to subscribe to remote data changes.
- **observer**: observer to unregister.| +| RdbStore |off(event:'dataChange', type: SubscribeType, observer: Callback>): void;| Unregisters the observer of the specified type for the RDB store. This method uses a callback to return the result.
- **type**: subscription type. **SUBSCRIBE_TYPE_REMOTE** means to subscribe to remote data changes.
- **observer**: observer to unregister.| ## How to Develop