@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 functionalities:

• 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 '@kit.ArkData';

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 and Universal Error Codes.

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

Example

import { BusinessError } from '@kit.BasicServicesKit';
import { ValuesBucket } from '@kit.ArkData';

try {
  let bucket1: ValuesBucket = {key:"name", value: "LiSi"};
  let bucket2: ValuesBucket = {key:"age", value: 20};
  let bucket3: ValuesBucket = {key:"deposits", value: 12.34};
  let people: Array<ValuesBucket> = new Array(bucket1, bucket2, bucket3);
  kvStore.putBatch(people, (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 do putBatch error.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 and Universal Error Codes.

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

Example

import { BusinessError } from '@kit.BasicServicesKit';
import { ValuesBucket } from '@kit.ArkData';

try {
  let bucket1: ValuesBucket = {key:"name", value: "LiSi"};
  let bucket2: ValuesBucket = {key:"age", value: 20};
  let bucket3: ValuesBucket = {key:"deposits", value: 12.34};
  let people: Array<ValuesBucket> = new Array(bucket1, bucket2, bucket3);
  kvStore.putBatch(people).then(() => {
    console.info(`Succeeded in putting patch`);
  }).catch((err: BusinessError) => {
    console.error(`Failed to do putBatch error.code is ${err.code},message is ${err.message}`);
  });
} catch (e) {
  let error = e as BusinessError;
  console.error(`Failed to do putBatch error.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 and Universal Error Codes.

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

Example

import { dataSharePredicates } from '@kit.ArkData';
import { BusinessError } from '@kit.BasicServicesKit';

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 and Universal Error Codes.

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

Example

import { dataSharePredicates } from '@kit.ArkData';
import { BusinessError } from '@kit.BasicServicesKit';

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 and Universal Error Codes.

Example

import { dataSharePredicates } from '@kit.ArkData';
import { BusinessError } from '@kit.BasicServicesKit';

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 and Universal Error Codes.

Example

import { dataSharePredicates } from '@kit.ArkData';
import { BusinessError } from '@kit.BasicServicesKit';

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 and Universal Error Codes.

Example

import { dataSharePredicates } from '@kit.ArkData';
import { BusinessError } from '@kit.BasicServicesKit';

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 and Universal Error Codes.

Example

import { dataSharePredicates } from '@kit.ArkData';
import { BusinessError } from '@kit.BasicServicesKit';

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 and Universal Error Codes.

Example

import { dataSharePredicates } from '@kit.ArkData';
import { BusinessError } from '@kit.BasicServicesKit';

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 and Universal Error Codes.

Example

import { dataSharePredicates } from '@kit.ArkData';
import { BusinessError } from '@kit.BasicServicesKit';

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}`);
}

你可能感兴趣的鸿蒙文章

harmony 鸿蒙ArkData (ArkData Management)

harmony 鸿蒙Data

harmony 鸿蒙OH_Cursor

harmony 鸿蒙OH_Predicates

harmony 鸿蒙OH_Rdb_Config

harmony 鸿蒙OH_Rdb_Store

harmony 鸿蒙OH_VBucket

harmony 鸿蒙OH_VObject

harmony 鸿蒙Preferences

harmony 鸿蒙_r_d_b