@ohos.data.distributedKVStore (Distributed KV Store) (System API)

The distributedKVStore module implements collaboration between databases for different devices that forms a Super Device. You can use the APIs provided by this module to save application data to a distributed key-value (KV) store and perform operations, such as adding, deleting, modifying, querying, and synchronizing data in distributed KV stores.

The distributedKVStore module provides the following:

• KVManager: provides a KVManager instance to obtain KV store information.
• KVStoreResultSet: provides APIs for accessing the results obtained from a KV store.
• Query: provides APIs for setting predicates for data query.
• SingleKVStore: provides APIs for querying and synchronizing data in single KV stores. The single KV stores manage data without distinguishing devices.
• DeviceKVStore: provides APIs for querying and synchronizing data in device KV stores. This class inherits from SingleKVStore. The device KV stores manage data by device.

NOTE

• The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.

• This topic describes only the system APIs provided by the module. For details about its public APIs, see @ohos.data.distributedKVStore.

Modules to Import

import distributedKVStore from '@ohos.data.distributedKVStore';

SingleKVStore

Implements data management in a single KV store, such as adding data, deleting data, and subscribing to data changes or data sync completion.

Before calling SingleKVStore APIs, you need to use getKVStore to create a SingleKVStore instance.

putBatch

putBatch(value: Array<ValuesBucket>, callback: AsyncCallback<void>): void

Writes batch data to this single KV store. This API uses an asynchronous callback to return the result.

Model restriction: This API can be used only in the stage model.

System API: This is a system API.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Error codes

For details about the error codes, see Distributed KV Store Error Codes.

For details about the error codes, see RDB Error Codes.

Example

import { BusinessError } from '@ohos.base';

try {
  let v8Arr: distributedKVStore.Entry[] = [];
  let arr = new Uint8Array([4, 5, 6, 7]);
  let vb1: distributedKVStore.Entry = { key: "name_1", value: {type: distributedKVStore.ValueType.INTEGER, value: 32} }
  let vb2: distributedKVStore.Entry = { key: "name_2", value: {type: distributedKVStore.ValueType.BYTE_ARRAY, value: arr} };
  let vb3: distributedKVStore.Entry = { key: "name_3", value: {type: distributedKVStore.ValueType.STRING, value: "lisi"} };

  v8Arr.push(vb1);
  v8Arr.push(vb2);
  v8Arr.push(vb3);
  kvStore.putBatch(v8Arr, async (err: BusinessError) => {
    if (err != undefined) {
      console.error(`Failed to put batch.code is ${err.code},message is ${err.message}`);
      return;
    }
    console.info('Succeeded in putting batch');
  })
} catch (e) {
  let error = e as BusinessError;
  console.error(`Failed to put batch.code is ${error.code},message is ${error.message}`);
}

putBatch

putBatch(value: Array<ValuesBucket>): Promise<void>

Writes batch data to this single KV store. This API uses a promise to return the result.

Model restriction: This API can be used only in the stage model.

System API: This is a system API.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Return value

Error codes

For details about the error codes, see Distributed KV Store Error Codes.

For details about the error codes, see RDB Error Codes.

Example

import { BusinessError } from '@ohos.base';

try {
  let v8Arr: distributedKVStore.Entry[] = [];
  let arr = new Uint8Array([4, 5, 6, 7]);
  let vb1: distributedKVStore.Entry = { key: "name_1", value: {type: distributedKVStore.ValueType.INTEGER, value: 32} }
  let vb2: distributedKVStore.Entry = { key: "name_2", value: {type: distributedKVStore.ValueType.BYTE_ARRAY, value: arr} };
  let vb3: distributedKVStore.Entry = { key: "name_3", value: {type: distributedKVStore.ValueType.STRING, value: "lisi"} };

  v8Arr.push(vb1);
  v8Arr.push(vb2);
  v8Arr.push(vb3);
  kvStore.putBatch(v8Arr).then(async () => {
    console.info(`Succeeded in putting patch`);
  }).catch((err: BusinessError) => {
    console.error(`putBatch fail.code is ${err.code},message is ${err.message}`);
  });
} catch (e) {
  let error = e as BusinessError;
  console.error(`putBatch fail.code is ${error.code},message is ${error.message}`);
}

