From a39e9b7a9cddf731779a3138437e6f91828a8f1b Mon Sep 17 00:00:00 2001 From: qing Date: Wed, 19 Oct 2022 18:03:35 +0800 Subject: [PATCH] kv-errcode-monthly Signed-off-by: qing --- .../database/database-mdds-guidelines.md | 139 +- .../reference/apis/Readme-CN.md | 8 +- .../apis/js-apis-distributed-data.md | 857 +-- .../apis/js-apis-distributedKVStore.md | 5790 +++++++++++++++++ .../errorcode-distributedKVStore.md | 96 + 5 files changed, 6012 insertions(+), 878 deletions(-) create mode 100644 zh-cn/application-dev/reference/apis/js-apis-distributedKVStore.md create mode 100644 zh-cn/application-dev/reference/errorcodes/errorcode-distributedKVStore.md diff --git a/zh-cn/application-dev/database/database-mdds-guidelines.md b/zh-cn/application-dev/database/database-mdds-guidelines.md index aa8938f6b2..4aa7350d3a 100644 --- a/zh-cn/application-dev/database/database-mdds-guidelines.md +++ b/zh-cn/application-dev/database/database-mdds-guidelines.md @@ -6,20 +6,20 @@ ## 接口说明 -分布式数据相关功能接口请见[分布式数据管理](../reference/apis/js-apis-distributed-data.md)。 +分布式数据相关功能接口请见[分布式键值数据库](../reference/apis/js-apis-distributedKVStore.md)。 **表1** 分布式数据服务关键API功能介绍 -| 接口名称 | 描述 | -| ------------------------------------------------------------ | ----------------------------------------------- | -| createKVManager(config: KVManagerConfig, callback: AsyncCallback<KVManager>): void
createKVManager(config: KVManagerConfig): Promise<KVManager> | 创建一个`KVManager`对象实例,用于管理数据库对象。 | -| getKVStore<TextendsKVStore>(storeId: string, options: Options, callback: AsyncCallback<T>): void
getKVStore<TextendsKVStore>(storeId: string, options: Options): Promise<T> | 指定`Options`和`storeId`,创建并获取`KVStore`数据库。 | -| put(key: string, value: Uint8Array\|string\|number\|boolean, callback: AsyncCallback<void>): void
put(key: string, value: Uint8Array\|string\|number\|boolean): Promise<void> | 插入和更新数据。 | -| delete(key: string, callback: AsyncCallback<void>): void
delete(key: string): Promise<void> | 删除数据。 | -| get(key: string, callback: AsyncCallback<Uint8Array\|string\|boolean\|number>): void
get(key: string): Promise<Uint8Array\|string\|boolean\|number> | 查询数据。 | -| on(event: 'dataChange', type: SubscribeType, observer: Callback<ChangeNotification>): void
on(event: 'syncComplete', syncCallback: Callback<Array<[string,number]>>): void | 订阅数据库中数据的变化。 | -| sync(deviceIdList: string[], mode: SyncMode, allowedDelayMs?: number): void | 在手动模式下,触发数据库同步。 | +| 接口名称 | 描述 | +| ------------------------------------------------------------ | ------------------------------------------------------------ | +| createKVManager(config: KVManagerConfig, callback: AsyncCallback<KVManager>): void
createKVManager(config: KVManagerConfig): Promise<KVManager> | 创建一个`KVManager`对象实例,用于管理数据库对象。 | +| getKVStore<TextendsKVStore>(storeId: string, options: Options, callback: AsyncCallback<T>): void
getKVStore<TextendsKVStore>(storeId: string, options: Options): Promise<T> | 指定`Options`和`storeId`,创建并获取指定类型`KVStore`数据库。 | +| put(key: string, value: Uint8Array\|string\|number\|boolean, callback: AsyncCallback<void>): void
put(key: string, value: Uint8Array\|string\|number\|boolean): Promise<void> | 插入和更新数据。 | +| delete(key: string, callback: AsyncCallback<void>): void
delete(key: string): Promise<void> | 删除数据。 | +| get(key: string, callback: AsyncCallback<Uint8Array\|string\|boolean\|number>): void
get(key: string): Promise<Uint8Array\|string\|boolean\|number> | 查询数据。 | +| on(event: 'dataChange', type: SubscribeType, observer: Callback<ChangeNotification>): void
on(event: 'syncComplete', syncCallback: Callback<Array<[string,number]>>): void | 订阅数据库中数据的变化。 | +| sync(deviceIdList: string[], mode: SyncMode, allowedDelayMs?: number): void | 在手动模式下,触发数据库同步。 | ## 开发步骤 @@ -28,23 +28,25 @@ 1. 导入模块。 ```js - import distributedData from '@ohos.data.distributedData'; + import distributedKVStore from '@ohos.data.distributedKVStore'; ``` + 2. 请求权限(同步操作时进行该步骤)。 需要在`config.json`文件里进行配置请求权限(FA模型),示例代码如下: ```json - { - "module": { - "reqPermissions": [ - { - "name": "ohos.permission.DISTRIBUTED_DATASYNC" - } - ] - } - } + { + "module": { + "reqPermissions": [ + { + "name": "ohos.permission.DISTRIBUTED_DATASYNC" + } + ] + } + } ``` + Stage模型下的权限请求请参见[权限声明-Stage模型](../security/accesstoken-guidelines.md#stage模型)。 这个权限还需要在应用首次启动的时候弹窗获取用户授权,可以通过如下代码实现: @@ -52,7 +54,7 @@ ```js // FA模型 import featureAbility from '@ohos.ability.featureAbility'; - + function grantPermission() { console.info('grantPermission'); let context = featureAbility.getContext(); @@ -62,21 +64,21 @@ console.info('failed: ${error}'); }) } - + grantPermission(); - + // Stage模型 import Ability from '@ohos.application.Ability'; - + let context = null; - + function grantPermission() { class MainAbility extends Ability { onWindowStageCreate(windowStage) { let context = this.context; } } - + let permissions = ['ohos.permission.DISTRIBUTED_DATASYNC']; context.requestPermissionsFromUser(permissions).then((data) => { console.log('success: ${data}'); @@ -84,7 +86,7 @@ console.log('failed: ${error}'); }); } - + grantPermission(); ``` @@ -99,7 +101,7 @@ // FA模型获取context import featureAbility from '@ohos.ability.featureAbility'; let context = featureAbility.getContext(); - + // Stage模型获取context import AbilityStage from '@ohos.application.Ability'; let context = null; @@ -108,27 +110,23 @@ context = this.context; } } - + let kvManager; try { const kvManagerConfig = { bundleName: 'com.example.datamanagertest', - userInfo: { - context:context, - userId: '0', - userType: distributedData.UserType.SAME_USER_ID - } + context:context, } - distributedData.createKVManager(kvManagerConfig, function (err, manager) { + distributedKVStore.createKVManager(kvManagerConfig, function (err, manager) { if (err) { - console.log('createKVManager err: ${error}'); + console.error(`Fail to createKVManager.code is ${err.code},message is ${err.message}`); return; } - console.log('createKVManager success'); + console.log('Succeeded in creating KVManager'); kvManager = manager; }); } catch (e) { - console.log('An unexpected error occurred. Error: ${e}'); + console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`); } ``` @@ -147,34 +145,38 @@ encrypt: false, backup: false, autoSync: false, - kvStoreType: distributedData.KVStoreType.SINGLE_VERSION, - securityLevel: distributedData.SecurityLevel.S0 + kvStoreType: distributedKVStore.KVStoreType.SINGLE_VERSION, + securityLevel: distributedKVStore.SecurityLevel.S1 }; kvManager.getKVStore('storeId', options, function (err, store) { if (err) { - console.log('getKVStore err: ${err}'); + console.error(`Fail to get KVStore: code is ${err.code},message is ${err.message}`); return; } - console.log('getKVStore success'); + console.log('Succeeded in getting KVStore'); kvStore = store; }); } catch (e) { - console.log('An unexpected error occurred. Error: ${e}'); + console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`); } ``` > **说明:** > > 组网设备间同步数据的场景,建议在应用启动时打开分布式数据库,获取数据库的句柄。在该句柄(如示例中的`kvStore`)的生命周期内无需重复创建数据库,可直接使用句柄对数据库进行数据的插入等操作。 - + 5. 订阅分布式数据变化。 以下为订阅单版本分布式数据库数据变化通知的代码示例: ```js - kvStore.on('dataChange', distributedData.SubscribeType.SUBSCRIBE_TYPE_ALL, function (data) { - console.log("dataChange callback call data: ${data}"); - }); + try{ + kvStore.on('dataChange', distributedKVStore.SubscribeType.SUBSCRIBE_TYPE_ALL, function (data) { + console.log(`dataChange callback call data: ${data}`); + }); + }catch(e){ + console.error(`An unexpected error occured.code is ${e.code},message is ${e.message}`); + } ``` 6. 将数据写入分布式数据库。 @@ -188,15 +190,15 @@ const KEY_TEST_STRING_ELEMENT = 'key_test_string'; const VALUE_TEST_STRING_ELEMENT = 'value-test-string'; try { - kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT, function (err, data) { + kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT, function (err,data) { if (err != undefined) { - console.log('put err: ${error}'); + console.error(`Fail to put.code is ${err.code},message is ${err.message}`); return; } - console.log('put success'); + console.log("Succeeded in putting"); }); - } catch (e) { - console.log('An unexpected error occurred. Error: ${e}'); + }catch (e) { + console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`); } ``` @@ -211,18 +213,22 @@ const KEY_TEST_STRING_ELEMENT = 'key_test_string'; const VALUE_TEST_STRING_ELEMENT = 'value-test-string'; try { - kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT, function (err, data) { + kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT, function (err,data) { + if (err != undefined) { + console.error(`Fail to put.code is ${err.code},message is ${err.message}`); + return; + } + console.log("Succeeded in putting"); + kvStore.get(KEY_TEST_STRING_ELEMENT, function (err,data) { if (err != undefined) { - console.log('put err: ${error}'); + console.error(`Fail to get.code is ${err.code},message is ${err.message}`); return; } - console.log('put success'); - kvStore.get(KEY_TEST_STRING_ELEMENT, function (err, data) { - console.log('get success data: ${data}'); + console.log(`Succeeded in getting data:${data}`); }); }); - } catch (e) { - console.log('An unexpected error occurred. Error: ${e}'); + }catch (e) { + console.error(`Fail to get.code is ${e.code},message is ${e.message}`); } ``` @@ -233,7 +239,7 @@ > **说明**: > > 其中`deviceManager`模块的接口均为系统接口。 - + 以下为单版本分布式数据库进行数据同步的代码示例: ```js @@ -254,20 +260,21 @@ } try{ // 1000表示最大延迟时间为1000ms - kvStore.sync(deviceIds, distributedData.SyncMode.PUSH_ONLY, 1000); + kvStore.sync(deviceIds, distributedKVStore.SyncMode.PUSH_ONLY, 1000); } catch (e) { - console.log('An unexpected error occurred. Error: ${e}'); + console.error(`An unexpected error occurred. code is ${e.code},message is ${e.message}`); } } }); ``` + ## 相关实例 针对分布式数据开发,有以下相关实例可供参考: - [`DistributedCalc`:分布式计算器(JS)(API8)(Full SDK)](https://gitee.com/openharmony/applications_app_samples/tree/master/common/DistributeCalc) -- [`DistributedCalc`:分布式计算器(ArkTS)(API8)(Full SDK)](https://gitee.com/openharmony/applications_app_samples/tree/master/Preset/DistributeCalc) -- [`DistributedDataGobang`:分布式五子棋(ArkTS)(API9)(Full SDK)](https://gitee.com/openharmony/applications_app_samples/tree/master/data/DistributedDataGobang) -- [`DDMQuery`:结果集与谓词(ArkTS)(API8)](https://gitee.com/openharmony/applications_app_samples/tree/master/data/DDMQuery) -- [`KvStore`:分布式数据库(ArkTS)(API8)(Full SDK)](https://gitee.com/openharmony/applications_app_samples/tree/master/data/Kvstore) +- [`DistributedCalc`:分布式计算器(eTS)(API8)(Full SDK)](https://gitee.com/openharmony/applications_app_samples/tree/master/Preset/DistributeCalc) +- [`DistributedDataGobang`:分布式五子棋(eTS)(API9)(Full SDK)](https://gitee.com/openharmony/applications_app_samples/tree/master/data/DistributedDataGobang) +- [`DDMQuery`:结果集与谓词(eTS)(API8)](https://gitee.com/openharmony/applications_app_samples/tree/master/data/DDMQuery) +- [`KvStore`:分布式数据库(eTS)(API8)(Full SDK)](https://gitee.com/openharmony/applications_app_samples/tree/master/data/Kvstore) - [分布式数据库(JS)(API8)](https://gitee.com/openharmony/codelabs/tree/master/Data/JsDistributedData) \ No newline at end of file diff --git a/zh-cn/application-dev/reference/apis/Readme-CN.md b/zh-cn/application-dev/reference/apis/Readme-CN.md index d73f1acb03..65a286bb55 100755 --- a/zh-cn/application-dev/reference/apis/Readme-CN.md +++ b/zh-cn/application-dev/reference/apis/Readme-CN.md @@ -63,7 +63,6 @@ - [@ohos.commonEvent (公共事件模块)](js-apis-commonEvent.md) - [@ohos.events.emitter (Emitter)](js-apis-emitter.md) - [@ohos.notification (Notification模块)](js-apis-notification.md) - - [@ohos.reminderAgent (后台代理提醒)](js-apis-reminderAgent.md) - application/[EventHub (EventHub)](js-apis-eventhub.md) - 应用程序包管理 - [@ohos.bundle (Bundle模块)](js-apis-Bundle.md) @@ -120,6 +119,7 @@ - 资源调度 - [@ohos.backgroundTaskManager (后台任务管理)](js-apis-backgroundTaskManager.md) - [@ohos.distributedMissionManager (分布式任务管理)](js-apis-distributedMissionManager.md) + - [@ohos.reminderAgentManager (后台代理提醒)](js-apis-reminderAgentManager.md) - [@ohos.workScheduler (延迟任务调度)](js-apis-workScheduler.md) - [@ohos.WorkSchedulerExtensionAbility (延迟任务调度回调)](js-apis-WorkSchedulerExtensionAbility.md) - 定制管理 @@ -140,8 +140,8 @@ - [@ohos.data.dataShare (数据共享)](js-apis-data-dataShare.md) - [@ohos.data.dataSharePredicates (数据共享谓词)](js-apis-data-dataSharePredicates.md) - [@ohos.data.dataShareResultSet (数据共享结果集)](js-apis-data-DataShareResultSet.md) - - [@ohos.data.distributedData (分布式数据管理)](js-apis-distributed-data.md) - [@ohos.data.distributedDataObject (分布式数据对象)](js-apis-data-distributedobject.md) + - [@ohos.data.distributedKVStore (分布式键值数据库)](js-apis-distributedKVStore.md) - [@ohos.data.preferences (首选项)](js-apis-data-preferences.md) - [@ohos.data.rdb (关系型数据库)](js-apis-data-rdb.md) - [@ohos.data.ValuesBucket (数据集)](js-apis-data-ValuesBucket.md) @@ -208,8 +208,8 @@ - [@ohos.systemTime (系统时间、时区)](js-apis-system-time.md) - [@ohos.systemTimer(系统定时器)](js-apis-system-timer.md) - [@ohos.wallpaper (壁纸)](js-apis-wallpaper.md) + - [@ohos.web.webview(Web)](js-apis-webview.md) - [Timer (定时器)](js-apis-timer.md) - - 设备管理 - [@ohos.batteryInfo (电量信息)](js-apis-battery-info.md) @@ -270,7 +270,9 @@ - 已停止维护的接口 - [@ohos.bytrace (性能打点)](js-apis-bytrace.md) - [@ohos.data.storage (轻量级存储)](js-apis-data-storage.md) + - [@ohos.data.distributedData (分布式数据管理)](js-apis-distributed-data.md) - [@ohos.prompt (弹窗)](js-apis-prompt.md) + - [@ohos.reminderAgent (后台代理提醒)](js-apis-reminderAgent.md) - [@system.app (应用上下文)](js-apis-system-app.md) - [@system.battery (电量信息)](js-apis-system-battery.md) - [@system.bluetooth (蓝牙)](js-apis-system-bluetooth.md) diff --git a/zh-cn/application-dev/reference/apis/js-apis-distributed-data.md b/zh-cn/application-dev/reference/apis/js-apis-distributed-data.md index bede5e9af5..462caa2391 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-distributed-data.md +++ b/zh-cn/application-dev/reference/apis/js-apis-distributed-data.md @@ -13,7 +13,9 @@ >**说明:** > ->本模块首批接口从API version 7开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。 +>- 从API Version 9开始,该接口不再维护,推荐使用新接口[`@ohos.data.distributedKVStore`](js-apis-distributedKVStore.md)。 +> +>- 本模块首批接口从API version 7开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。 ## 导入模块 @@ -39,56 +41,28 @@ createKVManager(config: KVManagerConfig, callback: AsyncCallback<KVManager> | callback | AsyncCallback<[KVManager](#kvmanager)> | 是 | 回调函数。返回创建的KVManager对象实例。 | **示例:** +```js -Stage模型下的示例: -```ts -import AbilityStage from '@ohos.application.Ability' let kvManager; -export default class MyAbilityStage extends AbilityStage { - onCreate() { - console.log("MyAbilityStage onCreate") - let context = this.context - const kvManagerConfig = { - context: context, - bundleName: 'com.example.datamanagertest', - userInfo: { - userId: '0', - userType: distributedData.UserType.SAME_USER_ID - } +try { + const kvManagerConfig = { + bundleName : 'com.example.datamanagertest', + userInfo : { + userId : '0', + userType : distributedData.UserType.SAME_USER_ID } - distributedData.createKVManager(kvManagerConfig, function (err, manager) { - if (err) { - console.log("Failed to create KVManager: " + JSON.stringify(err)); - return; - } - console.log("Succeeded in creating KVManager"); - kvManager = manager; - }); - } -} -``` - -FA模型下的示例: -```js -import featureAbility from '@ohos.ability.featureAbility' -let kvManager; -let context = featureAbility.getContext() -const kvManagerConfig = { - context: context, - bundleName: 'com.example.datamanagertest', - userInfo: { - userId: '0', - userType: distributedData.UserType.SAME_USER_ID } + distributedData.createKVManager(kvManagerConfig, function (err, manager) { + if (err) { + console.log("Failed to create KVManager: " + JSON.stringify(err)); + return; + } + console.log("Succeeded in creating KVManager"); + kvManager = manager; + }); +} catch (e) { + console.log("An unexpected error occurred. Error:" + e); } -distributedData.createKVManager(kvManagerConfig, function (err, manager) { - if (err) { - console.log("Failed to create KVManager: " + JSON.stringify(err)); - return; - } - console.log("Created KVManager"); - kvManager = manager; -}); ``` ## distributedData.createKVManager @@ -112,52 +86,28 @@ createKVManager(config: KVManagerConfig): Promise<KVManager> | Promise<[KVManager](#kvmanager)> | Promise对象。返回创建的KVManager对象实例。 | **示例:** +```js -Stage模型下的示例: -```ts -import AbilityStage from '@ohos.application.Ability' let kvManager; -export default class MyAbilityStage extends AbilityStage { - onCreate() { - console.log("MyAbilityStage onCreate") - let context = this.context - const kvManagerConfig = { - context: context, - bundleName: 'com.example.datamanagertest', - userInfo: { - userId: '0', - userType: distributedData.UserType.SAME_USER_ID - } +try { + const kvManagerConfig = { + bundleName : 'com.example.datamanagertest', + userInfo : { + userId : '0', + userType : distributedData.UserType.SAME_USER_ID } - distributedData.createKVManager(kvManagerConfig).then((manager) => { - console.log("Succeeded in creating KVManager"); - kvManager = manager; - }).catch((err) => { - console.log("Failed to create KVManager: " + JSON.stringify(err)); - }); - } -} -``` - -FA模型下的示例: -```js -import featureAbility from '@ohos.ability.featureAbility' -let kvManager; -let context = featureAbility.getContext() -const kvManagerConfig = { - context: context, - bundleName: 'com.example.datamanagertest', - userInfo: { - userId: '0', - userType: distributedData.UserType.SAME_USER_ID } + distributedData.createKVManager(kvManagerConfig, function (err, manager) { + if (err) { + console.log("Failed to create KVManager: " + JSON.stringify(err)); + return; + } + console.log("Succeeded in creating KVManager"); + kvManager = manager; + }); +} catch (e) { + console.log("An unexpected error occurred. Error:" + e); } -distributedData.createKVManager(kvManagerConfig).then((manager) => { - console.log("Succeeded in creating KVManager"); - kvManager = manager; -}).catch((err) => { - console.log("Failed to create KVManager: " + JSON.stringify(err)); -}); ``` ## KVManagerConfig @@ -168,7 +118,6 @@ distributedData.createKVManager(kvManagerConfig).then((manager) => { | 参数名 | 参数类型 | 必填 | 说明 | | ----- | ------ | ------ | ------ | -| context9+ | Context | 是 | 应用的上下文。
FA模型的应用Context定义见[Context](js-apis-Context.md)。
Stage模型的应用Context定义见[Context](js-apis-ability-context.md)。| | userInfo | [UserInfo](#userinfo) | 是 | 调用方的用户信息。 | | bundleName | string | 是 | 调用方的包名。 | @@ -2160,7 +2109,6 @@ try { } ``` - ### put put(key: string, value: Uint8Array | string | number | boolean): Promise<void> @@ -2282,303 +2230,6 @@ try { } ``` -### delete9+ - -delete(predicates: dataSharePredicates.DataSharePredicates, callback: AsyncCallback<void>) - -从数据库中删除符合predicates条件的键值对,使用callback异步回调。 - -**系统接口:** 此接口为系统接口。 - -**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core - -**参数:** - -| 参数名 | 参数类型 | 必填 | 说明 | -| ----- | ------ | ---- | ----------------------- | -| predicates | [DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | 是 |指示筛选条件,当此参数为null时,应定义处理逻辑。| -| callback | AsyncCallback<void> | 是 |回调函数。 | - -**示例:** - -```js -import dataSharePredicates from '@ohos.data.dataSharePredicates'; -let kvStore; -try { - let predicates = new dataSharePredicates.DataSharePredicates(); - kvStore.delete(predicates, function (err, data) { - if (err == undefined) { - console.log('delete success'); - } else { - console.log('delete fail' + err); - } - }); -} catch (e) { - console.log('An unexpected error occurred. Error:' + e); -} -``` - -### delete9+ - -delete(predicates: dataSharePredicates.DataSharePredicates): Promise<void> - -从数据库中删除符合predicates条件的键值对,使用Promise异步回调。 - -**系统接口:** 此接口为系统接口。 - -**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core - -**参数:** - -| 参数名 | 参数类型 | 必填 | 说明 | -| ----- | ------ | ---- | ----------------------- | -| predicates | [DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | 是 |指示筛选条件,当此参数为null时,应定义处理逻辑。| - - -**返回值:** - -| 类型 | 说明 | -| ------ | ------- | -| Promise<void> |无返回结果的Promise对象。| - -**示例:** - -```js -import dataSharePredicates from '@ohos.data.dataSharePredicates'; -let kvStore; -try { - let predicates = new dataSharePredicates.DataSharePredicates(); - let arr = ["name"]; - predicates.inKeys(arr); - kvStore.put("name", "bob").then((data) => { - console.log('put success' + JSON.stringify(data)); - kvStore.delete(predicates).then((data) => { - console.log('delete success'); - }).catch((err) => { - console.log('delete fail' + JSON.stringify(err)); - }); - }) .catch((err) => { - console.log(' put fail' + err); - }); -}catch (e) { - console.log("An unexpected error occurred. Error:" + e); -} - -``` - -### backup9+ - -backup(file:string, callback: AsyncCallback<void>):void - -以指定名称备份数据库,使用callback异步回调。 - -**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core - -**参数:** - -| 参数名 | 参数类型 | 必填 | 说明 | -| -------- | ------------------------- | ---- | ------------------------------------------------------------ | -| file | string | 是 | 备份数据库的指定名称,不能为空且长度不大于[MAX_KEY_LENGTH](#constants)。 | -| callback | AsyncCallback<void> | 是 | 回调函数。当以指定名称备份数据库成功,err为undefined,否则为错误对象。 | - -**示例:** - -```js -let kvStore; -let file = "BK001"; -try { - kvStore.backup(file, (err, data) => { - if (err) { - console.info("backup err : " + err); - } else { - console.info("backup data : " + data); - } - }); -} catch (e) { - console.log("An unexpected error occurred. Error : " + e); -} - -``` - -### backup9+ - -backup(file:string): Promise<void> - -以指定名称备份数据库,使用Promise异步回调。 - -**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core - -**参数:** - -| 参数名 | 参数类型 | 必填 | 说明 | -| ------ | -------- | ---- | ------------------------------------------------------------ | -| file | string | 是 | 备份数据库的指定名称,不能为空且长度不大于[MAX_KEY_LENGTH](#constants)。 | - -**返回值:** - -| 类型 | 说明 | -| ------------------- | ------------------------- | -| Promise<void> | 无返回结果的Promise对象。 | - -**示例:** - -```js -let kvStore; -let file = "BK001"; -try { - kvStore.backup(file).then((data) => { - console.info("backup data : " + data); - }).catch((err) => { - console.info("backup err : " + err); - }); -} catch (e) { - console.log("An unexpected error occurred. Error : " + e); -} - -``` - -### restore9+ - -restore(file:string, callback: AsyncCallback<void>):void - -从指定的数据库文件恢复数据库,使用callback异步回调。 - -**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core - -**参数:** - -| 参数名 | 参数类型 | 必填 | 说明 | -| -------- | ------------------------- | ---- | ------------------------------------------------------------ | -| file | string | 是 | 指定的数据库文件名称,不能为空且长度不大于[MAX_KEY_LENGTH](#constants)。 | -| callback | AsyncCallback<void> | 是 | 回调函数。当从指定的数据库文件恢复数据库成功,err为undefined,否则为错误对象。 | - -**示例:** - -```js -let kvStore; -let file = "BK001"; -try { - kvStore.restore(file, (err, data) => { - if (err) { - console.info("restore err : " + err); - } else { - console.info("restore data : " + data); - } - }); -} catch (e) { - console.log("An unexpected error occurred. Error : " + e); -} - -``` - -### restore9+ - -restore(file:string): Promise<void> - -从指定的数据库文件恢复数据库,使用Promise异步回调。 - -**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core - -**参数:** - -| 参数名 | 参数类型 | 必填 | 说明 | -| ------ | -------- | ---- | ------------------------------------------------------------ | -| file | string | 是 | 指定的数据库文件名称,不能为空且长度不大于[MAX_KEY_LENGTH](#constants)。 | - -**返回值:** - -| 类型 | 说明 | -| ------------------- | ------------------------- | -| Promise<void> | 无返回结果的Promise对象。 | - -**示例:** - -```js -let kvStore; -let file = "BK001"; -try { - kvStore.restore(file).then((data) => { - console.info("restore data : " + data); - }).catch((err) => { - console.info("restore err : " + err); - }); -} catch (e) { - console.log("An unexpected error occurred. Error : " + e); -} - -``` - -### deleteBackup9+ - -deleteBackup(files:Array<string>, callback: AsyncCallback<Array<[string, number]>>):void - -根据指定名称删除备份文件,使用callback异步回调。 - -**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core - -**参数:** - -| 参数名 | 参数类型 | 必填 | 说明 | -| -------- | -------------------------------------------------- | ---- | ------------------------------------------------------------ | -| files | Array<string> | 是 | 删除备份文件所指定的名称,不能为空且长度不大于[MAX_KEY_LENGTH](#constants)。 | -| callback | AsyncCallback<Array<[string, number]>> | 是 | 回调函数,返回删除备份的文件名及其处理结果。 | - -**示例:** - -```js -let kvStore; -let files = ["BK001", "BK002"]; -try { - kvStore.deleteBackup(files, (err, data) => { - if (err) { - console.info("deleteBackup err : " + err); - } else { - console.info("deleteBackup data : " + data); - } - }); -} catch (e) { - console.log("An unexpected error occurred. Error : " + e); -} - -``` - -### deleteBackup9+ - -deleteBackup(files:Array<string>): Promise<Array<[string, number]>> - -根据指定名称删除备份文件,使用Promise异步回调。 - -**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core - -**参数:** - -| 参数名 | 参数类型 | 必填 | 说明 | -| ------ | -------- | ---- | ------------------------------------------------------------ | -| files | Array<string> | 是 | 删除备份文件所指定的名称,不能为空且长度不大于[MAX_KEY_LENGTH](#constants)。 | - -**返回值:** - -| 类型 | 说明 | -| -------------------------------------------- | ----------------------------------------------- | -| Promise<Array<[string, number]>> | Promise对象,返回删除备份的文件名及其处理结果。 | - -**示例:** - -```js -let kvStore; -let files = ["BK001", "BK002"]; -try { - kvStore.deleteBackup(files).then((data) => { - console.info("deleteBackup data : " + data); - }).catch((err) => { - console.info("deleteBackup err : " + err); - }) -} catch (e) { - console.log("An unexpected error occurred. Error : " + e); -} - -``` - ### on('dataChange') on(event: 'dataChange', type: SubscribeType, listener: Callback<ChangeNotification>): void @@ -2604,7 +2255,6 @@ kvStore.on('dataChange', distributedData.SubscribeType.SUBSCRIBE_TYPE_LOCAL, fun }); ``` - ### on('syncComplete') on(event: 'syncComplete', syncCallback: Callback<Array<[string, number]>>): void @@ -2665,43 +2315,6 @@ class KvstoreModel { } ``` -### off('syncComplete')9+ - -off(event: 'syncComplete', syncCallback?: Callback<Array<[string, number]>>): void - -取消订阅同步完成事件回调通知,此方法为同步方法。 - -**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core - -**参数:** - -| 参数名 | 参数类型 | 必填 | 说明 | -| ----- | ------ | ---- | ----------------------- | -| event |string | 是 |取消订阅的事件名,固定为'syncComplete',表示同步完成事件。 | -| syncCallback |Callback<Array<[string, number]>> | 否 |用于向调用方发送同步结果的回调。 | - -**示例:** - -```js -let kvStore; -class KvstoreModel { - call(data) { - console.log("syncComplete: " + data); - } - subscribeSyncComplete() { - if (kvStore != null) { - kvStore.on('syncComplete', this.call); - } - } - unsubscribeSyncComplete() { - if (kvStore != null) { - kvStore.off('syncComplete', this.call); - } - } -} -``` - - ### putBatch8+ putBatch(entries: Entry[], callback: AsyncCallback<void>): void @@ -2783,112 +2396,24 @@ try { type : distributedData.ValueType.STRING, value : 'batch_test_string_value' } - } - entries.push(entry); - } - console.log('entries: ' + JSON.stringify(entries)); - kvStore.putBatch(entries).then(async (err) => { - console.log('putBatch success'); - kvStore.getEntries('batch_test_string_key').then((entries) => { - console.log('getEntries success'); - console.log('PutBatch ' + JSON.stringify(entries)); - }).catch((err) => { - console.log('getEntries fail ' + JSON.stringify(err)); - }); - }).catch((err) => { - console.log('putBatch fail ' + JSON.stringify(err)); - }); -}catch(e) { - console.log('PutBatch e ' + JSON.stringify(e)); -} -``` - -### putBatch9+ - -putBatch(value: Array<ValuesBucket>, callback: AsyncCallback<void>): void - -将值写入KvStore数据库,使用callback异步回调。 - -**系统接口:** 此接口为系统接口。 - -**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core - -**参数:** - -| 参数名 | 参数类型 | 必填 | 说明 | -| ----- | ------ | ---- | ----------------------- | -| value |Array<[ValuesBucket](js-apis-data-ValuesBucket.md#valuesbucket)> | 是 |表示要插入的数据。 | -| callback |Asyncallback<void> |是 |回调函数。 | - -**示例:** - -```js -let kvStore; -try { - let v8Arr = []; - let arr = new Uint8Array([4,5,6,7]); - let vb1 = {key : "name_1", value : 32} - let vb2 = {key : "name_2", value : arr}; - let vb3 = {key : "name_3", value : "lisi"}; - - v8Arr.push(vb1); - v8Arr.push(vb2); - v8Arr.push(vb3); - kvStore.putBatch(v8Arr, async function (err,data) { - console.log('putBatch success'); - }).catch((err) => { - console.log('putBatch fail ' + JSON.stringify(err)); - }); -}catch(e) { - console.log('putBatch e ' + JSON.stringify(e)); -} -``` - -### putBatch9+ - -putBatch(value: Array<ValuesBucket>): Promise<void> - -将valuesbucket类型的值写入KvStore数据库,使用Promise异步回调。 - -**系统接口:** 此接口为系统接口。 - -**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core - -**参数:** - -| 参数名 | 参数类型 | 必填 | 说明 | -| ----- | ------ | ---- | ----------------------- | -| value |Array<[ValuesBucket](js-apis-data-ValuesBucket.md#valuesbucket)> | 是 |表示要插入的数据。 | - -**返回值:** - -| 类型 | 说明 | -| ------ | ------- | -| Promise<void> |五返回结果的Promise对象。| - -**示例:** - -```js -let kvStore; -try { - let v8Arr = []; - let arr = new Uint8Array([4,5,6,7]); - let vb1 = {key : "name_1", value : 32} - let vb2 = {key : "name_2", value : arr}; - let vb3 = {key : "name_3", value : "lisi"}; - - v8Arr.push(vb1); - v8Arr.push(vb2); - v8Arr.push(vb3); - kvStore.putBatch(v8Arr).then(async (err) => { + } + entries.push(entry); + } + console.log('entries: ' + JSON.stringify(entries)); + kvStore.putBatch(entries).then(async (err) => { console.log('putBatch success'); + kvStore.getEntries('batch_test_string_key').then((entries) => { + console.log('getEntries success'); + console.log('PutBatch ' + JSON.stringify(entries)); + }).catch((err) => { + console.log('getEntries fail ' + JSON.stringify(err)); + }); }).catch((err) => { console.log('putBatch fail ' + JSON.stringify(err)); }); }catch(e) { console.log('PutBatch e ' + JSON.stringify(e)); } - ``` ### deleteBatch8+ @@ -3924,85 +3449,6 @@ try { } ``` -### getResultSet9+ - -getResultSet(predicates: dataSharePredicates.DataSharePredicates, callback: AsyncCallback<KvStoreResultSet>): void - -获取与指定Predicate对象匹配的KvStoreResultSet对象,使用callback异步回调。 - -**系统接口:** 此接口为系统接口。 - -**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core - -**参数:** - -| 参数名 | 参数类型 | 必填 | 说明 | -| ----- | ------ | ---- | ----------------------- | -| predicates | [DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | 是 |指示筛选条件,当此参数为null时,应定义处理逻辑。 | -| callback |AsyncCallback<[KvStoreResultSet](#kvstoreresultset8)> | 是 |回调函数,获取与指定Predicates对象匹配的KvStoreResultSet对象。 | - -**示例:** - -```js -import dataSharePredicates from '@ohos.data.dataSharePredicates'; -let kvStore; -try { - let resultSet; - let predicates = new dataSharePredicates.DataSharePredicates(); - predicates.prefixKey("batch_test_string_key"); - kvStore.getResultSet(predicates, async function (err, result) { - console.log(' GetResultSet success'); - resultSet = result; - kvStore.closeResultSet(resultSet, function (err, data) { - console.log(' closeResultSet success'); - }) - }); -}catch(e) { - console.log('An unexpected error occurred. Error:' + e); -} -``` -### getResultSet9+ - -getResultSet(predicates: dataSharePredicates.DataSharePredicates): Promise<KvStoreResultSet> - -获取与指定Predicate对象匹配的KvStoreResultSet对象,使用Promise异步回调。 - -**系统接口:** 此接口为系统接口。 - -**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core - -**参数:** - -| 参数名 | 参数类型 | 必填 | 说明 | -| ----- | ------ | ---- | ----------------------- | -| predicates |[DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | 是 |指示筛选条件,当此参数为null时,应定义处理逻辑。 | - -**返回值:** - -| 类型 | 说明 | -| ------ | ------- | -|Promise<[KvStoreResultSet](#kvstoreresultset8)> |无返回结果的Promise对象。| - -**示例:** - -```js -import dataSharePredicates from '@ohos.data.dataSharePredicates'; -let kvStore; -try { - let resultSet; - let predicates = new dataSharePredicates.DataSharePredicates(); - predicates.prefixKey("batch_test_string_key"); - kvStore.getResultSet(predicates) .then((result) => { - console.log(' GetResultSet success'); - resultSet = result; - kvStore.closeResultSet(resultSet, function (err, data) { - console.log(' closeResultSet success'); - }) - }); -}catch(e) { - console.log('An unexpected error occurred. Error:' + e); -} -``` ### closeResultSet8+ closeResultSet(resultSet: KvStoreResultSet, callback: AsyncCallback<void>): void @@ -4338,67 +3784,6 @@ class KvstoreModel { } ``` -### on('dataChange')9+ - -on(event: 'dataChange', type: SubscribeType, listener: Callback<ChangeNotification>): void - -订阅指定类型的数据变更通知,此方法为同步方法。 - -**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core - -**参数:** - -| 参数名 | 参数类型 | 必填 | 说明 | -| ----- | ------ | ---- | ----------------------- | -| event |string | 是 |订阅的事件名,固定为'dataChange',表示数据变更事件。 | -| type |[SubscribeType](#subscribetype) | 是 |表示订阅的类型。 | -| listener |Callback<[ChangeNotification](#changenotification)> | 是 |回调函数。 | - -**示例:** - -```js -let kvStore; -kvStore.on('dataChange', distributedData.SubscribeType.SUBSCRIBE_TYPE_LOCAL, function (data) { - console.log("dataChange callback call data: " + JSON.stringify(data)); -}); - -``` - -### off('dataChange')9+ - -off(event:'dataChange', listener?: Callback<ChangeNotification>): void - -取消订阅数据变更通知,此方法为同步方法。 - -**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core - -**参数:** - -| 参数名 | 参数类型 | 必填 | 说明 | -| ----- | ------ | ---- | ----------------------- | -| event |string | 是 |取消订阅的事件名,固定为'dataChange',表示数据变更事件。 | -| listener |Callback<[ChangeNotification](#changenotification)> |否 |回调函数。 | - -**示例:** - -```js -let kvStore; -class KvstoreModel { - call(data) { - console.log("dataChange: " + data); - } - subscribeDataChange() { - if (kvStore != null) { - kvStore.on('dataChange', distributedData.SubscribeType.SUBSCRIBE_TYPE_REMOTE, this.call); - } - } - unsubscribeDataChange() { - if (kvStore != null) { - kvStore.off('dataChange', this.call); - } - } -} -``` ### sync7+ @@ -4425,48 +3810,6 @@ let kvStore; kvStore.sync('deviceIds', distributedData.SyncMode.PULL_ONLY, 1000); ``` -### sync9+ -sync(deviceIds: string[], query: Query, mode: SyncMode, delayMs?: number): void - -在手动同步方式下,触发数据库同步,此方法为同步方法。关于分布式数据服务的同步方式说明,请见[分布式数据服务概述](../../database/database-mdds-overview.md)。 - -**需要权限**: ohos.permission.DISTRIBUTED_DATASYNC。 - -**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core - -**参数:** - -| 参数名 | 参数类型 | 必填 | 说明 | -| ----- | ------ | ---- | ----------------------- | -| deviceIds |string[] | 是 |同一组网环境下,需要同步的设备的deviceId列表。 | -| mode |[SyncMode](#syncmode) | 是 |同步模式。 | -| query |[Query](#query8) | 是 |表示数据库的查询谓词条件 | -| delayMs |number | 否 |可选参数,允许延时时间,单位:ms(毫秒)。 | - -**示例:** - -```js -let kvStore; -const KEY_TEST_SYNC_ELEMENT = 'key_test_sync'; -const VALUE_TEST_SYNC_ELEMENT = 'value-string-001'; -try { - kvStore.on('syncComplete', function (data) { - console.log('Sync dataChange'); - }); - kvStore.put(KEY_TEST_SYNC_ELEMENT + 'testSync101', VALUE_TEST_SYNC_ELEMENT, function (err,data) { - console.log('Sync put success'); - const devices = ['deviceList']; - const mode = distributedData.SyncMode.PULL_ONLY; - const query = new distributedData.Query(); - query.prefixKey("batch_test"); - query.deviceId('localDeviceId'); - kvStore.sync(devices, query, mode , 1000); - }); -}catch(e) { - console.log('Sync e' + e); -} -``` - ### setSyncParam8+ setSyncParam(defaultAllowedDelayMs: number, callback: AsyncCallback<void>): void @@ -5734,48 +5077,6 @@ try { } ``` -### sync9+ - -sync(deviceIds: string[], query: Query, mode: SyncMode, delayMs?: number): void - -在手动同步方式下, 触发数据库同步,此方法为同步方法。关于分布式数据服务的同步方式说明,请见[分布式数据服务概述](../../database/database-mdds-overview.md)。 - -**需要权限**: ohos.permission.DISTRIBUTED_DATASYNC。 - -**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core - -**参数:** - -| 参数名 | 参数类型 | 必填 | 说明 | -| ----- | ------ | ---- | ----------------------- | -| deviceIds |string[] | 是 |需要同步DeviceKvStore数据库的设备ID列表。 | -| query |[Query](#query8) | 是 | 数据库的查询谓词条件。| -| delayMs |number | 否 |可选参数,允许延时时间,单位:ms(毫秒)。 | - -**示例:** - -```js -let kvStore; -const KEY_TEST_SYNC_ELEMENT = 'key_test_sync'; -const VALUE_TEST_SYNC_ELEMENT = 'value-string-001'; -try { - kvStore.on('syncComplete', function (data) { - console.log('Sync dataChange'); - }); - kvStore.put(KEY_TEST_SYNC_ELEMENT + 'testSync101', VALUE_TEST_SYNC_ELEMENT, function (err,data) { - console.log('Sync put success'); - const devices = ['deviceList']; - const mode = distributedData.SyncMode.PULL_ONLY; - const query = new distributedData.Query(); - query.prefixKey("batch_test"); - query.deviceId('localDeviceId'); - kvStore.sync(devices, query, 1000); - }); -}catch(e) { - console.log('Sync e' + e); -} -``` - ### on('syncComplete')8+ on(event: 'syncComplete', syncCallback: Callback<Array<[string, number]>>): void @@ -5848,68 +5149,6 @@ class KvstoreModel { } ``` -### on('dataChange')9+ - -on(event: 'dataChange', type: SubscribeType, listener: Callback<ChangeNotification>): void - -订阅指定类型的数据变更通知,此方法为同步方法。 - -**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core - -**参数:** - -| 参数名 | 参数类型 | 必填 | 说明 | -| ----- | ------ | ---- | ----------------------- | -| event |string | 是 |订阅的事件名,固定为'dataChange',表示数据变更事件。 | -| type |[SubscribeType](#subscribetype) | 是 |表示订阅的类型。 | -| listener |Callback<[ChangeNotification](#changenotification)> | 是 |回调函数。 | - -**示例:** - -```js -let kvStore; -kvStore.on('dataChange', distributedData.SubscribeType.SUBSCRIBE_TYPE_LOCAL, function (data) { - console.log("dataChange callback call data: " + JSON.stringify(data)); -}); -``` - - -### off('dataChange')9+ - -off(event:'dataChange', listener?: Callback<ChangeNotification>): void - -取消订阅数据变更通知,此方法为同步方法。 - -**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core - -**参数:** - -| 参数名 | 参数类型 | 必填 | 说明 | -| ----- | ------ | ---- | ----------------------- | -| event |string | 是 |取消订阅的事件名,固定为'dataChange',表示数据变更事件。 | -| listener |Callback<[ChangeNotification](#changenotification)> |否 |回调函数。 | - -**示例:** - -```js -let kvStore; -class KvstoreModel { - call(data) { - console.log("dataChange: " + data); - } - subscribeDataChange() { - if (kvStore != null) { - kvStore.on('dataChange', distributedData.SubscribeType.SUBSCRIBE_TYPE_REMOTE, this.call); - } - } - unsubscribeDataChange() { - if (kvStore != null) { - kvStore.off('dataChange', this.call); - } - } -} -``` - ## SyncMode 同步模式枚举。 diff --git a/zh-cn/application-dev/reference/apis/js-apis-distributedKVStore.md b/zh-cn/application-dev/reference/apis/js-apis-distributedKVStore.md new file mode 100644 index 0000000000..03e8ca0df2 --- /dev/null +++ b/zh-cn/application-dev/reference/apis/js-apis-distributedKVStore.md @@ -0,0 +1,5790 @@ +# 分布式键值数据库 + +分布式键值数据库为应用程序提供不同设备间数据库的分布式协同能力。通过调用分布式键值数据库各个接口,应用程序可将数据保存到分布式键值数据库中,并可对分布式键值数据库中的数据进行增加、删除、修改、查询、同步等操作。 + +该模块提供以下分布式键值数据库相关的常用功能: + +- [KVManager](#kvmanager):分布式键值数据库管理实例,用于获取数据库的相关信息。 +- [KVStoreResultSet](#kvstoreresultset):提供获取数据库结果集的相关方法,包括查询和移动数据读取位置等。 +- [Query](#query):使用谓词表示数据库查询,提供创建Query实例、查询数据库中的数据和添加谓词的方法。 +- [SingleKVStore](#singlekvstore):单版本分布式键值数据库,不对数据所属设备进行区分,提供查询数据和同步数据的方法。 +- [DeviceKVStore](#devicekvstore):设备协同数据库,继承自[SingleKVStore](#kvstore),以设备维度对数据进行区分,提供查询数据和同步数据的方法。 + +> **说明:** +> +> 本模块首批接口从API version 9开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。 + +## 导入模块 + +```js +import distributedKVStore from '@ohos.data.distributedKVStore'; +``` + +## KVManagerConfig + +提供KVManager实例的配置信息,包括调用方的包名和应用的上下文。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +| 参数名 | 参数类型 | 必填 | 说明 | +| ---------- | --------------------- | ---- | ------------------------------------------------------------ | +| context | Context | 是 | 应用的上下文。
FA模型的应用Context定义见[Context](js-apis-Context.md)。
Stage模型的应用Context定义见[Context](js-apis-ability-context.md)。 | +| bundleName | string | 是 | 调用方的包名。 | + +## Constants + +分布式键值数据库常量。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +| 名称 | 值 | 说明 | +| --------------------- | ------- | --------------------------------------- | +| MAX_KEY_LENGTH | 1024 | 数据库中Key允许的最大长度,单位字节。 | +| MAX_VALUE_LENGTH | 4194303 | 数据库中Value允许的最大长度,单位字节。 | +| MAX_KEY_LENGTH_DEVICE | 896 | 最大设备密钥长度,单位字节。 | +| MAX_STORE_ID_LENGTH | 128 | 数据库标识符允许的最大长度,单位字节。 | +| MAX_QUERY_LENGTH | 512000 | 最大查询长度,单位字节。 | +| MAX_BATCH_SIZE | 128 | 最大批处理操作数量。 | + +## ValueType + +数据类型枚举。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +| 名称 | 说明 | +| ---------- | ---------------------- | +| STRING | 表示值类型为字符串。 | +| INTEGER | 表示值类型为整数。 | +| FLOAT | 表示值类型为浮点数。 | +| BYTE_ARRAY | 表示值类型为字节数组。 | +| BOOLEAN | 表示值类型为布尔值。 | +| DOUBLE | 表示值类型为双浮点数。 | + +## Value + +存储在数据库中的值对象。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +| 名称 | 参数类型 |可读 |可写 | 说明 | +| ----- | ------- | -----| ------|------------------------ | +| type | [ValueType](#valuetype) | 是 | 是 |值类型。 | +| value | Uint8Array \| string \| number \| boolean| 是 | 是 |值。 | + +## Entry + +存储在数据库中的键值对。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +| 名称 | 参数类型 | 可读 | 可写 | 说明 | +| ----- | --------------- | ---- | ---- | -------- | +| key | string | 是 | 是 | 键值。 | +| value | [Value](#value) | 是 | 是 | 值对象。 | + +## ChangeNotification + +数据变更时通知的对象,包括数据插入的数据、更新的数据、删除的数据和设备ID。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +| 名称 | 参数类型 | 可读 | 可写 | 说明 | +| ------------- | ----------------- | ---- | ---- | ------------------------ | +| insertEntries | [Entry](#entry)[] | 是 | 是 | 数据添加记录。 | +| updateEntries | [Entry](#entry)[] | 是 | 是 | 数据更新记录。 | +| deleteEntries | [Entry](#entry)[] | 是 | 是 | 数据删除记录。 | +| deviceId | string | 是 | 是 | 设备ID,此处为设备UUID。 | + +## SyncMode + +同步模式枚举。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +| 名称 | 说明 | +| --------- | ---------------------------------------------------- | +| PULL_ONLY | 表示只能从远端拉取数据到本端。 | +| PUSH_ONLY | 表示只能从本端推送数据到远端。 | +| PUSH_PULL | 表示从本端推送数据到远端,然后从远端拉取数据到本端。 | + +## SubscribeType + +订阅类型枚举。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +| 名称 | 说明 | +| --------------------- | ---------------------------- | +| SUBSCRIBE_TYPE_LOCAL | 表示订阅本地数据变更。 | +| SUBSCRIBE_TYPE_REMOTE | 表示订阅远端数据变更。 | +| SUBSCRIBE_TYPE_ALL | 表示订阅远端和本地数据变更。 | + +## KVStoreType + +分布式键值数据库类型枚举。 + +| 名称 | 说明 | +| -------------------- | ------------------------------------------------------------ | +| DEVICE_COLLABORATION | 表示多设备协同数据库。
**系统能力:** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore | +| SINGLE_VERSION | 表示单版本数据库。
**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core | + +## SecurityLevel + +数据库的安全级别枚举。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +| 名称 | 说明 | +| -------: | ------------------------------------------------------------ | +| S1 | 表示数据库的安全级别为低级别,当数据泄露时会产生较低影响。例如,包含壁纸等系统数据的数据库。 | +| S2 | 表示数据库的安全级别为中级别,当数据泄露时会产生较大影响。例如,包含录音、视频等用户生成数据或通话记录等信息的数据库。 | +| S3 | 表示数据库的安全级别为高级别,当数据泄露时会产生重大影响。例如,包含用户运动、健康、位置等信息的数据库。 | +| S4 | 表示数据库的安全级别为关键级别,当数据泄露时会产生严重影响。例如,包含认证凭据、财务数据等信息的数据库。 | + +## Options + +用于提供创建数据库的配置信息。 + +| 参数名 | 参数类型 | 必填 | 说明 | +| --------------- | ------------------------------- | ---- | ------------------------------------------------------------ | +| createIfMissing | boolean | 否 | 当数据库文件不存在时是否创建数据库,默认创建。
**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core | +| encrypt | boolean | 否 | 设置数据库文件是否加密,默认不加密。
**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core | +| backup | boolean | 否 | 设置数据库文件是否备份,默认备份。
**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core | +| autoSync | boolean | 否 | 设置数据库文件是否自动同步,默认不自动同步。
**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core
**需要权限**: ohos.permission.DISTRIBUTED_DATASYNC | +| kvStoreType | [KVStoreType](#kvstoretype) | 否 | 设置要创建的数据库类型,默认为多设备协同数据库。
**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core | +| securityLevel | [SecurityLevel](#securitylevel) | 是 | 设置数据库安全级别。
**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core | +| schema | [Schema](#schema) | 否 | 设置定义存储在数据库中的值,默认不适用Schema。
**系统能力:** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore | + +## Schema + +表示数据库模式,可以在创建或打开数据库时创建Schema对象并将它们放入[Options](#options)中。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore + +| 名称 | 类型 | 说明 | +| ------- | ----------------------- | -------------------------- | +| root | [FieldNode](#fieldnode) | 表示json根对象。 | +| indexes | Array\ | 表示json类型的字符串数组。 | +| mode | number | 表示Schema的模式。 | +| skip | number | Schema的跳跃大小。 | + +### constructor + +constructor() + +用于创建Schema实例的构造函数。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore + +## FieldNode + +表示 Schema 实例的节点,提供定义存储在数据库中的值的方法。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore + +| 名称 | 类型 | 说明 | +| -------- | ------- | ------------------------------ | +| nullable | boolean | 表示数据库字段是否可以为空。 | +| default | string | 表示Fieldnode的默认值。 | +| type | number | 表示指定节点对应数据类型的值。 | + +### constructor + +constructor(name: string) + +用于创建带有string字段FieldNode实例的构造函数。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| ------ | -------- | ---- | --------------- | +| name | string | 是 | FieldNode的值。 | + +### appendChild + +appendChild(child: FieldNode): boolean + +在当前 FieldNode 中添加一个子节点。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| ------ | ----------------------- | ---- | ---------------- | +| child | [FieldNode](#fieldnode) | 是 | 要附加的域节点。 | + +**返回值:** + +| 类型 | 说明 | +| ------- | ------------------------------------------------------------ | +| boolean | 返回true表示子节点成功添加到FieldNode;返回false则表示操作失败。 | + +**示例:** + +```js +import ddm from '@ohos.data.distributedKVStore'; + +try { + let node = new ddm.FieldNode("root"); + let child1 = new ddm.FieldNode("child1"); + let child2 = new ddm.FieldNode("child2"); + let child3 = new ddm.FieldNode("child3"); + node.appendChild(child1); + node.appendChild(child2); + node.appendChild(child3); + console.log("appendNode " + JSON.stringify(node)); + child1 = null; + child2 = null; + child3 = null; + node = null; +} catch (e) { + console.log("AppendChild " + e); +} +``` + +## distributedKVStore.createKVManager + +createKVManager(config: KVManagerConfig, callback: AsyncCallback<KVManager>): void + +创建一个KVManager对象实例,用于管理数据库对象,使用callback异步回调。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| -------- | -------------------------------------------- | ---- | ----------------------------------------------------------- | +| config | [KVManagerConfig](#kvmanagerconfig) | 是 | 提供KVManager实例的配置信息,包括调用方的包名和应用上下文。 | +| callback | AsyncCallback<[KVManager](#kvmanager)> | 是 | 回调函数。返回创建的KVManager对象实例。 | + +**示例:** + +Stage模型下的示例: + +```js +import AbilityStage from '@ohos.application.Ability' +let kvManager; +export default class MyAbilityStage extends AbilityStage { + onCreate() { + console.log("MyAbilityStage onCreate") + let context = this.context + const kvManagerConfig = { + context: context, + bundleName: 'com.example.datamanagertest', + } + try { + distributedKVStore.createKVManager(kvManagerConfig, function (err, manager) { + if (err) { + console.error(`Failed to create KVManager.code is ${err.code},message is ${err.message}`); + return; + } + console.log("Succeeded in creating KVManager"); + kvManager = manager; + }); + } catch (e) { + console.error(`Failed to create KVManager.code is ${e.code},message is ${e.message}`); + } + } +} +``` + +FA模型下的示例: + +```js +import featureAbility from '@ohos.ability.featureAbility' +let kvManager; +let context = featureAbility.getContext() +const kvManagerConfig = { + context: context, + bundleName: 'com.example.datamanagertest', +} +try { + distributedKVStore.createKVManager(kvManagerConfig, function (err, manager) { + if (err) { + console.error(`Failed to create KVManager.code is ${err.code},message is ${err.message}`); + return; + } + console.log("Succeeded in creating KVManager"); + kvManager = manager; + }); +} catch (e) { + console.error(`Failed to create KVManager.code is ${e.code},message is ${e.message}`); +} +``` + +## distributedKVStore.createKVManager + +createKVManager(config: KVManagerConfig): Promise<KVManager> + +创建一个KVManager对象实例,用于管理数据库对象,使用Promise异步回调。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| ------ | ----------------------------- | ---- | --------------------------------------------------------- | +| config | [KVManagerConfig](#kvmanager) | 是 | 提供KVManager实例的配置信息,包括调用方的包名和用户信息。 | + +**返回值:** + +| 类型 | 说明 | +| -------------------------------------- | ------------------------------------------ | +| Promise<[KVManager](#kvmanager)> | Promise对象。返回创建的KVManager对象实例。 | + +**示例:** + +Stage模型下的示例: + +```js +import AbilityStage from '@ohos.application.Ability' +let kvManager; +export default class MyAbilityStage extends AbilityStage { + onCreate() { + console.log("MyAbilityStage onCreate") + let context = this.context + const kvManagerConfig = { + context: context, + bundleName: 'com.example.datamanagertest', + } + try { + distributedKVStore.createKVManager(kvManagerConfig).then((manager) => { + console.log("Succeeded in creating KVManager"); + kvManager = manager; + }).catch((err) => { + console.error(`Failed to create KVManager.code is ${err.code},message is ${err.message}`); + }); + } catch (e) { + console.error(`Failed to create KVManager.code is ${e.code},message is ${e.message}`); + } + } +} +``` + +FA模型下的示例: + +```js +import featureAbility from '@ohos.ability.featureAbility' +let kvManager; +let context = featureAbility.getContext() +const kvManagerConfig = { + context: context, + bundleName: 'com.example.datamanagertest', +} +try { + distributedKVStore.createKVManager(kvManagerConfig).then((manager) => { + console.log("Succeeded in creating KVManager"); + kvManager = manager; + }).catch((err) => { + console.error(`Failed to create KVManager.code is ${err.code},message is ${err.message}`); + }); +} catch (e) { + console.error(`Failed to create KVManager.code is ${e.code},message is ${e.message}`); +} +``` + +## KVManager + +分布式键值数据库管理实例,用于获取分布式键值数据库的相关信息。在调用KVManager的方法前,需要先通过[createKVManager](#distributedkvstorecreatekvmanager)构建一个KVManager实例。 + +### getKVStore + +getKVStore<T >(storeId: string, options: Options, callback: AsyncCallback<T>): void + +通过指定Options和storeId,创建并获取分布式键值数据库,使用callback异步回调。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| -------- | ---------------------- | ---- | ------------------------------------------------------------ | +| storeId | string | 是 | 数据库唯一标识符,长度不大于[MAX_STORE_ID_LENGTH](#constants)。 | +| options | [Options](#options) | 是 | 创建分布式键值实例的配置信息。 | +| callback | AsyncCallback<T> | 是 | 回调函数。返回创建的分布式键值数据库实例(根据kvStoreType的不同,可以创建SingleKVStore实例和DeviceKVStore实例)。 | + +**错误码:** + +以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 + +| **错误码ID** | **错误信息** | +| ------------ | ------------------------------------------- | +| 15100002 | Open existed database with changed options. | +| 15100003 | Database corrupted. | + +**示例:** + +```js +let kvStore; +let kvManager; +try { + const options = { + createIfMissing: true, + encrypt: false, + backup: false, + autoSync: true, + kvStoreType: distributedKVStore.KVStoreType.SINGLE_VERSION, + securityLevel: distributedKVStore.SecurityLevel.S2, + }; + kvManager.getKVStore('storeId', options, function (err, store) { + if (err) { + console.error(`Fail to get KVStore.code is ${err.code},message is ${err.message}`); + return; + } + console.log("Succeeded in getting KVStore"); + kvStore = store; + }); +} catch (e) { + console.log(`An unexpected error occurred.code is ${e.code},message is ${e.message}`); +} +``` + +### getKVStore + +getKVStore<T >(storeId: string, options: Options): Promise<T> + +通过指定Options和storeId,创建并获取分布式键值数据库,使用Promise异步回调。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| ------- | ------------------- | ---- | ------------------------------------------------------------ | +| storeId | string | 是 | 数据库唯一标识符,长度不大于[MAX_STORE_ID_LENGTH](#constants)。 | +| options | [Options](#options) | 是 | 创建分布式键值实例的配置信息。 | + +**返回值:** + +| 类型 | 说明 | +| ---------------- | ------------------------------------------------------------ | +| Promise<T> | Promise对象。返回创建的分布式键值数据库实例(根据kvStoreType的不同,可以创建SingleKVStore实例和DeviceKVStore实例。 | + +**错误码:** + +以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 + +| **错误码ID** | **错误信息** | +| ------------ | ------------------------------------------- | +| 15100002 | Open existed database with changed options. | +| 15100003 | Database corrupted. | + +**示例:** + +```js +let kvStore; +let kvManager; +try { + const options = { + createIfMissing: true, + encrypt: false, + backup: false, + autoSync: true, + kvStoreType: distributedKVStore.KVStoreType.SINGLE_VERSION, + securityLevel: distributedKVStore.SecurityLevel.S2, + }; + kvManager.getKVStore('storeId', options).then((store) => { + console.log("Succeeded in getting KVStore"); + kvStore = store; + }).catch((err) => { + console.error(`Fail to get KVStore.code is ${err.code},message is ${err.message}`); + }); +} catch (e) { + console.log(`An unexpected error occurred.code is ${e.code},message is ${e.message}`); +} +``` + +### closeKVStore + +closeKVStore(appId: string, storeId: string, callback: AsyncCallback<void>): void + +通过storeId的值关闭指定的分布式键值数据库,使用callback异步回调。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| -------- | ------------------------- | ---- | ------------------------------------------------------------ | +| appId | string | 是 | 所调用数据库方的包名。 | +| storeId | string | 是 | 要关闭的数据库唯一标识符,长度不大于[MAX_STORE_ID_LENGTH](#constants)。 | +| callback | AsyncCallback<void> | 是 | 回调函数。 | + +**示例:** + +```js +let kvStore; +let kvManager; +const options = { + createIfMissing: true, + encrypt: false, + backup: false, + autoSync: true, + kvStoreType: distributedKVStore.KVStoreType.SINGLE_VERSION, + schema: '', + securityLevel: distributedKVStore.SecurityLevel.S2, +} +try { + kvManager.getKVStore('storeId', options, async function (err, store) { + console.log('Succeeded in getting KVStore'); + kvStore = store; + kvManager.closeKVStore('appId', 'storeId', function (err, data) { + if (err != undefined) { + console.error(`Fail to close KVStore.code is ${err.code},message is ${err.message}`); + return; + } + console.log('Succeeded in closing KVStore'); + }); + }); +} catch (e) { + console.error(`An unexpected error occurred.code is ${err.code},message is ${err.message}`); +} +``` + +### closeKVStore + +closeKVStore(appId: string, storeId: string): Promise<void> + +通过storeId的值关闭指定的分布式键值数据库,使用Promise异步回调。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| ------- | -------- | ---- | ------------------------------------------------------------ | +| appId | string | 是 | 所调用数据库方的包名。 | +| storeId | string | 是 | 要关闭的数据库唯一标识符,长度不大于[MAX_STORE_ID_LENGTH](#constants)。 | + +**返回值:** + +| 类型 | 说明 | +| -------------- | ------------------------- | +| Promise\ | 无返回结果的Promise对象。 | + +**示例:** + +```js +let kvManager; +let kvStore; +const options = { + createIfMissing: true, + encrypt: false, + backup: false, + autoSync: true, + kvStoreType: distributedKVStore.KVStoreType.SINGLE_VERSION, + schema: '', + securityLevel: distributedKVStore.SecurityLevel.S2, +} +try { + kvManager.getKVStore('storeId', options).then(async (store) => { + console.log('Succeeded in getting KVStore'); + kvStore = store; + kvManager.closeKVStore('appId', 'storeId').then(() => { + console.log('Succeeded in closing KVStore'); + }).catch((err) => { + console.error(`Fail to close KVStore.code is ${err.code},message is ${err.message}`); + }); + }).catch((err) => { + console.error(`Fail to get KVStore.code is ${err.code},message is ${err.message}`); + }); +} catch (e) { + console.error(`Fail to close KVStore.code is ${e.code},message is ${e.message}`); +} +``` + +### deleteKVStore + +deleteKVStore(appId: string, storeId: string, callback: AsyncCallback<void>): void + +通过storeId的值删除指定的分布式键值数据库,使用callback异步回调。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| -------- | ------------------------- | ---- | ------------------------------------------------------------ | +| appId | string | 是 | 所调用数据库方的包名。 | +| storeId | string | 是 | 要删除的数据库唯一标识符,长度不大于[MAX_STORE_ID_LENGTH](#constants)。 | +| callback | AsyncCallback<void> | 是 | 回调函数。 | + +**错误码:** + +以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 + +| **错误码ID** | **错误信息** | +| ------------ | ------------ | +| 15100004 | Not found. | + +**示例:** + +```js +let kvManager; +let kvStore; +const options = { + createIfMissing: true, + encrypt: false, + backup: false, + autoSync: true, + kvStoreType: distributedKVStore.KVStoreType.SINGLE_VERSION, + schema: '', + securityLevel: distributedKVStore.SecurityLevel.S2, +} +try { + kvManager.getKVStore('store', options, async function (err, store) { + if (err != undefined) { + console.error(`Fail to get KVStore.code is ${err.code},message is ${err.message}`); + return; + } + console.log('Succeeded in getting KVStore'); + kvStore = store; + kvManager.deleteKVStore('appId', 'storeId', function (err, data) { + if (err != undefined) { + console.error(`Fail to delete KVStore.code is ${err.code},message is ${err.message}`); + return; + } + console.log(`Succeeded in deleting KVStore`); + }); + }); +} catch (e) { + console.error(`Fail to delete KVStore.code is ${e.code},message is ${e.message}`); +} +``` + +### deleteKVStore + +deleteKVStore(appId: string, storeId: string): Promise<void> + +通过storeId的值删除指定的分布式键值数据库,使用Promise异步回调。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| ------- | -------- | ---- | ------------------------------------------------------------ | +| appId | string | 是 | 所调用数据库方的包名。 | +| storeId | string | 是 | 要删除的数据库唯一标识符,长度不大于[MAX_STORE_ID_LENGTH](#constants)。 | + +**返回值:** + +| 类型 | 说明 | +| ------------------- | ------------------------- | +| Promise<void> | 无返回结果的Promise对象。 | + +**错误码:** + +以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 + +| **错误码ID** | **错误信息** | +| ------------ | ------------ | +| 15100004 | Not found. | + +**示例:** + +```js +let kvManager; +let kvStore; +const options = { + createIfMissing: true, + encrypt: false, + backup: false, + autoSync: true, + kvStoreType: distributedKVStore.KVStoreType.SINGLE_VERSION, + schema: '', + securityLevel: distributedKVStore.SecurityLevel.S2, +} +try { + kvManager.getKVStore('storeId', options).then(async (store) => { + console.log('Succeeded in getting KVStore'); + kvStore = store; + kvManager.deleteKVStore('appId', 'storeId').then(() => { + console.log('Succeeded in deleting KVStore'); + }).catch((err) => { + console.error(`Fail to delete KVStore.code is ${err.code},message is ${err.message}`); + }); + }).catch((err) => { + console.error(`Fail to get KVStore.code is ${err.code},message is ${err.message}`); + }); +} catch (e) { + console.error(`Fail to delete KVStore.code is ${e.code},message is ${e.message}`); +} +``` + +### getAllKVStoreId + +getAllKVStoreId(appId: string, callback: AsyncCallback<string[]>): void + +获取所有通过[getKVStore](#getkvstore)方法创建的且没有调用[deleteKVStore](#deletekvstore)方法删除的分布式键值数据库的storeId,使用callback异步回调。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| -------- | ----------------------------- | ---- | --------------------------------------------------- | +| appId | string | 是 | 所调用数据库方的包名。 | +| callback | AsyncCallback<string[]> | 是 | 回调函数。返回所有创建的分布式键值数据库的storeId。 | + +**示例:** + +```js +let kvManager; +try { + kvManager.getAllKVStoreId('appId', function (err, data) { + if (err != undefined) { + console.error(`Fail to get AllKVStoreId.code is ${e.code},message is ${e.message}`); + return; + } + console.log('Succeeded in getting AllKVStoreId'); + console.log(`GetAllKVStoreId size = ${data.length}`); + }); +} catch (e) { + console.error(`Fail to get AllKVStoreId.code is ${e.code},message is ${e.message}`); +} +``` + +### getAllKVStoreId + +getAllKVStoreId(appId: string): Promise<string[]> + +获取所有通过[getKVStore](#getkvstore)方法创建的且没有调用[deleteKVStore](#deletekvstore)方法删除的分布式键值数据库的storeId,使用Promise异步回调。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| ------ | -------- | ---- | ---------------------- | +| appId | string | 是 | 所调用数据库方的包名。 | + +**返回值:** + +| 类型 | 说明 | +| ----------------------- | ------------------------------------------------------ | +| Promise<string[]> | Promise对象。返回所有创建的分布式键值数据库的storeId。 | + +**示例:** + +```js +let kvManager; +try { + console.log('GetAllKVStoreId'); + kvManager.getAllKVStoreId('appId').then((data) => { + console.log('Succeeded in getting AllKVStoreId'); + console.log(`GetAllKVStoreId size = ${data.length}`); + }).catch((err) => { + console.error(`Fail to get AllKVStoreId.code is ${err.code},message is ${err.message}`); + }); +} catch (e) { + console.error(`Fail to get AllKVStoreId.code is ${e.code},message is ${e.message}`); +} +``` + +### on('distributedDataServiceDie') + +on(event: 'distributedDataServiceDie', deathCallback: Callback<void>): void + +订阅服务状态变更通知,此方法为同步方法。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| ------------- | -------------------- | ---- | ------------------------------------------------------------ | +| event | string | 是 | 订阅的事件名,固定为'distributedDataServiceDie',即服务状态变更事件。 | +| deathCallback | Callback<void> | 是 | 回调函数。 | + +**示例:** + +```js +let kvManager; +try { + console.log('KVManagerOn'); + const deathCallback = function () { + console.log('death callback call'); + } + kvManager.on('distributedDataServiceDie', deathCallback); +} catch (e) { + console.log(`An unexpected error occurred.code is ${e.code},message is ${e.message}`); +} +``` + +### off('distributedDataServiceDie') + +off(event: 'distributedDataServiceDie', deathCallback?: Callback<void>): void + +取消订阅服务状态变更通知,此方法为同步方法。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| ------------- | -------------------- | ---- | ------------------------------------------------------------ | +| event | string | 是 | 取消订阅的事件名,固定为'distributedDataServiceDie',即服务状态变更事件。 | +| deathCallback | Callback<void> | 否 | 回调函数。 | + +**示例:** + +```js +let kvManager; +try { + console.log('KVManagerOff'); + const deathCallback = function () { + console.log('death callback call'); + } + kvManager.off('distributedDataServiceDie', deathCallback); +} catch (e) { + console.log(`An unexpected error occurred.code is ${e.code},message is ${e.message}`); +} +``` + +## KVStoreResultSet + +提供获取数据库结果集的相关方法,包括查询和移动数据读取位置等。 + +在调用KVStoreResultSet的方法前,需要先通过[getKVStore](#getkvstore)构建一个KvStore(SingleKVStore或者DeviceKVStore)实例。 + +### getCount + +getCount(): number + +获取结果集中的总行数。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**返回值:** + +| 类型 | 说明 | +| ------ | ------------------ | +| number | 返回数据的总行数。 | + +**示例:** + +```js +let kvStore; +try { + let resultSet; + kvStore.getResultSet('batch_test_string_key').then((result) => { + console.log('getResultSet succeed.'); + resultSet = result; + }).catch((err) => { + console.log('getResultSet failed: ' + err); + }); + const count = resultSet.getCount(); + console.log("getCount succeed:" + count); +} catch (e) { + console.log("getCount failed: " + e); +} +``` + +### getPosition + +getPosition(): number + +获取结果集中当前的读取位置。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**返回值:** + +| 类型 | 说明 | +| ------ | ------------------ | +| number | 返回当前读取位置。 | + +**示例:** + +```js +let kvStore; +try { + let resultSet; + kvStore.getResultSet('batch_test_string_key').then((result) => { + console.log('getResultSet succeeded.'); + resultSet = result; + }).catch((err) => { + console.log('getResultSet failed: ' + err); + }); + const position = resultSet.getPosition(); + console.log("getPosition succeed:" + position); +} catch (e) { + console.log("getPosition failed: " + e); +} +``` + +### moveToFirst + +moveToFirst(): boolean + +将读取位置移动到第一行。如果结果集为空,则返回false。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**返回值:** + +| 类型 | 说明 | +| ------- | ----------------------------------------------- | +| boolean | 返回true表示操作成功;返回false则表示操作失败。 | + +**示例:** + +```js +let kvStore; +try { + let resultSet; + kvStore.getResultSet('batch_test_string_key').then((result) => { + console.log('getResultSet succeed.'); + resultSet = result; + }).catch((err) => { + console.log('getResultSet failed: ' + err); + }); + const moved1 = resultSet.moveToFirst(); + console.log("moveToFirst succeed: " + moved1); +} catch (e) { + console.log("moveToFirst failed " + e); +} +``` + +### moveToLast + +moveToLast(): boolean + +将读取位置移动到最后一行。如果结果集为空,则返回false。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**返回值:** + +| 类型 | 说明 | +| ------- | ----------------------------------------------- | +| boolean | 返回true表示操作成功;返回false则表示操作失败。 | + +**示例:** + +```js +let kvStore; +try { + let resultSet; + kvStore.getResultSet('batch_test_string_key').then((result) => { + console.log('getResultSet succeed.'); + resultSet = result; + }).catch((err) => { + console.log('getResultSet failed: ' + err); + }); + const moved2 = resultSet.moveToLast(); + console.log("moveToLast succeed:" + moved2); +} catch (e) { + console.log("moveToLast failed: " + e); +} +``` + +### moveToNext + +moveToNext(): boolean + +将读取位置移动到下一行。如果结果集为空,则返回false。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**返回值:** + +| 类型 | 说明 | +| ------- | ----------------------------------------------- | +| boolean | 返回true表示操作成功;返回false则表示操作失败。 | + +**示例:** + +```js +let kvStore; +try { + let resultSet; + kvStore.getResultSet('batch_test_string_key').then((result) => { + console.log('getResultSet succeed.'); + resultSet = result; + }).catch((err) => { + console.log('getResultSet failed: ' + err); + }); + const moved3 = resultSet.moveToNext(); + console.log("moveToNext succeed: " + moved3); +} catch (e) { + console.log("moveToNext failed: " + e); +} +``` + +### moveToPrevious + +moveToPrevious(): boolean + +将读取位置移动到上一行。如果结果集为空,则返回false。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**返回值:** + +| 类型 | 说明 | +| ------- | ----------------------------------------------- | +| boolean | 返回true表示操作成功;返回false则表示操作失败。 | + +**示例:** + +```js +let kvStore; +try { + let resultSet; + kvStore.getResultSet('batch_test_string_key').then((result) => { + console.log('getResultSet succeed.'); + resultSet = result; + }).catch((err) => { + console.log('getResultSet failed: ' + err); + }); + const moved4 = resultSet.moveToPrevious(); + console.log("moveToPrevious succeed:" + moved4); +} catch (e) { + console.log("moveToPrevious failed: " + e); +} +``` + +### move + +move(offset: number): boolean + +将读取位置移动到当前位置的相对偏移量。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| ------ | -------- | ---- | ------------------------------------------------------------ | +| offset | number | 是 | 表示与当前位置的相对偏移量,负偏移表示向后移动,正偏移表示向前移动。 | + +**返回值:** + +| 类型 | 说明 | +| ------- | ----------------------------------------------- | +| boolean | 返回true表示操作成功;返回false则表示操作失败。 | + +**示例:** + +```js +let kvStore; +try { + let resultSet; + kvStore.getResultSet('batch_test_string_key').then((result) => { + console.log('Succeeded in getting resultSet'); + resultSet = result; + }).catch((err) => { + console.error(`Fail to get resultSet.code is ${err.code},message is ${err.message}`); + }); + const moved5 = resultSet.move(1); + console.log(`Succeeded in moving.moved5 = ${moved5}`); +} catch (e) { + console.log(`Fail to move.code is ${e.code},message is ${e.message}`); +} +``` + +### moveToPosition + +moveToPosition(position: number): boolean + +将读取位置从 0 移动到绝对位置。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| -------- | -------- | ---- | -------------- | +| position | number | 是 | 表示绝对位置。 | + +**返回值:** + +| 类型 | 说明 | +| ------- | ----------------------------------------------- | +| boolean | 返回true表示操作成功;返回false则表示操作失败。 | + +**示例** + +```js +let kvStore; +try { + let resultSet; + kvStore.getResultSet('batch_test_string_key').then((result) => { + console.log('Succeeded in getting resultSet'); + resultSet = result; + }).catch((err) => { + console.error(`Fail to get resultSet.code is ${err.code},message is ${err.message}`); + }); + const moved6 = resultSet.moveToPosition(1); + console.log(`Succeeded in moving to position.moved6=${moved6}`); +} catch (e) { + console.error(`Fail to move to position.code is ${e.code},message is ${e.message}`); +} +``` + +### isFirst + +isFirst(): boolean + +检查读取位置是否为第一行。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**返回值:** + +| 类型 | 说明 | +| ------- | ------------------------------------------------------------ | +| boolean | 返回true表示读取位置为第一行;返回false表示读取位置不是第一行。 | + +**示例:** + +```js +let kvStore; +try { + let resultSet; + kvStore.getResultSet('batch_test_string_key').then((result) => { + console.log('getResultSet succeed.'); + resultSet = result; + }).catch((err) => { + console.log('getResultSet failed: ' + err); + }); + const isfirst = resultSet.isFirst(); + console.log("Check isFirst succeed:" + isfirst); +} catch (e) { + console.log("Check isFirst failed: " + e); +} +``` + +### isLast + +isLast(): boolean + +检查读取位置是否为最后一行。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**返回值:** + +| 类型 | 说明 | +| ------- | ------------------------------------------------------------ | +| boolean | 返回true表示读取位置为最后一行;返回false表示读取位置不是最后一行。 | + +**示例:** + +```js +let kvStore; +try { + let resultSet; + kvStore.getResultSet('batch_test_string_key').then((result) => { + console.log('getResultSet succeed.'); + resultSet = result; + }).catch((err) => { + console.log('getResultSet failed: ' + err); + }); + const islast = resultSet.isLast(); + console.log("Check isLast succeed: " + islast); +} catch (e) { + console.log("Check isLast failed: " + e); +} +``` + +### isBeforeFirst + +isBeforeFirst(): boolean + +检查读取位置是否在第一行之前。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**返回值:** + +| 类型 | 说明 | +| ------- | ------------------------------------------------------------ | +| boolean | 返回true表示读取位置在第一行之前;返回false表示读取位置不在第一行之前。 | + +**示例:** + +```js +let kvStore; +try { + let resultSet; + kvStore.getResultSet('batch_test_string_key').then((result) => { + console.log('getResultSet succeed.'); + resultSet = result; + }).catch((err) => { + console.log('getResultSet failed: ' + err); + }); + const isbeforefirst = resultSet.isBeforeFirst(); + console.log("Check isBeforeFirst succeed: " + isbeforefirst); +} catch (e) { + console.log("Check isBeforeFirst failed: " + e); +} +``` + +### isAfterLast + +isAfterLast(): boolean + +检查读取位置是否在最后一行之后。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**返回值:** + +| 类型 | 说明 | +| ------- | ------------------------------------------------------------ | +| boolean | 返回true表示读取位置在最后一行之后;返回false表示读取位置不在最后一行之后。 | + +**示例:** + +```js +let kvStore; +try { + let resultSet; + kvStore.getResultSet('batch_test_string_key').then((result) => { + console.log('getResultSet succeed.'); + resultSet = result; + }).catch((err) => { + console.log('getResultSet failed: ' + err); + }); + const isafterlast = resultSet.isAfterLast(); + console.log("Check isAfterLast succeed:" + isafterlast); +} catch (e) { + console.log("Check isAfterLast failed: " + e); +} +``` + +### getEntry + +getEntry(): Entry + +从当前位置获取对应的键值对。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**返回值:** + +| 类型 | 说明 | +| --------------- | ------------ | +| [Entry](#entry) | 返回键值对。 | + +**示例:** + +```js +let kvStore; +try { + let resultSet; + kvStore.getResultSet('batch_test_string_key').then((result) => { + console.log('getResultSet succeed.'); + resultSet = result; + }).catch((err) => { + console.log('getResultSet failed: ' + err); + }); + const entry = resultSet.getEntry(); + console.log("getEntry succeed:" + JSON.stringify(entry)); +} catch (e) { + console.log("getEntry failed: " + e); +} +``` + +## Query + +使用谓词表示数据库查询,提供创建Query实例、查询数据库中的数据和添加谓词的方法。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +### constructor + +constructor() + +用于创建Schema实例的构造函数。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +### reset + +reset(): Query + +重置Query对象。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**返回值:** + +| 类型 | 说明 | +| -------------- | --------------------- | +| [Query](query) | 返回重置的Query对象。 | + +**示例:** + +```js +try { + let query = new distributedKVStore.Query(); + query.equalTo("key", "value"); + console.log("query is " + query.getSqlLike()); + query.reset(); + console.log("query is " + query.getSqlLike()); + query = null; +} catch (e) { + console.log("simply calls should be ok :" + e); +} +``` + +### equalTo + +equalTo(field: string, value: number|string|boolean): Query + +构造一个Query对象来查询具有指定字段的条目,其值等于指定的值。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| ----- | ------ | ---- | ----------------------- | +| fieId | string | 是 |表示指定字段,不能包含' ^ '。 | +| value | number\|string\|boolean | 是 | 表示指定的值。| + +**返回值:** + +| 类型 | 说明 | +| -------------- | --------------- | +| [Query](query) | 返回Query对象。 | + +**示例:** + +```js +try { + let query = new distributedKVStore.Query(); + query.equalTo("field", "value"); + console.log(`query is ${query.getSqlLike()}`); + query = null; +} catch (e) { + console.error(`duplicated calls should be ok.ode is ${e.code},message is ${e.message}`); +} +``` + +### notEqualTo + +notEqualTo(field: string, value: number|string|boolean): Query + +构造一个Query对象以查询具有指定字段且值不等于指定值的条目。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| ----- | ------ | ---- | ----------------------- | +| fieId | string | 是 |表示指定字段,不能包含' ^ '。 | +| value | number\|string\|boolean | 是 | 表示指定的值。| + +**返回值:** + +| 类型 | 说明 | +| -------------- | --------------- | +| [Query](query) | 返回Query对象。 | + +**示例:** + +```js +try { + let query = new distributedKVStore.Query(); + query.notEqualTo("field", "value"); + console.log(`query is ${query.getSqlLike()}`); + query = null; +} catch (e) { + console.error(`duplicated calls should be ok.code is ${e.code},message is ${e.message}`); +} +``` + +### greaterThan + +greaterThan(field: string, value: number|string|boolean): Query + +构造一个Query对象以查询具有大于指定值的指定字段的条目。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**参数:** +| 参数名 | 参数类型 | 必填 | 说明 | +| ----- | ------ | ---- | ----------------------- | +| fieId | string | 是 |表示指定字段,不能包含' ^ '。 | +| value | number\|string\|boolean | 是 | 表示指定的值。| + +**返回值:** + +| 类型 | 说明 | +| -------------- | --------------- | +| [Query](query) | 返回Query对象。 | + +**示例:** + +```js +try { + let query = new distributedKVStore.Query(); + query.greaterThan("field", "value"); + console.log(`query is ${query.getSqlLike()}`); + query = null; +} catch (e) { + console.error(`duplicated calls should be ok.code is ${e.code},message is ${e.message}`); +} +``` + +### lessThan + +lessThan(field: string, value: number|string): Query + +构造一个Query对象以查询具有小于指定值的指定字段的条目。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**参数:** + + +| 参数名 | 参数类型 | 必填 | 说明 | +| ----- | ------ | ---- | ----------------------- | +| fieId | string | 是 |表示指定字段,不能包含' ^ '。 | +| value | number\|string | 是 | 表示指定的值。| + +**返回值:** + +| 类型 | 说明 | +| -------------- | --------------- | +| [Query](query) | 返回Query对象。 | + +**示例:** + +```js +try { + let query = new distributedKVStore.Query(); + query.lessThan("field", "value"); + console.log(`query is ${query.getSqlLike()}`); + query = null; +} catch (e) { + console.error(`duplicated calls should be ok.code is ${e.code},message is ${e.message}`); +} +``` + +### greaterThanOrEqualTo + +greaterThanOrEqualTo(field: string, value: number|string): Query + +构造一个Query对象以查询具有指定字段且值大于或等于指定值的条目。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**参数:** + + +| 参数名 | 参数类型 | 必填 | 说明 | +| ----- | ------ | ---- | ----------------------- | +| fieId | string | 是 |表示指定字段,不能包含' ^ '。 | +| value | number\|string | 是 | 表示指定的值。| + +**返回值:** + +| 类型 | 说明 | +| -------------- | --------------- | +| [Query](query) | 返回Query对象。 | + +**示例:** + +```js +try { + let query = new distributedKVStore.Query(); + query.greaterThanOrEqualTo("field", "value"); + console.log(`query is ${query.getSqlLike()}`); + query = null; +} catch (e) { + console.error(`duplicated calls should be ok.code is ${e.code},message is ${e.message}`); +} +``` + +### lessThanOrEqualTo + +lessThanOrEqualTo(field: string, value: number|string): Query + +构造一个Query对象以查询具有指定字段且值小于或等于指定值的条目。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**参数:** + + +| 参数名 | 参数类型 | 必填 | 说明 | +| ----- | ------ | ---- | ----------------------- | +| fieId | string | 是 |表示指定字段,不能包含' ^ '。 | +| value | number\|string | 是 | 表示指定的值。| + +**返回值:** + +| 类型 | 说明 | +| -------------- | --------------- | +| [Query](query) | 返回Query对象。 | + +**示例:** + +```js +try { + let query = new distributedKVStore.Query(); + query.lessThanOrEqualTo("field", "value"); + console.log(`query is ${query.getSqlLike()}`); + query = null; +} catch (e) { + console.error(`duplicated calls should be ok.code is ${e.code},message is ${e.message}`); +} +``` + +### isNull + +isNull(field: string): Query + +构造一个Query对象以查询具有值为null的指定字段的条目。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| ------ | -------- | ---- | ----------------------------- | +| fieId | string | 是 | 表示指定字段,不能包含' ^ '。 | + +**返回值:** + +| 类型 | 说明 | +| -------------- | --------------- | +| [Query](query) | 返回Query对象。 | + +**示例:** + +```js +try { + let query = new distributedKVStore.Query(); + query.isNull("field"); + console.log(`query is ${query.getSqlLike()}`); + query = null; +} catch (e) { + console.error(`duplicated calls should be ok.code is ${e.code},message is ${e.message}`); +} +``` + +### inNumber + +inNumber(field: string, valueList: number[]): Query + +构造一个Query对象以查询具有指定字段的条目,其值在指定的值列表中。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| --------- | -------- | ---- | ----------------------------- | +| fieId | string | 是 | 表示指定字段,不能包含' ^ '。 | +| valueList | number[] | 是 | 表示指定的值列表。 | + +**返回值:** + +| 类型 | 说明 | +| -------------- | --------------- | +| [Query](query) | 返回Query对象。 | + +**示例:** + +```js +try { + let query = new distributedKVStore.Query(); + query.inNumber("field", [0, 1]); + console.log(`query is ${query.getSqlLike()}`); + query = null; +} catch (e) { + console.error(`duplicated calls should be ok.code is ${e.code},message is ${e.message}`); +} +``` + +### inString + +inString(field: string, valueList: string[]): Query + +构造一个Query对象以查询具有指定字段的条目,其值在指定的字符串值列表中。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| --------- | -------- | ---- | ----------------------------- | +| fieId | string | 是 | 表示指定字段,不能包含' ^ '。 | +| valueList | string[] | 是 | 表示指定的字符串值列表。 | + +**返回值:** + +| 类型 | 说明 | +| -------------- | --------------- | +| [Query](query) | 返回Query对象。 | + +**示例:** + +```js +try { + let query = new distributedKVStore.Query(); + query.inString("field", ['test1', 'test2']); + console.log(`query is ${query.getSqlLike()}`); + query = null; +} catch (e) { + console.error(`duplicated calls should be ok.code is ${e.code},message is ${e.message}`); +} +``` + +### notInNumber + +notInNumber(field: string, valueList: number[]): Query + +构造一个Query对象以查询具有指定字段的条目,该字段的值不在指定的值列表中。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| --------- | -------- | ---- | ----------------------------- | +| fieId | string | 是 | 表示指定字段,不能包含' ^ '。 | +| valueList | number[] | 是 | 表示指定的值列表。 | + +**返回值:** + +| 类型 | 说明 | +| -------------- | --------------- | +| [Query](query) | 返回Query对象。 | + +**示例:** + +```js +try { + let query = new distributedKVStore.Query(); + query.notInNumber("field", [0, 1]); + console.log(`query is ${query.getSqlLike()}`); + query = null; +} catch (e) { + console.error(`duplicated calls should be ok.code is ${e.code},message is ${e.message}`); +} +``` + +### notInString + +notInString(field: string, valueList: string[]): Query + +构造一个Query对象以查询具有指定字段且值不在指定字符串值列表中的条目。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| --------- | -------- | ---- | ----------------------------- | +| fieId | string | 是 | 表示指定字段,不能包含' ^ '。 | +| valueList | string[] | 是 | 表示指定的字符串值列表。 | + +**返回值:** + +| 类型 | 说明 | +| -------------- | --------------- | +| [Query](query) | 返回Query对象。 | + +**示例:** + +```js +try { + let query = new distributedKVStore.Query(); + query.notInString("field", ['test1', 'test2']); + console.log(`query is ${query.getSqlLike()}`); + query = null; +} catch (e) { + console.error(`duplicated calls should be ok.code is ${e.code},message is ${e.message}`); +} +``` + +### like + +like(field: string, value: string): Query + +构造一个Query对象以查询具有与指定字符串值相似的指定字段的条目。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| ------ | -------- | ---- | ----------------------------- | +| fieId | string | 是 | 表示指定字段,不能包含' ^ '。 | +| value | string | 是 | 表示指定的字符串值。 | + +**返回值:** + +| 类型 | 说明 | +| -------------- | --------------- | +| [Query](query) | 返回Query对象。 | + +**示例:** + +```js +try { + let query = new distributedKVStore.Query(); + query.like("field", "value"); + console.log(`query is ${query.getSqlLike()}`); + query = null; +} catch (e) { + console.error(`duplicated calls should be ok.code is ${e.code},message is ${e.message}`); +} +``` + +### unlike + +unlike(field: string, value: string): Query + +构造一个Query对象以查询具有与指定字符串值不相似的指定字段的条目。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| ------ | -------- | ---- | ----------------------------- | +| fieId | string | 是 | 表示指定字段,不能包含' ^ '。 | +| value | string | 是 | 表示指定的字符串值。 | + +**返回值:** + +| 类型 | 说明 | +| -------------- | --------------- | +| [Query](query) | 返回Query对象。 | + +**示例:** + +```js +try { + let query = new distributedKVStore.Query(); + query.unlike("field", "value"); + console.log(`query is ${query.getSqlLike()}`); + query = null; +} catch (e) { + console.error(`duplicated calls should be ok.code is ${e.code},message is ${e.message}`); +} +``` + +### and + +and(): Query + +构造一个带有与条件的查询对象。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**返回值:** + +| 类型 | 说明 | +| -------------- | -------------- | +| [Query](query) | 返回查询对象。 | + +**示例:** + +```js +try { + let query = new distributedKVStore.Query(); + query.notEqualTo("field", "value1"); + query.and(); + query.notEqualTo("field", "value2"); + console.log("query is " + query.getSqlLike()); + query = null; +} catch (e) { + console.log("duplicated calls should be ok :" + e); +} +``` + +### or + +or(): Query + +构造一个带有或条件的Query对象。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**返回值:** + +| 类型 | 说明 | +| -------------- | -------------- | +| [Query](query) | 返回查询对象。 | + +**示例:** + +```js +try { + let query = new distributedKVStore.Query(); + query.notEqualTo("field", "value1"); + query.or(); + query.notEqualTo("field", "value2"); + console.log("query is " + query.getSqlLike()); + query = null; +} catch (e) { + console.log("duplicated calls should be ok :" + e); +} +``` + +### orderByAsc + +orderByAsc(field: string): Query + +构造一个Query对象,将查询结果按升序排序。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| ------ | -------- | ---- | ----------------------------- | +| fieId | string | 是 | 表示指定字段,不能包含' ^ '。 | + +**返回值:** + +| 类型 | 说明 | +| -------------- | --------------- | +| [Query](query) | 返回Query对象。 | + +**示例:** + +```js +try { + let query = new distributedKVStore.Query(); + query.notEqualTo("field", "value"); + query.orderByAsc("field"); + console.log(`query is ${query.getSqlLike()}`); + query = null; +} catch (e) { + console.error(`duplicated calls should be ok.code is ${e.code},message is ${e.message}`); +} +``` + +### orderByDesc + +orderByDesc(field: string): Query + +构造一个Query对象,将查询结果按降序排序。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| ------ | -------- | ---- | ----------------------------- | +| fieId | string | 是 | 表示指定字段,不能包含' ^ '。 | + +**返回值:** + +| 类型 | 说明 | +| -------------- | --------------- | +| [Query](query) | 返回Query对象。 | + +**示例:** + +```js +try { + let query = new distributedKVStore.Query(); + query.notEqualTo("field", "value"); + query.orderByDesc("field"); + console.log(`query is ${query.getSqlLike()}`); + query = null; +} catch (e) { + console.error(`duplicated calls should be ok.code is ${e.code},message is ${e.message}`); +} +``` + +### limit + +limit(total: number, offset: number): Query + +构造一个Query对象来指定结果的数量和开始位置。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| ------ | -------- | ---- | ------------------ | +| total | number | 是 | 表示指定的结果数。 | +| offset | number | 是 | 表示起始位置。 | + +**返回值:** + +| 类型 | 说明 | +| -------------- | --------------- | +| [Query](query) | 返回Query对象。 | + +**示例:** + +```js +let total = 10; +let offset = 1; +try { + let query = new distributedKVStore.Query(); + query.notEqualTo("field", "value"); + query.limit(total, offset); + console.log(`query is ${query.getSqlLike()}`); + query = null; +} catch (e) { + console.error(`duplicated calls should be ok.code is ${e.code},message is ${e.message}`); +} +``` + +### isNotNull + +isNotNull(field: string): Query + +构造一个Query对象以查询具有值不为null的指定字段的条目。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| ------ | -------- | ---- | ----------------------------- | +| fieId | string | 是 | 表示指定字段,不能包含' ^ '。 | + +**返回值:** + +| 类型 | 说明 | +| -------------- | --------------- | +| [Query](query) | 返回Query对象。 | + +**示例:** + +```js +try { + let query = new distributedKVStore.Query(); + query.isNotNull("field"); + console.log(`query is ${query.getSqlLike()}`); + query = null; +} catch (e) { + console.error(`duplicated calls should be ok.code is ${e.code},message is ${e.message}`); +} +``` + +### beginGroup + +beginGroup(): Query + +创建一个带有左括号的查询条件组。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**返回值:** + +| 类型 | 说明 | +| -------------- | --------------- | +| [Query](query) | 返回Query对象。 | + +**示例:** + +```js +try { + let query = new distributedKVStore.Query(); + query.beginGroup(); + query.isNotNull("field"); + query.endGroup(); + console.log("query is " + query.getSqlLike()); + query = null; +} catch (e) { + console.log("duplicated calls should be ok :" + e); +} +``` + +### endGroup + +endGroup(): Query + +创建一个带有右括号的查询条件组。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**返回值:** + +| 类型 | 说明 | +| -------------- | --------------- | +| [Query](query) | 返回Query对象。 | + +**示例:** + +```js +try { + let query = new distributedKVStore.Query(); + query.beginGroup(); + query.isNotNull("field"); + query.endGroup(); + console.log("query is " + query.getSqlLike()); + query = null; +} catch (e) { + console.log("duplicated calls should be ok :" + e); +} +``` + +### prefixKey + +prefixKey(prefix: string): Query + +创建具有指定键前缀的查询条件。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| ------ | -------- | ---- | ------------------ | +| prefix | string | 是 | 表示指定的键前缀。 | + +**返回值:** + +| 类型 | 说明 | +| -------------- | --------------- | +| [Query](query) | 返回Query对象。 | + +**示例:** + +```js +try { + let query = new distributedKVStore.Query(); + query.prefixKey("$.name"); + query.prefixKey("0"); + console.log(`query is ${query.getSqlLike()}`); + query = null; +} catch (e) { + console.error(`duplicated calls should be ok.code is ${e.code},message is ${e.message}`); +} +``` + +### setSuggestIndex + +setSuggestIndex(index: string): Query + +设置一个指定的索引,将优先用于查询。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| ------ | -------- | ---- | ------------------ | +| index | string | 是 | 指示要设置的索引。 | + +**返回值:** + +| 类型 | 说明 | +| -------------- | --------------- | +| [Query](query) | 返回Query对象。 | + +**示例:** + +```js +try { + let query = new distributedKVStore.Query(); + query.setSuggestIndex("$.name"); + query.setSuggestIndex("0"); + console.log(`query is ${query.getSqlLike()}`); + query = null; +} catch (e) { + console.error(`duplicated calls should be ok.code is ${e.code},message is ${e.message}`); +} +``` + +### deviceId + +deviceId(deviceId:string):Query + +添加设备ID作为key的前缀。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| -------- | -------- | ---- | ------------------ | +| deviceId | string | 是 | 指示查询的设备ID。 | + +**返回值:** + +| 类型 | 说明 | +| -------------- | --------------- | +| [Query](query) | 返回Query对象。 | + +**示例:** + +```js +try { + let query = new distributedKVStore.Query(); + query.deviceId("deviceId"); + console.log(`query is ${query.getSqlLike()}`); +} catch (e) { + console.error(`duplicated calls should be ok.code is ${e.code},message is ${e.message}`); +} +``` + +### getSqlLike + +getSqlLike():string + +获取Query对象的查询语句。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**返回值:** + +| 类型 | 说明 | +| ------ | ------------------------------------ | +| string | 返回一个字段列中包含对应子串的结果。 | + +**示例:** + +```js +try { + let query = new distributedKVStore.Query(); + let sql1 = query.getSqlLike(); + console.log(`GetSqlLike sql= ${sql1}`); +} catch (e) { + console.log("duplicated calls should be ok : " + e); +} +``` + +## SingleKVStore + +SingleKVStore数据库实例,提供增加数据、删除数据和订阅数据变更、订阅数据同步完成的方法。 + +在调用SingleKVStore的方法前,需要先通过[getKVStore](#getkvstore)构建一个SingleKVStore实例。 + +### put + +put(key: string, value: Uint8Array | string | number | boolean, callback: AsyncCallback<void>): void + +添加指定类型键值对到数据库,使用callback异步回调。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| ----- | ------ | ---- | ----------------------- | +| key | string | 是 |要添加数据的key,不能为空且长度不大于[MAX_KEY_LENGTH](#constants)。 | +| value | Uint8Array \| string \| number \| boolean | 是 |要添加数据的value,支持Uint8Array、number 、 string 、boolean,Uint8Array、string 的长度不大于[MAX_VALUE_LENGTH](#constants)。 | +| callback | AsyncCallback<void> | 是 |回调函数。 | + +**错误码:** + +以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 + +| **错误码ID** | **错误信息** | +| ------------ | -------------------------------------- | +| 15100003 | Database corrupted. | +| 15100006 | Database or result set already closed. | + +**示例:** + +```js +let kvStore; +const KEY_TEST_STRING_ELEMENT = 'key_test_string'; +const VALUE_TEST_STRING_ELEMENT = 'value-test-string'; +try { + kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT, function (err, data) { + if (err != undefined) { + console.error(`Fail to put.code is ${err.code},message is ${err.message}`); + return; + } + console.log("Succeeded in putting"); + }); +} catch (e) { + console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`); +} +``` + +### put + +put(key: string, value: Uint8Array | string | number | boolean): Promise<void> + +添加指定类型键值对到数据库,使用Promise异步回调。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| ----- | ------ | ---- | ----------------------- | +| key | string | 是 |要添加数据的key,不能为空且长度不大于[MAX_KEY_LENGTH](#constants)。 | +| value | Uint8Array \| string \| number \| boolean | 是 |要添加数据的value,支持Uint8Array、number 、 string 、boolean,Uint8Array、string 的长度不大于[MAX_VALUE_LENGTH](#constants)。 | + +**返回值:** + +| 类型 | 说明 | +| ------------------- | ------------------------- | +| Promise<void> | 无返回结果的Promise对象。 | + +**错误码:** + +以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 + +| **错误码ID** | **错误信息** | +| ------------ | -------------------------------------- | +| 15100003 | Database corrupted. | +| 15100006 | Database or result set already closed. | + +**示例:** + +```js +let kvStore; +const KEY_TEST_STRING_ELEMENT = 'key_test_string'; +const VALUE_TEST_STRING_ELEMENT = 'value-test-string'; +try { + kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT).then((data) => { + console.log(`Succeeded in putting.data=${data}`); + }).catch((err) => { + console.error(`Fail to put.code is ${err.code},message is ${err.message}`); + }); +} catch (e) { + console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`); +} +``` + +### putBatch + +putBatch(entries: Entry[], callback: AsyncCallback<void>): void + +批量插入键值对到SingleKVStore数据库中,使用callback异步回调。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| -------- | ------------------------ | ---- | ------------------------ | +| entries | [Entry](#entry)[] | 是 | 表示要批量插入的键值对。 | +| callback | Asyncallback<void> | 是 | 回调函数。 | + +**错误码:** + +以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 + +| **错误码ID** | **错误信息** | +| ------------ | -------------------------------------- | +| 15100003 | Database corrupted. | +| 15100006 | Database or result set already closed. | + +**示例:** + +```js +let kvStore; +try { + let entries = []; + for (var i = 0; i < 10; i++) { + var key = 'batch_test_string_key'; + var entry = { + key: key + i, + value: { + type: distributedKVStore.ValueType.STRING, + value: 'batch_test_string_value' + } + } + entries.push(entry); + } + console.log(`entries: ${entries}`); + kvStore.putBatch(entries, async function (err, data) { + if (err != undefined) { + console.error(`Fail to put Batch.code is ${err.code},message is ${err.message}`); + return; + } + console.log('Succeeded in putting Batch'); + kvStore.getEntries('batch_test_string_key', function (err, entries) { + if (err != undefined) { + console.error(`Fail to get Entries.code is ${err.code},message is ${err.message}`); + } + console.log('Succeeded in getting Entries'); + console.log(`entries.length: ${entries.length}`); + console.log(`entries[0]: ${entries[0]}`); + }); + }); +} catch (e) { + console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message} `); +} +``` + +### putBatch + +putBatch(entries: Entry[]): Promise<void> + +批量插入键值对到SingleKVStore数据库中,使用Promise异步回调。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| ------- | ----------------- | ---- | ------------------------ | +| entries | [Entry](#entry)[] | 是 | 表示要批量插入的键值对。 | + +**返回值:** + +| 类型 | 说明 | +| ------------------- | ------------------------- | +| Promise<void> | 无返回结果的Promise对象。 | + +**错误码:** + +以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 + +| **错误码ID** | **错误信息** | +| ------------ | -------------------------------------- | +| 15100003 | Database corrupted. | +| 15100006 | Database or result set already closed. | + +**示例:** + +```js +let kvStore; +try { + let entries = []; + for (var i = 0; i < 10; i++) { + var key = 'batch_test_string_key'; + var entry = { + key: key + i, + value: { + type: distributedKVStore.ValueType.STRING, + value: 'batch_test_string_value' + } + } + entries.push(entry); + } + console.log(`entries: ${entries}`); + kvStore.putBatch(entries).then(async (entries) => { + console.log('Succeeded in putting Batch'); + kvStore.getEntries('batch_test_string_key').then((entries) => { + console.log('Succeeded in getting Entries'); + console.log(`PutBatch ${entries}`); + }).catch((err) => { + console.error(`Fail to get Entries.code is ${err.code},message is ${err.message}`); + }); + }).catch((err) => { + console.error(`Fail to put Batch.code is ${err.code},message is ${err.message}`); + }); +} catch (e) { + console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message} `); +} +``` + +### putBatch + +putBatch(value: Array<ValuesBucket>, callback: AsyncCallback<void>): void + +将值写入SingleKVStore数据库,使用callback异步回调。 + +**系统接口:** 此接口为系统接口。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| -------- | ------------------------------------------------------------ | ---- | ------------------ | +| value | Array<[ValuesBucket](js-apis-data-ValuesBucket.md#valuesbucket)> | 是 | 表示要插入的数据。 | +| callback | Asyncallback<void> | 是 | 回调函数。 | + +**错误码:** + +以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 + +| **错误码ID** | **错误信息** | +| ------------ | -------------------------------------- | +| 15100003 | Database corrupted. | +| 15100006 | Database or result set already closed. | + +**示例:** + +```js +let kvStore; +try { + let v8Arr = []; + let arr = new Uint8Array([4, 5, 6, 7]); + let vb1 = { key: "name_1", value: 32 } + let vb2 = { key: "name_2", value: arr }; + let vb3 = { key: "name_3", value: "lisi" }; + + v8Arr.push(vb1); + v8Arr.push(vb2); + v8Arr.push(vb3); + kvStore.putBatch(v8Arr, async function (err, data) { + if (err != undefined) { + console.error(`Fail to put batch.code is ${err.code},message is ${err.message}`); + return; + } + console.log('Succeeded in putting batch'); + }) +} catch (e) { + console.error(`Fail to put batch.code is ${e.code},message is ${e.message}`); +} +``` + +### putBatch + +putBatch(value: Array<ValuesBucket>): Promise<void> + +将valuesbucket类型的值写入SingleKVStore数据库,使用Promise异步回调。 + +**系统接口:** 此接口为系统接口。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| ------ | ------------------------------------------------------------ | ---- | ------------------ | +| value | Array<[ValuesBucket](js-apis-data-ValuesBucket.md#valuesbucket)> | 是 | 表示要插入的数据。 | + +**返回值:** + +| 类型 | 说明 | +| ------------------- | ------------------------- | +| Promise<void> | 五返回结果的Promise对象。 | + +**错误码:** + +以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 + +| **错误码ID** | **错误信息** | +| ------------ | -------------------------------------- | +| 15100003 | Database corrupted. | +| 15100006 | Database or result set already closed. | + +**示例:** + +```js +let kvStore; +try { + let v8Arr = []; + let arr = new Uint8Array([4, 5, 6, 7]); + let vb1 = { key: "name_1", value: 32 } + let vb2 = { key: "name_2", value: arr }; + let vb3 = { key: "name_3", value: "lisi" }; + + v8Arr.push(vb1); + v8Arr.push(vb2); + v8Arr.push(vb3); + kvStore.putBatch(v8Arr).then(async (data) => { + console.log(`Succeeded in putting patch`); + }).catch((err) => { + console.error(`putBatch fail.code is ${err.code},message is ${err.message}`); + }); +} catch (e) { + console.error(`putBatch fail.code is ${e.code},message is ${e.message}`); +} +``` + +### delete + +delete(key: string, callback: AsyncCallback<void>): void + +从数据库中删除指定键值的数据,使用callback异步回调。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| -------- | ------------------------- | ---- | ------------------------------------------------------------ | +| key | string | 是 | 要删除数据的key,不能为空且长度不大于[MAX_KEY_LENGTH](#constants)。 | +| callback | AsyncCallback<void> | 是 | 回调函数。 | + +**错误码:** + +以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 + +| **错误码ID** | **错误信息** | +| ------------ | -------------------------------------- | +| 15100003 | Database corrupted. | +| 15100004 | Not found. | +| 15100006 | Database or result set already closed. | + +**示例:** + +```js +let kvStore; +const KEY_TEST_STRING_ELEMENT = 'key_test_string'; +const VALUE_TEST_STRING_ELEMENT = 'value-test-string'; +try { + kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT, function (err, data) { + if (err != undefined) { + console.error(`Fail to put.code is ${err.code},message is ${err.message}`); + return; + } + console.log('Succeeded in putting'); + kvStore.delete(KEY_TEST_STRING_ELEMENT, function (err, data) { + if (err != undefined) { + console.error(`Fail to delete.code is ${err.code},message is ${err.message}`); + return; + } + console.log('Succeeded in deleting'); + }); + }); +} catch (e) { + console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`; +} +``` + +### delete + +delete(key: string): Promise<void> + +从数据库中删除指定键值的数据,使用Promise异步回调。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| ------ | -------- | ---- | ------------------------------------------------------------ | +| key | string | 是 | 要删除数据的key,不能为空且长度不大于[MAX_KEY_LENGTH](#constants)。 | + +**返回值:** + +| 类型 | 说明 | +| ------------------- | ------------------------- | +| Promise<void> | 无返回结果的Promise对象。 | + +**错误码:** + +以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 + +| **错误码ID** | **错误信息** | +| ------------ | -------------------------------------- | +| 15100003 | Database corrupted. | +| 15100004 | Not found. | +| 15100006 | Database or result set already closed. | + +**示例:** + +```js +let kvStore; +const KEY_TEST_STRING_ELEMENT = 'key_test_string'; +const VALUE_TEST_STRING_ELEMENT = 'value-test-string'; +try { + kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT).then((data) => { + console.log(`Succeeded in putting: ${data}`); + kvStore.delete(KEY_TEST_STRING_ELEMENT).then((data) => { + console.log('Succeeded in deleting'); + }).catch((err) => { + console.error(`Fail to delete.code is ${err.code},message is ${err.message}`); + }); + }).catch((err) => { + console.error(`Fail to put.code is ${err.code},message is ${err.message}`); + }); +} catch (e) { + console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`); +} +``` + +### delete + +delete(predicates: dataSharePredicates.DataSharePredicates, callback: AsyncCallback<void>) + +从数据库中删除符合predicates条件的键值对,使用callback异步回调。 + +**系统接口:** 此接口为系统接口。 + +**系统能力:** SystemCapability.DistributedDataManager.DataShare.Provider + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| ---------- | ------------------------------------------------------------ | ---- | ----------------------------------------------- | +| predicates | [DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | 是 | 指示筛选条件,当此参数为null时,应定义处理逻辑。 | +| callback | AsyncCallback<void> | 是 | 回调函数。 | + +**错误码:** + +以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 + +| **错误码ID** | **错误信息** | +| ------------ | -------------------------------------- | +| 15100003 | Database corrupted. | +| 15100004 | Not found. | +| 15100006 | Database or result set already closed. | + +**示例:** + +```js +import dataSharePredicates from '@ohos.data.dataSharePredicates'; +let kvStore; +try { + let predicates = new dataSharePredicates.DataSharePredicates(); + kvStore.delete(predicates, function (err, data) { + if (err == undefined) { + console.log('Succeeded in deleting'); + } else { + console.error(`Fail to delete.code is ${err.code},message is ${err.message}`); + } + }); +} catch (e) { + console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`); +} +``` + +### delete + +delete(predicates: dataSharePredicates.DataSharePredicates): Promise<void> + +从数据库中删除符合predicates条件的键值对,使用Promise异步回调。 + +**系统接口:** 此接口为系统接口。 + +**系统能力:** SystemCapability.DistributedDataManager.DataShare.Provider + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| ---------- | ------------------------------------------------------------ | ---- | ----------------------------------------------- | +| predicates | [DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | 是 | 指示筛选条件,当此参数为null时,应定义处理逻辑。 | + +**返回值:** + +| 类型 | 说明 | +| ------------------- | ------------------------- | +| Promise<void> | 无返回结果的Promise对象。 | + +**错误码:** + +以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 + +| **错误码ID** | **错误信息** | +| ------------ | -------------------------------------- | +| 15100003 | Database corrupted. | +| 15100004 | Not found. | +| 15100006 | Database or result set already closed. | + +**示例:** + +```js +import dataSharePredicates from '@ohos.data.dataSharePredicates'; + +let kvStore; +try { + let predicates = new dataSharePredicates.DataSharePredicates(); + let arr = ["name"]; + predicates.inKeys(arr); + kvStore.put("name", "bob").then((data) => { + console.log(`Succeeded in putting: ${data}`); + kvStore.delete(predicates).then((data) => { + console.log('Succeeded in deleting'); + }).catch((err) => { + console.error(`Fail to delete.code is ${err.code},message is ${err.message}`); + }); + }).catch((err) => { + console.error(`Fail to put.code is ${err.code},message is ${err.message}`); + }); +} catch (e) { + console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`); +} +``` + +### deleteBatch + +deleteBatch(keys: string[], callback: AsyncCallback<void>): void + +批量删除SingleKVStore数据库中的键值对,使用callback异步回调。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| -------- | ------------------------- | ---- | ------------------------ | +| keys | string[] | 是 | 表示要批量删除的键值对。 | +| callback | AsyncCallback<void> | 是 | 回调函数。 | + +**错误码:** + +以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 + +| **错误码ID** | **错误信息** | +| ------------ | -------------------------------------- | +| 15100003 | Database corrupted. | +| 15100004 | Not found. | +| 15100006 | Database or result set already closed. | + +**示例:** + +```js +let kvStore; +try { + let entries = []; + let keys = []; + for (var i = 0; i < 5; i++) { + var key = 'batch_test_string_key'; + var entry = { + key: key + i, + value: { + type: distributedKVStore.ValueType.STRING, + value: 'batch_test_string_value' + } + } + entries.push(entry); + keys.push(key + i); + } + console.log(`entries: ${entries}`); + kvStore.putBatch(entries, async function (err, data) { + if (err != undefined) { + console.error(`Fail to put Batch.code is ${err.code},message is ${err.message}`); + return; + } + console.log('Succeeded in putting Batch'); + kvStore.deleteBatch(keys, async function (err, data) { + if (err != undefined) { + console.error(`Fail to delete Batch.code is ${err.code},message is ${err.message}`); + return; + } + console.log('Succeeded in deleting Batch'); + }); + }); +} catch (e) { + console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`); +} +``` + +### deleteBatch + +deleteBatch(keys: string[]): Promise<void> + +批量删除SingleKVStore数据库中的键值对,使用Promise异步回调。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| ------ | -------- | ---- | ------------------------ | +| keys | string[] | 是 | 表示要批量删除的键值对。 | + +**返回值:** + +| 类型 | 说明 | +| ------------------- | ------------------------- | +| Promise<void> | 无返回结果的Promise对象。 | + +**错误码:** + +以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 + +| **错误码ID** | **错误信息** | +| ------------ | -------------------------------------- | +| 15100003 | Database corrupted. | +| 15100004 | Not found. | +| 15100006 | Database or result set already closed. | + +**示例:** + +```js +let kvStore; +try { + let entries = []; + let keys = []; + for (var i = 0; i < 5; i++) { + var key = 'batch_test_string_key'; + var entry = { + key: key + i, + value: { + type: distributedKVStore.ValueType.STRING, + value: 'batch_test_string_value' + } + } + entries.push(entry); + keys.push(key + i); + } + console.log(`entries: ${entries}`); + kvStore.putBatch(entries).then(async (data) => { + console.log('Succeeded in putting Batch'); + kvStore.deleteBatch(keys).then((err) => { + console.log('Succeeded in deleting Batch'); + }).catch((err) => { + console.error(`Fail to delete Batch.code is ${err.code},message is ${err.message}`); + }); + }).catch((err) => { + console.error(`Fail to put Batch.code is ${err.code},message is ${err.message}`); + }); +} catch (e) { + console.error(`An unexpected error occured.code is ${e.code},message is ${e.message}`); +} +``` + +### removeDeviceData + +removeDeviceData(deviceId: string, callback: AsyncCallback<void>): void + +删除指定设备的数据,使用callback异步回调。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| -------- | ------------------------- | ---- | ---------------------- | +| deviceId | string | 是 | 表示要删除设备的名称。 | +| callback | AsyncCallback<void> | 是 | 回调函数。 | + +**错误码:** + +以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 + +| **错误码ID** | **错误信息** | +| ------------ | -------------------------------------- | +| 15100006 | Database or result set already closed. | + +**示例:** + +```js +let kvStore; +const KEY_TEST_STRING_ELEMENT = 'key_test_string_2'; +const VALUE_TEST_STRING_ELEMENT = 'value-string-002'; +try { + kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT, async function (err, data) { + console.log('Succeeded in putting data'); + const deviceid = 'no_exist_device_id'; + kvStore.removeDeviceData(deviceid, async function (err, data) { + if (err == undefined) { + console.log('succeeded in removing device data'); + } else { + console.error(`Fail to remove device data.code is ${err.code},message is ${err.message} `); + kvStore.get(KEY_TEST_STRING_ELEMENT, async function (err, data) { + console.log('Succeeded in getting data'); + }); + } + }); + }); +} catch (e) { + console.error(`An unexpected error occured.code is ${e.code},message is ${e.message}`) +} +``` + +### removeDeviceData + +removeDeviceData(deviceId: string): Promise<void> + +删除指定设备的数据,使用Promise异步回调。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| -------- | -------- | ---- | ---------------------- | +| deviceId | string | 是 | 表示要删除设备的名称。 | + +**返回值:** + +| 类型 | 说明 | +| ------------------- | ------------------------- | +| Promise<void> | 无返回结果的Promise对象。 | + +**错误码:** + +以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 + +| **错误码ID** | **错误信息** | +| ------------ | -------------------------------------- | +| 15100006 | Database or result set already closed. | + +**示例:** + +```js +let kvStore; +const KEY_TEST_STRING_ELEMENT = 'key_test_string_2'; +const VALUE_TEST_STRING_ELEMENT = 'value-string-001'; +try { + kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT).then((err) => { + console.log('Succeeded in putting data'); + }).catch((err) => { + console.error(`Fail to put data.code is ${err.code},message is ${err.message} `); + }); + const deviceid = 'no_exist_device_id'; + kvStore.removeDeviceData(deviceid).then((err) => { + console.log('succeeded in removing device data'); + }).catch((err) => { + console.error(`Fail to remove device data.code is ${err.code},message is ${err.message} `); + }); + kvStore.get(KEY_TEST_STRING_ELEMENT).then((data) => { + console.log('Succeeded in getting data'); + }).catch((err) => { + console.error(`Fail to get data.code is ${err.code},message is ${err.message} `); + }); +} catch (e) { + console.error(`An unexpected error occured.code is ${e.code},message is ${e.message}`) +} +``` + +### get + +get(key: string, callback: AsyncCallback): void + +获取指定键的值,使用callback异步回调。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| ----- | ------ | ---- | ----------------------- | +| key |string | 是 |要查询数据的key,不能为空且长度不大于[MAX_KEY_LENGTH](#constants)。 | +| callback |AsyncCallback<Uint8Array \| string \| boolean \| number>) | 是 |回调函数。返回获取查询的值。 | + +**错误码:** + +以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 + +| **错误码ID** | **错误信息** | +| ------------ | -------------------------------------- | +| 15100003 | Database corrupted. | +| 15100004 | Not found. | +| 15100006 | Database or result set already closed. | + +**示例:** + +```js +let kvStore; +const KEY_TEST_STRING_ELEMENT = 'key_test_string'; +const VALUE_TEST_STRING_ELEMENT = 'value-test-string'; +try { + kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT, function (err, data) { + if (err != undefined) { + console.error(`Fail to put.code is ${err.code},message is ${err.message}`); + return; + } + console.log("Succeeded in putting"); + kvStore.get(KEY_TEST_STRING_ELEMENT, function (err, data) { + if (err != undefined) { + console.error(`Fail to get.code is ${err.code},message is ${err.message}`); + return; + } + console.log(`Succeeded in getting data.data=${data}`); + }); + }); +} catch (e) { + console.error(`Fail to get.code is ${e.code},message is ${e.message}`); +} +``` + +### get + +get(key: string): Promise<boolean | string| number | Uint8Array> + +获取指定键的值,使用Promise异步回调。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| ------ | -------- | ---- | ------------------------------------------------------------ | +| key | string | 是 | 要查询数据的key,不能为空且长度不大于[MAX_KEY_LENGTH](#constants)。 | + +**返回值:** + +| 类型 | 说明 | +| ------ | ------- | +|Promise<Uint8Array \| string \| boolean \| number> |Promise对象。返回获取查询的值。| + +**错误码:** + +以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 + +| **错误码ID** | **错误信息** | +| ------------ | -------------------------------------- | +| 15100003 | Database corrupted. | +| 15100004 | Not found. | +| 15100006 | Database or result set already closed. | + +**示例:** + +```js +let kvStore; +const KEY_TEST_STRING_ELEMENT = 'key_test_string'; +const VALUE_TEST_STRING_ELEMENT = 'value-test-string'; +try { + kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT).then((data) => { + console.log(`Succeeded in putting data.data=${data}`); + kvStore.get(KEY_TEST_STRING_ELEMENT).then((data) => { + console.log(`Succeeded in getting data.data=${data}`); + }).catch((err) => { + console.error(`Fail to get.code is ${err.code},message is ${err.message}`); + }); + }).catch((err) => { + console.error(`Fail to put.code is ${err.code},message is ${err.message}`); + }); +} catch (e) { + console.error(`Fail to get.code is ${e.code},message is ${e.message}`); +} +``` + +### getEntries + +getEntries(keyPrefix: string, callback: AsyncCallback<Entry[]>): void + +获取匹配指定键前缀的所有键值对,使用callback异步回调。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| --------- | -------------------------------------- | ---- | ---------------------------------------- | +| keyPrefix | string | 是 | 表示要匹配的键前缀。 | +| callback | AsyncCallback<[Entry](#entry)[]> | 是 | 回调函数。返回匹配指定前缀的键值对列表。 | + +**错误码:** + +以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 + +| **错误码ID** | **错误信息** | +| ------------ | -------------------------------------- | +| 15100003 | Database corrupted. | +| 15100006 | Database or result set already closed. | + +**示例:** + +```js +let kvStore; +try { + let entries = []; + for (var i = 0; i < 10; i++) { + var key = 'batch_test_string_key'; + var entry = { + key: key + i, + value: { + type: distributedKVStore.ValueType.STRING, + value: 'batch_test_string_value' + } + } + entries.push(entry); + } + console.log(`entries: ${entries}`); + kvStore.putBatch(entries, async function (err, data) { + if (err != undefined) { + console.error(`Fail to put Batch.code is ${err.code},message is ${err.message}`); + return; + } + console.log('Succeeded in putting Batch'); + kvStore.getEntries('batch_test_string_key', function (err, entries) { + if (err != undefined) { + console.error(`Fail to get Entries.code is ${err.code},message is ${err.message}`); + return; + } + console.log('Succeeded in getting Entries'); + console.log(`entries.length: ${entries.length}`); + console.log(`entries[0]: ${entries[0]}`); + }); + }); +} catch (e) { + console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message} `); +} +``` + +### getEntries + +getEntries(keyPrefix: string): Promise<Entry[]> + +获取匹配指定键前缀的所有键值对,使用Promise异步回调。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| --------- | -------- | ---- | -------------------- | +| keyPrefix | string | 是 | 表示要匹配的键前缀。 | + +**返回值:** + +| 类型 | 说明 | +| -------------------------------- | ------------------------------------------- | +| Promise<[Entry](#entry)[]> | Promise对象。返回匹配指定前缀的键值对列表。 | + +**错误码:** + +以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 + +| **错误码ID** | **错误信息** | +| ------------ | -------------------------------------- | +| 15100003 | Database corrupted. | +| 15100006 | Database or result set already closed. | + +**示例:** + +```js +let kvStore; +try { + let entries = []; + for (var i = 0; i < 10; i++) { + var key = 'batch_test_string_key'; + var entry = { + key: key + i, + value: { + type: distributedKVStore.ValueType.STRING, + value: 'batch_test_string_value' + } + } + entries.push(entry); + } + console.log(`entries: ${entries}`); + kvStore.putBatch(entries).then(async (entries) => { + console.log('Succeeded in putting Batch'); + kvStore.getEntries('batch_test_string_key').then((entries) => { + console.log('Succeeded in getting Entries'); + console.log(`PutBatch ${entries}`); + }).catch((err) => { + console.error(`Fail to get Entries.code is ${err.code},message is ${err.message}`); + }); + }).catch((err) => { + console.error(`Fail to put Batch.code is ${err.code},message is ${err.message}`); + }); +} catch (e) { + console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message} `); +} +``` + +### getEntries + +getEntries(query: Query, callback: AsyncCallback<Entry[]>): void + +获取与指定Query对象匹配的键值对列表,使用callback异步回调。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| -------- | -------------------------------------- | ---- | ----------------------------------------------- | +| query | [Query](query) | 是 | 表示要匹配的键前缀。 | +| callback | AsyncCallback<[Entry](#entry)[]> | 是 | 回调函数。返回与指定Query对象匹配的键值对列表。 | + +**错误码:** + +以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 + +| **错误码ID** | **错误信息** | +| ------------ | -------------------------------------- | +| 15100003 | Database corrupted. | +| 15100005 | Not support the operation. | +| 15100006 | Database or result set already closed. | + +**示例:** + +```js +let kvStore; +try { + var arr = new Uint8Array([21, 31]); + let entries = []; + for (var i = 0; i < 10; i++) { + var key = 'batch_test_bool_key'; + var entry = { + key: key + i, + value: { + type: distributedKVStore.ValueType.BYTE_ARRAY, + value: arr + } + } + entries.push(entry); + } + console.log(`entries: {entries}`); + kvStore.putBatch(entries, async function (err, data) { + console.log('Succeeded in putting Batch'); + const query = new distributedKVStore.Query(); + query.prefixKey("batch_test"); + kvStore.getEntries(query, function (err, entries) { + if (err != undefined) { + console.error(`Fail to get Entries.code is ${err.code},message is ${err.message}`); + return; + } + console.log('Succeeded in getting Entries'); + console.log(`entries.length: ${entries.length}`); + console.log(`entries[0]: ${entries[0]}`); + }); + }); +} catch (e) { + console.error(`Fail to get Entries.code is ${e.code},message is ${e.message}`); +} +``` + +### getEntries + +getEntries(query: Query): Promise<Entry[]> + +获取与指定Query对象匹配的键值对列表,使用Promise异步回调。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| ------ | -------------- | ---- | -------------- | +| query | [Query](query) | 是 | 表示查询对象。 | + +**返回值:** + +| 类型 | 说明 | +| -------------------------------- | -------------------------------------------------- | +| Promise<[Entry](#entry)[]> | Promise对象。返回与指定Query对象匹配的键值对列表。 | + +**错误码:** + +以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 + +| **错误码ID** | **错误信息** | +| ------------ | -------------------------------------- | +| 15100003 | Database corrupted. | +| 15100005 | Not support the operation. | +| 15100006 | Database or result set already closed. | + +**示例:** + +```js +let kvStore; +try { + var arr = new Uint8Array([21, 31]); + let entries = []; + for (var i = 0; i < 10; i++) { + var key = 'batch_test_bool_key'; + var entry = { + key: key + i, + value: { + type: distributedKVStore.ValueType.BYTE_ARRAY, + value: arr + } + } + entries.push(entry); + } + console.log(`entries: {entries}`); + kvStore.putBatch(entries).then(async (err) => { + console.log('Succeeded in putting Batch'); + const query = new distributedKVStore.Query(); + query.prefixKey("batch_test"); + kvStore.getEntries(query).then((entries) => { + console.log('Succeeded in getting Entries'); + }).catch((err) => { + console.error(`Fail to get Entries.code is ${err.code},message is ${err.message}`); + }); + }).catch((err) => { + console.error(`Fail to get Entries.code is ${err.code},message is ${err.message}`) + }); + console.log('Succeeded in getting Entries'); +} catch (e) { + console.error(`Fail to get Entries.code is ${e.code},message is ${e.message}`); +} +``` + +### getResultSet + +getResultSet(keyPrefix: string, callback: AsyncCallback<KVStoreResultSet>): void + +从SingleKVStore数据库中获取具有指定前缀的结果集,使用callback异步回调。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| --------- | ---------------------------------------------------------- | ---- | ------------------------------------ | +| keyPrefix | string | 是 | 表示要匹配的键前缀。 | +| callback | AsyncCallback<[KVStoreResultSet](#kvstoreresultset)> | 是 | 回调函数。返回具有指定前缀的结果集。 | + +**错误码:** + +以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 + +| **错误码ID** | **错误信息** | +| ------------ | -------------------------------------- | +| 15100003 | Database corrupted. | +| 15100006 | Database or result set already closed. | + +**示例:** + +```js +let kvStore; +try { + let resultSet; + let entries = []; + for (var i = 0; i < 10; i++) { + var key = 'batch_test_string_key'; + var entry = { + key: key + i, + value: { + type: distributedKVStore.ValueType.STRING, + value: 'batch_test_string_value' + } + } + entries.push(entry); + } + kvStore.putBatch(entries, async function (err, data) { + if (err != undefined) { + console.error(`Fail to put batch.code is ${err.code},message is ${err.message}`); + return; + } + console.log('Succeeded in putting batch'); + kvStore.getResultSet('batch_test_string_key', async function (err, result) { + if (err != undefined) { + console.error(`Fail to get resultset.code is ${err.code},message is ${err.message}`); + return; + } + console.log('Succeeded in getting result set'); + resultSet = result; + kvStore.closeResultSet(resultSet, function (err, data) { + if (err != undefined) { + console.error(`Fail to close resultset.code is ${err.code},message is ${err.message}`); + return; + } + console.log('Succeeded in closing result set'); + }) + }); + }); +} catch (e) { + console.error(`An unexpected error occured.code is ${e.code},message is ${e.message}`); +} +``` + +### getResultSet + +getResultSet(keyPrefix: string): Promise<KVStoreResultSet> + +从SingleKVStore数据库中获取具有指定前缀的结果集,使用Promise异步回调。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| --------- | -------- | ---- | -------------------- | +| keyPrefix | string | 是 | 表示要匹配的键前缀。 | + +**返回值:** + +| 类型 | 说明 | +| ---------------------------------------------------- | --------------------------------------- | +| Promise<[KVStoreResultSet](#kvstoreresultset)> | Promise对象。返回具有指定前缀的结果集。 | + +**错误码:** + +以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 + +| **错误码ID** | **错误信息** | +| ------------ | -------------------------------------- | +| 15100003 | Database corrupted. | +| 15100006 | Database or result set already closed. | + +**示例:** + +```js +let kvStore; +try { + let resultSet; + let entries = []; + for (var i = 0; i < 10; i++) { + var key = 'batch_test_string_key'; + var entry = { + key: key + i, + value: { + type: distributedKVStore.ValueType.STRING, + value: 'batch_test_string_value' + } + } + entries.push(entry); + } + kvStore.putBatch(entries).then(async (err) => { + console.log('Succeeded in putting batch'); + }).catch((err) => { + console.error(`Fail to put batch.code is ${err.code},message is ${err.message}`); + }); + kvStore.getResultSet('batch_test_string_key').then((result) => { + console.log('Succeeded in getting result set'); + resultSet = result; + }).catch((err) => { + console.error(`Fail to get resultset.code is ${err.code},message is ${err.message}`); + }); + kvStore.closeResultSet(resultSet).then((err) => { + console.log('Succeeded in closing result set'); + }).catch((err) => { + console.error(`Fail to close resultset.code is ${err.code},message is ${err.message}`); + }); +} catch (e) { + console.error(`An unexpected error occured.code is ${e.code},message is ${e.code}`); +} +``` + +### getResultSet + +getResultSet(query: Query, callback: AsyncCallback<KVStoreResultSet>): void + +获取与指定Query对象匹配的KVStoreResultSet对象,使用callback异步回调。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| -------- | ---------------------------------------------------------- | ---- | --------------------------------------------------------- | +| query | Query | 是 | 表示查询对象。 | +| callback | AsyncCallback<[KVStoreResultSet](#kvstoreresultset)> | 是 | 回调函数,获取与指定Query对象匹配的KVStoreResultSet对象。 | + +**错误码:** + +以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 + +| **错误码ID** | **错误信息** | +| ------------ | -------------------------------------- | +| 15100003 | Database corrupted. | +| 15100006 | Database or result set already closed. | + +**示例:** + +```js +let kvStore; +try { + let resultSet; + let entries = []; + for (var i = 0; i < 10; i++) { + var key = 'batch_test_string_key'; + var entry = { + key: key + i, + value: { + type: distributedKVStore.ValueType.STRING, + value: 'batch_test_string_value' + } + } + entries.push(entry); + } + kvStore.putBatch(entries, async function (err, data) { + if (err != undefined) { + console.error(`Fail to put batch.code is ${err.code},message is ${err.message}`); + return; + } + console.log('Succeeded in putting batch'); + const query = new distributedKVStore.Query(); + query.prefixKey("batch_test"); + kvStore.getResultSet(query, async function (err, result) { + if (err != undefined) { + console.error(`Fail to get resultset.code is ${err.code},message is ${err.message}`); + return; + } + console.log('Succeeded in getting result set'); + }); + }); +} catch (e) { + console.error(`An unexpected error occured.code is ${e.code},message is ${e.message}`); +} +``` + +### getResultSet + +getResultSet(query: Query): Promise<KVStoreResultSet> + +获取与指定Query对象匹配的KVStoreResultSet对象,使用Promise异步回调。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| ------ | -------------- | ---- | -------------- | +| query | [Query](query) | 是 | 表示查询对象。 | + +**返回值:** + +| 类型 | 说明 | +| ---------------------------------------------------- | ------------------------------------------------------------ | +| Promise<[KVStoreResultSet](#kvstoreresultset)> | Promise对象。获取与指定Query对象匹配的KVStoreResultSet对象。 | + +**错误码:** + +以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 + +| **错误码ID** | **错误信息** | +| ------------ | -------------------------------------- | +| 15100003 | Database corrupted. | +| 15100006 | Database or result set already closed. | + +**示例:** + +```js +let kvStore; +try { + let resultSet; + let entries = []; + for (var i = 0; i < 10; i++) { + var key = 'batch_test_string_key'; + var entry = { + key: key + i, + value: { + type: distributedKVStore.ValueType.STRING, + value: 'batch_test_string_value' + } + } + entries.push(entry); + } + kvStore.putBatch(entries).then(async (err) => { + console.log('Succeeded in putting batch'); + }).catch((err) => { + console.error(`Fail to put batch.code is ${err.code},message is ${err.message}`); + }); + const query = new distributedKVStore.Query(); + query.prefixKey("batch_test"); + kvStore.getResultSet(query).then((result) => { + console.log('Succeeded in getting result set'); + resultSet = result; + }).catch((err) => { + console.error(`Fail to get resultset.code is ${err.code},message is ${err.message}`); + }); +} catch (e) { + console.error(`An unexpected error occured.code is ${e.code},message is ${e.code}`); +} +``` + +### getResultSet + +getResultSet(predicates: dataSharePredicates.DataSharePredicates, callback: AsyncCallback<KVStoreResultSet>): void + +获取与指定Predicate对象匹配的KVStoreResultSet对象,使用callback异步回调。 + +**系统接口:** 此接口为系统接口。 + +**系统能力:** SystemCapability.DistributedDataManager.DataShare.Provider + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | +| predicates | [DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | 是 | 指示筛选条件,当此参数为null时,应定义处理逻辑。 | +| callback | AsyncCallback<[KVStoreResultSet](#kvstoreresultset)> | 是 | 回调函数,获取与指定Predicates对象匹配的KVStoreResultSet对象。 | + +**错误码:** + +以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 + +| **错误码ID** | **错误信息** | +| ------------ | -------------------------------------- | +| 15100003 | Database corrupted. | +| 15100006 | Database or result set already closed. | + +**示例:** + +```js +import dataSharePredicates from '@ohos.data.dataSharePredicates'; + +let kvStore; +try { + let resultSet; + let predicates = new dataSharePredicates.DataSharePredicates(); + predicates.prefixKey("batch_test_string_key"); + kvStore.getResultSet(predicates, async function (err, result) { + if (err != undefined) { + console.error(`Fail to get resultset.code is ${err.code},message is ${err.message}`); + return; + } + console.log('Succeeded in getting result set'); + resultSet = result; + kvStore.closeResultSet(resultSet, function (err, data) { + if (err != undefined) { + console.error(`Fail to close resultset.code is ${err.code},message is ${err.message}`); + return; + } + console.log('Succeeded in closing result set'); + }) + }); +} catch (e) { + console.error(`An unexpected error occured.code is ${e.code},message is ${e.code}`); +} +``` + +### getResultSet + +getResultSet(predicates: dataSharePredicates.DataSharePredicates): Promise<KVStoreResultSet> + +获取与指定Predicate对象匹配的KVStoreResultSet对象,使用Promise异步回调。 + +**系统接口:** 此接口为系统接口。 + +**系统能力:** SystemCapability.DistributedDataManager.DataShare.Provider + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| ---------- | ------------------------------------------------------------ | ---- | ----------------------------------------------- | +| predicates | [DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | 是 | 指示筛选条件,当此参数为null时,应定义处理逻辑。 | + +**返回值:** + +| 类型 | 说明 | +| ---------------------------------------------------- | ------------------------- | +| Promise<[KVStoreResultSet](#kvstoreresultset)> | 无返回结果的Promise对象。 | + +**错误码:** + +以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 + +| **错误码ID** | **错误信息** | +| ------------ | -------------------------------------- | +| 15100003 | Database corrupted. | +| 15100006 | Database or result set already closed. | + +**示例:** + +```js +import dataSharePredicates from '@ohos.data.dataSharePredicates'; + +let kvStore; +try { + let resultSet; + let predicates = new dataSharePredicates.DataSharePredicates(); + predicates.prefixKey("batch_test_string_key"); + kvStore.getResultSet(predicates).then((result) => { + console.log('Succeeded in getting result set'); + resultSet = result; + }).catch((err) => { + console.error(`Fail to get resultset.code is ${err.code},message is ${err.message}`); + }); + kvStore.closeResultSet(resultSet).then((err) => { + console.log('Succeeded in closing result set'); + }).catch((err) => { + console.error(`Fail to close resultset.code is ${err.code},message is ${err.message}`); + }); +} catch (e) { + console.error(`An unexpected error occured.code is ${e.code},message is ${e.code}`); +} +``` + +### closeResultSet + +closeResultSet(resultSet: KVStoreResultSet, callback: AsyncCallback<void>): void + +关闭由[SingleKvStore.getResultSet](#getresultset-1)返回的KVStoreResultSet对象,使用callback异步回调。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| --------- | ------------------------------------- | ---- | ---------------------------------- | +| resultSet | [KVStoreResultSet](#kvstoreresultset) | 是 | 表示要关闭的KVStoreResultSet对象。 | +| callback | AsyncCallback<void> | 是 | 回调函数。 | + +**示例:** + +```js +let kvStore; +try { + let resultSet = null; + kvStore.closeResultSet(resultSet, function (err, data) { + if (err == undefined) { + console.log('Succeeded in closing result set'); + } else { + console.error(`Fail to close resultset.code is ${err.code},message is ${err.message}`); + } + }); +} catch (e) { + console.error(`An unexpected error occured.code is ${e.code},message is ${e.code}`); +} +``` + +### closeResultSet + +closeResultSet(resultSet: KVStoreResultSet): Promise<void> + +关闭由[SingleKvStore.getResultSet](#getresultset-1)返回的KVStoreResultSet对象,使用Promise异步回调。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| --------- | ------------------------------------- | ---- | ---------------------------------- | +| resultSet | [KVStoreResultSet](#kvstoreresultset) | 是 | 表示要关闭的KVStoreResultSet对象。 | + +**返回值:** + +| 类型 | 说明 | +| ------------------- | ------------------------- | +| Promise<void> | 无返回结果的Promise对象。 | + +**示例:** + +```js +let kvStore; +try { + let resultSet = null; + kvStore.closeResultSet(resultSet).then(() => { + console.log('Succeeded in closing result set'); + }).catch((err) => { + console.error(`Fail to close resultset.code is ${err.code},message is ${err.message}`); + }); +} catch (e) { + console.error(`An unexpected error occured.code is ${e.code},message is ${e.code}`); +} +``` + +### getResultSize + +getResultSize(query: Query, callback: AsyncCallback<number>): void + +获取与指定Query对象匹配的结果数,使用callback异步回调。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| -------- | --------------------------- | ---- | ------------------------------------------- | +| query | [Query](query) | 是 | 表示查询对象。 | +| callback | AsyncCallback<number> | 是 | 回调函数。返回与指定Query对象匹配的结果数。 | + +**错误码:** + +以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 + +| **错误码ID** | **错误信息** | +| ------------ | -------------------------------------- | +| 15100003 | Database corrupted. | +| 15100006 | Database or result set already closed. | + +**示例:** + +```js +let kvStore; +try { + let entries = []; + for (var i = 0; i < 10; i++) { + var key = 'batch_test_string_key'; + var entry = { + key: key + i, + value: { + type: distributedKVStore.ValueType.STRING, + value: 'batch_test_string_value' + } + } + entries.push(entry); + } + kvStore.putBatch(entries, async function (err, data) { + console.log('Succeeded in putting batch'); + const query = new distributedKVStore.Query(); + query.prefixKey("batch_test"); + kvStore.getResultSize(query, async function (err, resultSize) { + if (err != undefined) { + console.error(`Fail to get result size.code is ${err.code},message is ${err.message}`); + return; + } + console.log('Succeeded in getting result set size'); + }); + }); +} catch (e) { + console.error(`An unexpected error occured.code is ${e.code},message is ${e.code}`); +} +``` + +### getResultSize + +getResultSize(query: Query): Promise<number> + +获取与指定Query对象匹配的结果数,使用Promise异步回调。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| ------ | -------------- | ---- | -------------- | +| query | [Query](query) | 是 | 表示查询对象。 | + +**返回值:** + +| 类型 | 说明 | +| --------------------- | ----------------------------------------------- | +| Promise<number> | Promise对象。获取与指定QuerV9对象匹配的结果数。 | + +**错误码:** + +以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 + +| **错误码ID** | **错误信息** | +| ------------ | -------------------------------------- | +| 15100003 | Database corrupted. | +| 15100006 | Database or result set already closed. | + +**示例:** + +```js +let kvStore; +try { + let entries = []; + for (var i = 0; i < 10; i++) { + var key = 'batch_test_string_key'; + var entry = { + key: key + i, + value: { + type: distributedKVStore.ValueType.STRING, + value: 'batch_test_string_value' + } + } + entries.push(entry); + } + kvStore.putBatch(entries).then(async (err) => { + console.log('Succeeded in putting batch'); + }).catch((err) => { + console.error(`Fail to put batch.code is ${err.code},message is ${err.message}`); + }); + const query = new distributedKVStore.Query(); + query.prefixKey("batch_test"); + kvStore.getResultSize(query).then((resultSize) => { + console.log('Succeeded in getting result set size'); + }).catch((err) => { + console.error(`Fail to get result size.code is ${err.code},message is ${err.message}`); + }); +} catch (e) { + console.error(`An unexpected error occured.code is ${e.code},message is ${e.code}`); +} +``` + +### backup + +backup(file:string, callback: AsyncCallback<void>):void + +以指定名称备份数据库,使用callback异步回调。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| -------- | ------------------------- | ---- | ------------------------------------------------------------ | +| file | string | 是 | 备份数据库的指定名称,不能为空且长度不大于[MAX_KEY_LENGTH](#constants)。 | +| callback | AsyncCallback<void> | 是 | 回调函数。当以指定名称备份数据库成功,err为undefined,否则为错误对象。 | + +**错误码:** + +以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 + +| **错误码ID** | **错误信息** | +| ------------ | -------------------------------------- | +| 15100005 | Not support the operation. | +| 15100006 | Database or result set already closed. | + +**示例:** + +```js +let kvStore; +let file = "BK001"; +try { + kvStore.backup(file, (err, data) => { + if (err) { + console.error(`Fail to backup.code is ${err.code},message is ${err.message} `); + } else { + console.info(`Succeeded in backupping data.data=${data}`); + } + }); +} catch (e) { + console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`); +} +``` + +### backup + +backup(file:string): Promise<void> + +以指定名称备份数据库,使用Promise异步回调。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| ------ | -------- | ---- | ------------------------------------------------------------ | +| file | string | 是 | 备份数据库的指定名称,不能为空且长度不大于[MAX_KEY_LENGTH](#constants)。 | + +**返回值:** + +| 类型 | 说明 | +| ------------------- | ------------------------- | +| Promise<void> | 无返回结果的Promise对象。 | + +**错误码:** + +以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 + +| **错误码ID** | **错误信息** | +| ------------ | -------------------------------------- | +| 15100005 | Not support the operation. | +| 15100006 | Database or result set already closed. | + +**示例:** + +```js +let kvStore; +let file = "BK001"; +try { + kvStore.backup(file).then((data) => { + console.info(`Succeeded in backupping data.data=${data}`); + }).catch((err) => { + console.error(`Fail to backup.code is ${err.code},message is ${err.message}`); + }); +} catch (e) { + console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`); +} +``` + +### restore + +restore(file:string, callback: AsyncCallback<void>):void + +从指定的数据库文件恢复数据库,使用callback异步回调。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| -------- | ------------------------- | ---- | ------------------------------------------------------------ | +| file | string | 是 | 指定的数据库文件名称,不能为空且长度不大于[MAX_KEY_LENGTH](#constants)。 | +| callback | AsyncCallback<void> | 是 | 回调函数。当从指定的数据库文件恢复数据库成功,err为undefined,否则为错误对象。 | + +**错误码:** + +以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 + +| **错误码ID** | **错误信息** | +| ------------ | -------------------------------------- | +| 15100005 | Not support the operation. | +| 15100006 | Database or result set already closed. | + +**示例:** + +```js +let kvStore; +let file = "BK001"; +try { + kvStore.restore(file, (err, data) => { + if (err) { + console.error(`Fail to restore.code is ${err.code},message is ${err.message}`); + } else { + console.info(`Succeeded in restoring data.data=${data}`); + } + }); +} catch (e) { + console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`); +} +``` + +### restore + +restore(file:string): Promise<void> + +从指定的数据库文件恢复数据库,使用Promise异步回调。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| ------ | -------- | ---- | ------------------------------------------------------------ | +| file | string | 是 | 指定的数据库文件名称,不能为空且长度不大于[MAX_KEY_LENGTH](#constants)。 | + +**返回值:** + +| 类型 | 说明 | +| ------------------- | ------------------------- | +| Promise<void> | 无返回结果的Promise对象。 | + +**错误码:** + +以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 + +| **错误码ID** | **错误信息** | +| ------------ | -------------------------------------- | +| 15100005 | Not support the operation. | +| 15100006 | Database or result set already closed. | + +**示例:** + +```js +let kvStore; +let file = "BK001"; +try { + kvStore.restore(file).then((data) => { + console.info(`Succeeded in restoring data.data=${data}`); + }).catch((err) => { + console.error(`Fail to restore.code is ${err.code},message is ${err.message}`); + }); +} catch (e) { + console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`); +} +``` + +### deleteBackup + +deleteBackup(files:Array<string>, callback: AsyncCallback<Array<[string, number]>>):void + +根据指定名称删除备份文件,使用callback异步回调。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| -------- | -------------------------------------------------- | ---- | ------------------------------------------------------------ | +| files | Array<string> | 是 | 删除备份文件所指定的名称,不能为空且长度不大于[MAX_KEY_LENGTH](#constants)。 | +| callback | AsyncCallback<Array<[string, number]>> | 是 | 回调函数,返回删除备份的文件名及其处理结果。 | + +**示例:** + +```js +let kvStore; +let files = ["BK001", "BK002"]; +try { + kvStore.deleteBackup(files, (err, data) => { + if (err) { + console.error(`Fail to delete Backup.code is ${err.code},message is ${err.message}`); + } else { + console.info(`Succeed in deleting Backup.data=${data}`); + } + }); +} catch (e) { + console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`); +} +``` + +### deleteBackup + +deleteBackup(files:Array<string>): Promise<Array<[string, number]>> + +根据指定名称删除备份文件,使用Promise异步回调。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| ------ | ------------------- | ---- | ------------------------------------------------------------ | +| files | Array<string> | 是 | 删除备份文件所指定的名称,不能为空且长度不大于[MAX_KEY_LENGTH](#constants)。 | + +**返回值:** + +| 类型 | 说明 | +| -------------------------------------------- | ----------------------------------------------- | +| Promise<Array<[string, number]>> | Promise对象,返回删除备份的文件名及其处理结果。 | + +**示例:** + +```js +let kvStore; +let files = ["BK001", "BK002"]; +try { + kvStore.deleteBackup(files).then((data) => { + console.info(`Succeed in deleting Backup.data=${data}`); + }).catch((err) => { + console.error(`Fail to delete Backup.code is ${err.code},message is ${err.message}`); + }) +} catch (e) { + console.log(`An unexpected error occurred.code is ${e.code},message is ${e.message}`); +} +``` + +### startTransaction + +startTransaction(callback: AsyncCallback<void>): void + +启动SingleKVStore数据库中的事务,使用callback异步回调。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| -------- | ------------------------- | ---- | ---------- | +| callback | AsyncCallback<void> | 是 | 回调函数。 | + +**错误码:** + +以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 + +| **错误码ID** | **错误信息** | +| ------------ | -------------------------------------- | +| 15100006 | Database or result set already closed. | + +**示例:** + +```js +let kvStore; +function putBatchString(len, prefix) { + let entries = []; + for (var i = 0; i < len; i++) { + var entry = { + key: prefix + i, + value: { + type: distributedKVStore.ValueType.STRING, + value: 'batch_test_string_value' + } + } + entries.push(entry); + } + return entries; +} + +try { + var count = 0; + kvStore.on('dataChange', 0, function (data) { + console.log(`startTransaction 0 ${data}`); + count++; + }); + kvStore.startTransaction(async function (err, data) { + if (err != undefined) { + console.error(`Fail to start Transaction.code is ${e.code},message is ${e.message}`); + return; + } + console.log('Succeeded in starting Transaction'); + let entries = putBatchString(10, 'batch_test_string_key'); + console.log(`entries: ${entries}`); + kvStore.putBatch(entries, async function (err, data) { + if (err != undefined) { + console.error(`Fail to put batch.code is ${e.code},message is ${e.message}`); + return; + } + console.log('Succeeded in putting Batch'); + }); + }); +} catch (e) { + console.error(`Fail to start Transaction.code is ${e.code},message is ${e.message}`); +} +``` + +### startTransaction + +startTransaction(): Promise<void> + +启动SingleKVStore数据库中的事务,使用Promise异步回调。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**返回值:** + +| 类型 | 说明 | +| ------------------- | ------------------------- | +| Promise<void> | 无返回结果的Promise对象。 | + +**错误码:** + +以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 + +| **错误码ID** | **错误信息** | +| ------------ | -------------------------------------- | +| 15100006 | Database or result set already closed. | + +**示例:** + +```js +let kvStore; +try { + var count = 0; + kvStore.on('dataChange', distributedKVStore.SubscribeType.SUBSCRIBE_TYPE_ALL, function (data) { + console.log(`startTransaction 0 ${data}`); + count++; + }); + kvStore.startTransaction().then(async (err) => { + console.log('Succeeded in starting Transaction'); + }).catch((err) => { + console.error(`Fail to start Transaction.code is ${err.code},message is ${err.message}`); + }); +} catch (e) { + console.error(`Fail to start Transaction.code is ${e.code},message is ${e.message}`); +} +``` + +### commit + +commit(callback: AsyncCallback<void>): void + +提交SingleKVStore数据库中的事务,使用callback异步回调。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| -------- | ------------------------- | ---- | ---------- | +| callback | AsyncCallback<void> | 是 | 回调函数。 | + +**错误码:** + +以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 + +| **错误码ID** | **错误信息** | +| ------------ | -------------------------------------- | +| 15100006 | Database or result set already closed. | + +**示例:** + +```js +let kvStore; +try { + kvStore.commit(function (err, data) { + if (err == undefined) { + console.log('Succeeded in committing'); + } else { + console.error(`Fail to commit.code is ${err.code},message is ${err.message}`); + } + }); +} catch (e) { + console.error(`An unexpected error occured.code is ${e.code},message is ${e.message}`); +} +``` + +### commit + +commit(): Promise<void> + +提交SingleKVStore数据库中的事务,使用Promise异步回调。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**返回值:** + +| 类型 | 说明 | +| ------------------- | ------------------------- | +| Promise<void> | 无返回结果的Promise对象。 | + +**错误码:** + +以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 + +| **错误码ID** | **错误信息** | +| ------------ | -------------------------------------- | +| 15100006 | Database or result set already closed. | + +**示例:** + +```js +let kvStore; +try { + kvStore.commit().then(async (err) => { + console.log('Succeeded in committing'); + }).catch((err) => { + console.error(`Fail to commit.code is ${err.code},message is ${err.message}`); + }); +} catch (e) { + console.error(`An unexpected error occured.ode is ${e.code},message is ${e.message}`); +} +``` + +### rollback + +rollback(callback: AsyncCallback<void>): void + +在SingleKVStore数据库中回滚事务,使用callback异步回调。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| -------- | ------------------------- | ---- | ---------- | +| callback | AsyncCallback<void> | 是 | 回调函数。 | + +**错误码:** + +以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 + +| **错误码ID** | **错误信息** | +| ------------ | -------------------------------------- | +| 15100006 | Database or result set already closed. | + +**示例:** + +```js +let kvStore; +try { + kvStore.rollback(function (err,data) { + if (err == undefined) { + console.log('Succeeded in rolling back'); + } else { + console.error(`Fail to rollback.code is ${err.code},message is ${err.message}`); + } + }); +}catch(e) { + console.error(`An unexpected error occured.code is ${e.code},message is ${e.message}`); +} +``` + +### rollback + +rollback(): Promise<void> + +在SingleKVStore数据库中回滚事务,使用Promise异步回调。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**返回值:** + +| 类型 | 说明 | +| ------------------- | ------------------------- | +| Promise<void> | 无返回结果的Promise对象。 | + +**错误码:** + +以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 + +| **错误码ID** | **错误信息** | +| ------------ | -------------------------------------- | +| 15100006 | Database or result set already closed. | + +**示例:** + +```js +let kvStore; +try { + kvStore.rollback().then(async (err) => { + console.log('Succeeded in rolling back'); + }).catch((err) => { + console.error(`Fail to rollback.code is ${err.code},message is ${err.message}`); + }); +} catch (e) { + console.error(`An unexpected error occured.code is ${e.code},message is ${e.message}`); +} +``` + +### enableSync + +enableSync(enabled: boolean, callback: AsyncCallback<void>): void + +设定是否开启同步,使用callback异步回调。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| -------- | ------------------------- | ---- | --------------------------------------------------------- | +| enabled | boolean | 是 | 设定是否开启同步,true表示开启同步,false表示不启用同步。 | +| callback | AsyncCallback<void> | 是 | 回调函数。 | + +**示例:** + +```js +let kvStore; +try { + kvStore.enableSync(true, function (err, data) { + if (err == undefined) { + console.log('Succeeded in enabling sync'); + } else { + console.error(`Fail to enable sync.code is ${err.code},message is ${err.message}`); + } + }); +} catch (e) { + console.error(`An unexpected error occured.code is ${e.code},message is ${e.message}`); +} +``` + +### enableSync + +enableSync(enabled: boolean): Promise<void> + +设定是否开启同步,使用Promise异步回调。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| ------- | -------- | ---- | --------------------------------------------------------- | +| enabled | boolean | 是 | 设定是否开启同步,true表示开启同步,false表示不启用同步。 | + +**返回值:** + +| 类型 | 说明 | +| ------------------- | ------------------------- | +| Promise<void> | 无返回结果的Promise对象。 | + +**示例:** + +```js +let kvStore; +try { + kvStore.enableSync(true).then((err) => { + console.log('Succeeded in enabling sync'); + }).catch((err) => { + console.error(`Fail to enable sync.code is ${err.code},message is ${err.message}`); + }); +} catch (e) { + console.error(`An unexpected error occured.code is ${e.code},message is ${e.message}`); +} +``` + +### setSyncRange + +setSyncRange(localLabels: string[], remoteSupportLabels: string[], callback: AsyncCallback<void>): void + +设置同步范围标签,使用callback异步回调。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| ------------------- | ------------------------- | ---- | -------------------------------- | +| localLabels | string[] | 是 | 表示本地设备的同步标签。 | +| remoteSupportLabels | string[] | 是 | 表示要同步数据的设备的同步标签。 | +| callback | AsyncCallback<void> | 是 | 回调函数。 | + +**示例:** + +```js +let kvStore; +try { + const localLabels = ['A', 'B']; + const remoteSupportLabels = ['C', 'D']; + kvStore.setSyncRange(localLabels, remoteSupportLabels, function (err, data) { + if (err != undefined) { + console.error(`Fail to set syncRange.code is ${err.code},message is ${err.message}`); + return; + } + console.log('Succeeded in setting syncRange'); + }); +} catch (e) { + console.error(`An unexpected error occured.code is ${e.code},message is ${e.message}`); +} +``` + +### setSyncRange + +setSyncRange(localLabels: string[], remoteSupportLabels: string[]): Promise<void> + +设置同步范围标签,使用Promise异步回调。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| ------------------- | -------- | ---- | -------------------------------- | +| localLabels | string[] | 是 | 表示本地设备的同步标签。 | +| remoteSupportLabels | string[] | 是 | 表示要同步数据的设备的同步标签。 | + +**返回值:** + +| 类型 | 说明 | +| ------------------- | ------------------------- | +| Promise<void> | 无返回结果的Promise对象。 | + +**示例:** + +```js +let kvStore; +try { + const localLabels = ['A', 'B']; + const remoteSupportLabels = ['C', 'D']; + kvStore.setSyncRange(localLabels, remoteSupportLabels).then((err) => { + console.log('Succeeded in setting syncRange'); + }).catch((err) => { + console.error(`Fail to set syncRange.code is ${err.code},message is ${err.message}`); + }); +} catch (e) { + console.error(`An unexpected error occured.code is ${e.code},message is ${e.message}`); +} +``` + +### setSyncParam + +setSyncParam(defaultAllowedDelayMs: number, callback: AsyncCallback<void>): void + +设置数据库同步允许的默认延迟,使用callback异步回调。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| --------------------- | ------------------------- | ---- | -------------------------------------------- | +| defaultAllowedDelayMs | number | 是 | 表示数据库同步允许的默认延迟,以毫秒为单位。 | +| callback | AsyncCallback<void> | 是 | 回调函数。 | + +**示例:** + +```js +let kvStore; +try { + const defaultAllowedDelayMs = 500; + kvStore.setSyncParam(defaultAllowedDelayMs, function (err, data) { + if (err != undefined) { + console.error(`Fail to set syncParam.code is ${err.code},message is ${err.message}`); + return; + } + console.log('Succeeded in setting syncParam'); + }); +} catch (e) { + console.error(`An unexpected error occured.code is ${e.code},message is ${e.message}`); +} +``` + +### setSyncParam + +setSyncParam(defaultAllowedDelayMs: number): Promise<void> + +设置数据库同步允许的默认延迟,使用Promise异步回调。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| --------------------- | -------- | ---- | -------------------------------------------- | +| defaultAllowedDelayMs | number | 是 | 表示数据库同步允许的默认延迟,以毫秒为单位。 | + +**返回值:** + +| 类型 | 说明 | +| ------------------- | ------------------------- | +| Promise<void> | 无返回结果的Promise对象。 | + +**示例:** + +```js +let kvStore; +try { + const defaultAllowedDelayMs = 500; + kvStore.setSyncParam(defaultAllowedDelayMs).then((err) => { + console.log('Succeeded in setting syncParam'); + }).catch((err) => { + console.error(`Fail to set syncParam.code is ${err.code},message is ${err.message}`); + }); +} catch (e) { + console.error(`An unexpected error occured.code is ${e.code},message is ${e.message}`); +} +``` + +### sync + +sync(deviceIds: string[], mode: SyncMode, delayMs?: number): void + +在手动同步方式下,触发数据库同步。关于分布式数据服务的同步方式说明,请见[分布式数据服务概述](../../database/database-mdds-overview.md)。 + +**需要权限**: ohos.permission.DISTRIBUTED_DATASYNC。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| --------- | --------------------- | ---- | ---------------------------------------------- | +| deviceIds | string[] | 是 | 同一组网环境下,需要同步的设备的deviceId列表。 | +| mode | [SyncMode](#syncmode) | 是 | 同步模式。 | +| delayMs | number | 否 | 可选参数,允许延时时间,单位:ms(毫秒)。 | + +**错误码:** + +以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 + +| **错误码ID** | **错误信息** | +| ------------ | ------------------- | +| 15100003 | Database corrupted. | +| 15100004 | Not found. | + +**示例:** + +```js +let kvStore; +try { + kvStore.sync('deviceIds', distributedKVStore.SyncMode.PULL_ONLY, 1000); +} catch (err) { + console.error(`Fail to syn.code is ${err.code},message is ${err.message}`); +} +``` + +### sync + +sync(deviceIds: string[], query: Query, mode: SyncMode, delayMs?: number): void + +在手动同步方式下,触发数据库同步,此方法为同步方法。关于分布式数据服务的同步方式说明,请见[分布式数据服务概述](../../database/database-mdds-overview.md)。 + +**需要权限**: ohos.permission.DISTRIBUTED_DATASYNC。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| --------- | --------------------- | ---- | ---------------------------------------------- | +| deviceIds | string[] | 是 | 同一组网环境下,需要同步的设备的deviceId列表。 | +| mode | [SyncMode](#syncmode) | 是 | 同步模式。 | +| query | [Query](query) | 是 | 表示数据库的查询谓词条件 | +| delayMs | number | 否 | 可选参数,允许延时时间,单位:ms(毫秒)。 | + +**错误码:** + +以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 + +| **错误码ID** | **错误信息** | +| ------------ | ------------------- | +| 15100003 | Database corrupted. | +| 15100004 | Not found. | + +**示例:** + +```js +let kvStore; +const KEY_TEST_SYNC_ELEMENT = 'key_test_sync'; +const VALUE_TEST_SYNC_ELEMENT = 'value-string-001'; +try { + kvStore.on('syncComplete', function (data) { + console.log('Sync dataChange'); + }); + kvStore.put(KEY_TEST_SYNC_ELEMENT + 'testSync101', VALUE_TEST_SYNC_ELEMENT, function (err, data) { + if (err != undefined) { + console.error(`Fail to sync.code is ${err.code},message is ${err.message}`); + return; + } + console.log('Succeeded in putting data'); + const devices = ['deviceList']; + const mode = distributedKVStore.SyncMode.PULL_ONLY; + const query = new distributedKVStore.Query(); + query.prefixKey("batch_test"); + query.deviceId('localDeviceId'); + kvStore.sync(devices, query, mode, 1000); + }); +} catch (e) { + console.error(`Fail to sync.code is ${e.code},message is ${e.message}`); +} +``` + +### on('dataChange') + +on(event: 'dataChange', type: SubscribeType, listener: Callback<ChangeNotification>): void + +订阅指定类型的数据变更通知,此方法为同步方法。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| -------- | --------------------------------------------------------- | ---- | ---------------------------------------------------- | +| event | string | 是 | 订阅的事件名,固定为'dataChange',表示数据变更事件。 | +| type | [SubscribeType](#subscribetype) | 是 | 表示订阅的类型。 | +| listener | Callback<[ChangeNotification](#changenotification)> | 是 | 回调函数。 | + +**错误码:** + +以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 + +| **错误码ID** | **错误信息** | +| ------------ | -------------------------------------- | +| 15100001 | Over max subscribe limits. | +| 15100006 | Database or result set already closed. | + +**示例:** + +```js +let kvStore; +try { + kvStore.on('dataChange', distributedKVStore.SubscribeType.SUBSCRIBE_TYPE_LOCAL, function (data) { + console.log(`dataChange callback call data: ${data}`); + }); +} catch (e) { + console.error(`An unexpected error occured.code is ${e.code},message is ${e.message}`); +} +``` + +### on('syncComplete') + +on(event: 'syncComplete', syncCallback: Callback<Array<[string, number]>>): void + +订阅同步完成事件回调通知,此方法为同步方法。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| ------------ | --------------------------------------------- | ---- | ------------------------------------------------------ | +| event | string | 是 | 订阅的事件名,固定为'syncComplete',表示同步完成事件。 | +| syncCallback | Callback<Array<[string, number]>> | 是 | 回调函数。用于向调用方发送同步结果的回调。 | + +**示例:** + +```js +let kvStore; +const KEY_TEST_FLOAT_ELEMENT = 'key_test_float'; +const VALUE_TEST_FLOAT_ELEMENT = 321.12; +try { + kvStore.on('syncComplete', function (data) { + console.log(`syncComplete ${data}`); + }); + kvStore.put(KEY_TEST_FLOAT_ELEMENT, VALUE_TEST_FLOAT_ELEMENT).then((data) => { + console.log('succeeded in putting'); + }).catch((err) => { + console.error(`Fail to put.code is ${err.code},message is ${err.message}`); + }); +} catch (e) { + console.error(`Fail to subscribe syncComplete.code is ${e.code},message is ${e.message}`); +} +``` + +### off('dataChange') + +off(event:'dataChange', listener?: Callback<ChangeNotification>): void + +取消订阅数据变更通知,此方法为同步方法。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| -------- | --------------------------------------------------------- | ---- | -------------------------------------------------------- | +| event | string | 是 | 取消订阅的事件名,固定为'dataChange',表示数据变更事件。 | +| listener | Callback<[ChangeNotification](#changenotification)> | 否 | 回调函数。 | + +**错误码:** + +以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 + +| **错误码ID** | **错误信息** | +| ------------ | -------------------------------------- | +| 15100006 | Database or result set already closed. | + +**示例:** + +```js +let kvStore; +class KvstoreModel { + call(data) { + console.log(`dataChange : ${data}`); + } + + subscribeDataChange() { + try { + if (kvStore != null) { + kvStore.on('dataChange', distributedKVStore.SubscribeType.SUBSCRIBE_TYPE_REMOTE, this.call); + } + } catch (err) { + console.error(`Fail to subscribeDataChange.code is ${err.code},message is ${err.message}`); + } + } + + unsubscribeDataChange() { + try { + if (kvStore != null) { + kvStore.off('dataChange', this.call); + } + } catch (err) { + console.error(`Fail to unsubscribeDataChange.code is ${err.code},message is ${err.message}`); + } + } +} +``` + +### off('syncComplete') + +off(event: 'syncComplete', syncCallback?: Callback<Array<[string, number]>>): void + +取消订阅同步完成事件回调通知,此方法为同步方法。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| ------------ | --------------------------------------------- | ---- | ---------------------------------------------------------- | +| event | string | 是 | 取消订阅的事件名,固定为'syncComplete',表示同步完成事件。 | +| syncCallback | Callback<Array<[string, number]>> | 否 | 回调函数。用于向调用方发送同步结果的回调。 | + +**示例:** + +```js +let kvStore; +class KvstoreModel { + call(data) { + console.log(`syncComplete : ${data}`); + } + + subscribeDataChange() { + try { + if (kvStore != null) { + kvStore.on('syncComplete', distributedKVStore.SubscribeType.SUBSCRIBE_TYPE_REMOTE, this.call); + } + } catch (err) { + console.error(`Fail to subscribeDataChange.code is ${err.code},message is ${err.message}`); + } + } + + unsubscribeDataChange() { + try { + if (kvStore != null) { + kvStore.off('dsyncComplete', this.call); + } + } catch (err) { + console.error(`Fail to unsubscribeDataChange.code is ${err.code},message is ${err.message}`); + } + } +} +``` + +### getSecurityLevel + +getSecurityLevel(callback: AsyncCallback<SecurityLevel>): void + +获取数据库的安全级别,使用callback异步回调。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| -------- | ---------------------------------------------------- | ---- | -------------------------------- | +| callback | AsyncCallback<[SecurityLevel](#securitylevel)> | 是 | 回调函数。返回数据库的安全级别。 | + +**错误码:** + +以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 + +| **错误码ID** | **错误信息** | +| ------------ | -------------------------------------- | +| 15100006 | Database or result set already closed. | + +**示例:** + +```js +let kvStore; +try { + kvStore.getSecurityLevel(function (err, data) { + if (err != undefined) { + console.error(`Fail to get SecurityLevel.code is ${err.code},message is ${err.message}`); + return; + } + console.log('Succeeded in getting securityLevel'); + }); +} catch (e) { + console.error(`An unexpected error occured.code is ${e.code},message is ${e.message}`); +} +``` + +### getSecurityLevel + +getSecurityLevel(): Promise<SecurityLevel> + +获取数据库的安全级别,使用Promise异步回调。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.Core + +**返回值:** + +| 类型 | 说明 | +| ---------------------------------------------- | ----------------------------------- | +| Promise<[SecurityLevel](#securitylevel)> | Promise对象。返回数据库的安全级别。 | + +**错误码:** + +以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 + +| **错误码ID** | **错误信息** | +| ------------ | -------------------------------------- | +| 15100006 | Database or result set already closed. | + +**示例:** + +```js +let kvStore; +try { + kvStore.getSecurityLevel().then((data) => { + console.log('Succeeded in getting securityLevel'); + }).catch((err) => { + console.error(`Fail to get SecurityLevel.code is ${err.code},message is ${err.message}`); + }); +} catch (e) { + console.error(`An unexpected error occured.code is ${e.code},message is ${e.message}`); +} +``` + +## DeviceKVStore + +设备协同数据库,继承自SingleKVStore,提供查询数据和同步数据的方法。 + +设备协同数据库,以设备维度对数据进行区分,每台设备仅能写入和修改本设备的数据,其它设备的数据对其是只读的,无法修改其它设备的数据。 + +比如,可以使用设备协同数据库实现设备间的图片分享,可以查看其他设备的图片,但无法修改和删除其他设备的图片。 + +在调用DeviceKVStore的方法前,需要先通过[getKVStore](#getkvstore)构建一个DeviceKVStore实例。 + +### get + +get(deviceId: string, key: string, callback: AsyncCallback<boolean|string|number|Uint8Array>): void + +获取与指定设备ID和key匹配的string值,使用callback异步回调。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| ----- | ------ | ---- | ----------------------- | +| deviceId |string | 是 |标识要查询其数据的设备。 | +| key |string | 是 |表示要查询key值的键。 | +| callback |AsyncCallback<boolean\|string\|number\|Uint8Array> | 是 |回调函数,返回匹配给定条件的字符串值。 | + +**错误码:** + +以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 + +| **错误码ID** | **错误信息** | +| ------------ | -------------------------------------- | +| 15100003 | Database corrupted. | +| 15100004 | Not found. | +| 15100006 | Database or result set already closed. | + +**示例:** + +```js +let kvStore; +const KEY_TEST_STRING_ELEMENT = 'key_test_string_2'; +const VALUE_TEST_STRING_ELEMENT = 'value-string-002'; +try { + kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT, async function (err, data) { + if (err != undefined) { + console.error(`Fail to put.code is ${err.code},message is ${err.message}`); + return; + } + console.log('Succeeded in putting'); + kvStore.get('localDeviceId', KEY_TEST_STRING_ELEMENT, function (err, data) { + if (err != undefined) { + console.error(`Fail to get.code is ${err.code},message is ${err.message}`); + return; + } + console.log('Succeeded in getting'); + }); + }) +} catch (e) { + console.error(`Fail to get.code is ${e.code},message is ${e.message}`); +} +``` + +### get + +get(deviceId: string, key: string): Promise<boolean|string|number|Uint8Array> + +获取与指定设备ID和key匹配的string值,使用Promise异步回调。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| -------- | -------- | ---- | ------------------------ | +| deviceId | string | 是 | 标识要查询其数据的设备。 | +| key | string | 是 | 表示要查询key值的键。 | + +**返回值:** + +| 类型 | 说明 | +| ------ | ------- | +|Promise<boolean\|string\|number\|Uint8Array> |Promise对象。返回匹配给定条件的字符串值。| + +**错误码:** + +以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 + +| **错误码ID** | **错误信息** | +| ------------ | -------------------------------------- | +| 15100003 | Database corrupted. | +| 15100004 | Not found. | +| 15100006 | Database or result set already closed. | + +**示例:** + +```js +let kvStore; +const KEY_TEST_STRING_ELEMENT = 'key_test_string_2'; +const VALUE_TEST_STRING_ELEMENT = 'value-string-002'; +try { + kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT).then(async (data) => { + console.log('Succeeded in putting'); + kvStore.get('localDeviceId', KEY_TEST_STRING_ELEMENT).then((data) => { + console.log('Succeeded in getting'); + }).catch((err) => { + console.error(`Fail to get.code is ${err.code},message is ${err.message}`); + }); + }).catch((error) => { + console.error(`Fail to put.code is ${err.code},message is ${err.message}`); + }); +} catch (e) { + console.error(`Fail to get.code is ${e.code},message is ${e.message}`); +} +``` + +### getEntries + +getEntries(deviceId: string, keyPrefix: string, callback: AsyncCallback<Entry[]>): void + +获取与指定设备ID和key前缀匹配的所有键值对,使用callback异步回调。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| --------- | -------------------------------------- | ---- | ---------------------------------------------- | +| deviceId | string | 是 | 标识要查询其数据的设备。 | +| keyPrefix | string | 是 | 表示要匹配的键前缀。 | +| callback | AsyncCallback<[Entry](#entry)[]> | 是 | 回调函数,返回满足给定条件的所有键值对的列表。 | + +**错误码:** + +以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 + +| **错误码ID** | **错误信息** | +| ------------ | -------------------------------------- | +| 15100003 | Database corrupted. | +| 15100006 | Database or result set already closed. | + +**示例:** + +```js +let kvStore; +try { + let entries = []; + for (var i = 0; i < 10; i++) { + var key = 'batch_test_string_key'; + var entry = { + key: key + i, + value: { + type: distributedKVStore.ValueType.STRING, + value: 'batch_test_string_value' + } + } + entries.push(entry); + } + console.log(`entries : ${entries}`); + kvStore.putBatch(entries, async function (err, data) { + if (err != undefined) { + console.error(`Fail to put batch.code is ${err.code},message is ${err.message}`); + return; + } + console.log('Succeeded in putting batch'); + kvStore.getEntries('localDeviceId', 'batch_test_string_key', function (err, entries) { + if (err != undefined) { + console.error(`Fail to get entries.code is ${err.code},message is ${err.message}`); + return; + } + console.log('Succeeded in getting entries'); + console.log(`entries.length: ${entries.length}`); + console.log(`entries[0]: ${entries[0]}`); + }); + }); +} catch (e) { + console.error(`Fail to put batch.code is ${e.code},message is ${e.message}`); +} +``` + +### getEntries + +getEntries(deviceId: string, keyPrefix: string): Promise<Entry[]> + +获取与指定设备ID和key前缀匹配的所有键值对,使用Promise异步回调。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| --------- | -------- | ---- | ------------------------ | +| deviceId | string | 是 | 标识要查询其数据的设备。 | +| keyPrefix | string | 是 | 表示要匹配的键前缀。 | + +**返回值:** + +| 类型 | 说明 | +| -------------------------------- | ------------------------------------------------- | +| Promise<[Entry](#entry)[]> | Promise对象。返回匹配给定条件的所有键值对的列表。 | + +**错误码:** + +以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 + +| **错误码ID** | **错误信息** | +| ------------ | -------------------------------------- | +| 15100003 | Database corrupted. | +| 15100006 | Database or result set already closed. | + +**示例:** + +```js +let kvStore; +try { + let entries = []; + for (var i = 0; i < 10; i++) { + var key = 'batch_test_string_key'; + var entry = { + key: key + i, + value: { + type: distributedKVStore.ValueType.STRING, + value: 'batch_test_string_value' + } + } + entries.push(entry); + } + console.log(`entries: ${entries}`); + kvStore.putBatch(entries).then(async (err) => { + console.log('Succeeded in putting batch'); + kvStore.getEntries('localDeviceId', 'batch_test_string_key').then((entries) => { + console.log('Succeeded in getting entries'); + console.log(`entries.length: ${entries.length}`); + console.log(`entries[0]: ${entries[0]}`); + console.log(`entries[0].value: ${entries[0].value}`); + console.log(`entries[0].value.value: ${entries[0].value.value}`); + }).catch((err) => { + console.error(`Fail to get entries.code is ${err.code},message is ${err.message}`); + }); + }).catch((err) => { + console.error(`Fail to put batch.code is ${err.code},message is ${err.message}`); + }); +} catch (e) { + console.error(`Fail to put batch.code is ${e.code},message is ${e.message}`); +} +``` + +### getEntries + +getEntries(deviceId: string, query: Query, callback: AsyncCallback<Entry[]>): void + +获取与指定设备ID和Query对象匹配的键值对列表,使用callback异步回调。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| -------- | -------------------------------------- | ---- | ------------------------------------------------------- | +| deviceId | string | 是 | 键值对所属的设备ID。 | +| query | [Query](query) | 是 | 表示查询对象。 | +| callback | AsyncCallback<[Entry](#entry)[]> | 是 | 回调函数。返回与指定设备ID和Query对象匹配的键值对列表。 | + +**错误码:** + +以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 + +| **错误码ID** | **错误信息** | +| ------------ | -------------------------------------- | +| 15100003 | Database corrupted. | +| 15100005 | Not support the operation. | +| 15100006 | Database or result set already closed. | + +**示例:** + +```js +let kvStore; +try { + var arr = new Uint8Array([21, 31]); + let entries = []; + for (var i = 0; i < 10; i++) { + var key = 'batch_test_bool_key'; + var entry = { + key: key + i, + value: { + type: distributedKVStore.ValueType.BYTE_ARRAY, + value: arr + } + } + entries.push(entry); + } + console.log(`entries: ${entries}`); + kvStore.putBatch(entries, async function (err, data) { + if (err != undefined) { + console.error(`Fail to put batch.code is ${err.code},message is ${err.message}`); + return; + } + console.log('Succeeded in putting batch'); + var query = new distributedKVStore.Query(); + query.deviceId('localDeviceId'); + query.prefixKey("batch_test"); + kvStore.getEntries('localDeviceId', query, function (err, entries) { + if (err != undefined) { + console.error(`Fail to get entries.code is ${err.code},message is ${err.message}`); + return; + } + console.log('Succeeded in getting entries'); + console.log(`entries.length: ${entries.length}`); + console.log(`entries[0]: ${entries[0]}`); + }) + }); + console.log('Succeeded in getting entries'); +} catch (e) { + console.error(`Fail to get entries.code is ${e.code},message is ${e.message}`); +} +``` + +### getEntries + +getEntries(deviceId: string, query: Query): Promise<Entry[]> + +获取与指定设备ID和Query对象匹配的键值对列表,使用Promise异步回调。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| -------- | -------------- | ---- | -------------------- | +| deviceId | string | 是 | 键值对所属的设备ID。 | +| query | [Query](query) | 是 | 表示查询对象。 | + +**返回值:** + +| 类型 | 说明 | +| -------------------------------- | ---------------------------------------------------------- | +| Promise<[Entry](#entry)[]> | Promise对象。返回与指定设备ID和Query对象匹配的键值对列表。 | + +**错误码:** + +以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 + +| **错误码ID** | **错误信息** | +| ------------ | -------------------------------------- | +| 15100003 | Database corrupted. | +| 15100005 | Not support the operation. | +| 15100006 | Database or result set already closed. | + +**示例:** + +```js +let kvStore; +try { + var arr = new Uint8Array([21, 31]); + let entries = []; + for (var i = 0; i < 10; i++) { + var key = 'batch_test_bool_key'; + var entry = { + key: key + i, + value: { + type: distributedKVStore.ValueType.BYTE_ARRAY, + value: arr + } + } + entries.push(entry); + } + console.log(`entries: ${entries}`); + kvStore.putBatch(entries).then(async (err) => { + console.log('Succeeded in putting batch'); + var query = new distributedKVStore.Query(); + query.deviceId('localDeviceId'); + query.prefixKey("batch_test"); + kvStore.getEntries('localDeviceId', query).then((entries) => { + console.log('Succeeded in getting entries'); + }).catch((err) => { + console.error(`Fail to get entries.code is ${err.code},message is ${err.message}`); + }); + }).catch((err) => { + console.error(`Fail to put batch.code is ${err.code},message is ${err.message}`); + }); + console.log('Succeeded in getting entries'); +} catch (e) { + console.error(`Fail to get entries.code is ${err.code},message is ${err.message}`); +} +``` + +### getResultSet + +getResultSet(deviceId: string, keyPrefix: string, callback: AsyncCallback<KVStoreResultSet>): void + +获取与指定设备ID和key前缀匹配的KVStoreResultSet对象,使用callback异步回调。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| --------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | +| deviceId | string | 是 | 标识要查询其数据的设备。 | +| keyPrefix | string | 是 | 表示要匹配的键前缀。 | +| callback | AsyncCallback<[KVStoreResultSet](#kvstoreresultset)[]> | 是 | 回调函数。返回与指定设备ID和key前缀匹配的KVStoreResultSet对象。 | + +**错误码:** + +以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 + +| **错误码ID** | **错误信息** | +| ------------ | -------------------------------------- | +| 15100003 | Database corrupted. | +| 15100006 | Database or result set already closed. | + +**示例:** + +```js +let kvStore; +try { + let resultSet; + kvStore.getResultSet('localDeviceId', 'batch_test_string_key', async function (err, result) { + if (err != undefined) { + console.error(`Fail to get resultSet.code is ${err.code},message is ${err.message}`); + return; + } + console.log('Succeeded in getting resultSet'); + resultSet = result; + kvStore.closeResultSet(resultSet, function (err, data) { + if (err != undefined) { + console.error(`Fail to close resultSet.code is ${err.code},message is ${err.message}`); + return; + } + console.log('Succeeded in closing resultSet'); + }) + }); +} catch (e) { + console.error(`Fail to get resultSet.code is ${e.code},message is ${e.message}`); +} +``` + +### getResultSet + +getResultSet(deviceId: string, keyPrefix: string): Promise<KVStoreResultSet> + +获取与指定设备ID和key前缀匹配的KVStoreResultSet对象,使用Promise异步回调。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| --------- | -------- | ---- | ------------------------ | +| deviceId | string | 是 | 标识要查询其数据的设备。 | +| keyPrefix | string | 是 | 表示要匹配的键前缀。 | + +**返回值:** + +| 类型 | 说明 | +| ------------------------------------------------------ | ------------------------------------------------------------ | +| Promise<[KVStoreResultSet](#kvstoreresultset)[]> | Promise对象。返回与指定设备ID和key前缀匹配的KVStoreResultSet对象。 | + +**错误码:** + +以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 + +| **错误码ID** | **错误信息** | +| ------------ | -------------------------------------- | +| 15100003 | Database corrupted. | +| 15100006 | Database or result set already closed. | + +**示例:** + +```js +let kvStore; +try { + let resultSet; + kvStore.getResultSet('localDeviceId', 'batch_test_string_key').then((result) => { + console.log('Succeeded in getting resultSet'); + resultSet = result; + }).catch((err) => { + console.error(`Fail to get resultSet.code is ${err.code},message is ${err.message}`); + }); + kvStore.closeResultSet(resultSet).then((err) => { + console.log('Succeeded in closing resultSet'); + }).catch((err) => { + console.error(`Fail to close resultSet.code is ${err.code},message is ${err.message}`); + }); +} catch (e) { + console.error(`Fail to get resultSet.code is ${e.code},message is ${e.message}`); +} +``` + +### getResultSet + +getResultSet(deviceId: string, query: Query, callback: AsyncCallback<KVStoreResultSet>): void + +获取与指定设备ID和Query对象匹配的KVStoreResultSet对象,使用callback异步回调。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | +| deviceId | string | 是 | KVStoreResultSet对象所属的设备ID。 | +| query | [Query](query) | 是 | 表示查询对象。 | +| callback | AsyncCallback<[KVStoreResultSet](#kvstoreresultset)[]> | 是 | 回调函数。返回与指定设备ID和Query对象匹配的KVStoreResultSet对象。 | + +**错误码:** + +以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 + +| **错误码ID** | **错误信息** | +| ------------ | -------------------------------------- | +| 15100003 | Database corrupted. | +| 15100006 | Database or result set already closed. | + +**示例:** + +```js +let kvStore; +try { + let resultSet; + let entries = []; + for (var i = 0; i < 10; i++) { + var key = 'batch_test_string_key'; + var entry = { + key: key + i, + value: { + type: distributedKVStore.ValueType.STRING, + value: 'batch_test_string_value' + } + } + entries.push(entry); + } + kvStore.putBatch(entries, async function (err, data) { + if (err != undefined) { + console.error(`Fail to put batch.code is ${err.code},message is ${err.message}`); + return; + } + console.log('Succeeded in putting batch'); + const query = new distributedKVStore.Query(); + query.prefixKey("batch_test"); + kvStore.getResultSet('localDeviceId', query, async function (err, result) { + if (err != undefined) { + console.error(`Fail to get resultSet.code is ${err.code},message is ${err.message}`); + return; + } + console.log('Succeeded in getting resultSet'); + resultSet = result; + kvStore.closeResultSet(resultSet, function (err, data) { + if (err != undefined) { + console.error(`Fail to close resultSet.code is ${err.code},message is ${err.message}`); + return; + } + console.log('Succeeded in closing resultSet'); + }) + }); + }); +} catch (e) { + console.error(`Fail to get resultSet.code is ${e.code},message is ${e.message}`); +} +``` + +### getResultSet + +getResultSet(deviceId: string, query: Query): Promise<KVStoreResultSet> + +获取与指定设备ID和Query对象匹配的KVStoreResultSet对象,使用Promise异步回调。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| -------- | -------------- | ---- | ---------------------------------- | +| deviceId | string | 是 | KVStoreResultSet对象所属的设备ID。 | +| query | [Query](query) | 是 | 表示查询对象。 | + +**返回值:** + +| 类型 | 说明 | +| ------------------------------------------------------ | ------------------------------------------------------------ | +| Promise<[KVStoreResultSet](#kvstoreresultset)[]> | Promise对象。返回与指定设备ID和Query对象匹配的KVStoreResultSet对象。 | + +**错误码:** + +以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 + +| **错误码ID** | **错误信息** | +| ------------ | -------------------------------------- | +| 15100003 | Database corrupted. | +| 15100006 | Database or result set already closed. | + +**示例:** + +```js +let kvStore; +try { + let resultSet; + let entries = []; + for (var i = 0; i < 10; i++) { + var key = 'batch_test_string_key'; + var entry = { + key: key + i, + value: { + type: distributedKVStore.ValueType.STRING, + value: 'batch_test_string_value' + } + } + entries.push(entry); + } + kvStore.putBatch(entries).then(async (err) => { + console.log('Succeeded in putting batch'); + }).catch((err) => { + console.error(`Fail to put batch.code is ${err.code},message is ${err.message}`); + }); + const query = new distributedKVStore.Query(); + query.prefixKey("batch_test"); + kvStore.getResultSet('localDeviceId', query).then((result) => { + console.log('Succeeded in getting resultSet'); + resultSet = result; + }).catch((err) => { + console.error(`Fail to get resultSet.code is ${err.code},message is ${err.message}`); + }); + query.deviceId('localDeviceId'); + console.log("GetResultSet " + query.getSqlLike()); + kvStore.closeResultSet(resultSet).then((err) => { + console.log('Succeeded in closing resultSet'); + }).catch((err) => { + console.error(`Fail to close resultSet.code is ${err.code},message is ${err.message}`); + }); + +} catch (e) { + console.error(`Fail to get resultSet.code is ${e.code},message is ${e.message}`); +} +``` + +### getResultSet + +getResultSet(deviceId: string, predicates: dataSharePredicates.DataSharePredicates, callback: AsyncCallback<KVStoreResultSet>): void + +获取与指定Predicate对象匹配的KVStoreResultSet对象,使用callback异步回调。 + +**系统接口:** 此接口为系统接口。 + +**系统能力:** SystemCapability.DistributedDataManager.DataShare.Provider + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | +| deviceId | string | 是 | 标识要查询其数据的设备。 | +| predicates | [DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | 是 | 指示筛选条件,当此参数为null时,应定义处理逻辑。 | +| callback | AsyncCallback<[KVStoreResultSet](#kvstoreresultset)> | 是 | 回调函数,获取与指定Predicates对象匹配的KVStoreResultSet对象。 | + +**错误码:** + +以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 + +| **错误码ID** | **错误信息** | +| ------------ | -------------------------------------- | +| 15100003 | Database corrupted. | +| 15100006 | Database or result set already closed. | + +**示例:** + +```js +import dataSharePredicates from '@ohos.data.dataSharePredicates'; + +let kvStore; +try { + let resultSet; + let predicates = new dataSharePredicates.DataSharePredicates(); + predicates.prefixKey("batch_test_string_key"); + kvStore.getResultSet('localDeviceId', predicates, async function (err, result) { + if (err != undefined) { + console.error(`Fail to get resultset.code is ${err.code},message is ${err.message}`); + return; + } + console.log('Succeeded in getting result set'); + resultSet = result; + kvStore.closeResultSet(resultSet, function (err, data) { + if (err != undefined) { + console.error(`Fail to close resultset.code is ${err.code},message is ${err.message}`); + return; + } + console.log('Succeeded in closing result set'); + }) + }); +} catch (e) { + console.error(`An unexpected error occured.code is ${e.code},message is ${e.code}`); +} +``` + +### getResultSet + +getResultSet(deviceId: string, predicates: dataSharePredicates.DataSharePredicates): Promise<KVStoreResultSet> + +获取与指定Predicate对象匹配的KVStoreResultSet对象,使用Promise异步回调。 + +**系统接口:** 此接口为系统接口。 + +**系统能力:** SystemCapability.DistributedDataManager.DataShare.Provider + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| ---------- | ------------------------------------------------------------ | ---- | ----------------------------------------------- | +| deviceId | string | 是 | 标识要查询其数据的设备。 | +| predicates | [DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | 是 | 指示筛选条件,当此参数为null时,应定义处理逻辑。 | + +**返回值:** + +| 类型 | 说明 | +| ---------------------------------------------------- | ------------------------- | +| Promise<[KVStoreResultSet](#kvstoreresultset)> | 无返回结果的Promise对象。 | + +**错误码:** + +以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 + +| **错误码ID** | **错误信息** | +| ------------ | -------------------------------------- | +| 15100003 | Database corrupted. | +| 15100006 | Database or result set already closed. | + +**示例:** + +```js +import dataSharePredicates from '@ohos.data.dataSharePredicates'; +let kvStore; +try { + let resultSet; + let predicates = new dataSharePredicates.DataSharePredicates(); + predicates.prefixKey("batch_test_string_key"); + kvStore.getResultSet('localDeviceId', predicates).then((result) => { + console.log('Succeeded in getting result set'); + resultSet = result; + }).catch((err) => { + console.error(`Fail to get resultset.code is ${err.code},message is ${err.message}`); + }); + kvStore.closeResultSet(resultSet).then((err) => { + console.log('Succeeded in closing result set'); + }).catch((err) => { + console.error(`Fail to close resultset.code is ${err.code},message is ${err.message}`); + }); +} catch (e) { + console.error(`An unexpected error occured.code is ${e.code},message is ${e.code}`); +} +``` + +### getResultSize + +getResultSize(deviceId: string, query: Query, callback: AsyncCallback<number>): void; + +获取与指定设备ID和Query对象匹配的结果数,使用callback异步回调。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| -------- | --------------------------- | ---- | --------------------------------------------------- | +| deviceId | string | 是 | KVStoreResultSet对象所属的设备ID。 | +| query | [Query](query) | 是 | 表示查询对象。 | +| callback | AsyncCallback<number> | 是 | 回调函数。返回与指定设备ID和Query对象匹配的结果数。 | + +**错误码:** + +以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 + +| **错误码ID** | **错误信息** | +| ------------ | -------------------------------------- | +| 15100003 | Database corrupted. | +| 15100006 | Database or result set already closed. | + +**示例:** + +```js +let kvStore; +try { + let entries = []; + for (var i = 0; i < 10; i++) { + var key = 'batch_test_string_key'; + var entry = { + key: key + i, + value: { + type: distributedKVStore.ValueType.STRING, + value: 'batch_test_string_value' + } + } + entries.push(entry); + } + kvStore.putBatch(entries, async function (err, data) { + if (err != undefined) { + console.error(`Fail to put batch.code is ${err.code},message is ${err.message}`); + return; + } + console.log('Succeeded in putting batch'); + const query = new distributedKVStore.Query(); + query.prefixKey("batch_test"); + kvStore.getResultSize('localDeviceId', query, async function (err, resultSize) { + if (err != undefined) { + console.error(`Fail to get resultSize.code is ${err.code},message is ${err.message}`); + return; + } + console.log('Succeeded in getting resultSize'); + ; + }); + }); +} catch (e) { + console.error(`Fail to get resultSize.code is ${e.code},message is ${e.message}`); +} +``` + +### getResultSize + +getResultSize(deviceId: string, query: Query): Promise<number> + +获取与指定设备ID和Query对象匹配的结果数,使用Promise异步回调。 + +**系统能力:** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore + +**参数:** + +| 参数名 | 参数类型 | 必填 | 说明 | +| -------- | -------------- | ---- | ---------------------------------- | +| deviceId | string | 是 | KVStoreResultSet对象所属的设备ID。 | +| query | [Query](query) | 是 | 表示查询对象。 | + +**返回值:** + +| 类型 | 说明 | +| --------------------- | ------------------------------------------------------ | +| Promise<number> | Promise对象。返回与指定设备ID和Query对象匹配的结果数。 | + +**错误码:** + +以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 + +| **错误码ID** | **错误信息** | +| ------------ | -------------------------------------- | +| 15100003 | Database corrupted. | +| 15100006 | Database or result set already closed. | + +**示例:** + +```js +let kvStore; +try { + let entries = []; + for (var i = 0; i < 10; i++) { + var key = 'batch_test_string_key'; + var entry = { + key: key + i, + value: { + type: distributedKVStore.ValueType.STRING, + value: 'batch_test_string_value' + } + } + entries.push(entry); + } + kvStore.putBatch(entries).then(async (err) => { + console.log('Succeeded in putting batch'); + }).catch((err) => { + console.error(`Fail to put batch.code is ${err.code},message is ${err.message}`); + }); + var query = new distributedKVStore.Query(); + query.prefixKey("batch_test"); + kvStore.getResultSize('localDeviceId', query).then((resultSize) => { + console.log('Succeeded in getting resultSize'); + ; + }).catch((err) => { + console.error(`Fail to get resultSize.code is ${err.code},message is ${err.message}`); + }); +} catch (e) { + console.error(`Fail to get resultSize.code is ${e.code},message is ${e.message}`); +} +``` diff --git a/zh-cn/application-dev/reference/errorcodes/errorcode-distributedKVStore.md b/zh-cn/application-dev/reference/errorcodes/errorcode-distributedKVStore.md new file mode 100644 index 0000000000..4ff21bd81f --- /dev/null +++ b/zh-cn/application-dev/reference/errorcodes/errorcode-distributedKVStore.md @@ -0,0 +1,96 @@ +# 分布式键值数据库错误码 + +## 15100001 超过最大订阅数量 + +### 错误信息 +Over max subscribe limits. + +### 错误描述 +该错误码表示在调用数据库变化订阅on接口时,订阅数量已超过最大限制。 + +### 可能原因 +在调用订阅数据库变化接口时,对数据库的订阅数量已超过最大限制。 + +### 处理步骤 +取消对数据库的部分订阅后,再次尝试订阅。 + +## 15100002 打开已有数据库时参数配置发生变化 + +### 错误信息 +Open existed database with changed options. + +### 错误描述 +该错误码表示在调用getKVStore接口打开已创建的数据库时,options配置参数发生变化。 + +### 可能原因 +打开已创建的数据库时,options参数配置发生了变化,可能原因如下: +1. 期望新建数据库时,使用了已创建过的数据库名称storeId。 +2. 期望改变已创建数据库的options参数配置。 + +### 处理步骤 +1. 新建数据库前,请检查数据库名称storeId不与已创建数据库的storeId重名。 +2. 期望改变已创建数据库的options参数配置时,当前不支持该操作,请自行删除数据库后使用新的options参数重新创建。 + +## 15100003 数据库损坏 + +### 错误信息 +Database corrupted. + +### 错误描述 +该错误码表示在调用数据库增、删、查、数据同步等接口时,数据库已损坏。 + +### 可能原因 +调用数据库增、删、查、数据同步等接口操作数据库时,数据库文件已损坏。 + +### 处理步骤 +1. 如果之前备份过数据库,可尝试使用已备份的数据库文件恢复数据库。 +2. 如果之前没有备份过数据库,可尝试删除数据库后重新创建。 + +## 15100004 未找到相关数据 + +### 错误信息 +Not found. + +### 错误描述 +该错误码表示在调用数据库deleteKVStore、delete、deleteBatch、get等接口时,未找到相关数据。 + +### 可能原因 +在调用删除数据库、数据查询、数据删除等接口时未找到相关数据,可能原因如下。 +1. 删除数据库操作时,数据库不存在或已删除。 +2. 数据库数据查询操作时,相关数据不存在或已删除。 +3. 数据库数据删除操作时,相关数据不存在或已删除。 + +### 处理步骤 +1. 在删除数据库操作前,请检查数据库名称是否正确或是否重复删除。 +2. 在数据库数据查询操作前,请检查查询关键字是否正确。 +3. 在数据库数据删除操作前,请检查删除关键字是否正确或是否重复删除。 + + +## 15100005 不支持当前操作 + +### 错误信息 +Not support the operation. + +### 错误描述 +该错误码表示在调用数据库backup、restore等接口时,当前数据库不支持该操作。 + +### 可能原因 +在调用数据库备份、恢复等接口时,当前数据库不支持该操作。 + +### 处理步骤 +检查当前数据库是否支持备份、恢复操作。 + +## 15100006 数据库或查询结果集已关闭 + +### 错误信息 +Database or result set already closed. + +### 错误描述 +该错误码表示在调用数据库或查询结果集相关接口时,数据库或查询结果集为关闭状态。 + +### 可能原因 +在数据库或查询结果集操作前,已经手动关闭了数据库或查询结果集。 + +### 处理步骤 +1. 在数据库相关操作前,请重新打开数据库之后再重试当前操作。 +2. 在查询结果集相关操作前,请重新查询获取结果集之后再重试当前操作。 -- GitLab