Distributed data management provides collaboration between databases of different devices for applications. The APIs provided by distributed data management can be used to save data to the distributed database and perform operations such as adding, deleting, modifying, and querying data in the distributed database.
The distributed data management module implements collaboration between databases of different devices for applications. The APIs provided by distributed data management can be used to save data to distributed databases and perform operations such as adding, deleting, modifying, querying, and synchronizing data in distributed databases.
This module provides the following functions:
-[KVManager](#kvmanager): provides a **KVManager** instance to manage key-value (KV) stores.
-[KvStoreResultSet<sup>8+</sup>](#kvstoreresultset8): provides methods to obtain the KV store result set and query or move the data read position.
-[Query<sup>8+</sup>](#query8): provides methods to query data from the database through a **Query** instance by using predicates.
-[KVStore](#kvstore): provides methods to add data, delete data, and observe data changes and data synchronization through a **KVStore** instance.
-[SingleKVStore](#singlekvstore): provides methods to query and synchronize data in a single KV store. This class inherits from [KVStore](#kvstore), and data is not distinguished by device.
-[DeviceKVStore<sup>8+</sup> ](#devicekvstore8): provides methods to query and synchronize data in a device KV store. This class inherits from [KVStore](#kvstore), and data is distinguished by device.
>**NOTE**<br/>
>**NOTE**<br/>
>
>
...
@@ -18,7 +27,7 @@ import distributedData from '@ohos.data.distributedData';
...
@@ -18,7 +27,7 @@ import distributedData from '@ohos.data.distributedData';
@@ -26,8 +35,8 @@ Creates a **KVManager** object to manage key-value (KV) stores. This API uses an
...
@@ -26,8 +35,8 @@ Creates a **KVManager** object to manage key-value (KV) stores. This API uses an
| Name| Type| Mandatory| Description|
| Name| Type| Mandatory| Description|
| ----- | ------ | ------ | ------ |
| ----- | ------ | ------ | ------ |
| config | [KVManagerConfig](#kvmanagerconfig) | Yes | Configuration of the **KVManager**object, including the bundle name and user information of the caller.|
| config | [KVManagerConfig](#kvmanagerconfig) | Yes | Configuration of the **KVManager**instance, including the bundle name and user information of the caller.|
| callback | AsyncCallback<[KVManager](#kvmanager)> | Yes | Callback invoked to return the **KVManager**object created.|
| callback | AsyncCallback<[KVManager](#kvmanager)> | Yes | Callback invoked to return the **KVManager**instance created.|
@@ -65,13 +74,13 @@ Creates a **KVManager** object to manage KV stores. This API uses a promise to r
...
@@ -65,13 +74,13 @@ Creates a **KVManager** object to manage KV stores. This API uses a promise to r
| Name| Type| Mandatory| Description|
| Name| Type| Mandatory| Description|
| ----- | ------ | ------ | ------ |
| ----- | ------ | ------ | ------ |
| config |[KVManagerConfig](#kvmanager) | Yes | Configuration of the **KVManager**object, including the bundle name and user information of the caller.|
| config |[KVManagerConfig](#kvmanager) | Yes | Configuration of the **KVManager**instance, including the bundle name and user information of the caller.|
**Return value**
**Return value**
| Type| Description|
| Type| Description|
| -------- | -------- |
| -------- | -------- |
| Promise<[KVManager](#kvmanager)> | Promise used to return the **KVManager**object created.|
| Promise<[KVManager](#kvmanager)> | Promise used to return the **KVManager**instance created.|
| Promise<T><T extends [KVStore](#kvstore)> | Promise used to return the KV store created.|
| Promise<T>,<T extends [KVStore](#kvstore)> | Promise used to return the KV store created.|
**Example**
**Example**
...
@@ -241,7 +250,7 @@ Closes a KV store. This API uses an asynchronous callback to return the result.
...
@@ -241,7 +250,7 @@ Closes a KV store. This API uses an asynchronous callback to return the result.
| appId | string | Yes | Bundle name of the app that invokes the KV store. |
| appId | string | Yes | Bundle name of the app that invokes the KV store. |
| storeId | string | Yes | Unique identifier of the KV store to close. The length cannot exceed [MAX_STORE_ID_LENGTH](#constants).|
| storeId | string | Yes | Unique identifier of the KV store to close. The length cannot exceed [MAX_STORE_ID_LENGTH](#constants).|
| kvStore | [KVStore](#kvstore) | Yes | KV store to close. |
| kvStore | [KVStore](#kvstore) | Yes | KV store to close. |
| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the KV store is closed, **true** will be returned. Otherwise, **false** will be returned. |
| callback | AsyncCallback<void> | Yes | Callback used to return the result.|
| appId | string | Yes | Bundle name of the app that invokes the KV store. |
| appId | string | Yes | Bundle name of the app that invokes the KV store. |
| storeId | string | Yes | Unique identifier of the KV store to delete. The length cannot exceed [MAX_STORE_ID_LENGTH](#constants).|
| storeId | string | Yes | Unique identifier of the KV store to delete. The length cannot exceed [MAX_STORE_ID_LENGTH](#constants).|
| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the KV store is deleted, **true** will be returned. Otherwise, **false** will be returned. |
| callback | AsyncCallback<void> | Yes | Callback used to return the result.|
@@ -388,7 +397,7 @@ Deletes a KV store. This API uses a promise to return the result.
...
@@ -388,7 +397,7 @@ Deletes a KV store. This API uses a promise to return the result.
| Type | Description |
| Type | Description |
| ------------- | -------------- |
| ------------- | -------------- |
| Promise<void> | Promise used to return the result. If the KV store is deleted, **true** will be returned. Otherwise, **false** will be returned.|
| Promise<void> | Promise that returns no value.|
Obtains the IDs of all the KV stores that are created using [getKVStore](#getkvstore) and have not been deleted using [deleteKVStore](#deletekvstore8). This API uses an asynchronous callback to return the result.
Obtains the IDs of all KV stores that are created by [getKVStore()](#getkvstore) and have not been deleted by [deleteKVStore()](#deletekvstore8). This API uses an asynchronous callback to return the result.
Obtains the IDs of all the KV stores that are created using [getKVStore](#getkvstore) and have not been deleted using [deleteKVStore](#deletekvstore8). This API uses a promise to return the result.
Obtains the IDs of all KV stores that are created by [getKVStore()](#getkvstore) and have not been deleted by [deleteKVStore()](#deletekvstore8). This API uses a promise to return the result.
| event | string | Yes | Name of the event to subscribe to. The value is **distributedDataServiceDie**, which indicates the service status change event.|
| event | string | Yes | Event to subscribe to. The value is **distributedDataServiceDie**, which indicates service status changes.|
| deathCallback | Callback<void> | Yes | Callback invoked when the distributed data service is dead. |
| deathCallback | Callback<void> | Yes | Callback invoked to return service status changes.|
| event | string | Yes | Name of the event to unsubscribe from. The value is **distributedDataServiceDie**, which indicates the service status change event.|
| event | string | Yes | Event to unsubscribe from. The value is **distributedDataServiceDie**, which indicates service status changes.|
| deathCallback | Callback<void> | No | Callback used to return the **distributedDataServiceDie** events. |
| deathCallback | Callback<void> | No | Callback used to return service status changes.|
**Example**
**Example**
...
@@ -562,41 +571,41 @@ Provides KV store configuration.
...
@@ -562,41 +571,41 @@ Provides KV store configuration.
| createIfMissing | boolean | No| Whether to create a KV store if no database file exists. By default, a KV store is created.<br>**System capability**: SystemCapability.DistributedDataManager.KVStore.Core |
| createIfMissing | boolean | No| Whether to create a KV store if no database file exists. By default, a KV store is created.<br>**System capability**: SystemCapability.DistributedDataManager.KVStore.Core |
| encrypt | boolean | No|Whether to encrypt database files. By default, database files are not encrypted.<br>**System capability**: SystemCapability.DistributedDataManager.KVStore.Core |
| encrypt | boolean | No|Whether to encrypt database files. By default, database files are not encrypted.<br>**System capability**: SystemCapability.DistributedDataManager.KVStore.Core |
| backup | boolean | No|Whether to back up database files. By default, database files are backed up. <br>**System capability**: SystemCapability.DistributedDataManager.KVStore.Core |
| backup | boolean | No|Whether to back up database files. By default, database files are backed up. <br>**System capability**: SystemCapability.DistributedDataManager.KVStore.Core |
| autoSync | boolean | No|Whether to automatically synchronize database files. By default, database files are not automatically synchronized.<br>**System capability**: SystemCapability.DistributedDataManager.KVStore.Core <br>**Required permissions**: ohos.permission.DISTRIBUTED_DATASYNC |
| autoSync | boolean | No|Whether database files are automatically synchronized. By default, database files are not automatically synchronized.<br>**System capability**: SystemCapability.DistributedDataManager.KVStore.Core<br>**Required permissions**: ohos.permission.DISTRIBUTED_DATASYNC |
| kvStoreType | [KVStoreType](#kvstoretype) | No|Type of the KV store to create. By default, a device KV store is created. The device KV store stores data for multiple devices that collaborate with each other.<br>**System capability**: SystemCapability.DistributedDataManager.KVStore.Core|
| kvStoreType | [KVStoreType](#kvstoretype) | No|Type of the KV store to create. By default, a device KV store is created. The device KV store stores data for multiple devices that collaborate with each other.<br>**System capability**: SystemCapability.DistributedDataManager.KVStore.Core|
| securityLevel | [SecurityLevel](#securitylevel) | No|Security level of the KV store. By default, the security level is not set.<br>**System capability**: SystemCapability.DistributedDataManager.KVStore.Core |
| securityLevel | [SecurityLevel](#securitylevel) | No|Security level of the KV store. By default, the security level is not set.<br>**System capability**: SystemCapability.DistributedDataManager.KVStore.Core |
| schema<sup>8+</sup> | [Schema](#schema8) | No| Schema used to define the values stored in a KV store.<br>**System capability**: SystemCapability.DistributedDataManager.KVStore.DistributedKVStore|
| schema<sup>8+</sup> | [Schema](#schema8) | No| Schema used to define the values stored in a KV store.<br>**System capability**: SystemCapability.DistributedDataManager.KVStore.DistributedKVStore|
| SINGLE_VERSION | 1 | Single KV store.<br>**System capability**: SystemCapability.DistributedDataManager.KVStore.Core|
| SINGLE_VERSION | 1 | Single KV store.<br>**System capability**: SystemCapability.DistributedDataManager.KVStore.Core|
| MULTI_VERSION | 2 | Multi-version KV store. This type is not supported currently.<br>**System capability**: SystemCapability.DistributedDataManager.KVStore.DistributedKVStore|
| MULTI_VERSION | 2 | Multi-version KV store. This type is not supported currently.<br>**System capability**: SystemCapability.DistributedDataManager.KVStore.DistributedKVStore|
| NO_LEVEL | 0 | No security level is set for the KV store. |
| NO_LEVEL | 0 | No security level is set for the KV store. |
| S0 | 1 | The KV store security level is public.|
| S0 | 1 | The KV store security level is public.|
| S1 | 2 | The KV store security level is low. If data leakage occurs, minor impact will be caused on the database. |
| S1 | 2 | The KV store security level is low. If data leakage occurs, minor impact will be caused on the database. For example, a KV store that contains system data such as wallpapers.|
| S2 | 3 | The KV store security level is medium. If data leakage occurs, moderate impact will be caused on the database. |
| S2 | 3 | The KV store security level is medium. If data leakage occurs, moderate impact will be caused on the database. For example, a KV store that contains information created by users or call records, such as audio or video clips.|
| S3 | 5 | The KV store security level is high. If data leakage occurs, major impact will be caused on the database. |
| S3 | 5 | The KV store security level is high. If data leakage occurs, major impact will be caused on the database. For example, a KV store that contains information such as user fitness, health, and location data.|
| S4 | 6 | The KV store security level is critical. If data leakage occurs, severe impact will be caused on the database. |
| S4 | 6 | The KV store security level is critical. If data leakage occurs, severe impact will be caused on the database. For example, a KV store that contains information such as authentication credentials and financial data.|
## Constants
## Constants
...
@@ -605,18 +614,18 @@ Defines the KV store constants.
...
@@ -605,18 +614,18 @@ Defines the KV store constants.
@@ -645,7 +654,7 @@ Represents a **Schema** instance, which provides the methods for defining the va
...
@@ -645,7 +654,7 @@ Represents a **Schema** instance, which provides the methods for defining the va
| --- | ---- | ----------------------- |
| --- | ---- | ----------------------- |
| nullable<sup>8+</sup> | boolean | Whether the database field can be null. |
| nullable<sup>8+</sup> | boolean | Whether the database field can be null. |
| default<sup>8+</sup> | string | Default value of a **FieldNode**.|
| default<sup>8+</sup> | string | Default value of a **FieldNode**.|
| type<sup>8+</sup> | number | Value to store.|
| type<sup>8+</sup> | number | Value of the data type corresponding to the specified node.|
### constructor<sup>8+</sup> ###
### constructor<sup>8+</sup> ###
...
@@ -693,7 +702,7 @@ try {
...
@@ -693,7 +702,7 @@ try {
node.appendChild(child1);
node.appendChild(child1);
node.appendChild(child2);
node.appendChild(child2);
node.appendChild(child3);
node.appendChild(child3);
console.log("appendNode "+node.toJson());
console.log("appendNode "+JSON.stringify(node));
child1=null;
child1=null;
child2=null;
child2=null;
child3=null;
child3=null;
...
@@ -706,14 +715,16 @@ try {
...
@@ -706,14 +715,16 @@ try {
## KvStoreResultSet<sup>8+</sup> ##
## KvStoreResultSet<sup>8+</sup> ##
Provides methods to obtain the KV store result set and query or move the data read position. Before calling any method in **KvStoreResultSet**, you must use **KvStore** to create a **KvStore** instance.
Provides methods to obtain the KV store result sets, and query and move the data read position.
Before calling any method in **KvStoreResultSet**, you must use [getKVStore](#getkvstore) to obtain a **KVStore** object.
### getCount<sup>8+</sup> ###
### getCount<sup>8+</sup> ###
getCount(): number
getCount(): number
Obtains the number of rows in the result set.
Obtains the total number of rows in the result set.
| fieId | string | Yes |Field to match. It cannot contain '^'. |
**Return value**
**Return value**
| Type | Description |
| Type | Description |
| ------ | ------- |
| ------ | ------- |
| [Query](#query8) |**Query** object Created.|
| [Query](#query8) |**Query** object created.|
**Example**
**Example**
...
@@ -1858,7 +1868,7 @@ try {
...
@@ -1858,7 +1868,7 @@ try {
console.log("query is "+query.getSqlLike());
console.log("query is "+query.getSqlLike());
query=null;
query=null;
}catch(e){
}catch(e){
console.log("dumplicated calls should be ok :"+e);
console.log("duplicated calls should be ok :"+e);
}
}
```
```
...
@@ -1875,7 +1885,7 @@ Creates a **Query** object for a query condition group with a left parenthesis.
...
@@ -1875,7 +1885,7 @@ Creates a **Query** object for a query condition group with a left parenthesis.
| Type | Description |
| Type | Description |
| ------ | ------- |
| ------ | ------- |
| [Query](#query8) |**Query** object Created.|
| [Query](#query8) |**Query** object created.|
**Example**
**Example**
...
@@ -1888,7 +1898,7 @@ try {
...
@@ -1888,7 +1898,7 @@ try {
console.log("query is "+query.getSqlLike());
console.log("query is "+query.getSqlLike());
query=null;
query=null;
}catch(e){
}catch(e){
console.log("dumplicated calls should be ok :"+e);
console.log("duplicated calls should be ok :"+e);
}
}
```
```
...
@@ -1905,7 +1915,7 @@ Creates a **Query** object for a query condition group with a right parenthesis.
...
@@ -1905,7 +1915,7 @@ Creates a **Query** object for a query condition group with a right parenthesis.
| Type | Description |
| Type | Description |
| ------ | ------- |
| ------ | ------- |
| [Query](#query8) |**Query** object Created.|
| [Query](#query8) |**Query** object created.|
**Example**
**Example**
...
@@ -1918,7 +1928,7 @@ try {
...
@@ -1918,7 +1928,7 @@ try {
console.log("query is "+query.getSqlLike());
console.log("query is "+query.getSqlLike());
query=null;
query=null;
}catch(e){
}catch(e){
console.log("dumplicated calls should be ok :"+e);
console.log("duplicated calls should be ok :"+e);
}
}
```
```
...
@@ -1941,7 +1951,7 @@ Creates a **Query** object with a specified key prefix.
...
@@ -1941,7 +1951,7 @@ Creates a **Query** object with a specified key prefix.
| Type | Description |
| Type | Description |
| ------ | ------- |
| ------ | ------- |
| [Query](#query8) |**Query** object Created.|
| [Query](#query8) |**Query** object created.|
**Example**
**Example**
...
@@ -1953,7 +1963,7 @@ try {
...
@@ -1953,7 +1963,7 @@ try {
console.log("query is "+query.getSqlLike());
console.log("query is "+query.getSqlLike());
query=null;
query=null;
}catch(e){
}catch(e){
console.log("dumplicated calls should be ok :"+e);
console.log("duplicated calls should be ok :"+e);
}
}
```
```
...
@@ -1976,7 +1986,7 @@ Creates a **Query** object with an index preferentially used for query.
...
@@ -1976,7 +1986,7 @@ Creates a **Query** object with an index preferentially used for query.
| Type | Description |
| Type | Description |
| ------ | ------- |
| ------ | ------- |
| [Query](#query8) |**Query** object Created.|
| [Query](#query8) |**Query** object created.|
**Example**
**Example**
...
@@ -1988,7 +1998,7 @@ try {
...
@@ -1988,7 +1998,7 @@ try {
console.log("query is "+query.getSqlLike());
console.log("query is "+query.getSqlLike());
query=null;
query=null;
}catch(e){
}catch(e){
console.log("dumplicated calls should be ok :"+e);
console.log("duplicated calls should be ok :"+e);
}
}
```
```
...
@@ -2012,7 +2022,7 @@ Creates a **Query** object with the device ID as the key prefix.
...
@@ -2012,7 +2022,7 @@ Creates a **Query** object with the device ID as the key prefix.
| Type | Description |
| Type | Description |
| ------ | ------- |
| ------ | ------- |
| [Query](#query8) |**Query** object Created.|
| [Query](#query8) |**Query** object created.|
**Example**
**Example**
...
@@ -2049,14 +2059,16 @@ try {
...
@@ -2049,14 +2059,16 @@ try {
letsql1=query.getSqlLike();
letsql1=query.getSqlLike();
console.log("GetSqlLike sql="+sql1);
console.log("GetSqlLike sql="+sql1);
}catch(e){
}catch(e){
console.log("dumplicated calls should be ok : "+e);
console.log("duplicated calls should be ok : "+e);
}
}
```
```
## KVStore
## KVStore
Provides methods to manage data in a KV store, for example, adding or deleting data and subscribing to data changes or completion of data synchronization. Before calling any method in **KVStore**, you must use [getKVStore](#getkvstore) to obtain a **KVStore** object.
Provides methods to manage data in a KV store, for example, adding or deleting data and subscribing to data changes or completion of data synchronization.
Before calling any method in **KVStore**, you must use [getKVStore](#getkvstore) to obtain a **KVStore** object.
### put
### put
...
@@ -2113,7 +2125,7 @@ Adds a KV pair of the specified type to this KV store. This API uses a promise t
...
@@ -2113,7 +2125,7 @@ Adds a KV pair of the specified type to this KV store. This API uses a promise t
| Type | Description |
| Type | Description |
| ------ | ------- |
| ------ | ------- |
| Promise<void> |Promise used to return the result.|
| Promise<void> |Promise that returns no value.|
Provides methods to query and synchronize data in a single KV store. This class inherits from **KVStore**. Before calling any method in **SingleKVStore**, you must use [getKVStore](#getkvstore) to obtain a **SingleKVStore** object.
Provides methods to query and synchronize data in a single KV store. This class inherits from [KVStore](#kvstore).
Data is not distinguished by device in a single KV store. The data written to different devices using the same key will be overwritten. For example, a single KV store can be used to synchronize a user's calendar and contact data between different devices.
Before calling any method in **SingleKVStore**, you must use [getKVStore](#getkvstore) to obtain a **SingleKVStore** instance.
Manually triggers KV store synchronization synchronously. For details about the synchronization mode of the distributed data service, see [Distributed Data Service Overview] (../../database/database-mdds-overview.md).
Synchronizes the KV store manually. For details about the synchronization modes of the distributed data service, see [Distributed Data Service Overview] (../../database/database-mdds-overview.md).
| callback |AsyncCallback<[SecurityLevel](#securitylevel)> | Yes |Callback used to return the security level obtained. |
| callback |AsyncCallback<[SecurityLevel](#securitylevel)> | Yes |Callback invoked to return the security level obtained. |
**Example**
**Example**
...
@@ -3892,7 +3902,7 @@ Obtains the security level of this KV store. This API uses a promise to return t
...
@@ -3892,7 +3902,7 @@ Obtains the security level of this KV store. This API uses a promise to return t
| Type | Description |
| Type | Description |
| ------ | ------- |
| ------ | ------- |
|Promise<[SecurityLevel](#securitylevel)> |Promise used to return the value obtained.|
|Promise<[SecurityLevel](#securitylevel)> |Promise used to return the security level obtained.|
**Example**
**Example**
...
@@ -3912,13 +3922,19 @@ try {
...
@@ -3912,13 +3922,19 @@ try {
## DeviceKVStore<sup>8+</sup> ##
## DeviceKVStore<sup>8+</sup> ##
Provides methods to manage distributed data by device in the distributed system. This class inherits from **KVStore** and provides data query and synchronization methods. Before calling any method in **DeviceKVStore**, you must use [getKVStore](#getkvstore) to obtain a **DeviceKVStore** object.
Provides methods to query and synchronize data in a device KV store. This class inherits from [KVStore](#kvstore).
Data is distinguished by device in a device KV store. Each device can only write and modify its own data. Data of other devices is read-only and cannot be modified.
For example, a device KV store can be used to implement image sharing between devices. The images of other devices can be viewed, but not be modified or deleted.
Before calling any method in **DeviceKVStore**, you must use [getKVStore](#getkvstore) to obtain a **DeviceKVStore** object.
Obtains the **KvStoreResultSet** object that matches the specified key prefix for a device. This API uses an asynchronous callback to return the result.
Obtains a **KvStoreResultSet** object that matches the specified device ID and key prefix. This API uses an asynchronous callback to return the result.
Obtains the **KvStoreResultSet** object that matches the specified **Query** object for a device. This API uses an asynchronous callback to return the result.
Obtains a **KvStoreResultSet** object that matches the specified device ID and **Query** object. This API uses an asynchronous callback to return the result.
Manually triggers KV store synchronization synchronously. For details about the synchronization mode of the distributed data service, see [Distributed Data Service Overview] (../../database/database-mdds-overview.md).
Synchronizes the KV store manually. For details about the synchronization modes of the distributed data service, see [Distributed Data Service Overview] (../../database/database-mdds-overview.md).