delete

delete(predicates: dataSharePredicates.DataSharePredicates, callback: AsyncCallback<void>)

Deletes KV pairs from this KV store. This API uses an asynchronous callback to return the result.

Model restriction: This API can be used only in the stage model.

System API: This is a system API.

System capability: SystemCapability.DistributedDataManager.DataShare.Provider

Parameters

Error codes

For details about the error codes, see Distributed KV Store Error Codes.

For details about the error codes, see RDB Error Codes.

Example

import dataSharePredicates from '@ohos.data.dataSharePredicates';
import { BusinessError } from '@ohos.base';

try {
  let predicates = new dataSharePredicates.DataSharePredicates();
  let arr = ["name"];
  predicates.inKeys(arr);
  kvStore.put("name", "bob", (err:BusinessError) => {
    if (err != undefined) {
      console.error(`Failed to put.code is ${err.code},message is ${err.message}`);
      return;
    }
    console.info("Succeeded in putting");
    if (kvStore != null) {
      kvStore.delete(predicates, (err:BusinessError) => {
        if (err == undefined) {
          console.info('Succeeded in deleting');
        } else {
          console.error(`Failed to delete.code is ${err.code},message is ${err.message}`);
        }
      });
    }
  });
} catch (e) {
  let error = e as BusinessError;
  console.error(`An unexpected error occurred.code is ${error.code},message is ${error.message}`);
}

delete

delete(predicates: dataSharePredicates.DataSharePredicates): Promise<void>

Deletes KV pairs from this KV store. This API uses a promise to return the result.

Model restriction: This API can be used only in the stage model.

System API: This is a system API.

System capability: SystemCapability.DistributedDataManager.DataShare.Provider

Parameters

Return value

Error codes

For details about the error codes, see Distributed KV Store Error Codes.

For details about the error codes, see RDB Error Codes.

Example

import dataSharePredicates from '@ohos.data.dataSharePredicates';
import { BusinessError } from '@ohos.base';

try {
  let predicates = new dataSharePredicates.DataSharePredicates();
  let arr = ["name"];
  predicates.inKeys(arr);
  kvStore.put("name", "bob").then(() => {
    console.info(`Succeeded in putting data`);
    if (kvStore != null) {
      kvStore.delete(predicates).then(() => {
        console.info('Succeeded in deleting');
      }).catch((err: BusinessError) => {
        console.error(`Failed to delete.code is ${err.code},message is ${err.message}`);
      });
    }
  }).catch((err: BusinessError) => {
    console.error(`Failed to put.code is ${err.code},message is ${err.message}`);
  });
} catch (e) {
  let error = e as BusinessError;
  console.error(`An unexpected error occurred.code is ${error.code},message is ${error.message}`);
}

getResultSet

getResultSet(predicates: dataSharePredicates.DataSharePredicates, callback: AsyncCallback<KVStoreResultSet>): void

Obtains a KVStoreResultSet object that matches the specified conditions. This API uses an asynchronous callback to return the result.

Model restriction: This API can be used only in the stage model.

System API: This is a system API.

System capability: SystemCapability.DistributedDataManager.DataShare.Provider

Parameters

Error codes

For details about the error codes, see Distributed KV Store Error Codes.

Example

import dataSharePredicates from '@ohos.data.dataSharePredicates';
import { BusinessError } from '@ohos.base';

try {
  let resultSet: distributedKVStore.KVStoreResultSet;
  let predicates = new dataSharePredicates.DataSharePredicates();
  predicates.prefixKey("batch_test_string_key");
  kvStore.getResultSet(predicates, async (err: BusinessError, result: distributedKVStore.KVStoreResultSet) => {
    if (err != undefined) {
      console.error(`Failed to get resultset.code is ${err.code},message is ${err.message}`);
      return;
    }
    console.info('Succeeded in getting result set');
    resultSet = result;
    if (kvStore != null) {
      kvStore.closeResultSet(resultSet, (err: BusinessError) => {
        if (err != undefined) {
          console.error(`Failed to close resultset.code is ${err.code},message is ${err.message}`);
          return;
        }
        console.info('Succeeded in closing result set');
      });
    }
  });
} catch (e) {
  let error = e as BusinessError;
  console.error(`An unexpected error occurred.code is ${error.code},message is ${error.code}`);
}

getResultSet

getResultSet(predicates: dataSharePredicates.DataSharePredicates): Promise<KVStoreResultSet>

Obtains a KVStoreResultSet object that matches the specified conditions. This API uses a promise to return the result.

Model restriction: This API can be used only in the stage model.

System API: This is a system API.

System capability: SystemCapability.DistributedDataManager.DataShare.Provider

Parameters

Return value

Error codes

For details about the error codes, see Distributed KV Store Error Codes.

Example

import dataSharePredicates from '@ohos.data.dataSharePredicates';
import { BusinessError } from '@ohos.base';

try {
  let resultSet: distributedKVStore.KVStoreResultSet;
  let predicates = new dataSharePredicates.DataSharePredicates();
  predicates.prefixKey("batch_test_string_key");
  kvStore.getResultSet(predicates).then((result: distributedKVStore.KVStoreResultSet) => {
    console.info('Succeeded in getting result set');
    resultSet = result;
    if (kvStore != null) {
      kvStore.closeResultSet(resultSet).then(() => {
        console.info('Succeeded in closing result set');
      }).catch((err: BusinessError) => {
        console.error(`Failed to close resultset.code is ${err.code},message is ${err.message}`);
      });
    }
  }).catch((err: BusinessError) => {
    console.error(`Failed to get resultset.code is ${err.code},message is ${err.message}`);
  });

} catch (e) {
  let error = e as BusinessError;
  console.error(`An unexpected error occurred.code is ${error.code},message is ${error.code}`);
}

DeviceKVStore

Provides APIs for querying and synchronizing data in a device KV store. This class inherits from SingleKVStore.

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 DeviceKVStore APIs, you need to use getKVStore to create a DeviceKVStore instance.

getResultSet

getResultSet(predicates: dataSharePredicates.DataSharePredicates, callback: AsyncCallback<KVStoreResultSet>): void

Obtains a KVStoreResultSet object that matches the specified conditions for this device. This API uses an asynchronous callback to return the result.

Model restriction: This API can be used only in the stage model.

System API: This is a system API.

System capability: SystemCapability.DistributedDataManager.DataShare.Provider

Parameters

Error codes

For details about the error codes, see Distributed KV Store Error Codes.

Example

import dataSharePredicates from '@ohos.data.dataSharePredicates';
import { BusinessError } from '@ohos.base';

try {
  let resultSet: distributedKVStore.KVStoreResultSet;
  let predicates = new dataSharePredicates.DataSharePredicates();
  predicates.prefixKey("batch_test_string_key");
  kvStore.getResultSet(predicates, async (err: BusinessError, result: distributedKVStore.KVStoreResultSet) => {
    if (err != undefined) {
      console.error(`Failed to get resultset.code is ${err.code},message is ${err.message}`);
      return;
    }
    console.info('Succeeded in getting result set');
    resultSet = result;
    if (kvStore != null) {
      kvStore.closeResultSet(resultSet, (err: BusinessError) => {
        if (err != undefined) {
          console.error(`Failed to close resultset.code is ${err.code},message is ${err.message}`);
          return;
        }
        console.info('Succeeded in closing result set');
      })
    }
  });
} catch (e) {
  let error = e as BusinessError;
  console.error(`An unexpected error occurred.code is ${error.code},message is ${error.code}`);
}

getResultSet

getResultSet(predicates: dataSharePredicates.DataSharePredicates): Promise<KVStoreResultSet>

Obtains a KVStoreResultSet object that matches the specified conditions for this device. This API uses a promise to return the result.

Model restriction: This API can be used only in the stage model.

System API: This is a system API.

System capability: SystemCapability.DistributedDataManager.DataShare.Provider

Parameters

Return value

Error codes

For details about the error codes, see Distributed KV Store Error Codes.

Example

import dataSharePredicates from '@ohos.data.dataSharePredicates';
import { BusinessError } from '@ohos.base';

try {
  let resultSet: distributedKVStore.KVStoreResultSet;
  let predicates = new dataSharePredicates.DataSharePredicates();
  predicates.prefixKey("batch_test_string_key");
  kvStore.getResultSet(predicates).then((result: distributedKVStore.KVStoreResultSet) => {
    console.info('Succeeded in getting result set');
    resultSet = result;
    if (kvStore != null) {
      kvStore.closeResultSet(resultSet).then(() => {
        console.info('Succeeded in closing result set');
      }).catch((err: BusinessError) => {
        console.error(`Failed to close resultset.code is ${err.code},message is ${err.message}`);
      });
    }
  }).catch((err: BusinessError) => {
    console.error(`Failed to get resultset.code is ${err.code},message is ${err.message}`);
  });
} catch (e) {
  let error = e as BusinessError;
  console.error(`An unexpected error occurred.code is ${error.code},message is ${error.code}`);
}

getResultSet

getResultSet(deviceId: string, predicates: dataSharePredicates.DataSharePredicates, callback: AsyncCallback<KVStoreResultSet>): void

Obtains a KVStoreResultSet object that matches the specified conditions for a device. This API uses an asynchronous callback to return the result.

NOTE

deviceId can be obtained by deviceManager.getAvailableDeviceListSync. For details about how to obtain deviceId, see the example of sync.

Model restriction: This API can be used only in the stage model.

System API: This is a system API.

System capability: SystemCapability.DistributedDataManager.DataShare.Provider

Parameters

Error codes

For details about the error codes, see Distributed KV Store Error Codes.

Example

import dataSharePredicates from '@ohos.data.dataSharePredicates';
import { BusinessError } from '@ohos.base';

try {
  let resultSet: distributedKVStore.KVStoreResultSet;
  let predicates = new dataSharePredicates.DataSharePredicates();
  predicates.prefixKey("batch_test_string_key");
  kvStore.getResultSet('localDeviceId', predicates, async (err: BusinessError, result: distributedKVStore.KVStoreResultSet) => {
    if (err != undefined) {
      console.error(`Failed to get resultset.code is ${err.code},message is ${err.message}`);
      return;
    }
    console.info('Succeeded in getting result set');
    resultSet = result;
    if (kvStore != null) {
      kvStore.closeResultSet(resultSet, (err: BusinessError) => {
        if (err != undefined) {
          console.error(`Failed to close resultset.code is ${err.code},message is ${err.message}`);
          return;
        }
        console.info('Succeeded in closing result set');
      })
    }
  });
} catch (e) {
  let error = e as BusinessError;
  console.error(`An unexpected error occurred.code is ${error.code},message is ${error.code}`);
}

getResultSet

getResultSet(deviceId: string, predicates: dataSharePredicates.DataSharePredicates): Promise<KVStoreResultSet>

Obtains a KVStoreResultSet object that matches the specified conditions for a device. This API uses a promise to return the result.

NOTE

deviceId can be obtained by deviceManager.getAvailableDeviceListSync. For details about how to obtain deviceId, see the example of sync.

Model restriction: This API can be used only in the stage model.

System API: This is a system API.

System capability: SystemCapability.DistributedDataManager.DataShare.Provider

Parameters

Return value

Error codes

For details about the error codes, see Distributed KV Store Error Codes.

Example

import dataSharePredicates from '@ohos.data.dataSharePredicates';
import { BusinessError } from '@ohos.base';

try {
  let resultSet: distributedKVStore.KVStoreResultSet;
  let predicates = new dataSharePredicates.DataSharePredicates();
  predicates.prefixKey("batch_test_string_key");
  kvStore.getResultSet('localDeviceId', predicates).then((result: distributedKVStore.KVStoreResultSet) => {
    console.info('Succeeded in getting result set');
    resultSet = result;
    if (kvStore != null) {
      kvStore.closeResultSet(resultSet).then(() => {
        console.info('Succeeded in closing result set');
      }).catch((err: BusinessError) => {
        console.error(`Failed to close resultset.code is ${err.code},message is ${err.message}`);
      });
    }
  }).catch((err: BusinessError) => {
    console.error(`Failed to get resultset.code is ${err.code},message is ${err.message}`);
  });
} catch (e) {
  let error = e as BusinessError;
  console.error(`An unexpected error occurred.code is ${error.code},message is ${error.code}`);
}