1# @ohos.data.distributedKVStore (分布式键值数据库) 2 3分布式键值数据库为应用程序提供不同设备间数据库的分布式协同能力。通过调用分布式键值数据库各个接口，应用程序可将数据保存到分布式键值数据库中，并可对分布式键值数据库中的数据进行增加、删除、修改、查询、同步等操作。 4 5该模块提供以下分布式键值数据库相关的常用功能： 6 7- [KVManager](#kvmanager)：分布式键值数据库管理实例，用于获取数据库的相关信息。 8- [KVStoreResultSet](#kvstoreresultset)：提供获取数据库结果集的相关方法，包括查询和移动数据读取位置等。 9- [Query](#query)：使用谓词表示数据库查询，提供创建Query实例、查询数据库中的数据和添加谓词的方法。 10- [SingleKVStore](#singlekvstore)：单版本分布式键值数据库，不对数据所属设备进行区分，提供查询数据和同步数据的方法。 11- [DeviceKVStore](#devicekvstore)：设备协同数据库，继承自[SingleKVStore](#singlekvstore)，以设备维度对数据进行区分，提供查询数据和同步数据的方法。 12 13> **说明：** 14> 15> 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 16> <br>本模块中所有需要获取deviceId的接口，都仅系统应用可用。 17 18## 导入模块 19 20```js 21import distributedKVStore from '@ohos.data.distributedKVStore'; 22``` 23 24## KVManagerConfig 25 26提供KVManager实例的配置信息，包括调用方的包名和应用的上下文。 27 28**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 29 30| 名称 | 类型 | 必填 | 说明 | 31| ---------- | --------------------- | ---- | ------------------------------------------------------------ | 32| context | Context | 是 |应用的上下文。 <br>FA模型的应用Context定义见[Context](js-apis-inner-app-context.md)。<br>Stage模型的应用Context定义见[Context](js-apis-inner-application-uiAbilityContext.md)。 | 33| bundleName | string | 是 | 调用方的包名。 | 34 35## Constants 36 37分布式键值数据库常量。 38 39**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 40 41| 名称 | 值 | 说明 | 42| --------------------- | ------- | --------------------------------------- | 43| MAX_KEY_LENGTH | 1024 | 数据库中Key允许的最大长度，单位字节。 | 44| MAX_VALUE_LENGTH | 4194303 | 数据库中Value允许的最大长度，单位字节。 | 45| MAX_KEY_LENGTH_DEVICE | 896 | 设备协同数据库中key允许的最大长度，单位字节。 | 46| MAX_STORE_ID_LENGTH | 128 | 数据库标识符允许的最大长度，单位字节。 | 47| MAX_QUERY_LENGTH | 512000 | 最大查询长度，单位字节。 | 48| MAX_BATCH_SIZE | 128 | 最大批处理操作数量。 | 49 50## ValueType 51 52数据类型枚举。 53 54**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 55 56| 名称 | 说明 | 57| ---------- | ---------------------- | 58| STRING | 表示值类型为字符串。 | 59| INTEGER | 表示值类型为整数。 | 60| FLOAT | 表示值类型为浮点数。 | 61| BYTE_ARRAY | 表示值类型为字节数组。 | 62| BOOLEAN | 表示值类型为布尔值。 | 63| DOUBLE | 表示值类型为双浮点数。 | 64 65## Value 66 67存储在数据库中的值对象。 68 69**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 70 71| 名称 | 类型 |必填 | 说明 | 72| ----- | ------- |-----|------------------------ | 73| type | [ValueType](#valuetype) | 是|值类型。 | 74| value | Uint8Array \| string \| number \| boolean| 是|值。 | 75 76## Entry 77 78存储在数据库中的键值对。 79 80**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 81 82| 名称 | 类型 | 必填 | 说明 | 83| ----- | --------------- | ---- | -------- | 84| key | string | 是 | 键值。 | 85| value | [Value](#value) | 是 | 值对象。 | 86 87## ChangeNotification 88 89数据变更时通知的对象，包括数据插入的数据、更新的数据、删除的数据和设备ID。 90 91**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 92 93| 名称 | 类型 | 必填 | 说明 | 94| ------------- | ----------------- | ---- | ------------------------ | 95| insertEntries | [Entry](#entry)[] | 是 | 数据添加记录。 | 96| updateEntries | [Entry](#entry)[] | 是 | 数据更新记录。 | 97| deleteEntries | [Entry](#entry)[] | 是 | 数据删除记录。 | 98| deviceId | string | 是 | 设备ID，此处为设备UUID。 | 99 100## SyncMode 101 102同步模式枚举。 103 104**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 105 106| 名称 | 说明 | 107| --------- | ---------------------------------------------------- | 108| PULL_ONLY | 表示只能从远端拉取数据到本端。 | 109| PUSH_ONLY | 表示只能从本端推送数据到远端。 | 110| PUSH_PULL | 表示从本端推送数据到远端，然后从远端拉取数据到本端。 | 111 112## SubscribeType 113 114订阅类型枚举。 115 116**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 117 118| 名称 | 说明 | 119| --------------------- | ---------------------------- | 120| SUBSCRIBE_TYPE_LOCAL | 表示订阅本地数据变更。 | 121| SUBSCRIBE_TYPE_REMOTE | 表示订阅远端数据变更。 | 122| SUBSCRIBE_TYPE_ALL | 表示订阅远端和本地数据变更。 | 123 124## KVStoreType 125 126分布式键值数据库类型枚举。 127 128| 名称 | 说明 | 129| -------------------- | ------------------------------------------------------------ | 130| DEVICE_COLLABORATION | 表示多设备协同数据库。<br> **数据库特点：** 数据以设备的维度管理，不存在冲突；支持按照设备的维度查询数据。<br>**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore | 131| SINGLE_VERSION | 表示单版本数据库。<br> **数据库特点：** 数据不分设备，设备之间修改相同的key会覆盖。 <br>**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core | 132 133## SecurityLevel 134 135数据库的安全级别枚举。 136 137**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 138 139| 名称 | 说明 | 140| -------: | ------------------------------------------------------------ | 141| S1 | 表示数据库的安全级别为低级别，数据的泄露、篡改、破坏、销毁可能会给个人或组织导致有限的不利影响。<br>例如，性别、国籍，用户申请记录等。 | 142| S2 | 表示数据库的安全级别为中级别，数据的泄露、篡改、破坏、销毁可能会给个人或组织导致严重的不利影响。<br>例如，个人详细通信地址，姓名昵称等。 | 143| S3 | 表示数据库的安全级别为高级别，数据的泄露、篡改、破坏、销毁可能会给个人或组织导致严峻的不利影响。<br>例如，个人实时精确定位信息、运动轨迹等。 | 144| S4 | 表示数据库的安全级别为关键级别，业界法律法规中定义的特殊数据类型，涉及个人的最私密领域的信息或者一旦泄露、篡改、破坏、销毁可能会给个人或组织造成重大的不利影响数据。<br>例如，政治观点、宗教、和哲学信仰、工会成员资格、基因数据、生物信息、健康和性生活状况、性取向等或设备认证鉴权、个人的信用卡等财务信息。 | 145 146## Options 147 148用于提供创建数据库的配置信息。 149 150| 名称 | 类型 | 必填 | 说明 | 151| --------------- | -------------- | ---- | -------------------------| 152| createIfMissing | boolean | 否 | 当数据库文件不存在时是否创建数据库，默认为true，即创建。<br>**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core | 153| encrypt | boolean | 否 | 设置数据库文件是否加密，默认为false，即不加密。<br>**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core | 154| backup | boolean | 否 | 设置数据库文件是否备份，默认为true，即备份。 <br>**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core | 155| autoSync | boolean | 否 | 设置数据库文件是否自动同步。默认为false，即手动同步。<br>**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core<br>**需要权限**： ohos.permission.DISTRIBUTED_DATASYNC | 156| kvStoreType | [KVStoreType](#kvstoretype) | 否 | 设置要创建的数据库类型，默认为DEVICE_COLLABORATION，即多设备协同数据库。<br>**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core | 157| securityLevel | [SecurityLevel](#securitylevel) | 是 | 设置数据库安全级别。<br>**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core | 158| schema | [Schema](#schema) | 否 | 设置定义存储在数据库中的值，默认为undefined，即不使用Schema。<br>**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore | 159 160## Schema 161 162表示数据库模式，可以在创建或打开数据库时创建Schema对象并将它们放入[Options](#options)中。 163 164**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 165 166| 名称 | 类型 | 可读 | 可写 | 说明 | 167| ------- | ----------------------- | ---- | ---- | -------------------------- | 168| root | [FieldNode](#fieldnode) | 是 | 是 | 表示json根对象。 | 169| indexes | Array\<string> | 是 | 是 | 表示json类型的字符串数组。 | 170| mode | number | 是 | 是 | 表示Schema的模式。 | 171| skip | number | 是 | 是 | Schema的跳跃大小。 | 172 173### constructor 174 175constructor() 176 177用于创建Schema实例的构造函数。 178 179**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 180 181## FieldNode 182 183表示 Schema 实例的节点，提供定义存储在数据库中的值的方法。 184 185**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 186 187| 名称 | 类型 | 可读 | 可写 | 说明 | 188| -------- | ------- | ---- | ---- | ------------------------------ | 189| nullable | boolean | 是 | 是 | 表示数据库字段是否可以为空。 | 190| default | string | 是 | 是 | 表示Fieldnode的默认值。 | 191| type | number | 是 | 是 | 表示指定节点对应数据类型的值。 | 192 193### constructor 194 195constructor(name: string) 196 197用于创建带有string字段FieldNode实例的构造函数。 198 199**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 200 201**参数：** 202 203| 参数名 | 类型 | 必填 | 说明 | 204| ------ | -------- | ---- | --------------- | 205| name | string | 是 | FieldNode的值。 | 206 207### appendChild 208 209appendChild(child: FieldNode): boolean 210 211在当前 FieldNode 中添加一个子节点。 212 213**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 214 215**参数：** 216 217| 参数名 | 类型 | 必填 | 说明 | 218| ------ | ----------------------- | ---- | ---------------- | 219| child | [FieldNode](#fieldnode) | 是 | 要附加的域节点。 | 220 221**返回值：** 222 223| 类型 | 说明 | 224| ------- | ------------------------------------------------------------ | 225| boolean | 返回true表示子节点成功添加到FieldNode；返回false则表示操作失败。 | 226 227**示例：** 228 229```js 230import distributedKVStore from '@ohos.data.distributedKVStore'; 231 232try { 233 let node = new distributedKVStore.FieldNode("root"); 234 let child1 = new distributedKVStore.FieldNode("child1"); 235 let child2 = new distributedKVStore.FieldNode("child2"); 236 let child3 = new distributedKVStore.FieldNode("child3"); 237 node.appendChild(child1); 238 node.appendChild(child2); 239 node.appendChild(child3); 240 console.info("appendNode " + JSON.stringify(node)); 241 child1 = null; 242 child2 = null; 243 child3 = null; 244 node = null; 245} catch (e) { 246 console.error("AppendChild " + e); 247} 248``` 249 250## distributedKVStore.createKVManager 251 252createKVManager(config: KVManagerConfig): KVManager 253 254创建一个KVManager对象实例，用于管理数据库对象。 255 256**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 257 258**参数：** 259 260| 参数名 | 类型 | 必填 | 说明 | 261| ------ | ----------------------------- | ---- | --------------------------------------------------------- | 262| config | [KVManagerConfig](#kvmanagerconfig) | 是 | 提供KVManager实例的配置信息，包括调用方的包名和用户信息。 | 263 264**返回值：** 265 266| 类型 | 说明 | 267| -------------------------------------- | ------------------------------------------ | 268| [KVManager](#kvmanager) | 返回创建的KVManager对象实例。 | 269 270**示例：** 271 272Stage模型下的示例： 273 274```js 275import UIAbility from '@ohos.app.ability.UIAbility'; 276 277let kvManager; 278export default class EntryAbility extends UIAbility { 279 onCreate() { 280 console.info("MyAbilityStage onCreate") 281 let context = this.context 282 const kvManagerConfig = { 283 context: context, 284 bundleName: 'com.example.datamanagertest', 285 } 286 try { 287 kvManager = distributedKVStore.createKVManager(kvManagerConfig); 288 console.info("Succeeded in creating KVManager"); 289 } catch (e) { 290 console.error(`Failed to create KVManager.code is ${e.code},message is ${e.message}`); 291 } 292 } 293} 294``` 295 296FA模型下的示例： 297 298```js 299import featureAbility from '@ohos.ability.featureAbility'; 300let kvManager; 301let context = featureAbility.getContext() 302const kvManagerConfig = { 303 context: context, 304 bundleName: 'com.example.datamanagertest', 305} 306try { 307 kvManager = distributedKVStore.createKVManager(kvManagerConfig); 308 console.info("Succeeded in creating KVManager"); 309} catch (e) { 310 console.error(`Failed to create KVManager.code is ${e.code},message is ${e.message}`); 311} 312``` 313 314## KVManager 315 316分布式键值数据库管理实例，用于获取分布式键值数据库的相关信息。在调用KVManager的方法前，需要先通过[createKVManager](#distributedkvstorecreatekvmanager)构建一个KVManager实例。 317 318### getKVStore 319 320getKVStore<T>(storeId: string, options: Options, callback: AsyncCallback<T>): void 321 322通过指定Options和storeId，创建并获取分布式键值数据库，使用callback异步回调。 323 324**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 325 326**参数：** 327 328| 参数名 | 类型 | 必填 | 说明 | 329| -------- | ---------------------- | ---- | ------------------------------------------------------------ | 330| storeId | string | 是 | 数据库唯一标识符，长度不大于[MAX_STORE_ID_LENGTH](#constants)。 | 331| options | [Options](#options) | 是 | 创建分布式键值实例的配置信息。 | 332| callback | AsyncCallback<T> | 是 | 回调函数。返回创建的分布式键值数据库实例（根据kvStoreType的不同，可以创建SingleKVStore实例和DeviceKVStore实例）。 | 333 334**错误码：** 335 336以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 337 338| **错误码ID** | **错误信息** | 339| ------------ | ------------------------------------------- | 340| 15100002 | Open existed database with changed options. | 341| 15100003 | Database corrupted. | 342 343**示例：** 344 345```js 346let kvStore; 347let kvManager; 348try { 349 const options = { 350 createIfMissing: true, 351 encrypt: false, 352 backup: false, 353 autoSync: true, 354 kvStoreType: distributedKVStore.KVStoreType.SINGLE_VERSION, 355 securityLevel: distributedKVStore.SecurityLevel.S2, 356 }; 357 kvManager.getKVStore('storeId', options, function (err, store) { 358 if (err) { 359 console.error(`Failed to get KVStore.code is ${err.code},message is ${err.message}`); 360 return; 361 } 362 console.info("Succeeded in getting KVStore"); 363 kvStore = store; 364 }); 365} catch (e) { 366 console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`); 367} 368``` 369 370### getKVStore 371 372getKVStore<T>(storeId: string, options: Options): Promise<T> 373 374通过指定Options和storeId，创建并获取分布式键值数据库，使用Promise异步回调。 375 376**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 377 378**参数：** 379 380| 参数名 | 类型 | 必填 | 说明 | 381| ------- | ------------------- | ---- | ------------------------------------------------------------ | 382| storeId | string | 是 | 数据库唯一标识符，长度不大于[MAX_STORE_ID_LENGTH](#constants)。 | 383| options | [Options](#options) | 是 | 创建分布式键值实例的配置信息。 | 384 385**返回值：** 386 387| 类型 | 说明 | 388| ---------------- | ------------------------------------------------------------ | 389| Promise<T> | Promise对象。返回创建的分布式键值数据库实例（根据kvStoreType的不同，可以创建SingleKVStore实例和DeviceKVStore实例。 | 390 391**错误码：** 392 393以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 394 395| **错误码ID** | **错误信息** | 396| ------------ | ------------------------------------------- | 397| 15100002 | Open existed database with changed options. | 398| 15100003 | Database corrupted. | 399 400**示例：** 401 402```js 403let kvStore; 404let kvManager; 405try { 406 const options = { 407 createIfMissing: true, 408 encrypt: false, 409 backup: false, 410 autoSync: true, 411 kvStoreType: distributedKVStore.KVStoreType.SINGLE_VERSION, 412 securityLevel: distributedKVStore.SecurityLevel.S2, 413 }; 414 kvManager.getKVStore('storeId', options).then((store) => { 415 console.info("Succeeded in getting KVStore"); 416 kvStore = store; 417 }).catch((err) => { 418 console.error(`Failed to get KVStore.code is ${err.code},message is ${err.message}`); 419 }); 420} catch (e) { 421 console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`); 422} 423``` 424 425### closeKVStore 426 427closeKVStore(appId: string, storeId: string, callback: AsyncCallback<void>): void 428 429通过storeId的值关闭指定的分布式键值数据库，使用callback异步回调。 430 431**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 432 433**参数：** 434 435| 参数名 | 类型 | 必填 | 说明 | 436| -------- | ------------------------- | ---- | ------------------------------------------------------------ | 437| appId | string | 是 | 所调用数据库方的包名。 | 438| storeId | string | 是 | 要关闭的数据库唯一标识符，长度不大于[MAX_STORE_ID_LENGTH](#constants)。 | 439| callback | AsyncCallback<void> | 是 | 回调函数。 | 440 441**示例：** 442 443```js 444let kvStore; 445let kvManager; 446const options = { 447 createIfMissing: true, 448 encrypt: false, 449 backup: false, 450 autoSync: true, 451 kvStoreType: distributedKVStore.KVStoreType.SINGLE_VERSION, 452 schema: undefined, 453 securityLevel: distributedKVStore.SecurityLevel.S2, 454} 455try { 456 kvManager.getKVStore('storeId', options, async function (err, store) { 457 if (err != undefined) { 458 console.error(`Failed to get KVStore.code is ${err.code},message is ${err.message}`); 459 return; 460 } 461 console.info('Succeeded in getting KVStore'); 462 kvStore = store; 463 kvStore = null; 464 store = null; 465 kvManager.closeKVStore('appId', 'storeId', function (err) { 466 if (err != undefined) { 467 console.error(`Failed to close KVStore.code is ${err.code},message is ${err.message}`); 468 return; 469 } 470 console.info('Succeeded in closing KVStore'); 471 }); 472 }); 473} catch (e) { 474 console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`); 475} 476``` 477 478### closeKVStore 479 480closeKVStore(appId: string, storeId: string): Promise<void> 481 482通过storeId的值关闭指定的分布式键值数据库，使用Promise异步回调。 483 484**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 485 486**参数：** 487 488| 参数名 | 类型 | 必填 | 说明 | 489| ------- | -------- | ---- | ------------------------------------------------------------ | 490| appId | string | 是 | 所调用数据库方的包名。 | 491| storeId | string | 是 | 要关闭的数据库唯一标识符，长度不大于[MAX_STORE_ID_LENGTH](#constants)。 | 492 493**返回值：** 494 495| 类型 | 说明 | 496| -------------- | ------------------------- | 497| Promise\<void> | 无返回结果的Promise对象。 | 498 499**示例：** 500 501```js 502let kvManager; 503let kvStore; 504const options = { 505 createIfMissing: true, 506 encrypt: false, 507 backup: false, 508 autoSync: true, 509 kvStoreType: distributedKVStore.KVStoreType.SINGLE_VERSION, 510 schema: undefined, 511 securityLevel: distributedKVStore.SecurityLevel.S2, 512} 513try { 514 kvManager.getKVStore('storeId', options).then(async (store) => { 515 console.info('Succeeded in getting KVStore'); 516 kvStore = store; 517 kvStore = null; 518 store = null; 519 kvManager.closeKVStore('appId', 'storeId').then(() => { 520 console.info('Succeeded in closing KVStore'); 521 }).catch((err) => { 522 console.error(`Failed to close KVStore.code is ${err.code},message is ${err.message}`); 523 }); 524 }).catch((err) => { 525 console.error(`Failed to get KVStore.code is ${err.code},message is ${err.message}`); 526 }); 527} catch (e) { 528 console.error(`Failed to close KVStore.code is ${e.code},message is ${e.message}`); 529} 530``` 531 532### deleteKVStore 533 534deleteKVStore(appId: string, storeId: string, callback: AsyncCallback<void>): void 535 536通过storeId的值删除指定的分布式键值数据库，使用callback异步回调。 537 538**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 539 540**参数：** 541 542| 参数名 | 类型 | 必填 | 说明 | 543| -------- | ------------------------- | ---- | ------------------------------------------------------------ | 544| appId | string | 是 | 所调用数据库方的包名。 | 545| storeId | string | 是 | 要删除的数据库唯一标识符，长度不大于[MAX_STORE_ID_LENGTH](#constants)。 | 546| callback | AsyncCallback<void> | 是 | 回调函数。 | 547 548**错误码：** 549 550以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 551 552| **错误码ID** | **错误信息** | 553| ------------ | ------------ | 554| 15100004 | Not found. | 555 556**示例：** 557 558```js 559let kvManager; 560let kvStore; 561const options = { 562 createIfMissing: true, 563 encrypt: false, 564 backup: false, 565 autoSync: true, 566 kvStoreType: distributedKVStore.KVStoreType.SINGLE_VERSION, 567 schema: undefined, 568 securityLevel: distributedKVStore.SecurityLevel.S2, 569} 570try { 571 kvManager.getKVStore('store', options, async function (err, store) { 572 if (err != undefined) { 573 console.error(`Failed to get KVStore.code is ${err.code},message is ${err.message}`); 574 return; 575 } 576 console.info('Succeeded in getting KVStore'); 577 kvStore = store; 578 kvStore = null; 579 store = null; 580 kvManager.deleteKVStore('appId', 'storeId', function (err) { 581 if (err != undefined) { 582 console.error(`Failed to delete KVStore.code is ${err.code},message is ${err.message}`); 583 return; 584 } 585 console.info(`Succeeded in deleting KVStore`); 586 }); 587 }); 588} catch (e) { 589 console.error(`Failed to delete KVStore.code is ${e.code},message is ${e.message}`); 590} 591``` 592 593### deleteKVStore 594 595deleteKVStore(appId: string, storeId: string): Promise<void> 596 597通过storeId的值删除指定的分布式键值数据库，使用Promise异步回调。 598 599**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 600 601**参数：** 602 603| 参数名 | 类型 | 必填 | 说明 | 604| ------- | -------- | ---- | ------------------------------------------------------------ | 605| appId | string | 是 | 所调用数据库方的包名。 | 606| storeId | string | 是 | 要删除的数据库唯一标识符，长度不大于[MAX_STORE_ID_LENGTH](#constants)。 | 607 608**返回值：** 609 610| 类型 | 说明 | 611| ------------------- | ------------------------- | 612| Promise<void> | 无返回结果的Promise对象。 | 613 614**错误码：** 615 616以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 617 618| **错误码ID** | **错误信息** | 619| ------------ | ------------ | 620| 15100004 | Not found. | 621 622**示例：** 623 624```js 625let kvManager; 626let kvStore; 627const options = { 628 createIfMissing: true, 629 encrypt: false, 630 backup: false, 631 autoSync: true, 632 kvStoreType: distributedKVStore.KVStoreType.SINGLE_VERSION, 633 schema: undefined, 634 securityLevel: distributedKVStore.SecurityLevel.S2, 635} 636try { 637 kvManager.getKVStore('storeId', options).then(async (store) => { 638 console.info('Succeeded in getting KVStore'); 639 kvStore = store; 640 kvStore = null; 641 store = null; 642 kvManager.deleteKVStore('appId', 'storeId').then(() => { 643 console.info('Succeeded in deleting KVStore'); 644 }).catch((err) => { 645 console.error(`Failed to delete KVStore.code is ${err.code},message is ${err.message}`); 646 }); 647 }).catch((err) => { 648 console.error(`Failed to get KVStore.code is ${err.code},message is ${err.message}`); 649 }); 650} catch (e) { 651 console.error(`Failed to delete KVStore.code is ${e.code},message is ${e.message}`); 652} 653``` 654 655### getAllKVStoreId 656 657getAllKVStoreId(appId: string, callback: AsyncCallback<string[]>): void 658 659获取所有通过[getKVStore](#getkvstore)方法创建的且没有调用[deleteKVStore](#deletekvstore)方法删除的分布式键值数据库的storeId，使用callback异步回调。 660 661**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 662 663**参数：** 664 665| 参数名 | 类型 | 必填 | 说明 | 666| -------- | ----------------------------- | ---- | --------------------------------------------------- | 667| appId | string | 是 | 所调用数据库方的包名。 | 668| callback | AsyncCallback<string[]> | 是 | 回调函数。返回所有创建的分布式键值数据库的storeId。 | 669 670**示例：** 671 672```js 673let kvManager; 674try { 675 kvManager.getAllKVStoreId('appId', function (err, data) { 676 if (err != undefined) { 677 console.error(`Failed to get AllKVStoreId.code is ${err.code},message is ${err.message}`); 678 return; 679 } 680 console.info('Succeeded in getting AllKVStoreId'); 681 console.info(`GetAllKVStoreId size = ${data.length}`); 682 }); 683} catch (e) { 684 console.error(`Failed to get AllKVStoreId.code is ${e.code},message is ${e.message}`); 685} 686``` 687 688### getAllKVStoreId 689 690getAllKVStoreId(appId: string): Promise<string[]> 691 692获取所有通过[getKVStore](#getkvstore)方法创建的且没有调用[deleteKVStore](#deletekvstore)方法删除的分布式键值数据库的storeId，使用Promise异步回调。 693 694**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 695 696**参数：** 697 698| 参数名 | 类型 | 必填 | 说明 | 699| ------ | -------- | ---- | ---------------------- | 700| appId | string | 是 | 所调用数据库方的包名。 | 701 702**返回值：** 703 704| 类型 | 说明 | 705| ----------------------- | ------------------------------------------------------ | 706| Promise<string[]> | Promise对象。返回所有创建的分布式键值数据库的storeId。 | 707 708**示例：** 709 710```js 711let kvManager; 712try { 713 console.info('GetAllKVStoreId'); 714 kvManager.getAllKVStoreId('appId').then((data) => { 715 console.info('Succeeded in getting AllKVStoreId'); 716 console.info(`GetAllKVStoreId size = ${data.length}`); 717 }).catch((err) => { 718 console.error(`Failed to get AllKVStoreId.code is ${err.code},message is ${err.message}`); 719 }); 720} catch (e) { 721 console.error(`Failed to get AllKVStoreId.code is ${e.code},message is ${e.message}`); 722} 723``` 724 725### on('distributedDataServiceDie') 726 727on(event: 'distributedDataServiceDie', deathCallback: Callback<void>): void 728 729订阅服务状态变更通知。如果服务终止，需要重新注册数据变更通知和同步完成事件回调通知，并且同步操作会返回失败。 730 731**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 732 733**参数：** 734 735| 参数名 | 类型 | 必填 | 说明 | 736| ------------- | -------------------- | ---- | ------------------------------------------------------------ | 737| event | string | 是 | 订阅的事件名，固定为'distributedDataServiceDie'，即服务状态变更事件。 | 738| deathCallback | Callback<void> | 是 | 回调函数。 | 739 740**示例：** 741 742```js 743let kvManager; 744try { 745 console.info('KVManagerOn'); 746 const deathCallback = function () { 747 console.info('death callback call'); 748 } 749 kvManager.on('distributedDataServiceDie', deathCallback); 750} catch (e) { 751 console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`); 752} 753``` 754 755### off('distributedDataServiceDie') 756 757off(event: 'distributedDataServiceDie', deathCallback?: Callback<void>): void 758 759取消订阅服务状态变更通知。参数中的deathCallback必须是已经订阅过的deathCallback，否则会取消订阅失败。 760 761**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 762 763**参数：** 764 765| 参数名 | 类型 | 必填 | 说明 | 766| ------------- | -------------------- | ---- | ------------------------------------------------------------ | 767| event | string | 是 | 取消订阅的事件名，固定为'distributedDataServiceDie'，即服务状态变更事件。 | 768| deathCallback | Callback<void> | 否 | 回调函数。如果该参数不填，那么会将之前订阅过的所有的deathCallback取消订阅。 | 769 770**示例：** 771 772```js 773let kvManager; 774try { 775 console.info('KVManagerOff'); 776 const deathCallback = function () { 777 console.info('death callback call'); 778 } 779 kvManager.off('distributedDataServiceDie', deathCallback); 780} catch (e) { 781 console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`); 782} 783``` 784 785## KVStoreResultSet 786 787提供获取数据库结果集的相关方法，包括查询和移动数据读取位置等。同时允许打开的结果集的最大数量为8个。 788 789在调用KVStoreResultSet的方法前，需要先通过[getKVStore](#getkvstore)构建一个SingleKVStore或者DeviceKVStore实例。 790 791### getCount 792 793getCount(): number 794 795获取结果集中的总行数。 796 797**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 798 799**返回值：** 800 801| 类型 | 说明 | 802| ------ | ------------------ | 803| number | 返回数据的总行数。 | 804 805**示例：** 806 807```js 808let kvStore; 809try { 810 let resultSet; 811 let count; 812 kvStore.getResultSet('batch_test_string_key').then((result) => { 813 console.info('getResultSet succeed.'); 814 resultSet = result; 815 count = resultSet.getCount(); 816 console.info("getCount succeed:" + count); 817 }).catch((err) => { 818 console.error('getResultSet failed: ' + err); 819 }); 820} catch (e) { 821 console.error("getCount failed: " + e); 822} 823``` 824 825### getPosition 826 827getPosition(): number 828 829获取结果集中当前的读取位置。读取位置会因[moveToFirst](#movetofirst)、[moveToLast](#movetolast)等操作而发生变化。 830 831**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 832 833**返回值：** 834 835| 类型 | 说明 | 836| ------ | ------------------ | 837| number | 返回当前读取位置。取值范围>= -1，值为 -1 时表示还未开始读取，值为 0 时表示第一行。 | 838 839**示例：** 840 841```js 842let kvStore; 843try { 844 let resultSet; 845 let position; 846 kvStore.getResultSet('batch_test_string_key').then((result) => { 847 console.info('getResultSet succeeded.'); 848 resultSet = result; 849 position = resultSet.getPosition(); 850 console.info("getPosition succeed:" + position); 851 }).catch((err) => { 852 console.error('getResultSet failed: ' + err); 853 }); 854} catch (e) { 855 console.error("getPosition failed: " + e); 856} 857``` 858 859### moveToFirst 860 861moveToFirst(): boolean 862 863将读取位置移动到第一行。如果结果集为空，则返回false。 864 865**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 866 867**返回值：** 868 869| 类型 | 说明 | 870| ------- | ----------------------------------------------- | 871| boolean | 返回true表示操作成功；返回false则表示操作失败。 | 872 873**示例：** 874 875```js 876let kvStore; 877try { 878 let resultSet; 879 let moved; 880 kvStore.getResultSet('batch_test_string_key').then((result) => { 881 console.info('getResultSet succeed.'); 882 resultSet = result; 883 moved = resultSet.moveToFirst(); 884 console.info("moveToFirst succeed: " + moved); 885 }).catch((err) => { 886 console.error('getResultSet failed: ' + err); 887 }); 888} catch (e) { 889 console.error("moveToFirst failed " + e); 890} 891``` 892 893### moveToLast 894 895moveToLast(): boolean 896 897将读取位置移动到最后一行。如果结果集为空，则返回false。 898 899**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 900 901**返回值：** 902 903| 类型 | 说明 | 904| ------- | ----------------------------------------------- | 905| boolean | 返回true表示操作成功；返回false则表示操作失败。 | 906 907**示例：** 908 909```js 910let kvStore; 911try { 912 let resultSet; 913 let moved; 914 kvStore.getResultSet('batch_test_string_key').then((result) => { 915 console.info('getResultSet succeed.'); 916 resultSet = result; 917 moved = resultSet.moveToLast(); 918 console.info("moveToLast succeed:" + moved); 919 }).catch((err) => { 920 console.error('getResultSet failed: ' + err); 921 }); 922} catch (e) { 923 console.error("moveToLast failed: " + e); 924} 925``` 926 927### moveToNext 928 929moveToNext(): boolean 930 931将读取位置移动到下一行。如果结果集为空，则返回false。适用于全量获取数据库结果集的场景。 932 933**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 934 935**返回值：** 936 937| 类型 | 说明 | 938| ------- | ----------------------------------------------- | 939| boolean | 返回true表示操作成功；返回false则表示操作失败。 | 940 941**示例：** 942 943```js 944let kvStore; 945try { 946 let resultSet; 947 let moved; 948 kvStore.getResultSet('batch_test_string_key').then((result) => { 949 console.info('getResultSet succeed.'); 950 resultSet = result; 951 do { 952 moved = resultSet.moveToNext(); 953 const entry = resultSet.getEntry(); 954 console.info("moveToNext succeed: " + moved); 955 } while (moved) 956 }).catch((err) => { 957 console.error('getResultSet failed: ' + err); 958 }); 959} catch (e) { 960 console.error("moveToNext failed: " + e); 961} 962``` 963 964### moveToPrevious 965 966moveToPrevious(): boolean 967 968将读取位置移动到上一行。如果结果集为空，则返回false。适用于全量获取数据库结果集的场景。 969 970**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 971 972**返回值：** 973 974| 类型 | 说明 | 975| ------- | ----------------------------------------------- | 976| boolean | 返回true表示操作成功；返回false则表示操作失败。 | 977 978**示例：** 979 980```js 981let kvStore; 982try { 983 let resultSet; 984 let moved; 985 kvStore.getResultSet('batch_test_string_key').then((result) => { 986 console.info('getResultSet succeed.'); 987 resultSet = result; 988 moved = resultSet.moveToLast(); 989 moved = resultSet.moveToPrevious(); 990 console.info("moveToPrevious succeed:" + moved); 991 }).catch((err) => { 992 console.error('getResultSet failed: ' + err); 993 }); 994} catch (e) { 995 console.error("moveToPrevious failed: " + e); 996} 997``` 998 999### move 1000 1001move(offset: number): boolean 1002 1003将读取位置移动到当前位置的相对偏移量。即当前游标位置向下偏移 offset 行。 1004 1005**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1006 1007**参数：** 1008 1009| 参数名 | 类型 | 必填 | 说明 | 1010| ------ | -------- | ---- | ------------------------------------------------------------ | 1011| offset | number | 是 | 表示与当前位置的相对偏移量，负偏移表示向后移动，正偏移表示向前移动。 | 1012 1013**返回值：** 1014 1015| 类型 | 说明 | 1016| ------- | ----------------------------------------------- | 1017| boolean | 返回true表示操作成功；返回false则表示操作失败。 | 1018 1019**示例：** 1020 1021```js 1022let kvStore; 1023try { 1024 let resultSet; 1025 let moved; 1026 kvStore.getResultSet('batch_test_string_key').then((result) => { 1027 console.info('Succeeded in getting resultSet'); 1028 resultSet = result; 1029 moved = resultSet.move(2); //若当前位置为0，将读取位置从绝对位置为0的位置移动2行，即移动到绝对位置为2，行数为3的位置 1030 console.info(`Succeeded in moving.moved = ${moved}`); 1031 }).catch((err) => { 1032 console.error(`Failed to get resultSet.code is ${err.code},message is ${err.message}`); 1033 }); 1034} catch (e) { 1035 console.error(`Failed to move.code is ${e.code},message is ${e.message}`); 1036} 1037``` 1038 1039### moveToPosition 1040 1041moveToPosition(position: number): boolean 1042 1043将读取位置从 0 移动到绝对位置。 1044 1045**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1046 1047**参数：** 1048 1049| 参数名 | 类型 | 必填 | 说明 | 1050| -------- | -------- | ---- | -------------- | 1051| position | number | 是 | 表示绝对位置。 | 1052 1053**返回值：** 1054 1055| 类型 | 说明 | 1056| ------- | ----------------------------------------------- | 1057| boolean | 返回true表示操作成功；返回false则表示操作失败。 | 1058 1059**示例** 1060 1061```js 1062let kvStore; 1063try { 1064 let resultSet; 1065 let moved; 1066 kvStore.getResultSet('batch_test_string_key').then((result) => { 1067 console.info('Succeeded in getting resultSet'); 1068 resultSet = result; 1069 moved = resultSet.moveToPosition(1); 1070 console.info(`Succeeded in moving to position.moved=${moved}`); 1071 }).catch((err) => { 1072 console.error(`Failed to get resultSet.code is ${err.code},message is ${err.message}`); 1073 }); 1074} catch (e) { 1075 console.error(`Failed to move to position.code is ${e.code},message is ${e.message}`); 1076} 1077``` 1078 1079### isFirst 1080 1081isFirst(): boolean 1082 1083检查读取位置是否为第一行。 1084 1085**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1086 1087**返回值：** 1088 1089| 类型 | 说明 | 1090| ------- | ------------------------------------------------------------ | 1091| boolean | 返回true表示读取位置为第一行；返回false表示读取位置不是第一行。 | 1092 1093**示例：** 1094 1095```js 1096let kvStore; 1097try { 1098 let resultSet; 1099 let isfirst; 1100 kvStore.getResultSet('batch_test_string_key').then((result) => { 1101 console.info('getResultSet succeed.'); 1102 resultSet = result; 1103 isfirst = resultSet.isFirst(); 1104 console.info("Check isFirst succeed:" + isfirst); 1105 }).catch((err) => { 1106 console.error('getResultSet failed: ' + err); 1107 }); 1108} catch (e) { 1109 console.error("Check isFirst failed: " + e); 1110} 1111``` 1112 1113### isLast 1114 1115isLast(): boolean 1116 1117检查读取位置是否为最后一行。 1118 1119**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1120 1121**返回值：** 1122 1123| 类型 | 说明 | 1124| ------- | ------------------------------------------------------------ | 1125| boolean | 返回true表示读取位置为最后一行；返回false表示读取位置不是最后一行。 | 1126 1127**示例：** 1128 1129```js 1130let kvStore; 1131try { 1132 let resultSet; 1133 let islast; 1134 kvStore.getResultSet('batch_test_string_key').then((result) => { 1135 console.info('getResultSet succeed.'); 1136 resultSet = result; 1137 islast = resultSet.isLast(); 1138 console.info("Check isLast succeed: " + islast); 1139 }).catch((err) => { 1140 console.error('getResultSet failed: ' + err); 1141 }); 1142} catch (e) { 1143 console.error("Check isLast failed: " + e); 1144} 1145``` 1146 1147### isBeforeFirst 1148 1149isBeforeFirst(): boolean 1150 1151检查读取位置是否在第一行之前。 1152 1153**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1154 1155**返回值：** 1156 1157| 类型 | 说明 | 1158| ------- | ------------------------------------------------------------ | 1159| boolean | 返回true表示读取位置在第一行之前；返回false表示读取位置不在第一行之前。 | 1160 1161**示例：** 1162 1163```js 1164let kvStore; 1165try { 1166 let resultSet; 1167 kvStore.getResultSet('batch_test_string_key').then((result) => { 1168 console.info('getResultSet succeed.'); 1169 resultSet = result; 1170 const isbeforefirst = resultSet.isBeforeFirst(); 1171 console.info("Check isBeforeFirst succeed: " + isbeforefirst); 1172 }).catch((err) => { 1173 console.error('getResultSet failed: ' + err); 1174 }); 1175} catch (e) { 1176 console.error("Check isBeforeFirst failed: " + e); 1177} 1178``` 1179 1180### isAfterLast 1181 1182isAfterLast(): boolean 1183 1184检查读取位置是否在最后一行之后。 1185 1186**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1187 1188**返回值：** 1189 1190| 类型 | 说明 | 1191| ------- | ------------------------------------------------------------ | 1192| boolean | 返回true表示读取位置在最后一行之后；返回false表示读取位置不在最后一行之后。 | 1193 1194**示例：** 1195 1196```js 1197let kvStore; 1198try { 1199 let resultSet; 1200 kvStore.getResultSet('batch_test_string_key').then((result) => { 1201 console.info('getResultSet succeed.'); 1202 resultSet = result; 1203 const isafterlast = resultSet.isAfterLast(); 1204 console.info("Check isAfterLast succeed:" + isafterlast); 1205 }).catch((err) => { 1206 console.error('getResultSet failed: ' + err); 1207 }); 1208} catch (e) { 1209 console.log("Check isAfterLast failed: " + e); 1210} 1211``` 1212 1213### getEntry 1214 1215getEntry(): Entry 1216 1217从当前位置获取对应的键值对。 1218 1219**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1220 1221**返回值：** 1222 1223| 类型 | 说明 | 1224| --------------- | ------------ | 1225| [Entry](#entry) | 返回键值对。 | 1226 1227**示例：** 1228 1229```js 1230let kvStore; 1231try { 1232 let resultSet; 1233 kvStore.getResultSet('batch_test_string_key').then((result) => { 1234 console.info('getResultSet succeed.'); 1235 resultSet = result; 1236 const entry = resultSet.getEntry(); 1237 console.info("getEntry succeed:" + JSON.stringify(entry)); 1238 }).catch((err) => { 1239 console.error('getResultSet failed: ' + err); 1240 }); 1241} catch (e) { 1242 console.error("getEntry failed: " + e); 1243} 1244``` 1245 1246## Query 1247 1248使用谓词表示数据库查询，提供创建Query实例、查询数据库中的数据和添加谓词的方法。一个Query对象中谓词数量上限为256个。 1249 1250**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1251 1252### constructor 1253 1254constructor() 1255 1256用于创建Schema实例的构造函数。 1257 1258**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1259 1260### reset 1261 1262reset(): Query 1263 1264重置Query对象。 1265 1266**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1267 1268**返回值：** 1269 1270| 类型 | 说明 | 1271| -------------- | --------------------- | 1272| [Query](#query) | 返回重置的Query对象。 | 1273 1274**示例：** 1275 1276```js 1277try { 1278 let query = new distributedKVStore.Query(); 1279 query.equalTo("key", "value"); 1280 console.info("query is " + query.getSqlLike()); 1281 query.reset(); 1282 console.info("query is " + query.getSqlLike()); 1283 query = null; 1284} catch (e) { 1285 console.error("simply calls should be ok :" + e); 1286} 1287``` 1288 1289### equalTo 1290 1291equalTo(field: string, value: number|string|boolean): Query 1292 1293构造一个Query对象来查询具有指定字段的条目，其值等于指定的值。 1294 1295**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1296 1297**参数：** 1298 1299| 参数名 | 类型 | 必填 | 说明 | 1300| ----- | ------ | ---- | ----------------------- | 1301| fieId | string | 是 |表示指定字段，不能包含' ^ '。 | 1302| value | number\|string\|boolean | 是 | 表示指定的值。| 1303 1304**返回值：** 1305 1306| 类型 | 说明 | 1307| -------------- | --------------- | 1308| [Query](#query) | 返回Query对象。 | 1309 1310**示例：** 1311 1312```js 1313try { 1314 let query = new distributedKVStore.Query(); 1315 query.equalTo("field", "value"); 1316 console.info(`query is ${query.getSqlLike()}`); 1317 query = null; 1318} catch (e) { 1319 console.error(`duplicated calls should be ok.code is ${e.code},message is ${e.message}`); 1320} 1321``` 1322 1323### notEqualTo 1324 1325notEqualTo(field: string, value: number|string|boolean): Query 1326 1327构造一个Query对象以查询具有指定字段且值不等于指定值的条目。 1328 1329**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1330 1331**参数：** 1332 1333| 参数名 | 类型 | 必填 | 说明 | 1334| ----- | ------ | ---- | ----------------------- | 1335| fieId | string | 是 |表示指定字段，不能包含' ^ '。 | 1336| value | number\|string\|boolean | 是 | 表示指定的值。| 1337 1338**返回值：** 1339 1340| 类型 | 说明 | 1341| -------------- | --------------- | 1342| [Query](#query) | 返回Query对象。 | 1343 1344**示例：** 1345 1346```js 1347try { 1348 let query = new distributedKVStore.Query(); 1349 query.notEqualTo("field", "value"); 1350 console.info(`query is ${query.getSqlLike()}`); 1351 query = null; 1352} catch (e) { 1353 console.error(`duplicated calls should be ok.code is ${e.code},message is ${e.message}`); 1354} 1355``` 1356 1357### greaterThan 1358 1359greaterThan(field: string, value: number|string|boolean): Query 1360 1361构造一个Query对象以查询具有大于指定值的指定字段的条目。 1362 1363**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1364 1365**参数：** 1366| 参数名 | 类型 | 必填 | 说明 | 1367| ----- | ------ | ---- | ----------------------- | 1368| fieId | string | 是 |表示指定字段，不能包含' ^ '。 | 1369| value | number\|string\|boolean | 是 | 表示指定的值。| 1370 1371**返回值：** 1372 1373| 类型 | 说明 | 1374| -------------- | --------------- | 1375| [Query](#query) | 返回Query对象。 | 1376 1377**示例：** 1378 1379```js 1380try { 1381 let query = new distributedKVStore.Query(); 1382 query.greaterThan("field", "value"); 1383 console.info(`query is ${query.getSqlLike()}`); 1384 query = null; 1385} catch (e) { 1386 console.error(`duplicated calls should be ok.code is ${e.code},message is ${e.message}`); 1387} 1388``` 1389 1390### lessThan 1391 1392lessThan(field: string, value: number|string): Query 1393 1394构造一个Query对象以查询具有小于指定值的指定字段的条目。 1395 1396**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1397 1398**参数：** 1399 1400 1401| 参数名 | 类型 | 必填 | 说明 | 1402| ----- | ------ | ---- | ----------------------- | 1403| fieId | string | 是 |表示指定字段，不能包含' ^ '。 | 1404| value | number\|string | 是 | 表示指定的值。| 1405 1406**返回值：** 1407 1408| 类型 | 说明 | 1409| -------------- | --------------- | 1410| [Query](#query) | 返回Query对象。 | 1411 1412**示例：** 1413 1414```js 1415try { 1416 let query = new distributedKVStore.Query(); 1417 query.lessThan("field", "value"); 1418 console.info(`query is ${query.getSqlLike()}`); 1419 query = null; 1420} catch (e) { 1421 console.error(`duplicated calls should be ok.code is ${e.code},message is ${e.message}`); 1422} 1423``` 1424 1425### greaterThanOrEqualTo 1426 1427greaterThanOrEqualTo(field: string, value: number|string): Query 1428 1429构造一个Query对象以查询具有指定字段且值大于或等于指定值的条目。 1430 1431**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1432 1433**参数：** 1434 1435 1436| 参数名 | 类型 | 必填 | 说明 | 1437| ----- | ------ | ---- | ----------------------- | 1438| fieId | string | 是 |表示指定字段，不能包含' ^ '。 | 1439| value | number\|string | 是 | 表示指定的值。| 1440 1441**返回值：** 1442 1443| 类型 | 说明 | 1444| -------------- | --------------- | 1445| [Query](#query) | 返回Query对象。 | 1446 1447**示例：** 1448 1449```js 1450try { 1451 let query = new distributedKVStore.Query(); 1452 query.greaterThanOrEqualTo("field", "value"); 1453 console.info(`query is ${query.getSqlLike()}`); 1454 query = null; 1455} catch (e) { 1456 console.error(`duplicated calls should be ok.code is ${e.code},message is ${e.message}`); 1457} 1458``` 1459 1460### lessThanOrEqualTo 1461 1462lessThanOrEqualTo(field: string, value: number|string): Query 1463 1464构造一个Query对象以查询具有指定字段且值小于或等于指定值的条目。 1465 1466**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1467 1468**参数：** 1469 1470 1471| 参数名 | 类型 | 必填 | 说明 | 1472| ----- | ------ | ---- | ----------------------- | 1473| fieId | string | 是 |表示指定字段，不能包含' ^ '。 | 1474| value | number\|string | 是 | 表示指定的值。| 1475 1476**返回值：** 1477 1478| 类型 | 说明 | 1479| -------------- | --------------- | 1480| [Query](#query) | 返回Query对象。 | 1481 1482**示例：** 1483 1484```js 1485try { 1486 let query = new distributedKVStore.Query(); 1487 query.lessThanOrEqualTo("field", "value"); 1488 console.info(`query is ${query.getSqlLike()}`); 1489 query = null; 1490} catch (e) { 1491 console.error(`duplicated calls should be ok.code is ${e.code},message is ${e.message}`); 1492} 1493``` 1494 1495### isNull 1496 1497isNull(field: string): Query 1498 1499构造一个Query对象以查询具有值为null的指定字段的条目。 1500 1501**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1502 1503**参数：** 1504 1505| 参数名 | 类型 | 必填 | 说明 | 1506| ------ | -------- | ---- | ----------------------------- | 1507| fieId | string | 是 | 表示指定字段，不能包含' ^ '。 | 1508 1509**返回值：** 1510 1511| 类型 | 说明 | 1512| -------------- | --------------- | 1513| [Query](#query) | 返回Query对象。 | 1514 1515**示例：** 1516 1517```js 1518try { 1519 let query = new distributedKVStore.Query(); 1520 query.isNull("field"); 1521 console.info(`query is ${query.getSqlLike()}`); 1522 query = null; 1523} catch (e) { 1524 console.error(`duplicated calls should be ok.code is ${e.code},message is ${e.message}`); 1525} 1526``` 1527 1528### inNumber 1529 1530inNumber(field: string, valueList: number[]): Query 1531 1532构造一个Query对象以查询具有指定字段的条目，其值在指定的值列表中。 1533 1534**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1535 1536**参数：** 1537 1538| 参数名 | 类型 | 必填 | 说明 | 1539| --------- | -------- | ---- | ----------------------------- | 1540| fieId | string | 是 | 表示指定字段，不能包含' ^ '。 | 1541| valueList | number[] | 是 | 表示指定的值列表。 | 1542 1543**返回值：** 1544 1545| 类型 | 说明 | 1546| -------------- | --------------- | 1547| [Query](#query) | 返回Query对象。 | 1548 1549**示例：** 1550 1551```js 1552try { 1553 let query = new distributedKVStore.Query(); 1554 query.inNumber("field", [0, 1]); 1555 console.info(`query is ${query.getSqlLike()}`); 1556 query = null; 1557} catch (e) { 1558 console.error(`duplicated calls should be ok.code is ${e.code},message is ${e.message}`); 1559} 1560``` 1561 1562### inString 1563 1564inString(field: string, valueList: string[]): Query 1565 1566构造一个Query对象以查询具有指定字段的条目，其值在指定的字符串值列表中。 1567 1568**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1569 1570**参数：** 1571 1572| 参数名 | 类型 | 必填 | 说明 | 1573| --------- | -------- | ---- | ----------------------------- | 1574| fieId | string | 是 | 表示指定字段，不能包含' ^ '。 | 1575| valueList | string[] | 是 | 表示指定的字符串值列表。 | 1576 1577**返回值：** 1578 1579| 类型 | 说明 | 1580| -------------- | --------------- | 1581| [Query](#query) | 返回Query对象。 | 1582 1583**示例：** 1584 1585```js 1586try { 1587 let query = new distributedKVStore.Query(); 1588 query.inString("field", ['test1', 'test2']); 1589 console.info(`query is ${query.getSqlLike()}`); 1590 query = null; 1591} catch (e) { 1592 console.error(`duplicated calls should be ok.code is ${e.code},message is ${e.message}`); 1593} 1594``` 1595 1596### notInNumber 1597 1598notInNumber(field: string, valueList: number[]): Query 1599 1600构造一个Query对象以查询具有指定字段的条目，该字段的值不在指定的值列表中。 1601 1602**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1603 1604**参数：** 1605 1606| 参数名 | 类型 | 必填 | 说明 | 1607| --------- | -------- | ---- | ----------------------------- | 1608| fieId | string | 是 | 表示指定字段，不能包含' ^ '。 | 1609| valueList | number[] | 是 | 表示指定的值列表。 | 1610 1611**返回值：** 1612 1613| 类型 | 说明 | 1614| -------------- | --------------- | 1615| [Query](#query) | 返回Query对象。 | 1616 1617**示例：** 1618 1619```js 1620try { 1621 let query = new distributedKVStore.Query(); 1622 query.notInNumber("field", [0, 1]); 1623 console.info(`query is ${query.getSqlLike()}`); 1624 query = null; 1625} catch (e) { 1626 console.error(`duplicated calls should be ok.code is ${e.code},message is ${e.message}`); 1627} 1628``` 1629 1630### notInString 1631 1632notInString(field: string, valueList: string[]): Query 1633 1634构造一个Query对象以查询具有指定字段且值不在指定字符串值列表中的条目。 1635 1636**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1637 1638**参数：** 1639 1640| 参数名 | 类型 | 必填 | 说明 | 1641| --------- | -------- | ---- | ----------------------------- | 1642| fieId | string | 是 | 表示指定字段，不能包含' ^ '。 | 1643| valueList | string[] | 是 | 表示指定的字符串值列表。 | 1644 1645**返回值：** 1646 1647| 类型 | 说明 | 1648| -------------- | --------------- | 1649| [Query](#query) | 返回Query对象。 | 1650 1651**示例：** 1652 1653```js 1654try { 1655 let query = new distributedKVStore.Query(); 1656 query.notInString("field", ['test1', 'test2']); 1657 console.info(`query is ${query.getSqlLike()}`); 1658 query = null; 1659} catch (e) { 1660 console.error(`duplicated calls should be ok.code is ${e.code},message is ${e.message}`); 1661} 1662``` 1663 1664### like 1665 1666like(field: string, value: string): Query 1667 1668构造一个Query对象以查询具有与指定字符串值相似的指定字段的条目。 1669 1670**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1671 1672**参数：** 1673 1674| 参数名 | 类型 | 必填 | 说明 | 1675| ------ | -------- | ---- | ----------------------------- | 1676| fieId | string | 是 | 表示指定字段，不能包含' ^ '。 | 1677| value | string | 是 | 表示指定的字符串值。 | 1678 1679**返回值：** 1680 1681| 类型 | 说明 | 1682| -------------- | --------------- | 1683| [Query](#query) | 返回Query对象。 | 1684 1685**示例：** 1686 1687```js 1688try { 1689 let query = new distributedKVStore.Query(); 1690 query.like("field", "value"); 1691 console.info(`query is ${query.getSqlLike()}`); 1692 query = null; 1693} catch (e) { 1694 console.error(`duplicated calls should be ok.code is ${e.code},message is ${e.message}`); 1695} 1696``` 1697 1698### unlike 1699 1700unlike(field: string, value: string): Query 1701 1702构造一个Query对象以查询具有与指定字符串值不相似的指定字段的条目。 1703 1704**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1705 1706**参数：** 1707 1708| 参数名 | 类型 | 必填 | 说明 | 1709| ------ | -------- | ---- | ----------------------------- | 1710| fieId | string | 是 | 表示指定字段，不能包含' ^ '。 | 1711| value | string | 是 | 表示指定的字符串值。 | 1712 1713**返回值：** 1714 1715| 类型 | 说明 | 1716| -------------- | --------------- | 1717| [Query](#query) | 返回Query对象。 | 1718 1719**示例：** 1720 1721```js 1722try { 1723 let query = new distributedKVStore.Query(); 1724 query.unlike("field", "value"); 1725 console.info(`query is ${query.getSqlLike()}`); 1726 query = null; 1727} catch (e) { 1728 console.error(`duplicated calls should be ok.code is ${e.code},message is ${e.message}`); 1729} 1730``` 1731 1732### and 1733 1734and(): Query 1735 1736构造一个带有与条件的查询对象。 1737 1738**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1739 1740**返回值：** 1741 1742| 类型 | 说明 | 1743| -------------- | -------------- | 1744| [Query](#query) | 返回查询对象。 | 1745 1746**示例：** 1747 1748```js 1749try { 1750 let query = new distributedKVStore.Query(); 1751 query.notEqualTo("field", "value1"); 1752 query.and(); 1753 query.notEqualTo("field", "value2"); 1754 console.info("query is " + query.getSqlLike()); 1755 query = null; 1756} catch (e) { 1757 console.error("duplicated calls should be ok :" + e); 1758} 1759``` 1760 1761### or 1762 1763or(): Query 1764 1765构造一个带有或条件的Query对象。 1766 1767**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1768 1769**返回值：** 1770 1771| 类型 | 说明 | 1772| -------------- | -------------- | 1773| [Query](#query) | 返回查询对象。 | 1774 1775**示例：** 1776 1777```js 1778try { 1779 let query = new distributedKVStore.Query(); 1780 query.notEqualTo("field", "value1"); 1781 query.or(); 1782 query.notEqualTo("field", "value2"); 1783 console.info("query is " + query.getSqlLike()); 1784 query = null; 1785} catch (e) { 1786 console.error("duplicated calls should be ok :" + e); 1787} 1788``` 1789 1790### orderByAsc 1791 1792orderByAsc(field: string): Query 1793 1794构造一个Query对象，将查询结果按升序排序。 1795 1796**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1797 1798**参数：** 1799 1800| 参数名 | 类型 | 必填 | 说明 | 1801| ------ | -------- | ---- | ----------------------------- | 1802| fieId | string | 是 | 表示指定字段，不能包含' ^ '。 | 1803 1804**返回值：** 1805 1806| 类型 | 说明 | 1807| -------------- | --------------- | 1808| [Query](#query) | 返回Query对象。 | 1809 1810**示例：** 1811 1812```js 1813try { 1814 let query = new distributedKVStore.Query(); 1815 query.notEqualTo("field", "value"); 1816 query.orderByAsc("field"); 1817 console.info(`query is ${query.getSqlLike()}`); 1818 query = null; 1819} catch (e) { 1820 console.error(`duplicated calls should be ok.code is ${e.code},message is ${e.message}`); 1821} 1822``` 1823 1824### orderByDesc 1825 1826orderByDesc(field: string): Query 1827 1828构造一个Query对象，将查询结果按降序排序。 1829 1830**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1831 1832**参数：** 1833 1834| 参数名 | 类型 | 必填 | 说明 | 1835| ------ | -------- | ---- | ----------------------------- | 1836| fieId | string | 是 | 表示指定字段，不能包含' ^ '。 | 1837 1838**返回值：** 1839 1840| 类型 | 说明 | 1841| -------------- | --------------- | 1842| [Query](#query) | 返回Query对象。 | 1843 1844**示例：** 1845 1846```js 1847try { 1848 let query = new distributedKVStore.Query(); 1849 query.notEqualTo("field", "value"); 1850 query.orderByDesc("field"); 1851 console.info(`query is ${query.getSqlLike()}`); 1852 query = null; 1853} catch (e) { 1854 console.error(`duplicated calls should be ok.code is ${e.code},message is ${e.message}`); 1855} 1856``` 1857 1858### limit 1859 1860limit(total: number, offset: number): Query 1861 1862构造一个Query对象来指定结果的数量和开始位置。该接口必须要在Query对象查询和升降序等操作之后调用，调用limit接口后，不可再对Query对象进行查询和升降序等操作。 1863 1864**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1865 1866**参数：** 1867 1868| 参数名 | 类型 | 必填 | 说明 | 1869| ------ | -------- | ---- | ------------------ | 1870| total | number | 是 | 表示指定的结果数。 | 1871| offset | number | 是 | 表示起始位置。 | 1872 1873**返回值：** 1874 1875| 类型 | 说明 | 1876| -------------- | --------------- | 1877| [Query](#query) | 返回Query对象。 | 1878 1879**示例：** 1880 1881```js 1882let total = 10; 1883let offset = 1; 1884try { 1885 let query = new distributedKVStore.Query(); 1886 query.notEqualTo("field", "value"); 1887 query.limit(total, offset); 1888 console.info(`query is ${query.getSqlLike()}`); 1889 query = null; 1890} catch (e) { 1891 console.error(`duplicated calls should be ok.code is ${e.code},message is ${e.message}`); 1892} 1893``` 1894 1895### isNotNull 1896 1897isNotNull(field: string): Query 1898 1899构造一个Query对象以查询具有值不为null的指定字段的条目。 1900 1901**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1902 1903**参数：** 1904 1905| 参数名 | 类型 | 必填 | 说明 | 1906| ------ | -------- | ---- | ----------------------------- | 1907| fieId | string | 是 | 表示指定字段，不能包含' ^ '。 | 1908 1909**返回值：** 1910 1911| 类型 | 说明 | 1912| -------------- | --------------- | 1913| [Query](#query) | 返回Query对象。 | 1914 1915**示例：** 1916 1917```js 1918try { 1919 let query = new distributedKVStore.Query(); 1920 query.isNotNull("field"); 1921 console.info(`query is ${query.getSqlLike()}`); 1922 query = null; 1923} catch (e) { 1924 console.error(`duplicated calls should be ok.code is ${e.code},message is ${e.message}`); 1925} 1926``` 1927 1928### beginGroup 1929 1930beginGroup(): Query 1931 1932创建一个带有左括号的查询条件组。 1933 1934**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1935 1936**返回值：** 1937 1938| 类型 | 说明 | 1939| -------------- | --------------- | 1940| [Query](#query) | 返回Query对象。 | 1941 1942**示例：** 1943 1944```js 1945try { 1946 let query = new distributedKVStore.Query(); 1947 query.beginGroup(); 1948 query.isNotNull("field"); 1949 query.endGroup(); 1950 console.info("query is " + query.getSqlLike()); 1951 query = null; 1952} catch (e) { 1953 console.error("duplicated calls should be ok :" + e); 1954} 1955``` 1956 1957### endGroup 1958 1959endGroup(): Query 1960 1961创建一个带有右括号的查询条件组。 1962 1963**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1964 1965**返回值：** 1966 1967| 类型 | 说明 | 1968| -------------- | --------------- | 1969| [Query](#query) | 返回Query对象。 | 1970 1971**示例：** 1972 1973```js 1974try { 1975 let query = new distributedKVStore.Query(); 1976 query.beginGroup(); 1977 query.isNotNull("field"); 1978 query.endGroup(); 1979 console.info("query is " + query.getSqlLike()); 1980 query = null; 1981} catch (e) { 1982 console.error("duplicated calls should be ok :" + e); 1983} 1984``` 1985 1986### prefixKey 1987 1988prefixKey(prefix: string): Query 1989 1990创建具有指定键前缀的查询条件。 1991 1992**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1993 1994**参数：** 1995 1996| 参数名 | 类型 | 必填 | 说明 | 1997| ------ | -------- | ---- | ------------------ | 1998| prefix | string | 是 | 表示指定的键前缀。 | 1999 2000**返回值：** 2001 2002| 类型 | 说明 | 2003| -------------- | --------------- | 2004| [Query](#query) | 返回Query对象。 | 2005 2006**示例：** 2007 2008```js 2009try { 2010 let query = new distributedKVStore.Query(); 2011 query.prefixKey("$.name"); 2012 query.prefixKey("0"); 2013 console.info(`query is ${query.getSqlLike()}`); 2014 query = null; 2015} catch (e) { 2016 console.error(`duplicated calls should be ok.code is ${e.code},message is ${e.message}`); 2017} 2018``` 2019 2020### setSuggestIndex 2021 2022setSuggestIndex(index: string): Query 2023 2024设置一个指定的索引，将优先用于查询。 2025 2026**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 2027 2028**参数：** 2029 2030| 参数名 | 类型 | 必填 | 说明 | 2031| ------ | -------- | ---- | ------------------ | 2032| index | string | 是 | 指示要设置的索引。 | 2033 2034**返回值：** 2035 2036| 类型 | 说明 | 2037| -------------- | --------------- | 2038| [Query](#query) | 返回Query对象。 | 2039 2040**示例：** 2041 2042```js 2043try { 2044 let query = new distributedKVStore.Query(); 2045 query.setSuggestIndex("$.name"); 2046 query.setSuggestIndex("0"); 2047 console.info(`query is ${query.getSqlLike()}`); 2048 query = null; 2049} catch (e) { 2050 console.error(`duplicated calls should be ok.code is ${e.code},message is ${e.message}`); 2051} 2052``` 2053 2054### deviceId 2055 2056deviceId(deviceId:string):Query 2057 2058添加设备ID作为key的前缀。 2059 2060**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 2061 2062**参数：** 2063 2064| 参数名 | 类型 | 必填 | 说明 | 2065| -------- | -------- | ---- | ------------------ | 2066| deviceId | string | 是 | 指示查询的设备ID。 | 2067 2068**返回值：** 2069 2070| 类型 | 说明 | 2071| -------------- | --------------- | 2072| [Query](#query) | 返回Query对象。 | 2073 2074**示例：** 2075 2076```js 2077try { 2078 let query = new distributedKVStore.Query(); 2079 query.deviceId("deviceId"); 2080 console.info(`query is ${query.getSqlLike()}`); 2081} catch (e) { 2082 console.error(`duplicated calls should be ok.code is ${e.code},message is ${e.message}`); 2083} 2084``` 2085 2086### getSqlLike 2087 2088getSqlLike():string 2089 2090获取Query对象的查询语句。 2091 2092**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 2093 2094**返回值：** 2095 2096| 类型 | 说明 | 2097| ------ | ------------------------------------ | 2098| string | 返回一个字段列中包含对应子串的结果。 | 2099 2100**示例：** 2101 2102```js 2103try { 2104 let query = new distributedKVStore.Query(); 2105 let sql1 = query.getSqlLike(); 2106 console.info(`GetSqlLike sql= ${sql1}`); 2107} catch (e) { 2108 console.error("duplicated calls should be ok : " + e); 2109} 2110``` 2111 2112## SingleKVStore 2113 2114SingleKVStore数据库实例，提供增加数据、删除数据和订阅数据变更、订阅数据同步完成的方法。 2115 2116在调用SingleKVStore的方法前，需要先通过[getKVStore](#getkvstore)构建一个SingleKVStore实例。 2117 2118### put 2119 2120put(key: string, value: Uint8Array | string | number | boolean, callback: AsyncCallback<void>): void 2121 2122添加指定类型键值对到数据库，使用callback异步回调。 2123 2124**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 2125 2126**参数：** 2127 2128| 参数名 | 类型 | 必填 | 说明 | 2129| ----- | ------ | ---- | ----------------------- | 2130| key | string | 是 |要添加数据的key，不能为空且长度不大于[MAX_KEY_LENGTH](#constants)。 | 2131| value | Uint8Array \| string \| number \| boolean | 是 |要添加数据的value，支持Uint8Array、number 、 string 、boolean，Uint8Array、string 的长度不大于[MAX_VALUE_LENGTH](#constants)。 | 2132| callback | AsyncCallback<void> | 是 |回调函数。 | 2133 2134**错误码：** 2135 2136以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 2137 2138| **错误码ID** | **错误信息** | 2139| ------------ | -------------------------------------- | 2140| 15100003 | Database corrupted. | 2141| 15100005 | Database or result set already closed. | 2142 2143**示例：** 2144 2145```js 2146let kvStore; 2147const KEY_TEST_STRING_ELEMENT = 'key_test_string'; 2148const VALUE_TEST_STRING_ELEMENT = 'value-test-string'; 2149try { 2150 kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT, function (err) { 2151 if (err != undefined) { 2152 console.error(`Failed to put.code is ${err.code},message is ${err.message}`); 2153 return; 2154 } 2155 console.info("Succeeded in putting"); 2156 }); 2157} catch (e) { 2158 console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`); 2159} 2160``` 2161 2162### put 2163 2164put(key: string, value: Uint8Array | string | number | boolean): Promise<void> 2165 2166添加指定类型键值对到数据库，使用Promise异步回调。 2167 2168**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 2169 2170**参数：** 2171 2172| 参数名 | 类型 | 必填 | 说明 | 2173| ----- | ------ | ---- | ----------------------- | 2174| key | string | 是 |要添加数据的key，不能为空且长度不大于[MAX_KEY_LENGTH](#constants)。 | 2175| value | Uint8Array \| string \| number \| boolean | 是 |要添加数据的value，支持Uint8Array、number 、 string 、boolean，Uint8Array、string 的长度不大于[MAX_VALUE_LENGTH](#constants)。 | 2176 2177**返回值：** 2178 2179| 类型 | 说明 | 2180| ------------------- | ------------------------- | 2181| Promise<void> | 无返回结果的Promise对象。 | 2182 2183**错误码：** 2184 2185以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 2186 2187| **错误码ID** | **错误信息** | 2188| ------------ | -------------------------------------- | 2189| 15100003 | Database corrupted. | 2190| 15100005 | Database or result set already closed. | 2191 2192**示例：** 2193 2194```js 2195let kvStore; 2196const KEY_TEST_STRING_ELEMENT = 'key_test_string'; 2197const VALUE_TEST_STRING_ELEMENT = 'value-test-string'; 2198try { 2199 kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT).then(() => { 2200 console.info(`Succeeded in putting data`); 2201 }).catch((err) => { 2202 console.error(`Failed to put.code is ${err.code},message is ${err.message}`); 2203 }); 2204} catch (e) { 2205 console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`); 2206} 2207``` 2208 2209### putBatch 2210 2211putBatch(entries: Entry[], callback: AsyncCallback<void>): void 2212 2213批量插入键值对到SingleKVStore数据库中，使用callback异步回调。 2214 2215**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 2216 2217**参数：** 2218 2219| 参数名 | 类型 | 必填 | 说明 | 2220| -------- | ------------------------ | ---- | ------------------------ | 2221| entries | [Entry](#entry)[] | 是 | 表示要批量插入的键值对。一个entries对象中允许的最大条目个数为128个。 | 2222| callback | AsyncCallback<void> | 是 | 回调函数。 | 2223 2224**错误码：** 2225 2226以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 2227 2228| **错误码ID** | **错误信息** | 2229| ------------ | -------------------------------------- | 2230| 15100003 | Database corrupted. | 2231| 15100005 | Database or result set already closed. | 2232 2233**示例：** 2234 2235```js 2236let kvStore; 2237try { 2238 let entries = []; 2239 for (var i = 0; i < 10; i++) { 2240 var key = 'batch_test_string_key'; 2241 var entry = { 2242 key: key + i, 2243 value: { 2244 type: distributedKVStore.ValueType.STRING, 2245 value: 'batch_test_string_value' 2246 } 2247 } 2248 entries.push(entry); 2249 } 2250 console.info(`entries: ${entries}`); 2251 kvStore.putBatch(entries, async function (err) { 2252 if (err != undefined) { 2253 console.error(`Failed to put Batch.code is ${err.code},message is ${err.message}`); 2254 return; 2255 } 2256 console.info('Succeeded in putting Batch'); 2257 kvStore.getEntries('batch_test_string_key', function (err, entries) { 2258 if (err != undefined) { 2259 console.error(`Failed to get Entries.code is ${err.code},message is ${err.message}`); 2260 } 2261 console.info('Succeeded in getting Entries'); 2262 console.info(`entries.length: ${entries.length}`); 2263 console.info(`entries[0]: ${entries[0]}`); 2264 }); 2265 }); 2266} catch (e) { 2267 console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message} `); 2268} 2269``` 2270 2271### putBatch 2272 2273putBatch(entries: Entry[]): Promise<void> 2274 2275批量插入键值对到SingleKVStore数据库中，使用Promise异步回调。 2276 2277**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 2278 2279**参数：** 2280 2281| 参数名 | 类型 | 必填 | 说明 | 2282| ------- | ----------------- | ---- | ------------------------ | 2283| entries | [Entry](#entry)[] | 是 | 表示要批量插入的键值对。一个entries对象中允许的最大条目个数为128个。 | 2284 2285**返回值：** 2286 2287| 类型 | 说明 | 2288| ------------------- | ------------------------- | 2289| Promise<void> | 无返回结果的Promise对象。 | 2290 2291**错误码：** 2292 2293以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 2294 2295| **错误码ID** | **错误信息** | 2296| ------------ | -------------------------------------- | 2297| 15100003 | Database corrupted. | 2298| 15100005 | Database or result set already closed. | 2299 2300**示例：** 2301 2302```js 2303let kvStore; 2304try { 2305 let entries = []; 2306 for (var i = 0; i < 10; i++) { 2307 var key = 'batch_test_string_key'; 2308 var entry = { 2309 key: key + i, 2310 value: { 2311 type: distributedKVStore.ValueType.STRING, 2312 value: 'batch_test_string_value' 2313 } 2314 } 2315 entries.push(entry); 2316 } 2317 console.info(`entries: ${entries}`); 2318 kvStore.putBatch(entries).then(async () => { 2319 console.info('Succeeded in putting Batch'); 2320 kvStore.getEntries('batch_test_string_key').then((entries) => { 2321 console.info('Succeeded in getting Entries'); 2322 console.info(`PutBatch ${entries}`); 2323 }).catch((err) => { 2324 console.error(`Failed to get Entries.code is ${err.code},message is ${err.message}`); 2325 }); 2326 }).catch((err) => { 2327 console.error(`Failed to put Batch.code is ${err.code},message is ${err.message}`); 2328 }); 2329} catch (e) { 2330 console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message} `); 2331} 2332``` 2333 2334### putBatch 2335 2336putBatch(value: Array<ValuesBucket>, callback: AsyncCallback<void>): void 2337 2338将值写入SingleKVStore数据库，使用callback异步回调。 2339 2340**系统接口：** 此接口为系统接口。 2341 2342**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 2343 2344**参数：** 2345 2346| 参数名 | 类型 | 必填 | 说明 | 2347| -------- | ------------------------------------------------------------ | ---- | ------------------ | 2348| value | Array<[ValuesBucket](js-apis-data-valuesBucket.md#valuesbucket)> | 是 | 表示要插入的数据。 | 2349| callback | AsyncCallback<void> | 是 | 回调函数。 | 2350 2351**错误码：** 2352 2353以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 2354 2355| **错误码ID** | **错误信息** | 2356| ------------ | -------------------------------------- | 2357| 15100003 | Database corrupted. | 2358| 15100005 | Database or result set already closed. | 2359 2360**示例：** 2361 2362```js 2363let kvStore; 2364try { 2365 let v8Arr = []; 2366 let arr = new Uint8Array([4, 5, 6, 7]); 2367 let vb1 = { key: "name_1", value: 32 } 2368 let vb2 = { key: "name_2", value: arr }; 2369 let vb3 = { key: "name_3", value: "lisi" }; 2370 2371 v8Arr.push(vb1); 2372 v8Arr.push(vb2); 2373 v8Arr.push(vb3); 2374 kvStore.putBatch(v8Arr, async function (err) { 2375 if (err != undefined) { 2376 console.error(`Failed to put batch.code is ${err.code},message is ${err.message}`); 2377 return; 2378 } 2379 console.info('Succeeded in putting batch'); 2380 }) 2381} catch (e) { 2382 console.error(`Failed to put batch.code is ${e.code},message is ${e.message}`); 2383} 2384``` 2385 2386### putBatch 2387 2388putBatch(value: Array<ValuesBucket>): Promise<void> 2389 2390将valuesbucket类型的值写入SingleKVStore数据库，使用Promise异步回调。 2391 2392**系统接口：** 此接口为系统接口。 2393 2394**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 2395 2396**参数：** 2397 2398| 参数名 | 类型 | 必填 | 说明 | 2399| ------ | ------------------------------------------------------------ | ---- | ------------------ | 2400| value | Array<[ValuesBucket](js-apis-data-valuesBucket.md#valuesbucket)> | 是 | 表示要插入的数据。 | 2401 2402**返回值：** 2403 2404| 类型 | 说明 | 2405| ------------------- | ------------------------- | 2406| Promise<void> | 五返回结果的Promise对象。 | 2407 2408**错误码：** 2409 2410以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 2411 2412| **错误码ID** | **错误信息** | 2413| ------------ | -------------------------------------- | 2414| 15100003 | Database corrupted. | 2415| 15100005 | Database or result set already closed. | 2416 2417**示例：** 2418 2419```js 2420let kvStore; 2421try { 2422 let v8Arr = []; 2423 let arr = new Uint8Array([4, 5, 6, 7]); 2424 let vb1 = { key: "name_1", value: 32 } 2425 let vb2 = { key: "name_2", value: arr }; 2426 let vb3 = { key: "name_3", value: "lisi" }; 2427 2428 v8Arr.push(vb1); 2429 v8Arr.push(vb2); 2430 v8Arr.push(vb3); 2431 kvStore.putBatch(v8Arr).then(async () => { 2432 console.info(`Succeeded in putting patch`); 2433 }).catch((err) => { 2434 console.error(`putBatch fail.code is ${err.code},message is ${err.message}`); 2435 }); 2436} catch (e) { 2437 console.error(`putBatch fail.code is ${e.code},message is ${e.message}`); 2438} 2439``` 2440 2441### delete 2442 2443delete(key: string, callback: AsyncCallback<void>): void 2444 2445从数据库中删除指定键值的数据，使用callback异步回调。 2446 2447**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 2448 2449**参数：** 2450 2451| 参数名 | 类型 | 必填 | 说明 | 2452| -------- | ------------------------- | ---- | ------------------------------------------------------------ | 2453| key | string | 是 | 要删除数据的key，不能为空且长度不大于[MAX_KEY_LENGTH](#constants)。 | 2454| callback | AsyncCallback<void> | 是 | 回调函数。 | 2455 2456**错误码：** 2457 2458以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 2459 2460| **错误码ID** | **错误信息** | 2461| ------------ | -------------------------------------- | 2462| 15100003 | Database corrupted. | 2463| 15100005 | Database or result set already closed. | 2464 2465**示例：** 2466 2467```js 2468let kvStore; 2469const KEY_TEST_STRING_ELEMENT = 'key_test_string'; 2470const VALUE_TEST_STRING_ELEMENT = 'value-test-string'; 2471try { 2472 kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT, function (err) { 2473 if (err != undefined) { 2474 console.error(`Failed to put.code is ${err.code},message is ${err.message}`); 2475 return; 2476 } 2477 console.info('Succeeded in putting'); 2478 kvStore.delete(KEY_TEST_STRING_ELEMENT, function (err) { 2479 if (err != undefined) { 2480 console.error(`Failed to delete.code is ${err.code},message is ${err.message}`); 2481 return; 2482 } 2483 console.info('Succeeded in deleting'); 2484 }); 2485 }); 2486} catch (e) { 2487 console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`); 2488} 2489``` 2490 2491### delete 2492 2493delete(key: string): Promise<void> 2494 2495从数据库中删除指定键值的数据，使用Promise异步回调。 2496 2497**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 2498 2499**参数：** 2500 2501| 参数名 | 类型 | 必填 | 说明 | 2502| ------ | -------- | ---- | ------------------------------------------------------------ | 2503| key | string | 是 | 要删除数据的key，不能为空且长度不大于[MAX_KEY_LENGTH](#constants)。 | 2504 2505**返回值：** 2506 2507| 类型 | 说明 | 2508| ------------------- | ------------------------- | 2509| Promise<void> | 无返回结果的Promise对象。 | 2510 2511**错误码：** 2512 2513以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 2514 2515| **错误码ID** | **错误信息** | 2516| ------------ | -------------------------------------- | 2517| 15100003 | Database corrupted. | 2518| 15100005 | Database or result set already closed. | 2519 2520**示例：** 2521 2522```js 2523let kvStore; 2524const KEY_TEST_STRING_ELEMENT = 'key_test_string'; 2525const VALUE_TEST_STRING_ELEMENT = 'value-test-string'; 2526try { 2527 kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT).then(() => { 2528 console.info(`Succeeded in putting data`); 2529 kvStore.delete(KEY_TEST_STRING_ELEMENT).then(() => { 2530 console.info('Succeeded in deleting'); 2531 }).catch((err) => { 2532 console.error(`Failed to delete.code is ${err.code},message is ${err.message}`); 2533 }); 2534 }).catch((err) => { 2535 console.error(`Failed to put.code is ${err.code},message is ${err.message}`); 2536 }); 2537} catch (e) { 2538 console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`); 2539} 2540``` 2541 2542### delete 2543 2544delete(predicates: dataSharePredicates.DataSharePredicates, callback: AsyncCallback<void>) 2545 2546从数据库中删除符合predicates条件的键值对，使用callback异步回调。 2547 2548**系统接口：** 此接口为系统接口。 2549 2550**系统能力：** SystemCapability.DistributedDataManager.DataShare.Provider 2551 2552**参数：** 2553 2554| 参数名 | 类型 | 必填 | 说明 | 2555| ---------- | ------------------------------------------------------------ | ---- | ----------------------------------------------- | 2556| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | 是 | 指示筛选条件,当此参数为null时，应定义处理逻辑。 | 2557| callback | AsyncCallback<void> | 是 | 回调函数。 | 2558 2559**错误码：** 2560 2561以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 2562 2563| **错误码ID** | **错误信息** | 2564| ------------ | -------------------------------------- | 2565| 15100003 | Database corrupted. | 2566| 15100005 | Database or result set already closed. | 2567 2568**示例：** 2569 2570```js 2571import dataSharePredicates from '@ohos.data.dataSharePredicates'; 2572let kvStore; 2573try { 2574 let predicates = new dataSharePredicates.DataSharePredicates(); 2575 kvStore.delete(predicates, function (err) { 2576 if (err == undefined) { 2577 console.info('Succeeded in deleting'); 2578 } else { 2579 console.error(`Failed to delete.code is ${err.code},message is ${err.message}`); 2580 } 2581 }); 2582} catch (e) { 2583 console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`); 2584} 2585``` 2586 2587### delete 2588 2589delete(predicates: dataSharePredicates.DataSharePredicates): Promise<void> 2590 2591从数据库中删除符合predicates条件的键值对，使用Promise异步回调。 2592 2593**系统接口：** 此接口为系统接口。 2594 2595**系统能力：** SystemCapability.DistributedDataManager.DataShare.Provider 2596 2597**参数：** 2598 2599| 参数名 | 类型 | 必填 | 说明 | 2600| ---------- | ------------------------------------------------------------ | ---- | ----------------------------------------------- | 2601| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | 是 | 指示筛选条件,当此参数为null时，应定义处理逻辑。 | 2602 2603**返回值：** 2604 2605| 类型 | 说明 | 2606| ------------------- | ------------------------- | 2607| Promise<void> | 无返回结果的Promise对象。 | 2608 2609**错误码：** 2610 2611以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 2612 2613| **错误码ID** | **错误信息** | 2614| ------------ | -------------------------------------- | 2615| 15100003 | Database corrupted. | 2616| 15100005 | Database or result set already closed. | 2617 2618**示例：** 2619 2620```js 2621import dataSharePredicates from '@ohos.data.dataSharePredicates'; 2622 2623let kvStore; 2624try { 2625 let predicates = new dataSharePredicates.DataSharePredicates(); 2626 let arr = ["name"]; 2627 predicates.inKeys(arr); 2628 kvStore.put("name", "bob").then(() => { 2629 console.info(`Succeeded in putting data`); 2630 kvStore.delete(predicates).then(() => { 2631 console.info('Succeeded in deleting'); 2632 }).catch((err) => { 2633 console.error(`Failed to delete.code is ${err.code},message is ${err.message}`); 2634 }); 2635 }).catch((err) => { 2636 console.error(`Failed to put.code is ${err.code},message is ${err.message}`); 2637 }); 2638} catch (e) { 2639 console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`); 2640} 2641``` 2642 2643### deleteBatch 2644 2645deleteBatch(keys: string[], callback: AsyncCallback<void>): void 2646 2647批量删除SingleKVStore数据库中的键值对，使用callback异步回调。 2648 2649**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 2650 2651**参数：** 2652 2653| 参数名 | 类型 | 必填 | 说明 | 2654| -------- | ------------------------- | ---- | ------------------------ | 2655| keys | string[] | 是 | 表示要批量删除的键值对。 | 2656| callback | AsyncCallback<void> | 是 | 回调函数。 | 2657 2658**错误码：** 2659 2660以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 2661 2662| **错误码ID** | **错误信息** | 2663| ------------ | -------------------------------------- | 2664| 15100003 | Database corrupted. | 2665| 15100005 | Database or result set already closed. | 2666 2667**示例：** 2668 2669```js 2670let kvStore; 2671try { 2672 let entries = []; 2673 let keys = []; 2674 for (var i = 0; i < 5; i++) { 2675 var key = 'batch_test_string_key'; 2676 var entry = { 2677 key: key + i, 2678 value: { 2679 type: distributedKVStore.ValueType.STRING, 2680 value: 'batch_test_string_value' 2681 } 2682 } 2683 entries.push(entry); 2684 keys.push(key + i); 2685 } 2686 console.info(`entries: ${entries}`); 2687 kvStore.putBatch(entries, async function (err) { 2688 if (err != undefined) { 2689 console.error(`Failed to put Batch.code is ${err.code},message is ${err.message}`); 2690 return; 2691 } 2692 console.info('Succeeded in putting Batch'); 2693 kvStore.deleteBatch(keys, async function (err) { 2694 if (err != undefined) { 2695 console.error(`Failed to delete Batch.code is ${err.code},message is ${err.message}`); 2696 return; 2697 } 2698 console.info('Succeeded in deleting Batch'); 2699 }); 2700 }); 2701} catch (e) { 2702 console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`); 2703} 2704``` 2705 2706### deleteBatch 2707 2708deleteBatch(keys: string[]): Promise<void> 2709 2710批量删除SingleKVStore数据库中的键值对，使用Promise异步回调。 2711 2712**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 2713 2714**参数：** 2715 2716| 参数名 | 类型 | 必填 | 说明 | 2717| ------ | -------- | ---- | ------------------------ | 2718| keys | string[] | 是 | 表示要批量删除的键值对。 | 2719 2720**返回值：** 2721 2722| 类型 | 说明 | 2723| ------------------- | ------------------------- | 2724| Promise<void> | 无返回结果的Promise对象。 | 2725 2726**错误码：** 2727 2728以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 2729 2730| **错误码ID** | **错误信息** | 2731| ------------ | -------------------------------------- | 2732| 15100003 | Database corrupted. | 2733| 15100005 | Database or result set already closed. | 2734 2735**示例：** 2736 2737```js 2738let kvStore; 2739try { 2740 let entries = []; 2741 let keys = []; 2742 for (var i = 0; i < 5; i++) { 2743 var key = 'batch_test_string_key'; 2744 var entry = { 2745 key: key + i, 2746 value: { 2747 type: distributedKVStore.ValueType.STRING, 2748 value: 'batch_test_string_value' 2749 } 2750 } 2751 entries.push(entry); 2752 keys.push(key + i); 2753 } 2754 console.info(`entries: ${entries}`); 2755 kvStore.putBatch(entries).then(async () => { 2756 console.info('Succeeded in putting Batch'); 2757 kvStore.deleteBatch(keys).then(() => { 2758 console.info('Succeeded in deleting Batch'); 2759 }).catch((err) => { 2760 console.error(`Failed to delete Batch.code is ${err.code},message is ${err.message}`); 2761 }); 2762 }).catch((err) => { 2763 console.error(`Failed to put Batch.code is ${err.code},message is ${err.message}`); 2764 }); 2765} catch (e) { 2766 console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`); 2767} 2768``` 2769 2770### removeDeviceData 2771 2772removeDeviceData(deviceId: string, callback: AsyncCallback<void>): void 2773 2774删除指定设备的数据，使用callback异步回调。 2775 2776**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 2777 2778**参数：** 2779 2780| 参数名 | 类型 | 必填 | 说明 | 2781| -------- | ------------------------- | ---- | ---------------------- | 2782| deviceId | string | 是 | 表示要删除设备的名称。 | 2783| callback | AsyncCallback<void> | 是 | 回调函数。 | 2784 2785**错误码：** 2786 2787以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 2788 2789| **错误码ID** | **错误信息** | 2790| ------------ | -------------------------------------- | 2791| 15100005 | Database or result set already closed. | 2792 2793**示例：** 2794 2795```js 2796let kvStore; 2797const KEY_TEST_STRING_ELEMENT = 'key_test_string_2'; 2798const VALUE_TEST_STRING_ELEMENT = 'value-string-002'; 2799try { 2800 kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT, async function (err) { 2801 console.info('Succeeded in putting data'); 2802 const deviceid = 'no_exist_device_id'; 2803 kvStore.removeDeviceData(deviceid, async function (err) { 2804 if (err == undefined) { 2805 console.info('succeeded in removing device data'); 2806 } else { 2807 console.error(`Failed to remove device data.code is ${err.code},message is ${err.message} `); 2808 kvStore.get(KEY_TEST_STRING_ELEMENT, async function (err, data) { 2809 console.info('Succeeded in getting data'); 2810 }); 2811 } 2812 }); 2813 }); 2814} catch (e) { 2815 console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`) 2816} 2817``` 2818 2819### removeDeviceData 2820 2821removeDeviceData(deviceId: string): Promise<void> 2822 2823删除指定设备的数据，使用Promise异步回调。 2824 2825**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 2826 2827**参数：** 2828 2829| 参数名 | 类型 | 必填 | 说明 | 2830| -------- | -------- | ---- | ---------------------- | 2831| deviceId | string | 是 | 表示要删除设备的名称。 | 2832 2833**返回值：** 2834 2835| 类型 | 说明 | 2836| ------------------- | ------------------------- | 2837| Promise<void> | 无返回结果的Promise对象。 | 2838 2839**错误码：** 2840 2841以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 2842 2843| **错误码ID** | **错误信息** | 2844| ------------ | -------------------------------------- | 2845| 15100005 | Database or result set already closed. | 2846 2847**示例：** 2848 2849```js 2850let kvStore; 2851const KEY_TEST_STRING_ELEMENT = 'key_test_string_2'; 2852const VALUE_TEST_STRING_ELEMENT = 'value-string-001'; 2853try { 2854 kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT).then(() => { 2855 console.info('Succeeded in putting data'); 2856 }).catch((err) => { 2857 console.error(`Failed to put data.code is ${err.code},message is ${err.message} `); 2858 }); 2859 const deviceid = 'no_exist_device_id'; 2860 kvStore.removeDeviceData(deviceid).then(() => { 2861 console.info('succeeded in removing device data'); 2862 }).catch((err) => { 2863 console.error(`Failed to remove device data.code is ${err.code},message is ${err.message} `); 2864 }); 2865 kvStore.get(KEY_TEST_STRING_ELEMENT).then((data) => { 2866 console.info('Succeeded in getting data'); 2867 }).catch((err) => { 2868 console.error(`Failed to get data.code is ${err.code},message is ${err.message} `); 2869 }); 2870} catch (e) { 2871 console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`) 2872} 2873``` 2874 2875### get 2876 2877get(key: string, callback: AsyncCallback<boolean | string | number | Uint8Array>): void 2878 2879获取指定键的值，使用callback异步回调。 2880 2881**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 2882 2883**参数：** 2884 2885| 参数名 | 类型 | 必填 | 说明 | 2886| ----- | ------ | ---- | ----------------------- | 2887| key |string | 是 |要查询数据的key，不能为空且长度不大于[MAX_KEY_LENGTH](#constants)。 | 2888| callback |AsyncCallback<boolean \| string \| number \| Uint8Array> | 是 |回调函数。返回获取查询的值。 | 2889 2890**错误码：** 2891 2892以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 2893 2894| **错误码ID** | **错误信息** | 2895| ------------ | -------------------------------------- | 2896| 15100003 | Database corrupted. | 2897| 15100004 | Not found. | 2898| 15100005 | Database or result set already closed. | 2899 2900**示例：** 2901 2902```js 2903let kvStore; 2904const KEY_TEST_STRING_ELEMENT = 'key_test_string'; 2905const VALUE_TEST_STRING_ELEMENT = 'value-test-string'; 2906try { 2907 kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT, function (err) { 2908 if (err != undefined) { 2909 console.error(`Failed to put.code is ${err.code},message is ${err.message}`); 2910 return; 2911 } 2912 console.info("Succeeded in putting"); 2913 kvStore.get(KEY_TEST_STRING_ELEMENT, function (err, data) { 2914 if (err != undefined) { 2915 console.error(`Failed to get.code is ${err.code},message is ${err.message}`); 2916 return; 2917 } 2918 console.info(`Succeeded in getting data.data=${data}`); 2919 }); 2920 }); 2921} catch (e) { 2922 console.error(`Failed to get.code is ${e.code},message is ${e.message}`); 2923} 2924``` 2925 2926### get 2927 2928get(key: string): Promise<boolean | string | number | Uint8Array> 2929 2930获取指定键的值，使用Promise异步回调。 2931 2932**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 2933 2934**参数：** 2935 2936| 参数名 | 类型 | 必填 | 说明 | 2937| ------ | -------- | ---- | ------------------------------------------------------------ | 2938| key | string | 是 | 要查询数据的key，不能为空且长度不大于[MAX_KEY_LENGTH](#constants)。 | 2939 2940**返回值：** 2941 2942| 类型 | 说明 | 2943| ------ | ------- | 2944|Promise<Uint8Array \| string \| boolean \| number> |Promise对象。返回获取查询的值。| 2945 2946**错误码：** 2947 2948以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 2949 2950| **错误码ID** | **错误信息** | 2951| ------------ | -------------------------------------- | 2952| 15100003 | Database corrupted. | 2953| 15100004 | Not found. | 2954| 15100005 | Database or result set already closed. | 2955 2956**示例：** 2957 2958```js 2959let kvStore; 2960const KEY_TEST_STRING_ELEMENT = 'key_test_string'; 2961const VALUE_TEST_STRING_ELEMENT = 'value-test-string'; 2962try { 2963 kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT).then(() => { 2964 console.info(`Succeeded in putting data`); 2965 kvStore.get(KEY_TEST_STRING_ELEMENT).then((data) => { 2966 console.info(`Succeeded in getting data.data=${data}`); 2967 }).catch((err) => { 2968 console.error(`Failed to get.code is ${err.code},message is ${err.message}`); 2969 }); 2970 }).catch((err) => { 2971 console.error(`Failed to put.code is ${err.code},message is ${err.message}`); 2972 }); 2973} catch (e) { 2974 console.error(`Failed to get.code is ${e.code},message is ${e.message}`); 2975} 2976``` 2977 2978### getEntries 2979 2980getEntries(keyPrefix: string, callback: AsyncCallback<Entry[]>): void 2981 2982获取匹配指定键前缀的所有键值对，使用callback异步回调。 2983 2984**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 2985 2986**参数：** 2987 2988| 参数名 | 类型 | 必填 | 说明 | 2989| --------- | -------------------------------------- | ---- | ---------------------------------------- | 2990| keyPrefix | string | 是 | 表示要匹配的键前缀。 | 2991| callback | AsyncCallback<[Entry](#entry)[]> | 是 | 回调函数。返回匹配指定前缀的键值对列表。 | 2992 2993**错误码：** 2994 2995以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 2996 2997| **错误码ID** | **错误信息** | 2998| ------------ | -------------------------------------- | 2999| 15100003 | Database corrupted. | 3000| 15100005 | Database or result set already closed. | 3001 3002**示例：** 3003 3004```js 3005let kvStore; 3006try { 3007 let entries = []; 3008 for (var i = 0; i < 10; i++) { 3009 var key = 'batch_test_string_key'; 3010 var entry = { 3011 key: key + i, 3012 value: { 3013 type: distributedKVStore.ValueType.STRING, 3014 value: 'batch_test_string_value' 3015 } 3016 } 3017 entries.push(entry); 3018 } 3019 console.info(`entries: ${entries}`); 3020 kvStore.putBatch(entries, async function (err) { 3021 if (err != undefined) { 3022 console.error(`Failed to put Batch.code is ${err.code},message is ${err.message}`); 3023 return; 3024 } 3025 console.info('Succeeded in putting Batch'); 3026 kvStore.getEntries('batch_test_string_key', function (err, entries) { 3027 if (err != undefined) { 3028 console.error(`Failed to get Entries.code is ${err.code},message is ${err.message}`); 3029 return; 3030 } 3031 console.info('Succeeded in getting Entries'); 3032 console.info(`entries.length: ${entries.length}`); 3033 console.info(`entries[0]: ${entries[0]}`); 3034 }); 3035 }); 3036} catch (e) { 3037 console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message} `); 3038} 3039``` 3040 3041### getEntries 3042 3043getEntries(keyPrefix: string): Promise<Entry[]> 3044 3045获取匹配指定键前缀的所有键值对，使用Promise异步回调。 3046 3047**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 3048 3049**参数：** 3050 3051| 参数名 | 类型 | 必填 | 说明 | 3052| --------- | -------- | ---- | -------------------- | 3053| keyPrefix | string | 是 | 表示要匹配的键前缀。 | 3054 3055**返回值：** 3056 3057| 类型 | 说明 | 3058| -------------------------------- | ------------------------------------------- | 3059| Promise<[Entry](#entry)[]> | Promise对象。返回匹配指定前缀的键值对列表。 | 3060 3061**错误码：** 3062 3063以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 3064 3065| **错误码ID** | **错误信息** | 3066| ------------ | -------------------------------------- | 3067| 15100003 | Database corrupted. | 3068| 15100005 | Database or result set already closed. | 3069 3070**示例：** 3071 3072```js 3073let kvStore; 3074try { 3075 let entries = []; 3076 for (var i = 0; i < 10; i++) { 3077 var key = 'batch_test_string_key'; 3078 var entry = { 3079 key: key + i, 3080 value: { 3081 type: distributedKVStore.ValueType.STRING, 3082 value: 'batch_test_string_value' 3083 } 3084 } 3085 entries.push(entry); 3086 } 3087 console.info(`entries: ${entries}`); 3088 kvStore.putBatch(entries).then(async () => { 3089 console.info('Succeeded in putting Batch'); 3090 kvStore.getEntries('batch_test_string_key').then((entries) => { 3091 console.info('Succeeded in getting Entries'); 3092 console.info(`PutBatch ${entries}`); 3093 }).catch((err) => { 3094 console.error(`Failed to get Entries.code is ${err.code},message is ${err.message}`); 3095 }); 3096 }).catch((err) => { 3097 console.error(`Failed to put Batch.code is ${err.code},message is ${err.message}`); 3098 }); 3099} catch (e) { 3100 console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message} `); 3101} 3102``` 3103 3104### getEntries 3105 3106getEntries(query: Query, callback: AsyncCallback<Entry[]>): void 3107 3108获取与指定Query对象匹配的键值对列表，使用callback异步回调。 3109 3110**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 3111 3112**参数：** 3113 3114| 参数名 | 类型 | 必填 | 说明 | 3115| -------- | -------------------------------------- | ---- | ----------------------------------------------- | 3116| query | [Query](#query) | 是 | 表示要匹配的键前缀。 | 3117| callback | AsyncCallback<[Entry](#entry)[]> | 是 | 回调函数。返回与指定Query对象匹配的键值对列表。 | 3118 3119**错误码：** 3120 3121以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 3122 3123| **错误码ID** | **错误信息** | 3124| ------------ | -------------------------------------- | 3125| 15100003 | Database corrupted. | 3126| 15100005 | Database or result set already closed. | 3127 3128**示例：** 3129 3130```js 3131let kvStore; 3132try { 3133 var arr = new Uint8Array([21, 31]); 3134 let entries = []; 3135 for (var i = 0; i < 10; i++) { 3136 var key = 'batch_test_bool_key'; 3137 var entry = { 3138 key: key + i, 3139 value: { 3140 type: distributedKVStore.ValueType.BYTE_ARRAY, 3141 value: arr 3142 } 3143 } 3144 entries.push(entry); 3145 } 3146 console.info(`entries: {entries}`); 3147 kvStore.putBatch(entries, async function (err) { 3148 console.info('Succeeded in putting Batch'); 3149 const query = new distributedKVStore.Query(); 3150 query.prefixKey("batch_test"); 3151 kvStore.getEntries(query, function (err, entries) { 3152 if (err != undefined) { 3153 console.error(`Failed to get Entries.code is ${err.code},message is ${err.message}`); 3154 return; 3155 } 3156 console.info('Succeeded in getting Entries'); 3157 console.info(`entries.length: ${entries.length}`); 3158 console.info(`entries[0]: ${entries[0]}`); 3159 }); 3160 }); 3161} catch (e) { 3162 console.error(`Failed to get Entries.code is ${e.code},message is ${e.message}`); 3163} 3164``` 3165 3166### getEntries 3167 3168getEntries(query: Query): Promise<Entry[]> 3169 3170获取与指定Query对象匹配的键值对列表，使用Promise异步回调。 3171 3172**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 3173 3174**参数：** 3175 3176| 参数名 | 类型 | 必填 | 说明 | 3177| ------ | -------------- | ---- | -------------- | 3178| query | [Query](#query) | 是 | 表示查询对象。 | 3179 3180**返回值：** 3181 3182| 类型 | 说明 | 3183| -------------------------------- | -------------------------------------------------- | 3184| Promise<[Entry](#entry)[]> | Promise对象。返回与指定Query对象匹配的键值对列表。 | 3185 3186**错误码：** 3187 3188以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 3189 3190| **错误码ID** | **错误信息** | 3191| ------------ | -------------------------------------- | 3192| 15100003 | Database corrupted. | 3193| 15100005 | Database or result set already closed. | 3194 3195**示例：** 3196 3197```js 3198let kvStore; 3199try { 3200 var arr = new Uint8Array([21, 31]); 3201 let entries = []; 3202 for (var i = 0; i < 10; i++) { 3203 var key = 'batch_test_bool_key'; 3204 var entry = { 3205 key: key + i, 3206 value: { 3207 type: distributedKVStore.ValueType.BYTE_ARRAY, 3208 value: arr 3209 } 3210 } 3211 entries.push(entry); 3212 } 3213 console.info(`entries: {entries}`); 3214 kvStore.putBatch(entries).then(async () => { 3215 console.info('Succeeded in putting Batch'); 3216 const query = new distributedKVStore.Query(); 3217 query.prefixKey("batch_test"); 3218 kvStore.getEntries(query).then((entries) => { 3219 console.info('Succeeded in getting Entries'); 3220 }).catch((err) => { 3221 console.error(`Failed to get Entries.code is ${err.code},message is ${err.message}`); 3222 }); 3223 }).catch((err) => { 3224 console.error(`Failed to get Entries.code is ${err.code},message is ${err.message}`) 3225 }); 3226 console.info('Succeeded in getting Entries'); 3227} catch (e) { 3228 console.error(`Failed to get Entries.code is ${e.code},message is ${e.message}`); 3229} 3230``` 3231 3232### getResultSet 3233 3234getResultSet(keyPrefix: string, callback: AsyncCallback<KVStoreResultSet>): void 3235 3236从SingleKVStore数据库中获取具有指定前缀的结果集，使用callback异步回调。 3237 3238**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 3239 3240**参数：** 3241 3242| 参数名 | 类型 | 必填 | 说明 | 3243| --------- | ---------------------------------------------------------- | ---- | ------------------------------------ | 3244| keyPrefix | string | 是 | 表示要匹配的键前缀。 | 3245| callback | AsyncCallback<[KVStoreResultSet](#kvstoreresultset)> | 是 | 回调函数。返回具有指定前缀的结果集。 | 3246 3247**错误码：** 3248 3249以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 3250 3251| **错误码ID** | **错误信息** | 3252| ------------ | -------------------------------------- | 3253| 15100003 | Database corrupted. | 3254| 15100005 | Database or result set already closed. | 3255 3256**示例：** 3257 3258```js 3259let kvStore; 3260try { 3261 let resultSet; 3262 let entries = []; 3263 for (var i = 0; i < 10; i++) { 3264 var key = 'batch_test_string_key'; 3265 var entry = { 3266 key: key + i, 3267 value: { 3268 type: distributedKVStore.ValueType.STRING, 3269 value: 'batch_test_string_value' 3270 } 3271 } 3272 entries.push(entry); 3273 } 3274 kvStore.putBatch(entries, async function (err) { 3275 if (err != undefined) { 3276 console.error(`Failed to put batch.code is ${err.code},message is ${err.message}`); 3277 return; 3278 } 3279 console.info('Succeeded in putting batch'); 3280 kvStore.getResultSet('batch_test_string_key', async function (err, result) { 3281 if (err != undefined) { 3282 console.error(`Failed to get resultset.code is ${err.code},message is ${err.message}`); 3283 return; 3284 } 3285 console.info('Succeeded in getting result set'); 3286 resultSet = result; 3287 kvStore.closeResultSet(resultSet, function (err) { 3288 if (err != undefined) { 3289 console.error(`Failed to close resultset.code is ${err.code},message is ${err.message}`); 3290 return; 3291 } 3292 console.info('Succeeded in closing result set'); 3293 }) 3294 }); 3295 }); 3296} catch (e) { 3297 console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`); 3298} 3299``` 3300 3301### getResultSet 3302 3303getResultSet(keyPrefix: string): Promise<KVStoreResultSet> 3304 3305从SingleKVStore数据库中获取具有指定前缀的结果集，使用Promise异步回调。 3306 3307**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 3308 3309**参数：** 3310 3311| 参数名 | 类型 | 必填 | 说明 | 3312| --------- | -------- | ---- | -------------------- | 3313| keyPrefix | string | 是 | 表示要匹配的键前缀。 | 3314 3315**返回值：** 3316 3317| 类型 | 说明 | 3318| ---------------------------------------------------- | --------------------------------------- | 3319| Promise<[KVStoreResultSet](#kvstoreresultset)> | Promise对象。返回具有指定前缀的结果集。 | 3320 3321**错误码：** 3322 3323以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 3324 3325| **错误码ID** | **错误信息** | 3326| ------------ | -------------------------------------- | 3327| 15100003 | Database corrupted. | 3328| 15100005 | Database or result set already closed. | 3329 3330**示例：** 3331 3332```js 3333let kvStore; 3334try { 3335 let resultSet; 3336 let entries = []; 3337 for (var i = 0; i < 10; i++) { 3338 var key = 'batch_test_string_key'; 3339 var entry = { 3340 key: key + i, 3341 value: { 3342 type: distributedKVStore.ValueType.STRING, 3343 value: 'batch_test_string_value' 3344 } 3345 } 3346 entries.push(entry); 3347 } 3348 kvStore.putBatch(entries).then(async () => { 3349 console.info('Succeeded in putting batch'); 3350 }).catch((err) => { 3351 console.error(`Failed to put batch.code is ${err.code},message is ${err.message}`); 3352 }); 3353 kvStore.getResultSet('batch_test_string_key').then((result) => { 3354 console.info('Succeeded in getting result set'); 3355 resultSet = result; 3356 }).catch((err) => { 3357 console.error(`Failed to get resultset.code is ${err.code},message is ${err.message}`); 3358 }); 3359 kvStore.closeResultSet(resultSet).then(() => { 3360 console.info('Succeeded in closing result set'); 3361 }).catch((err) => { 3362 console.error(`Failed to close resultset.code is ${err.code},message is ${err.message}`); 3363 }); 3364} catch (e) { 3365 console.error(`An unexpected error occurred.code is ${e.code},message is ${e.code}`); 3366} 3367``` 3368 3369### getResultSet 3370 3371getResultSet(query: Query, callback: AsyncCallback<KVStoreResultSet>): void 3372 3373获取与指定Query对象匹配的KVStoreResultSet对象，使用callback异步回调。 3374 3375**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 3376 3377**参数：** 3378 3379| 参数名 | 类型 | 必填 | 说明 | 3380| -------- | ---------------------------------------------------------- | ---- | --------------------------------------------------------- | 3381| query | Query | 是 | 表示查询对象。 | 3382| callback | AsyncCallback<[KVStoreResultSet](#kvstoreresultset)> | 是 | 回调函数，获取与指定Query对象匹配的KVStoreResultSet对象。 | 3383 3384**错误码：** 3385 3386以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 3387 3388| **错误码ID** | **错误信息** | 3389| ------------ | -------------------------------------- | 3390| 15100003 | Database corrupted. | 3391| 15100005 | Database or result set already closed. | 3392 3393**示例：** 3394 3395```js 3396let kvStore; 3397try { 3398 let resultSet; 3399 let entries = []; 3400 for (var i = 0; i < 10; i++) { 3401 var key = 'batch_test_string_key'; 3402 var entry = { 3403 key: key + i, 3404 value: { 3405 type: distributedKVStore.ValueType.STRING, 3406 value: 'batch_test_string_value' 3407 } 3408 } 3409 entries.push(entry); 3410 } 3411 kvStore.putBatch(entries, async function (err) { 3412 if (err != undefined) { 3413 console.error(`Failed to put batch.code is ${err.code},message is ${err.message}`); 3414 return; 3415 } 3416 console.info('Succeeded in putting batch'); 3417 const query = new distributedKVStore.Query(); 3418 query.prefixKey("batch_test"); 3419 kvStore.getResultSet(query, async function (err, result) { 3420 if (err != undefined) { 3421 console.error(`Failed to get resultset.code is ${err.code},message is ${err.message}`); 3422 return; 3423 } 3424 console.info('Succeeded in getting result set'); 3425 }); 3426 }); 3427} catch (e) { 3428 console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`); 3429} 3430``` 3431 3432### getResultSet 3433 3434getResultSet(query: Query): Promise<KVStoreResultSet> 3435 3436获取与指定Query对象匹配的KVStoreResultSet对象，使用Promise异步回调。 3437 3438**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 3439 3440**参数：** 3441 3442| 参数名 | 类型 | 必填 | 说明 | 3443| ------ | -------------- | ---- | -------------- | 3444| query | [Query](#query) | 是 | 表示查询对象。 | 3445 3446**返回值：** 3447 3448| 类型 | 说明 | 3449| ---------------------------------------------------- | ------------------------------------------------------------ | 3450| Promise<[KVStoreResultSet](#kvstoreresultset)> | Promise对象。获取与指定Query对象匹配的KVStoreResultSet对象。 | 3451 3452**错误码：** 3453 3454以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 3455 3456| **错误码ID** | **错误信息** | 3457| ------------ | -------------------------------------- | 3458| 15100003 | Database corrupted. | 3459| 15100005 | Database or result set already closed. | 3460 3461**示例：** 3462 3463```js 3464let kvStore; 3465try { 3466 let resultSet; 3467 let entries = []; 3468 for (var i = 0; i < 10; i++) { 3469 var key = 'batch_test_string_key'; 3470 var entry = { 3471 key: key + i, 3472 value: { 3473 type: distributedKVStore.ValueType.STRING, 3474 value: 'batch_test_string_value' 3475 } 3476 } 3477 entries.push(entry); 3478 } 3479 kvStore.putBatch(entries).then(async () => { 3480 console.info('Succeeded in putting batch'); 3481 }).catch((err) => { 3482 console.error(`Failed to put batch.code is ${err.code},message is ${err.message}`); 3483 }); 3484 const query = new distributedKVStore.Query(); 3485 query.prefixKey("batch_test"); 3486 kvStore.getResultSet(query).then((result) => { 3487 console.info('Succeeded in getting result set'); 3488 resultSet = result; 3489 }).catch((err) => { 3490 console.error(`Failed to get resultset.code is ${err.code},message is ${err.message}`); 3491 }); 3492} catch (e) { 3493 console.error(`An unexpected error occurred.code is ${e.code},message is ${e.code}`); 3494} 3495``` 3496 3497### getResultSet 3498 3499getResultSet(predicates: dataSharePredicates.DataSharePredicates, callback: AsyncCallback<KVStoreResultSet>): void 3500 3501获取与指定Predicate对象匹配的KVStoreResultSet对象，使用callback异步回调。 3502 3503**系统接口：** 此接口为系统接口。 3504 3505**系统能力：** SystemCapability.DistributedDataManager.DataShare.Provider 3506 3507**参数：** 3508 3509| 参数名 | 类型 | 必填 | 说明 | 3510| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 3511| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | 是 | 指示筛选条件,当此参数为null时，应定义处理逻辑。 | 3512| callback | AsyncCallback<[KVStoreResultSet](#kvstoreresultset)> | 是 | 回调函数，获取与指定Predicates对象匹配的KVStoreResultSet对象。 | 3513 3514**错误码：** 3515 3516以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 3517 3518| **错误码ID** | **错误信息** | 3519| ------------ | -------------------------------------- | 3520| 15100003 | Database corrupted. | 3521| 15100005 | Database or result set already closed. | 3522 3523**示例：** 3524 3525```js 3526import dataSharePredicates from '@ohos.data.dataSharePredicates'; 3527 3528let kvStore; 3529try { 3530 let resultSet; 3531 let predicates = new dataSharePredicates.DataSharePredicates(); 3532 predicates.prefixKey("batch_test_string_key"); 3533 kvStore.getResultSet(predicates, async function (err, result) { 3534 if (err != undefined) { 3535 console.error(`Failed to get resultset.code is ${err.code},message is ${err.message}`); 3536 return; 3537 } 3538 console.info('Succeeded in getting result set'); 3539 resultSet = result; 3540 kvStore.closeResultSet(resultSet, function (err) { 3541 if (err != undefined) { 3542 console.error(`Failed to close resultset.code is ${err.code},message is ${err.message}`); 3543 return; 3544 } 3545 console.info('Succeeded in closing result set'); 3546 }) 3547 }); 3548} catch (e) { 3549 console.error(`An unexpected error occurred.code is ${e.code},message is ${e.code}`); 3550} 3551``` 3552 3553### getResultSet 3554 3555getResultSet(predicates: dataSharePredicates.DataSharePredicates): Promise<KVStoreResultSet> 3556 3557获取与指定Predicate对象匹配的KVStoreResultSet对象，使用Promise异步回调。 3558 3559**系统接口：** 此接口为系统接口。 3560 3561**系统能力：** SystemCapability.DistributedDataManager.DataShare.Provider 3562 3563**参数：** 3564 3565| 参数名 | 类型 | 必填 | 说明 | 3566| ---------- | ------------------------------------------------------------ | ---- | ----------------------------------------------- | 3567| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | 是 | 指示筛选条件,当此参数为null时，应定义处理逻辑。 | 3568 3569**返回值：** 3570 3571| 类型 | 说明 | 3572| ---------------------------------------------------- | ------------------------- | 3573| Promise<[KVStoreResultSet](#kvstoreresultset)> | 无返回结果的Promise对象。 | 3574 3575**错误码：** 3576 3577以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 3578 3579| **错误码ID** | **错误信息** | 3580| ------------ | -------------------------------------- | 3581| 15100003 | Database corrupted. | 3582| 15100005 | Database or result set already closed. | 3583 3584**示例：** 3585 3586```js 3587import dataSharePredicates from '@ohos.data.dataSharePredicates'; 3588 3589let kvStore; 3590try { 3591 let resultSet; 3592 let predicates = new dataSharePredicates.DataSharePredicates(); 3593 predicates.prefixKey("batch_test_string_key"); 3594 kvStore.getResultSet(predicates).then((result) => { 3595 console.info('Succeeded in getting result set'); 3596 resultSet = result; 3597 }).catch((err) => { 3598 console.error(`Failed to get resultset.code is ${err.code},message is ${err.message}`); 3599 }); 3600 kvStore.closeResultSet(resultSet).then(() => { 3601 console.info('Succeeded in closing result set'); 3602 }).catch((err) => { 3603 console.error(`Failed to close resultset.code is ${err.code},message is ${err.message}`); 3604 }); 3605} catch (e) { 3606 console.error(`An unexpected error occurred.code is ${e.code},message is ${e.code}`); 3607} 3608``` 3609 3610### closeResultSet 3611 3612closeResultSet(resultSet: KVStoreResultSet, callback: AsyncCallback<void>): void 3613 3614关闭由[SingleKvStore.getResultSet](#getresultset-1)返回的KVStoreResultSet对象，使用callback异步回调。 3615 3616**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 3617 3618**参数：** 3619 3620| 参数名 | 类型 | 必填 | 说明 | 3621| --------- | ------------------------------------- | ---- | ---------------------------------- | 3622| resultSet | [KVStoreResultSet](#kvstoreresultset) | 是 | 表示要关闭的KVStoreResultSet对象。 | 3623| callback | AsyncCallback<void> | 是 | 回调函数。 | 3624 3625**示例：** 3626 3627```js 3628let kvStore; 3629try { 3630 let resultSet = null; 3631 kvStore.closeResultSet(resultSet, function (err) { 3632 if (err == undefined) { 3633 console.info('Succeeded in closing result set'); 3634 } else { 3635 console.error(`Failed to close resultset.code is ${err.code},message is ${err.message}`); 3636 } 3637 }); 3638} catch (e) { 3639 console.error(`An unexpected error occurred.code is ${e.code},message is ${e.code}`); 3640} 3641``` 3642 3643### closeResultSet 3644 3645closeResultSet(resultSet: KVStoreResultSet): Promise<void> 3646 3647关闭由[SingleKvStore.getResultSet](#getresultset-1)返回的KVStoreResultSet对象，使用Promise异步回调。 3648 3649**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 3650 3651**参数：** 3652 3653| 参数名 | 类型 | 必填 | 说明 | 3654| --------- | ------------------------------------- | ---- | ---------------------------------- | 3655| resultSet | [KVStoreResultSet](#kvstoreresultset) | 是 | 表示要关闭的KVStoreResultSet对象。 | 3656 3657**返回值：** 3658 3659| 类型 | 说明 | 3660| ------------------- | ------------------------- | 3661| Promise<void> | 无返回结果的Promise对象。 | 3662 3663**示例：** 3664 3665```js 3666let kvStore; 3667try { 3668 let resultSet = null; 3669 kvStore.closeResultSet(resultSet).then(() => { 3670 console.info('Succeeded in closing result set'); 3671 }).catch((err) => { 3672 console.error(`Failed to close resultset.code is ${err.code},message is ${err.message}`); 3673 }); 3674} catch (e) { 3675 console.error(`An unexpected error occurred.code is ${e.code},message is ${e.code}`); 3676} 3677``` 3678 3679### getResultSize 3680 3681getResultSize(query: Query, callback: AsyncCallback<number>): void 3682 3683获取与指定Query对象匹配的结果数，使用callback异步回调。 3684 3685**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 3686 3687**参数：** 3688 3689| 参数名 | 类型 | 必填 | 说明 | 3690| -------- | --------------------------- | ---- | ------------------------------------------- | 3691| query | [Query](#query) | 是 | 表示查询对象。 | 3692| callback | AsyncCallback<number> | 是 | 回调函数。返回与指定Query对象匹配的结果数。 | 3693 3694**错误码：** 3695 3696以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 3697 3698| **错误码ID** | **错误信息** | 3699| ------------ | -------------------------------------- | 3700| 15100003 | Database corrupted. | 3701| 15100005 | Database or result set already closed. | 3702 3703**示例：** 3704 3705```js 3706let kvStore; 3707try { 3708 let entries = []; 3709 for (var i = 0; i < 10; i++) { 3710 var key = 'batch_test_string_key'; 3711 var entry = { 3712 key: key + i, 3713 value: { 3714 type: distributedKVStore.ValueType.STRING, 3715 value: 'batch_test_string_value' 3716 } 3717 } 3718 entries.push(entry); 3719 } 3720 kvStore.putBatch(entries, async function (err) { 3721 console.info('Succeeded in putting batch'); 3722 const query = new distributedKVStore.Query(); 3723 query.prefixKey("batch_test"); 3724 kvStore.getResultSize(query, async function (err, resultSize) { 3725 if (err != undefined) { 3726 console.error(`Failed to get result size.code is ${err.code},message is ${err.message}`); 3727 return; 3728 } 3729 console.info('Succeeded in getting result set size'); 3730 }); 3731 }); 3732} catch (e) { 3733 console.error(`An unexpected error occurred.code is ${e.code},message is ${e.code}`); 3734} 3735``` 3736 3737### getResultSize 3738 3739getResultSize(query: Query): Promise<number> 3740 3741获取与指定Query对象匹配的结果数，使用Promise异步回调。 3742 3743**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 3744 3745**参数：** 3746 3747| 参数名 | 类型 | 必填 | 说明 | 3748| ------ | -------------- | ---- | -------------- | 3749| query | [Query](#query) | 是 | 表示查询对象。 | 3750 3751**返回值：** 3752 3753| 类型 | 说明 | 3754| --------------------- | ----------------------------------------------- | 3755| Promise<number> | Promise对象。获取与指定QuerV9对象匹配的结果数。 | 3756 3757**错误码：** 3758 3759以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 3760 3761| **错误码ID** | **错误信息** | 3762| ------------ | -------------------------------------- | 3763| 15100003 | Database corrupted. | 3764| 15100005 | Database or result set already closed. | 3765 3766**示例：** 3767 3768```js 3769let kvStore; 3770try { 3771 let entries = []; 3772 for (var i = 0; i < 10; i++) { 3773 var key = 'batch_test_string_key'; 3774 var entry = { 3775 key: key + i, 3776 value: { 3777 type: distributedKVStore.ValueType.STRING, 3778 value: 'batch_test_string_value' 3779 } 3780 } 3781 entries.push(entry); 3782 } 3783 kvStore.putBatch(entries).then(async () => { 3784 console.info('Succeeded in putting batch'); 3785 }).catch((err) => { 3786 console.error(`Failed to put batch.code is ${err.code},message is ${err.message}`); 3787 }); 3788 const query = new distributedKVStore.Query(); 3789 query.prefixKey("batch_test"); 3790 kvStore.getResultSize(query).then((resultSize) => { 3791 console.info('Succeeded in getting result set size'); 3792 }).catch((err) => { 3793 console.error(`Failed to get result size.code is ${err.code},message is ${err.message}`); 3794 }); 3795} catch (e) { 3796 console.error(`An unexpected error occurred.code is ${e.code},message is ${e.code}`); 3797} 3798``` 3799 3800### backup 3801 3802backup(file:string, callback: AsyncCallback<void>):void 3803 3804以指定名称备份数据库，使用callback异步回调。 3805 3806**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 3807 3808**参数：** 3809 3810| 参数名 | 类型 | 必填 | 说明 | 3811| -------- | ------------------------- | ---- | ------------------------------------------------------------ | 3812| file | string | 是 | 备份数据库的指定名称，不能为空且长度不大于[MAX_KEY_LENGTH](#constants)。 | 3813| callback | AsyncCallback<void> | 是 | 回调函数。当以指定名称备份数据库成功，err为undefined，否则为错误对象。 | 3814 3815**错误码：** 3816 3817以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 3818 3819| **错误码ID** | **错误信息** | 3820| ------------ | -------------------------------------- | 3821| 15100005 | Database or result set already closed. | 3822 3823**示例：** 3824 3825```js 3826let kvStore; 3827let file = "BK001"; 3828try { 3829 kvStore.backup(file, (err) => { 3830 if (err) { 3831 console.error(`Failed to backup.code is ${err.code},message is ${err.message} `); 3832 } else { 3833 console.info(`Succeeded in backupping data`); 3834 } 3835 }); 3836} catch (e) { 3837 console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`); 3838} 3839``` 3840 3841### backup 3842 3843backup(file:string): Promise<void> 3844 3845以指定名称备份数据库，使用Promise异步回调。 3846 3847**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 3848 3849**参数：** 3850 3851| 参数名 | 类型 | 必填 | 说明 | 3852| ------ | -------- | ---- | ------------------------------------------------------------ | 3853| file | string | 是 | 备份数据库的指定名称，不能为空且长度不大于[MAX_KEY_LENGTH](#constants)。 | 3854 3855**返回值：** 3856 3857| 类型 | 说明 | 3858| ------------------- | ------------------------- | 3859| Promise<void> | 无返回结果的Promise对象。 | 3860 3861**错误码：** 3862 3863以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 3864 3865| **错误码ID** | **错误信息** | 3866| ------------ | -------------------------------------- | 3867| 15100005 | Database or result set already closed. | 3868 3869**示例：** 3870 3871```js 3872let kvStore; 3873let file = "BK001"; 3874try { 3875 kvStore.backup(file).then(() => { 3876 console.info(`Succeeded in backupping data`); 3877 }).catch((err) => { 3878 console.error(`Failed to backup.code is ${err.code},message is ${err.message}`); 3879 }); 3880} catch (e) { 3881 console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`); 3882} 3883``` 3884 3885### restore 3886 3887restore(file:string, callback: AsyncCallback<void>):void 3888 3889从指定的数据库文件恢复数据库，使用callback异步回调。 3890 3891**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 3892 3893**参数：** 3894 3895| 参数名 | 类型 | 必填 | 说明 | 3896| -------- | ------------------------- | ---- | ------------------------------------------------------------ | 3897| file | string | 是 | 指定的数据库文件名称，不能为空且长度不大于[MAX_KEY_LENGTH](#constants)。 | 3898| callback | AsyncCallback<void> | 是 | 回调函数。当从指定的数据库文件恢复数据库成功，err为undefined，否则为错误对象。 | 3899 3900**错误码：** 3901 3902以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 3903 3904| **错误码ID** | **错误信息** | 3905| ------------ | -------------------------------------- | 3906| 15100005 | Database or result set already closed. | 3907 3908**示例：** 3909 3910```js 3911let kvStore; 3912let file = "BK001"; 3913try { 3914 kvStore.restore(file, (err) => { 3915 if (err) { 3916 console.error(`Failed to restore.code is ${err.code},message is ${err.message}`); 3917 } else { 3918 console.info(`Succeeded in restoring data`); 3919 } 3920 }); 3921} catch (e) { 3922 console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`); 3923} 3924``` 3925 3926### restore 3927 3928restore(file:string): Promise<void> 3929 3930从指定的数据库文件恢复数据库，使用Promise异步回调。 3931 3932**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 3933 3934**参数：** 3935 3936| 参数名 | 类型 | 必填 | 说明 | 3937| ------ | -------- | ---- | ------------------------------------------------------------ | 3938| file | string | 是 | 指定的数据库文件名称，不能为空且长度不大于[MAX_KEY_LENGTH](#constants)。 | 3939 3940**返回值：** 3941 3942| 类型 | 说明 | 3943| ------------------- | ------------------------- | 3944| Promise<void> | 无返回结果的Promise对象。 | 3945 3946**错误码：** 3947 3948以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 3949 3950| **错误码ID** | **错误信息** | 3951| ------------ | -------------------------------------- | 3952| 15100005 | Database or result set already closed. | 3953 3954**示例：** 3955 3956```js 3957let kvStore; 3958let file = "BK001"; 3959try { 3960 kvStore.restore(file).then(() => { 3961 console.info(`Succeeded in restoring data`); 3962 }).catch((err) => { 3963 console.error(`Failed to restore.code is ${err.code},message is ${err.message}`); 3964 }); 3965} catch (e) { 3966 console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`); 3967} 3968``` 3969 3970### deleteBackup 3971 3972deleteBackup(files:Array<string>, callback: AsyncCallback<Array<[string, number]>>):void 3973 3974根据指定名称删除备份文件，使用callback异步回调。 3975 3976**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 3977 3978**参数：** 3979 3980| 参数名 | 类型 | 必填 | 说明 | 3981| -------- | -------------------------------------------------- | ---- | ------------------------------------------------------------ | 3982| files | Array<string> | 是 | 删除备份文件所指定的名称，不能为空且长度不大于[MAX_KEY_LENGTH](#constants)。 | 3983| callback | AsyncCallback<Array<[string, number]>> | 是 | 回调函数，返回删除备份的文件名及其处理结果。 | 3984 3985**示例：** 3986 3987```js 3988let kvStore; 3989let files = ["BK001", "BK002"]; 3990try { 3991 kvStore.deleteBackup(files, (err, data) => { 3992 if (err) { 3993 console.error(`Failed to delete Backup.code is ${err.code},message is ${err.message}`); 3994 } else { 3995 console.info(`Succeed in deleting Backup.data=${data}`); 3996 } 3997 }); 3998} catch (e) { 3999 console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`); 4000} 4001``` 4002 4003### deleteBackup 4004 4005deleteBackup(files:Array<string>): Promise<Array<[string, number]>> 4006 4007根据指定名称删除备份文件，使用Promise异步回调。 4008 4009**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 4010 4011**参数：** 4012 4013| 参数名 | 类型 | 必填 | 说明 | 4014| ------ | ------------------- | ---- | ------------------------------------------------------------ | 4015| files | Array<string> | 是 | 删除备份文件所指定的名称，不能为空且长度不大于[MAX_KEY_LENGTH](#constants)。 | 4016 4017**返回值：** 4018 4019| 类型 | 说明 | 4020| -------------------------------------------- | ----------------------------------------------- | 4021| Promise<Array<[string, number]>> | Promise对象，返回删除备份的文件名及其处理结果。 | 4022 4023**示例：** 4024 4025```js 4026let kvStore; 4027let files = ["BK001", "BK002"]; 4028try { 4029 kvStore.deleteBackup(files).then((data) => { 4030 console.info(`Succeed in deleting Backup.data=${data}`); 4031 }).catch((err) => { 4032 console.error(`Failed to delete Backup.code is ${err.code},message is ${err.message}`); 4033 }) 4034} catch (e) { 4035 console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`); 4036} 4037``` 4038 4039### startTransaction 4040 4041startTransaction(callback: AsyncCallback<void>): void 4042 4043启动SingleKVStore数据库中的事务，使用callback异步回调。 4044 4045**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 4046 4047**参数：** 4048 4049| 参数名 | 类型 | 必填 | 说明 | 4050| -------- | ------------------------- | ---- | ---------- | 4051| callback | AsyncCallback<void> | 是 | 回调函数。 | 4052 4053**错误码：** 4054 4055以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 4056 4057| **错误码ID** | **错误信息** | 4058| ------------ | -------------------------------------- | 4059| 15100005 | Database or result set already closed. | 4060 4061**示例：** 4062 4063```js 4064let kvStore; 4065function putBatchString(len, prefix) { 4066 let entries = []; 4067 for (var i = 0; i < len; i++) { 4068 var entry = { 4069 key: prefix + i, 4070 value: { 4071 type: distributedKVStore.ValueType.STRING, 4072 value: 'batch_test_string_value' 4073 } 4074 } 4075 entries.push(entry); 4076 } 4077 return entries; 4078} 4079 4080try { 4081 var count = 0; 4082 kvStore.on('dataChange', 0, function (data) { 4083 console.info(`startTransaction 0 ${data}`); 4084 count++; 4085 }); 4086 kvStore.startTransaction(async function (err) { 4087 if (err != undefined) { 4088 console.error(`Failed to start Transaction.code is ${err.code},message is ${err.message}`); 4089 return; 4090 } 4091 console.info('Succeeded in starting Transaction'); 4092 let entries = putBatchString(10, 'batch_test_string_key'); 4093 console.info(`entries: ${entries}`); 4094 kvStore.putBatch(entries, async function (err) { 4095 if (err != undefined) { 4096 console.error(`Failed to put batch.code is ${err.code},message is ${err.message}`); 4097 return; 4098 } 4099 console.info('Succeeded in putting Batch'); 4100 }); 4101 }); 4102} catch (e) { 4103 console.error(`Failed to start Transaction.code is ${e.code},message is ${e.message}`); 4104} 4105``` 4106 4107### startTransaction 4108 4109startTransaction(): Promise<void> 4110 4111启动SingleKVStore数据库中的事务，使用Promise异步回调。 4112 4113**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 4114 4115**返回值：** 4116 4117| 类型 | 说明 | 4118| ------------------- | ------------------------- | 4119| Promise<void> | 无返回结果的Promise对象。 | 4120 4121**错误码：** 4122 4123以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 4124 4125| **错误码ID** | **错误信息** | 4126| ------------ | -------------------------------------- | 4127| 15100005 | Database or result set already closed. | 4128 4129**示例：** 4130 4131```js 4132let kvStore; 4133try { 4134 var count = 0; 4135 kvStore.on('dataChange', distributedKVStore.SubscribeType.SUBSCRIBE_TYPE_ALL, function (data) { 4136 console.info(`startTransaction 0 ${data}`); 4137 count++; 4138 }); 4139 kvStore.startTransaction().then(async () => { 4140 console.info('Succeeded in starting Transaction'); 4141 }).catch((err) => { 4142 console.error(`Failed to start Transaction.code is ${err.code},message is ${err.message}`); 4143 }); 4144} catch (e) { 4145 console.error(`Failed to start Transaction.code is ${e.code},message is ${e.message}`); 4146} 4147``` 4148 4149### commit 4150 4151commit(callback: AsyncCallback<void>): void 4152 4153提交SingleKVStore数据库中的事务，使用callback异步回调。 4154 4155**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 4156 4157**参数：** 4158 4159| 参数名 | 类型 | 必填 | 说明 | 4160| -------- | ------------------------- | ---- | ---------- | 4161| callback | AsyncCallback<void> | 是 | 回调函数。 | 4162 4163**错误码：** 4164 4165以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 4166 4167| **错误码ID** | **错误信息** | 4168| ------------ | -------------------------------------- | 4169| 15100005 | Database or result set already closed. | 4170 4171**示例：** 4172 4173```js 4174let kvStore; 4175try { 4176 kvStore.commit(function (err) { 4177 if (err == undefined) { 4178 console.info('Succeeded in committing'); 4179 } else { 4180 console.error(`Failed to commit.code is ${err.code},message is ${err.message}`); 4181 } 4182 }); 4183} catch (e) { 4184 console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`); 4185} 4186``` 4187 4188### commit 4189 4190commit(): Promise<void> 4191 4192提交SingleKVStore数据库中的事务，使用Promise异步回调。 4193 4194**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 4195 4196**返回值：** 4197 4198| 类型 | 说明 | 4199| ------------------- | ------------------------- | 4200| Promise<void> | 无返回结果的Promise对象。 | 4201 4202**错误码：** 4203 4204以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 4205 4206| **错误码ID** | **错误信息** | 4207| ------------ | -------------------------------------- | 4208| 15100005 | Database or result set already closed. | 4209 4210**示例：** 4211 4212```js 4213let kvStore; 4214try { 4215 kvStore.commit().then(async () => { 4216 console.info('Succeeded in committing'); 4217 }).catch((err) => { 4218 console.error(`Failed to commit.code is ${err.code},message is ${err.message}`); 4219 }); 4220} catch (e) { 4221 console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`); 4222} 4223``` 4224 4225### rollback 4226 4227rollback(callback: AsyncCallback<void>): void 4228 4229在SingleKVStore数据库中回滚事务，使用callback异步回调。 4230 4231**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 4232 4233**参数：** 4234 4235| 参数名 | 类型 | 必填 | 说明 | 4236| -------- | ------------------------- | ---- | ---------- | 4237| callback | AsyncCallback<void> | 是 | 回调函数。 | 4238 4239**错误码：** 4240 4241以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 4242 4243| **错误码ID** | **错误信息** | 4244| ------------ | -------------------------------------- | 4245| 15100005 | Database or result set already closed. | 4246 4247**示例：** 4248 4249```js 4250let kvStore; 4251try { 4252 kvStore.rollback(function (err) { 4253 if (err == undefined) { 4254 console.info('Succeeded in rolling back'); 4255 } else { 4256 console.error(`Failed to rollback.code is ${err.code},message is ${err.message}`); 4257 } 4258 }); 4259}catch(e) { 4260 console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`); 4261} 4262``` 4263 4264### rollback 4265 4266rollback(): Promise<void> 4267 4268在SingleKVStore数据库中回滚事务，使用Promise异步回调。 4269 4270**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 4271 4272**返回值：** 4273 4274| 类型 | 说明 | 4275| ------------------- | ------------------------- | 4276| Promise<void> | 无返回结果的Promise对象。 | 4277 4278**错误码：** 4279 4280以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 4281 4282| **错误码ID** | **错误信息** | 4283| ------------ | -------------------------------------- | 4284| 15100005 | Database or result set already closed. | 4285 4286**示例：** 4287 4288```js 4289let kvStore; 4290try { 4291 kvStore.rollback().then(async () => { 4292 console.info('Succeeded in rolling back'); 4293 }).catch((err) => { 4294 console.error(`Failed to rollback.code is ${err.code},message is ${err.message}`); 4295 }); 4296} catch (e) { 4297 console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`); 4298} 4299``` 4300 4301### enableSync 4302 4303enableSync(enabled: boolean, callback: AsyncCallback<void>): void 4304 4305设定是否开启同步，使用callback异步回调。 4306 4307**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 4308 4309**参数：** 4310 4311| 参数名 | 类型 | 必填 | 说明 | 4312| -------- | ------------------------- | ---- | --------------------------------------------------------- | 4313| enabled | boolean | 是 | 设定是否开启同步，true表示开启同步，false表示不启用同步。 | 4314| callback | AsyncCallback<void> | 是 | 回调函数。 | 4315 4316**示例：** 4317 4318```js 4319let kvStore; 4320try { 4321 kvStore.enableSync(true, function (err) { 4322 if (err == undefined) { 4323 console.info('Succeeded in enabling sync'); 4324 } else { 4325 console.error(`Failed to enable sync.code is ${err.code},message is ${err.message}`); 4326 } 4327 }); 4328} catch (e) { 4329 console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`); 4330} 4331``` 4332 4333### enableSync 4334 4335enableSync(enabled: boolean): Promise<void> 4336 4337设定是否开启同步，使用Promise异步回调。 4338 4339**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 4340 4341**参数：** 4342 4343| 参数名 | 类型 | 必填 | 说明 | 4344| ------- | -------- | ---- | --------------------------------------------------------- | 4345| enabled | boolean | 是 | 设定是否开启同步，true表示开启同步，false表示不启用同步。 | 4346 4347**返回值：** 4348 4349| 类型 | 说明 | 4350| ------------------- | ------------------------- | 4351| Promise<void> | 无返回结果的Promise对象。 | 4352 4353**示例：** 4354 4355```js 4356let kvStore; 4357try { 4358 kvStore.enableSync(true).then(() => { 4359 console.info('Succeeded in enabling sync'); 4360 }).catch((err) => { 4361 console.error(`Failed to enable sync.code is ${err.code},message is ${err.message}`); 4362 }); 4363} catch (e) { 4364 console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`); 4365} 4366``` 4367 4368### setSyncRange 4369 4370setSyncRange(localLabels: string[], remoteSupportLabels: string[], callback: AsyncCallback<void>): void 4371 4372设置同步范围标签，使用callback异步回调。 4373 4374**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 4375 4376**参数：** 4377 4378| 参数名 | 类型 | 必填 | 说明 | 4379| ------------------- | ------------------------- | ---- | -------------------------------- | 4380| localLabels | string[] | 是 | 表示本地设备的同步标签。 | 4381| remoteSupportLabels | string[] | 是 | 表示要同步数据的设备的同步标签。 | 4382| callback | AsyncCallback<void> | 是 | 回调函数。 | 4383 4384**示例：** 4385 4386```js 4387let kvStore; 4388try { 4389 const localLabels = ['A', 'B']; 4390 const remoteSupportLabels = ['C', 'D']; 4391 kvStore.setSyncRange(localLabels, remoteSupportLabels, function (err) { 4392 if (err != undefined) { 4393 console.error(`Failed to set syncRange.code is ${err.code},message is ${err.message}`); 4394 return; 4395 } 4396 console.info('Succeeded in setting syncRange'); 4397 }); 4398} catch (e) { 4399 console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`); 4400} 4401``` 4402 4403### setSyncRange 4404 4405setSyncRange(localLabels: string[], remoteSupportLabels: string[]): Promise<void> 4406 4407设置同步范围标签，使用Promise异步回调。 4408 4409**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 4410 4411**参数：** 4412 4413| 参数名 | 类型 | 必填 | 说明 | 4414| ------------------- | -------- | ---- | -------------------------------- | 4415| localLabels | string[] | 是 | 表示本地设备的同步标签。 | 4416| remoteSupportLabels | string[] | 是 | 表示要同步数据的设备的同步标签。 | 4417 4418**返回值：** 4419 4420| 类型 | 说明 | 4421| ------------------- | ------------------------- | 4422| Promise<void> | 无返回结果的Promise对象。 | 4423 4424**示例：** 4425 4426```js 4427let kvStore; 4428try { 4429 const localLabels = ['A', 'B']; 4430 const remoteSupportLabels = ['C', 'D']; 4431 kvStore.setSyncRange(localLabels, remoteSupportLabels).then(() => { 4432 console.info('Succeeded in setting syncRange'); 4433 }).catch((err) => { 4434 console.error(`Failed to set syncRange.code is ${err.code},message is ${err.message}`); 4435 }); 4436} catch (e) { 4437 console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`); 4438} 4439``` 4440 4441### setSyncParam 4442 4443setSyncParam(defaultAllowedDelayMs: number, callback: AsyncCallback<void>): void 4444 4445设置数据库同步允许的默认延迟，使用callback异步回调。 4446 4447**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 4448 4449**参数：** 4450 4451| 参数名 | 类型 | 必填 | 说明 | 4452| --------------------- | ------------------------- | ---- | -------------------------------------------- | 4453| defaultAllowedDelayMs | number | 是 | 表示数据库同步允许的默认延迟，以毫秒为单位。 | 4454| callback | AsyncCallback<void> | 是 | 回调函数。 | 4455 4456**示例：** 4457 4458```js 4459let kvStore; 4460try { 4461 const defaultAllowedDelayMs = 500; 4462 kvStore.setSyncParam(defaultAllowedDelayMs, function (err) { 4463 if (err != undefined) { 4464 console.error(`Failed to set syncParam.code is ${err.code},message is ${err.message}`); 4465 return; 4466 } 4467 console.info('Succeeded in setting syncParam'); 4468 }); 4469} catch (e) { 4470 console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`); 4471} 4472``` 4473 4474### setSyncParam 4475 4476setSyncParam(defaultAllowedDelayMs: number): Promise<void> 4477 4478设置数据库同步允许的默认延迟，使用Promise异步回调。 4479 4480**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 4481 4482**参数：** 4483 4484| 参数名 | 类型 | 必填 | 说明 | 4485| --------------------- | -------- | ---- | -------------------------------------------- | 4486| defaultAllowedDelayMs | number | 是 | 表示数据库同步允许的默认延迟，以毫秒为单位。 | 4487 4488**返回值：** 4489 4490| 类型 | 说明 | 4491| ------------------- | ------------------------- | 4492| Promise<void> | 无返回结果的Promise对象。 | 4493 4494**示例：** 4495 4496```js 4497let kvStore; 4498try { 4499 const defaultAllowedDelayMs = 500; 4500 kvStore.setSyncParam(defaultAllowedDelayMs).then(() => { 4501 console.info('Succeeded in setting syncParam'); 4502 }).catch((err) => { 4503 console.error(`Failed to set syncParam.code is ${err.code},message is ${err.message}`); 4504 }); 4505} catch (e) { 4506 console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`); 4507} 4508``` 4509 4510### sync 4511 4512sync(deviceIds: string[], mode: SyncMode, delayMs?: number): void 4513 4514在手动同步方式下，触发数据库同步。关于键值型数据库的同步方式说明，请见[键值型数据库跨设备数据同步](../../database/data-sync-of-kv-store.md)。 4515> **说明：** 4516> 4517> 其中deviceIds通过调用[deviceManager.getTrustedDeviceListSync](js-apis-device-manager.md#gettrusteddevicelistsync)方法得到。deviceManager模块的接口均为系统接口，仅系统应用可用。 4518 4519**需要权限**： ohos.permission.DISTRIBUTED_DATASYNC。 4520 4521**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 4522 4523**参数：** 4524 4525| 参数名 | 类型 | 必填 | 说明 | 4526| --------- | --------------------- | ---- | ---------------------------------------------- | 4527| deviceIds | string[] | 是 | 同一组网环境下，需要同步的设备的deviceId列表。 | 4528| mode | [SyncMode](#syncmode) | 是 | 同步模式。 | 4529| delayMs | number | 否 | 可选参数，允许延时时间，单位：ms（毫秒），默认为0。 | 4530 4531**错误码：** 4532 4533以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 4534 4535| **错误码ID** | **错误信息** | 4536| ------------ | ------------------- | 4537| 15100003 | Database corrupted. | 4538| 15100004 | Not found. | 4539 4540**示例：** 4541 4542```js 4543import deviceManager from '@ohos.distributedHardware.deviceManager'; 4544 4545let devManager; 4546let kvStore; 4547const KEY_TEST_SYNC_ELEMENT = 'key_test_sync'; 4548const VALUE_TEST_SYNC_ELEMENT = 'value-string-001'; 4549// create deviceManager 4550deviceManager.createDeviceManager('bundleName', (err, value) => { 4551 if (!err) { 4552 devManager = value; 4553 let deviceIds = []; 4554 if (devManager != null) { 4555 var devices = devManager.getTrustedDeviceListSync(); 4556 for (var i = 0; i < devices.length; i++) { 4557 deviceIds[i] = devices[i].deviceId; 4558 } 4559 } 4560 try { 4561 kvStore.on('syncComplete', function (data) { 4562 console.info('Sync dataChange'); 4563 }); 4564 kvStore.put(KEY_TEST_SYNC_ELEMENT + 'testSync101', VALUE_TEST_SYNC_ELEMENT, function (err) { 4565 if (err != undefined) { 4566 console.error(`Failed to sync.code is ${err.code},message is ${err.message}`); 4567 return; 4568 } 4569 console.info('Succeeded in putting data'); 4570 const mode = distributedKVStore.SyncMode.PULL_ONLY; 4571 kvStore.sync(deviceIds, mode, 1000); 4572 }); 4573 } catch (e) { 4574 console.error(`Failed to sync.code is ${e.code},message is ${e.message}`); 4575 } 4576 } 4577}); 4578``` 4579 4580### sync 4581 4582sync(deviceIds: string[], query: Query, mode: SyncMode, delayMs?: number): void 4583 4584在手动同步方式下，触发数据库同步，此方法为同步方法。关于键值型数据库的同步方式说明，请见[键值型数据库跨设备数据同步](../../database/data-sync-of-kv-store.md)。 4585> **说明：** 4586> 4587> 其中deviceIds通过调用[deviceManager.getTrustedDeviceListSync](js-apis-device-manager.md#gettrusteddevicelistsync)方法得到。deviceManager模块的接口均为系统接口，仅系统应用可用。 4588 4589**需要权限**： ohos.permission.DISTRIBUTED_DATASYNC。 4590 4591**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 4592 4593**参数：** 4594 4595| 参数名 | 类型 | 必填 | 说明 | 4596| --------- | --------------------- | ---- | ---------------------------------------------- | 4597| deviceIds | string[] | 是 | 同一组网环境下，需要同步的设备的deviceId列表。 | 4598| mode | [SyncMode](#syncmode) | 是 | 同步模式。 | 4599| query | [Query](#query) | 是 | 表示数据库的查询谓词条件 | 4600| delayMs | number | 否 | 可选参数，允许延时时间，单位：ms（毫秒），默认为0。 | 4601 4602**错误码：** 4603 4604以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 4605 4606| **错误码ID** | **错误信息** | 4607| ------------ | ------------------- | 4608| 15100003 | Database corrupted. | 4609| 15100004 | Not found. | 4610 4611**示例：** 4612 4613```js 4614import deviceManager from '@ohos.distributedHardware.deviceManager'; 4615 4616let devManager; 4617let kvStore; 4618const KEY_TEST_SYNC_ELEMENT = 'key_test_sync'; 4619const VALUE_TEST_SYNC_ELEMENT = 'value-string-001'; 4620// create deviceManager 4621deviceManager.createDeviceManager('bundleName', (err, value) => { 4622 if (!err) { 4623 devManager = value; 4624 let deviceIds = []; 4625 if (devManager != null) { 4626 var devices = devManager.getTrustedDeviceListSync(); 4627 for (var i = 0; i < devices.length; i++) { 4628 deviceIds[i] = devices[i].deviceId; 4629 } 4630 } 4631 try { 4632 kvStore.on('syncComplete', function (data) { 4633 console.info('Sync dataChange'); 4634 }); 4635 kvStore.put(KEY_TEST_SYNC_ELEMENT + 'testSync101', VALUE_TEST_SYNC_ELEMENT, function (err) { 4636 if (err != undefined) { 4637 console.error(`Failed to sync.code is ${err.code},message is ${err.message}`); 4638 return; 4639 } 4640 console.info('Succeeded in putting data'); 4641 const mode = distributedKVStore.SyncMode.PULL_ONLY; 4642 const query = new distributedKVStore.Query(); 4643 query.prefixKey("batch_test"); 4644 query.deviceId('localDeviceId'); 4645 kvStore.sync(deviceIds, query, mode, 1000); 4646 }); 4647 } catch (e) { 4648 console.error(`Failed to sync.code is ${e.code},message is ${e.message}`); 4649 } 4650 } 4651}); 4652``` 4653 4654### on('dataChange') 4655 4656on(event: 'dataChange', type: SubscribeType, listener: Callback<ChangeNotification>): void 4657 4658订阅指定类型的数据变更通知。 4659 4660**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 4661 4662**参数：** 4663 4664| 参数名 | 类型 | 必填 | 说明 | 4665| -------- | --------------------------------------------------------- | ---- | ---------------------------------------------------- | 4666| event | string | 是 | 订阅的事件名，固定为'dataChange'，表示数据变更事件。 | 4667| type | [SubscribeType](#subscribetype) | 是 | 表示订阅的类型。 | 4668| listener | Callback<[ChangeNotification](#changenotification)> | 是 | 回调函数。 | 4669 4670**错误码：** 4671 4672以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 4673 4674| **错误码ID** | **错误信息** | 4675| ------------ | -------------------------------------- | 4676| 15100001 | Over max subscribe limits. | 4677| 15100005 | Database or result set already closed. | 4678 4679**示例：** 4680 4681```js 4682let kvStore; 4683try { 4684 kvStore.on('dataChange', distributedKVStore.SubscribeType.SUBSCRIBE_TYPE_LOCAL, function (data) { 4685 console.info(`dataChange callback call data: ${data}`); 4686 }); 4687} catch (e) { 4688 console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`); 4689} 4690``` 4691 4692### on('syncComplete') 4693 4694on(event: 'syncComplete', syncCallback: Callback<Array<[string, number]>>): void 4695 4696订阅同步完成事件回调通知。 4697 4698**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 4699 4700**参数：** 4701 4702| 参数名 | 类型 | 必填 | 说明 | 4703| ------------ | --------------------------------------------- | ---- | ------------------------------------------------------ | 4704| event | string | 是 | 订阅的事件名，固定为'syncComplete'，表示同步完成事件。 | 4705| syncCallback | Callback<Array<[string, number]>> | 是 | 回调函数。用于向调用方发送同步结果的回调。 | 4706 4707**示例：** 4708 4709```js 4710let kvStore; 4711const KEY_TEST_FLOAT_ELEMENT = 'key_test_float'; 4712const VALUE_TEST_FLOAT_ELEMENT = 321.12; 4713try { 4714 kvStore.on('syncComplete', function (data) { 4715 console.info(`syncComplete ${data}`); 4716 }); 4717 kvStore.put(KEY_TEST_FLOAT_ELEMENT, VALUE_TEST_FLOAT_ELEMENT).then(() => { 4718 console.info('succeeded in putting'); 4719 }).catch((err) => { 4720 console.error(`Failed to put.code is ${err.code},message is ${err.message}`); 4721 }); 4722} catch (e) { 4723 console.error(`Failed to subscribe syncComplete.code is ${e.code},message is ${e.message}`); 4724} 4725``` 4726 4727### off('dataChange') 4728 4729off(event:'dataChange', listener?: Callback<ChangeNotification>): void 4730 4731取消订阅数据变更通知。 4732 4733**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 4734 4735**参数：** 4736 4737| 参数名 | 类型 | 必填 | 说明 | 4738| -------- | --------------------------------------------------------- | ---- | -------------------------------------------------------- | 4739| event | string | 是 | 取消订阅的事件名，固定为'dataChange'，表示数据变更事件。 | 4740| listener | Callback<[ChangeNotification](#changenotification)> | 否 | 取消订阅的函数。如不设置callback，则取消所有已订阅的函数。 | 4741 4742**错误码：** 4743 4744以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 4745 4746| **错误码ID** | **错误信息** | 4747| ------------ | -------------------------------------- | 4748| 15100005 | Database or result set already closed. | 4749 4750**示例：** 4751 4752```js 4753let kvStore; 4754class KvstoreModel { 4755 call(data) { 4756 console.info(`dataChange : ${data}`); 4757 } 4758 4759 subscribeDataChange() { 4760 try { 4761 if (kvStore != null) { 4762 kvStore.on('dataChange', distributedKVStore.SubscribeType.SUBSCRIBE_TYPE_REMOTE, this.call); 4763 } 4764 } catch (err) { 4765 console.error(`Failed to subscribeDataChange.code is ${err.code},message is ${err.message}`); 4766 } 4767 } 4768 4769 unsubscribeDataChange() { 4770 try { 4771 if (kvStore != null) { 4772 kvStore.off('dataChange', this.call); 4773 } 4774 } catch (err) { 4775 console.error(`Failed to unsubscribeDataChange.code is ${err.code},message is ${err.message}`); 4776 } 4777 } 4778} 4779``` 4780 4781### off('syncComplete') 4782 4783off(event: 'syncComplete', syncCallback?: Callback<Array<[string, number]>>): void 4784 4785取消订阅同步完成事件回调通知。 4786 4787**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 4788 4789**参数：** 4790 4791| 参数名 | 类型 | 必填 | 说明 | 4792| ------------ | --------------------------------------------- | ---- | ---------------------------------------------------------- | 4793| event | string | 是 | 取消订阅的事件名，固定为'syncComplete'，表示同步完成事件。 | 4794| syncCallback | Callback<Array<[string, number]>> | 否 | 取消订阅的函数。如不设置callback，则取消所有已订阅的函数。 | 4795 4796**示例：** 4797 4798```js 4799let kvStore; 4800class KvstoreModel { 4801 call(data) { 4802 console.info(`syncComplete : ${data}`); 4803 } 4804 4805 subscribeDataChange() { 4806 try { 4807 if (kvStore != null) { 4808 kvStore.on('syncComplete', distributedKVStore.SubscribeType.SUBSCRIBE_TYPE_REMOTE, this.call); 4809 } 4810 } catch (err) { 4811 console.error(`Failed to subscribeDataChange.code is ${err.code},message is ${err.message}`); 4812 } 4813 } 4814 4815 unsubscribeDataChange() { 4816 try { 4817 if (kvStore != null) { 4818 kvStore.off('dsyncComplete', this.call); 4819 } 4820 } catch (err) { 4821 console.error(`Failed to unsubscribeDataChange.code is ${err.code},message is ${err.message}`); 4822 } 4823 } 4824} 4825``` 4826 4827### getSecurityLevel 4828 4829getSecurityLevel(callback: AsyncCallback<SecurityLevel>): void 4830 4831获取数据库的安全级别，使用callback异步回调。 4832 4833**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 4834 4835**参数：** 4836 4837| 参数名 | 类型 | 必填 | 说明 | 4838| -------- | ---------------------------------------------------- | ---- | -------------------------------- | 4839| callback | AsyncCallback<[SecurityLevel](#securitylevel)> | 是 | 回调函数。返回数据库的安全级别。 | 4840 4841**错误码：** 4842 4843以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 4844 4845| **错误码ID** | **错误信息** | 4846| ------------ | -------------------------------------- | 4847| 15100005 | Database or result set already closed. | 4848 4849**示例：** 4850 4851```js 4852let kvStore; 4853try { 4854 kvStore.getSecurityLevel(function (err, data) { 4855 if (err != undefined) { 4856 console.error(`Failed to get SecurityLevel.code is ${err.code},message is ${err.message}`); 4857 return; 4858 } 4859 console.info('Succeeded in getting securityLevel'); 4860 }); 4861} catch (e) { 4862 console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`); 4863} 4864``` 4865 4866### getSecurityLevel 4867 4868getSecurityLevel(): Promise<SecurityLevel> 4869 4870获取数据库的安全级别，使用Promise异步回调。 4871 4872**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 4873 4874**返回值：** 4875 4876| 类型 | 说明 | 4877| ---------------------------------------------- | ----------------------------------- | 4878| Promise<[SecurityLevel](#securitylevel)> | Promise对象。返回数据库的安全级别。 | 4879 4880**错误码：** 4881 4882以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 4883 4884| **错误码ID** | **错误信息** | 4885| ------------ | -------------------------------------- | 4886| 15100005 | Database or result set already closed. | 4887 4888**示例：** 4889 4890```js 4891let kvStore; 4892try { 4893 kvStore.getSecurityLevel().then((data) => { 4894 console.info('Succeeded in getting securityLevel'); 4895 }).catch((err) => { 4896 console.error(`Failed to get SecurityLevel.code is ${err.code},message is ${err.message}`); 4897 }); 4898} catch (e) { 4899 console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`); 4900} 4901``` 4902 4903## DeviceKVStore 4904 4905设备协同数据库，继承自SingleKVStore，提供查询数据和同步数据的方法。 4906 4907设备协同数据库，以设备维度对数据进行区分，每台设备仅能写入和修改本设备的数据，其它设备的数据对其是只读的，无法修改其它设备的数据。 4908 4909比如，可以使用设备协同数据库实现设备间的图片分享，可以查看其他设备的图片，但无法修改和删除其他设备的图片。 4910 4911在调用DeviceKVStore的方法前，需要先通过[getKVStore](#getkvstore)构建一个DeviceKVStore实例。 4912 4913### get 4914 4915get(key: string, callback: AsyncCallback<boolean | string | number | Uint8Array>): void 4916 4917获取本设备指定键的值，使用callback异步回调。 4918 4919**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 4920 4921**参数：** 4922 4923| 参数名 | 类型 | 必填 | 说明 | 4924| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 4925| key | string | 是 | 要查询数据的key，不能为空且长度不大于[MAX_KEY_LENGTH](#constants)。 | 4926| callback | AsyncCallback<boolean \| string \| number \| Uint8Array> | 是 | 回调函数。返回获取查询的值。 | 4927 4928**错误码：** 4929 4930以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 4931 4932| **错误码ID** | **错误信息** | 4933| ------------ | -------------------------------------- | 4934| 15100003 | Database corrupted. | 4935| 15100004 | Not found. | 4936| 15100005 | Database or result set already closed. | 4937 4938**示例：** 4939 4940```js 4941let kvStore; 4942const KEY_TEST_STRING_ELEMENT = 'key_test_string'; 4943const VALUE_TEST_STRING_ELEMENT = 'value-test-string'; 4944try { 4945 kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT, function (err) { 4946 if (err != undefined) { 4947 console.error(`Failed to put.code is ${err.code},message is ${err.message}`); 4948 return; 4949 } 4950 console.info("Succeeded in putting"); 4951 kvStore.get(KEY_TEST_STRING_ELEMENT, function (err, data) { 4952 if (err != undefined) { 4953 console.error(`Failed to get.code is ${err.code},message is ${err.message}`); 4954 return; 4955 } 4956 console.info(`Succeeded in getting data.data=${data}`); 4957 }); 4958 }); 4959} catch (e) { 4960 console.error(`Failed to get.code is ${e.code},message is ${e.message}`); 4961} 4962``` 4963 4964### get 4965 4966get(key: string): Promise<boolean | string | number | Uint8Array> 4967 4968获取本设备指定键的值，使用Promise异步回调。 4969 4970**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 4971 4972**参数：** 4973 4974| 参数名 | 类型 | 必填 | 说明 | 4975| ------ | ------ | ---- | ------------------------------------------------------------ | 4976| key | string | 是 | 要查询数据的key，不能为空且长度不大于[MAX_KEY_LENGTH](#constants)。 | 4977 4978**返回值：** 4979 4980| 类型 | 说明 | 4981| -------------------------------------------------------- | ------------------------------- | 4982| Promise<Uint8Array \| string \| boolean \| number> | Promise对象。返回获取查询的值。 | 4983 4984**错误码：** 4985 4986以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 4987 4988| **错误码ID** | **错误信息** | 4989| ------------ | -------------------------------------- | 4990| 15100003 | Database corrupted. | 4991| 15100004 | Not found. | 4992| 15100005 | Database or result set already closed. | 4993 4994**示例：** 4995 4996```js 4997let kvStore; 4998const KEY_TEST_STRING_ELEMENT = 'key_test_string'; 4999const VALUE_TEST_STRING_ELEMENT = 'value-test-string'; 5000try { 5001 kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT).then(() => { 5002 console.info(`Succeeded in putting data`); 5003 kvStore.get(KEY_TEST_STRING_ELEMENT).then((data) => { 5004 console.info(`Succeeded in getting data.data=${data}`); 5005 }).catch((err) => { 5006 console.error(`Failed to get.code is ${err.code},message is ${err.message}`); 5007 }); 5008 }).catch((err) => { 5009 console.error(`Failed to put.code is ${err.code},message is ${err.message}`); 5010 }); 5011} catch (e) { 5012 console.error(`Failed to get.code is ${e.code},message is ${e.message}`); 5013} 5014``` 5015 5016### get 5017 5018get(deviceId: string, key: string, callback: AsyncCallback<boolean | string | number | Uint8Array>): void 5019 5020获取与指定设备ID和key匹配的string值，使用callback异步回调。 5021 5022**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 5023 5024**参数：** 5025 5026| 参数名 | 类型 | 必填 | 说明 | 5027| ----- | ------ | ---- | ----------------------- | 5028| deviceId |string | 是 |标识要查询其数据的设备。 | 5029| key |string | 是 |表示要查询key值的键。 | 5030| callback |AsyncCallback<boolean\|string\|number\|Uint8Array> | 是 |回调函数，返回匹配给定条件的字符串值。 | 5031 5032**错误码：** 5033 5034以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 5035 5036| **错误码ID** | **错误信息** | 5037| ------------ | -------------------------------------- | 5038| 15100003 | Database corrupted. | 5039| 15100004 | Not found. | 5040| 15100005 | Database or result set already closed. | 5041 5042**示例：** 5043 5044```js 5045let kvStore; 5046const KEY_TEST_STRING_ELEMENT = 'key_test_string_2'; 5047const VALUE_TEST_STRING_ELEMENT = 'value-string-002'; 5048try { 5049 kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT, async function (err) { 5050 if (err != undefined) { 5051 console.error(`Failed to put.code is ${err.code},message is ${err.message}`); 5052 return; 5053 } 5054 console.info('Succeeded in putting'); 5055 kvStore.get('localDeviceId', KEY_TEST_STRING_ELEMENT, function (err, data) { 5056 if (err != undefined) { 5057 console.error(`Failed to get.code is ${err.code},message is ${err.message}`); 5058 return; 5059 } 5060 console.info('Succeeded in getting'); 5061 }); 5062 }) 5063} catch (e) { 5064 console.error(`Failed to get.code is ${e.code},message is ${e.message}`); 5065} 5066``` 5067 5068### get 5069 5070get(deviceId: string, key: string): Promise<boolean | string | number | Uint8Array> 5071 5072获取与指定设备ID和key匹配的string值，使用Promise异步回调。 5073 5074**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 5075 5076**参数：** 5077 5078| 参数名 | 类型 | 必填 | 说明 | 5079| -------- | -------- | ---- | ------------------------ | 5080| deviceId | string | 是 | 标识要查询其数据的设备。 | 5081| key | string | 是 | 表示要查询key值的键。 | 5082 5083**返回值：** 5084 5085| 类型 | 说明 | 5086| ------ | ------- | 5087|Promise<boolean\|string\|number\|Uint8Array> |Promise对象。返回匹配给定条件的字符串值。| 5088 5089**错误码：** 5090 5091以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 5092 5093| **错误码ID** | **错误信息** | 5094| ------------ | -------------------------------------- | 5095| 15100003 | Database corrupted. | 5096| 15100004 | Not found. | 5097| 15100005 | Database or result set already closed. | 5098 5099**示例：** 5100 5101```js 5102let kvStore; 5103const KEY_TEST_STRING_ELEMENT = 'key_test_string_2'; 5104const VALUE_TEST_STRING_ELEMENT = 'value-string-002'; 5105try { 5106 kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT).then(async () => { 5107 console.info('Succeeded in putting'); 5108 kvStore.get('localDeviceId', KEY_TEST_STRING_ELEMENT).then((data) => { 5109 console.info('Succeeded in getting'); 5110 }).catch((err) => { 5111 console.error(`Failed to get.code is ${err.code},message is ${err.message}`); 5112 }); 5113 }).catch((error) => { 5114 console.error(`Failed to put.code is ${error.code},message is ${error.message}`); 5115 }); 5116} catch (e) { 5117 console.error(`Failed to get.code is ${e.code},message is ${e.message}`); 5118} 5119``` 5120 5121### getEntries 5122 5123getEntries(keyPrefix: string, callback: AsyncCallback<Entry[]>): void 5124 5125获取匹配本设备指定键前缀的所有键值对，使用callback异步回调。 5126 5127**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 5128 5129**参数：** 5130 5131| 参数名 | 类型 | 必填 | 说明 | 5132| --------- | -------------------------------------- | ---- | ---------------------------------------- | 5133| keyPrefix | string | 是 | 表示要匹配的键前缀。 | 5134| callback | AsyncCallback<[Entry](#entry)[]> | 是 | 回调函数。返回匹配指定前缀的键值对列表。 | 5135 5136**错误码：** 5137 5138以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 5139 5140| **错误码ID** | **错误信息** | 5141| ------------ | -------------------------------------- | 5142| 15100003 | Database corrupted. | 5143| 15100005 | Database or result set already closed. | 5144 5145**示例：** 5146 5147```js 5148let kvStore; 5149try { 5150 let entries = []; 5151 for (var i = 0; i < 10; i++) { 5152 var key = 'batch_test_string_key'; 5153 var entry = { 5154 key: key + i, 5155 value: { 5156 type: distributedKVStore.ValueType.STRING, 5157 value: 'batch_test_string_value' 5158 } 5159 } 5160 entries.push(entry); 5161 } 5162 console.info(`entries: ${entries}`); 5163 kvStore.putBatch(entries, async function (err) { 5164 if (err != undefined) { 5165 console.error(`Failed to put Batch.code is ${err.code},message is ${err.message}`); 5166 return; 5167 } 5168 console.info('Succeeded in putting Batch'); 5169 kvStore.getEntries('batch_test_string_key', function (err, entries) { 5170 if (err != undefined) { 5171 console.error(`Failed to get Entries.code is ${err.code},message is ${err.message}`); 5172 return; 5173 } 5174 console.info('Succeeded in getting Entries'); 5175 console.info(`entries.length: ${entries.length}`); 5176 console.info(`entries[0]: ${entries[0]}`); 5177 }); 5178 }); 5179} catch (e) { 5180 console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message} `); 5181} 5182``` 5183 5184### getEntries 5185 5186getEntries(keyPrefix: string): Promise<Entry[]> 5187 5188获取匹配本设备指定键前缀的所有键值对，使用Promise异步回调。 5189 5190**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 5191 5192**参数：** 5193 5194| 参数名 | 类型 | 必填 | 说明 | 5195| --------- | ------ | ---- | -------------------- | 5196| keyPrefix | string | 是 | 表示要匹配的键前缀。 | 5197 5198**返回值：** 5199 5200| 类型 | 说明 | 5201| -------------------------------- | ------------------------------------------- | 5202| Promise<[Entry](#entry)[]> | Promise对象。返回匹配指定前缀的键值对列表。 | 5203 5204**错误码：** 5205 5206以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 5207 5208| **错误码ID** | **错误信息** | 5209| ------------ | -------------------------------------- | 5210| 15100003 | Database corrupted. | 5211| 15100005 | Database or result set already closed. | 5212 5213**示例：** 5214 5215```js 5216let kvStore; 5217try { 5218 let entries = []; 5219 for (var i = 0; i < 10; i++) { 5220 var key = 'batch_test_string_key'; 5221 var entry = { 5222 key: key + i, 5223 value: { 5224 type: distributedKVStore.ValueType.STRING, 5225 value: 'batch_test_string_value' 5226 } 5227 } 5228 entries.push(entry); 5229 } 5230 console.info(`entries: ${entries}`); 5231 kvStore.putBatch(entries).then(async () => { 5232 console.info('Succeeded in putting Batch'); 5233 kvStore.getEntries('batch_test_string_key').then((entries) => { 5234 console.info('Succeeded in getting Entries'); 5235 console.info(`PutBatch ${entries}`); 5236 }).catch((err) => { 5237 console.error(`Failed to get Entries.code is ${err.code},message is ${err.message}`); 5238 }); 5239 }).catch((err) => { 5240 console.error(`Failed to put Batch.code is ${err.code},message is ${err.message}`); 5241 }); 5242} catch (e) { 5243 console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message} `); 5244} 5245``` 5246 5247### getEntries 5248 5249getEntries(deviceId: string, keyPrefix: string, callback: AsyncCallback<Entry[]>): void 5250 5251获取与指定设备ID和key前缀匹配的所有键值对，使用callback异步回调。 5252 5253**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 5254 5255**参数：** 5256 5257| 参数名 | 类型 | 必填 | 说明 | 5258| --------- | -------------------------------------- | ---- | ---------------------------------------------- | 5259| deviceId | string | 是 | 标识要查询其数据的设备。 | 5260| keyPrefix | string | 是 | 表示要匹配的键前缀。 | 5261| callback | AsyncCallback<[Entry](#entry)[]> | 是 | 回调函数，返回满足给定条件的所有键值对的列表。 | 5262 5263**错误码：** 5264 5265以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 5266 5267| **错误码ID** | **错误信息** | 5268| ------------ | -------------------------------------- | 5269| 15100003 | Database corrupted. | 5270| 15100005 | Database or result set already closed. | 5271 5272**示例：** 5273 5274```js 5275let kvStore; 5276try { 5277 let entries = []; 5278 for (var i = 0; i < 10; i++) { 5279 var key = 'batch_test_string_key'; 5280 var entry = { 5281 key: key + i, 5282 value: { 5283 type: distributedKVStore.ValueType.STRING, 5284 value: 'batch_test_string_value' 5285 } 5286 } 5287 entries.push(entry); 5288 } 5289 console.info(`entries : ${entries}`); 5290 kvStore.putBatch(entries, async function (err) { 5291 if (err != undefined) { 5292 console.error(`Failed to put batch.code is ${err.code},message is ${err.message}`); 5293 return; 5294 } 5295 console.info('Succeeded in putting batch'); 5296 kvStore.getEntries('localDeviceId', 'batch_test_string_key', function (err, entries) { 5297 if (err != undefined) { 5298 console.error(`Failed to get entries.code is ${err.code},message is ${err.message}`); 5299 return; 5300 } 5301 console.info('Succeeded in getting entries'); 5302 console.info(`entries.length: ${entries.length}`); 5303 console.info(`entries[0]: ${entries[0]}`); 5304 }); 5305 }); 5306} catch (e) { 5307 console.error(`Failed to put batch.code is ${e.code},message is ${e.message}`); 5308} 5309``` 5310 5311### getEntries 5312 5313getEntries(deviceId: string, keyPrefix: string): Promise<Entry[]> 5314 5315获取与指定设备ID和key前缀匹配的所有键值对，使用Promise异步回调。 5316 5317**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 5318 5319**参数：** 5320 5321| 参数名 | 类型 | 必填 | 说明 | 5322| --------- | -------- | ---- | ------------------------ | 5323| deviceId | string | 是 | 标识要查询其数据的设备。 | 5324| keyPrefix | string | 是 | 表示要匹配的键前缀。 | 5325 5326**返回值：** 5327 5328| 类型 | 说明 | 5329| -------------------------------- | ------------------------------------------------- | 5330| Promise<[Entry](#entry)[]> | Promise对象。返回匹配给定条件的所有键值对的列表。 | 5331 5332**错误码：** 5333 5334以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 5335 5336| **错误码ID** | **错误信息** | 5337| ------------ | -------------------------------------- | 5338| 15100003 | Database corrupted. | 5339| 15100005 | Database or result set already closed. | 5340 5341**示例：** 5342 5343```js 5344let kvStore; 5345try { 5346 let entries = []; 5347 for (var i = 0; i < 10; i++) { 5348 var key = 'batch_test_string_key'; 5349 var entry = { 5350 key: key + i, 5351 value: { 5352 type: distributedKVStore.ValueType.STRING, 5353 value: 'batch_test_string_value' 5354 } 5355 } 5356 entries.push(entry); 5357 } 5358 console.info(`entries: ${entries}`); 5359 kvStore.putBatch(entries).then(async () => { 5360 console.info('Succeeded in putting batch'); 5361 kvStore.getEntries('localDeviceId', 'batch_test_string_key').then((entries) => { 5362 console.info('Succeeded in getting entries'); 5363 console.info(`entries.length: ${entries.length}`); 5364 console.info(`entries[0]: ${entries[0]}`); 5365 console.info(`entries[0].value: ${entries[0].value}`); 5366 console.info(`entries[0].value.value: ${entries[0].value.value}`); 5367 }).catch((err) => { 5368 console.error(`Failed to get entries.code is ${err.code},message is ${err.message}`); 5369 }); 5370 }).catch((err) => { 5371 console.error(`Failed to put batch.code is ${err.code},message is ${err.message}`); 5372 }); 5373} catch (e) { 5374 console.error(`Failed to put batch.code is ${e.code},message is ${e.message}`); 5375} 5376``` 5377 5378### getEntries 5379 5380getEntries(query: Query, callback: AsyncCallback<Entry[]>): void 5381 5382获取本设备与指定Query对象匹配的键值对列表，使用callback异步回调。 5383 5384**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 5385 5386**参数：** 5387 5388| 参数名 | 类型 | 必填 | 说明 | 5389| -------- | -------------------------------------- | ---- | ----------------------------------------------------- | 5390| query | [Query](#query) | 是 | 表示要匹配的键前缀。 | 5391| callback | AsyncCallback<[Entry](#entry)[]> | 是 | 回调函数。返回本设备与指定Query对象匹配的键值对列表。 | 5392 5393**错误码：** 5394 5395以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 5396 5397| **错误码ID** | **错误信息** | 5398| ------------ | -------------------------------------- | 5399| 15100003 | Database corrupted. | 5400| 15100005 | Database or result set already closed. | 5401 5402**示例：** 5403 5404```js 5405let kvStore; 5406try { 5407 var arr = new Uint8Array([21, 31]); 5408 let entries = []; 5409 for (var i = 0; i < 10; i++) { 5410 var key = 'batch_test_bool_key'; 5411 var entry = { 5412 key: key + i, 5413 value: { 5414 type: distributedKVStore.ValueType.BYTE_ARRAY, 5415 value: arr 5416 } 5417 } 5418 entries.push(entry); 5419 } 5420 console.info(`entries: {entries}`); 5421 kvStore.putBatch(entries, async function (err) { 5422 console.info('Succeeded in putting Batch'); 5423 const query = new distributedKVStore.Query(); 5424 query.prefixKey("batch_test"); 5425 kvStore.getEntries(query, function (err, entries) { 5426 if (err != undefined) { 5427 console.error(`Failed to get Entries.code is ${err.code},message is ${err.message}`); 5428 return; 5429 } 5430 console.info('Succeeded in getting Entries'); 5431 console.info(`entries.length: ${entries.length}`); 5432 console.info(`entries[0]: ${entries[0]}`); 5433 }); 5434 }); 5435} catch (e) { 5436 console.error(`Failed to get Entries.code is ${e.code},message is ${e.message}`); 5437} 5438``` 5439 5440### getEntries 5441 5442getEntries(query: Query): Promise<Entry[]> 5443 5444获取本设备与指定Query对象匹配的键值对列表，使用Promise异步回调。 5445 5446**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 5447 5448**参数：** 5449 5450| 参数名 | 类型 | 必填 | 说明 | 5451| ------ | -------------- | ---- | -------------- | 5452| query | [Query](#query) | 是 | 表示查询对象。 | 5453 5454**返回值：** 5455 5456| 类型 | 说明 | 5457| -------------------------------- | -------------------------------------------------------- | 5458| Promise<[Entry](#entry)[]> | Promise对象。返回本设备与指定Query对象匹配的键值对列表。 | 5459 5460**错误码：** 5461 5462以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 5463 5464| **错误码ID** | **错误信息** | 5465| ------------ | -------------------------------------- | 5466| 15100003 | Database corrupted. | 5467| 15100005 | Database or result set already closed. | 5468 5469**示例：** 5470 5471```js 5472let kvStore; 5473try { 5474 var arr = new Uint8Array([21, 31]); 5475 let entries = []; 5476 for (var i = 0; i < 10; i++) { 5477 var key = 'batch_test_bool_key'; 5478 var entry = { 5479 key: key + i, 5480 value: { 5481 type: distributedKVStore.ValueType.BYTE_ARRAY, 5482 value: arr 5483 } 5484 } 5485 entries.push(entry); 5486 } 5487 console.info(`entries: {entries}`); 5488 kvStore.putBatch(entries).then(async () => { 5489 console.info('Succeeded in putting Batch'); 5490 const query = new distributedKVStore.Query(); 5491 query.prefixKey("batch_test"); 5492 kvStore.getEntries(query).then((entries) => { 5493 console.info('Succeeded in getting Entries'); 5494 }).catch((err) => { 5495 console.error(`Failed to get Entries.code is ${err.code},message is ${err.message}`); 5496 }); 5497 }).catch((err) => { 5498 console.error(`Failed to get Entries.code is ${err.code},message is ${err.message}`) 5499 }); 5500 console.info('Succeeded in getting Entries'); 5501} catch (e) { 5502 console.error(`Failed to get Entries.code is ${e.code},message is ${e.message}`); 5503} 5504``` 5505 5506### getEntries 5507 5508getEntries(deviceId: string, query: Query, callback: AsyncCallback<Entry[]>): void 5509 5510获取与指定设备ID和Query对象匹配的键值对列表，使用callback异步回调。 5511 5512**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 5513 5514**参数：** 5515 5516| 参数名 | 类型 | 必填 | 说明 | 5517| -------- | -------------------------------------- | ---- | ------------------------------------------------------- | 5518| deviceId | string | 是 | 键值对所属的设备ID。 | 5519| query | [Query](#query) | 是 | 表示查询对象。 | 5520| callback | AsyncCallback<[Entry](#entry)[]> | 是 | 回调函数。返回与指定设备ID和Query对象匹配的键值对列表。 | 5521 5522**错误码：** 5523 5524以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 5525 5526| **错误码ID** | **错误信息** | 5527| ------------ | -------------------------------------- | 5528| 15100003 | Database corrupted. | 5529| 15100005 | Database or result set already closed. | 5530 5531**示例：** 5532 5533```js 5534let kvStore; 5535try { 5536 var arr = new Uint8Array([21, 31]); 5537 let entries = []; 5538 for (var i = 0; i < 10; i++) { 5539 var key = 'batch_test_bool_key'; 5540 var entry = { 5541 key: key + i, 5542 value: { 5543 type: distributedKVStore.ValueType.BYTE_ARRAY, 5544 value: arr 5545 } 5546 } 5547 entries.push(entry); 5548 } 5549 console.info(`entries: ${entries}`); 5550 kvStore.putBatch(entries, async function (err) { 5551 if (err != undefined) { 5552 console.error(`Failed to put batch.code is ${err.code},message is ${err.message}`); 5553 return; 5554 } 5555 console.info('Succeeded in putting batch'); 5556 var query = new distributedKVStore.Query(); 5557 query.deviceId('localDeviceId'); 5558 query.prefixKey("batch_test"); 5559 kvStore.getEntries('localDeviceId', query, function (err, entries) { 5560 if (err != undefined) { 5561 console.error(`Failed to get entries.code is ${err.code},message is ${err.message}`); 5562 return; 5563 } 5564 console.info('Succeeded in getting entries'); 5565 console.info(`entries.length: ${entries.length}`); 5566 console.info(`entries[0]: ${entries[0]}`); 5567 }) 5568 }); 5569 console.info('Succeeded in getting entries'); 5570} catch (e) { 5571 console.error(`Failed to get entries.code is ${e.code},message is ${e.message}`); 5572} 5573``` 5574 5575### getEntries 5576 5577getEntries(deviceId: string, query: Query): Promise<Entry[]> 5578 5579获取与指定设备ID和Query对象匹配的键值对列表，使用Promise异步回调。 5580 5581**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 5582 5583**参数：** 5584 5585| 参数名 | 类型 | 必填 | 说明 | 5586| -------- | -------------- | ---- | -------------------- | 5587| deviceId | string | 是 | 键值对所属的设备ID。 | 5588| query | [Query](#query) | 是 | 表示查询对象。 | 5589 5590**返回值：** 5591 5592| 类型 | 说明 | 5593| -------------------------------- | ---------------------------------------------------------- | 5594| Promise<[Entry](#entry)[]> | Promise对象。返回与指定设备ID和Query对象匹配的键值对列表。 | 5595 5596**错误码：** 5597 5598以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 5599 5600| **错误码ID** | **错误信息** | 5601| ------------ | -------------------------------------- | 5602| 15100003 | Database corrupted. | 5603| 15100005 | Database or result set already closed. | 5604 5605**示例：** 5606 5607```js 5608let kvStore; 5609try { 5610 var arr = new Uint8Array([21, 31]); 5611 let entries = []; 5612 for (var i = 0; i < 10; i++) { 5613 var key = 'batch_test_bool_key'; 5614 var entry = { 5615 key: key + i, 5616 value: { 5617 type: distributedKVStore.ValueType.BYTE_ARRAY, 5618 value: arr 5619 } 5620 } 5621 entries.push(entry); 5622 } 5623 console.info(`entries: ${entries}`); 5624 kvStore.putBatch(entries).then(async () => { 5625 console.info('Succeeded in putting batch'); 5626 var query = new distributedKVStore.Query(); 5627 query.deviceId('localDeviceId'); 5628 query.prefixKey("batch_test"); 5629 kvStore.getEntries('localDeviceId', query).then((entries) => { 5630 console.info('Succeeded in getting entries'); 5631 }).catch((err) => { 5632 console.error(`Failed to get entries.code is ${err.code},message is ${err.message}`); 5633 }); 5634 }).catch((err) => { 5635 console.error(`Failed to put batch.code is ${err.code},message is ${err.message}`); 5636 }); 5637 console.info('Succeeded in getting entries'); 5638} catch (e) { 5639 console.error(`Failed to get entries.code is ${e.code},message is ${e.message}`); 5640} 5641``` 5642 5643### getResultSet 5644 5645getResultSet(keyPrefix: string, callback: AsyncCallback<KVStoreResultSet>): void 5646 5647从DeviceKVStore数据库中获取本设备具有指定前缀的结果集，使用callback异步回调。 5648 5649**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 5650 5651**参数：** 5652 5653| 参数名 | 类型 | 必填 | 说明 | 5654| --------- | ---------------------------------------------------------- | ---- | ------------------------------------ | 5655| keyPrefix | string | 是 | 表示要匹配的键前缀。 | 5656| callback | AsyncCallback<[KVStoreResultSet](#kvstoreresultset)> | 是 | 回调函数。返回具有指定前缀的结果集。 | 5657 5658**错误码：** 5659 5660以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 5661 5662| **错误码ID** | **错误信息** | 5663| ------------ | -------------------------------------- | 5664| 15100003 | Database corrupted. | 5665| 15100005 | Database or result set already closed. | 5666 5667**示例：** 5668 5669```js 5670let kvStore; 5671try { 5672 let resultSet; 5673 let entries = []; 5674 for (var i = 0; i < 10; i++) { 5675 var key = 'batch_test_string_key'; 5676 var entry = { 5677 key: key + i, 5678 value: { 5679 type: distributedKVStore.ValueType.STRING, 5680 value: 'batch_test_string_value' 5681 } 5682 } 5683 entries.push(entry); 5684 } 5685 kvStore.putBatch(entries, async function (err) { 5686 if (err != undefined) { 5687 console.error(`Failed to put batch.code is ${err.code},message is ${err.message}`); 5688 return; 5689 } 5690 console.info('Succeeded in putting batch'); 5691 kvStore.getResultSet('batch_test_string_key', async function (err, result) { 5692 if (err != undefined) { 5693 console.error(`Failed to get resultset.code is ${err.code},message is ${err.message}`); 5694 return; 5695 } 5696 console.info('Succeeded in getting result set'); 5697 resultSet = result; 5698 kvStore.closeResultSet(resultSet, function (err) { 5699 if (err != undefined) { 5700 console.error(`Failed to close resultset.code is ${err.code},message is ${err.message}`); 5701 return; 5702 } 5703 console.info('Succeeded in closing result set'); 5704 }) 5705 }); 5706 }); 5707} catch (e) { 5708 console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`); 5709} 5710``` 5711 5712### getResultSet 5713 5714getResultSet(keyPrefix: string): Promise<KVStoreResultSet> 5715 5716从DeviceKVStore数据库中获取本设备具有指定前缀的结果集，使用Promise异步回调。 5717 5718**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 5719 5720**参数：** 5721 5722| 参数名 | 类型 | 必填 | 说明 | 5723| --------- | ------ | ---- | -------------------- | 5724| keyPrefix | string | 是 | 表示要匹配的键前缀。 | 5725 5726**返回值：** 5727 5728| 类型 | 说明 | 5729| ---------------------------------------------------- | --------------------------------------- | 5730| Promise<[KVStoreResultSet](#kvstoreresultset)> | Promise对象。返回具有指定前缀的结果集。 | 5731 5732**错误码：** 5733 5734以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 5735 5736| **错误码ID** | **错误信息** | 5737| ------------ | -------------------------------------- | 5738| 15100003 | Database corrupted. | 5739| 15100005 | Database or result set already closed. | 5740 5741**示例：** 5742 5743```js 5744let kvStore; 5745try { 5746 let resultSet; 5747 let entries = []; 5748 for (var i = 0; i < 10; i++) { 5749 var key = 'batch_test_string_key'; 5750 var entry = { 5751 key: key + i, 5752 value: { 5753 type: distributedKVStore.ValueType.STRING, 5754 value: 'batch_test_string_value' 5755 } 5756 } 5757 entries.push(entry); 5758 } 5759 kvStore.putBatch(entries).then(async () => { 5760 console.info('Succeeded in putting batch'); 5761 }).catch((err) => { 5762 console.error(`Failed to put batch.code is ${err.code},message is ${err.message}`); 5763 }); 5764 kvStore.getResultSet('batch_test_string_key').then((result) => { 5765 console.info('Succeeded in getting result set'); 5766 resultSet = result; 5767 }).catch((err) => { 5768 console.error(`Failed to get resultset.code is ${err.code},message is ${err.message}`); 5769 }); 5770 kvStore.closeResultSet(resultSet).then(() => { 5771 console.info('Succeeded in closing result set'); 5772 }).catch((err) => { 5773 console.error(`Failed to close resultset.code is ${err.code},message is ${err.message}`); 5774 }); 5775} catch (e) { 5776 console.error(`An unexpected error occurred.code is ${e.code},message is ${e.code}`); 5777} 5778``` 5779 5780### getResultSet 5781 5782getResultSet(deviceId: string, keyPrefix: string, callback: AsyncCallback<KVStoreResultSet>): void 5783 5784获取与指定设备ID和key前缀匹配的KVStoreResultSet对象，使用callback异步回调。 5785 5786**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 5787 5788**参数：** 5789 5790| 参数名 | 类型 | 必填 | 说明 | 5791| --------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 5792| deviceId | string | 是 | 标识要查询其数据的设备。 | 5793| keyPrefix | string | 是 | 表示要匹配的键前缀。 | 5794| callback | AsyncCallback<[KVStoreResultSet](#kvstoreresultset)> | 是 | 回调函数。返回与指定设备ID和key前缀匹配的KVStoreResultSet对象。 | 5795 5796**错误码：** 5797 5798以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 5799 5800| **错误码ID** | **错误信息** | 5801| ------------ | -------------------------------------- | 5802| 15100003 | Database corrupted. | 5803| 15100005 | Database or result set already closed. | 5804 5805**示例：** 5806 5807```js 5808let kvStore; 5809try { 5810 let resultSet; 5811 kvStore.getResultSet('localDeviceId', 'batch_test_string_key', async function (err, result) { 5812 if (err != undefined) { 5813 console.error(`Failed to get resultSet.code is ${err.code},message is ${err.message}`); 5814 return; 5815 } 5816 console.info('Succeeded in getting resultSet'); 5817 resultSet = result; 5818 kvStore.closeResultSet(resultSet, function (err) { 5819 if (err != undefined) { 5820 console.error(`Failed to close resultSet.code is ${err.code},message is ${err.message}`); 5821 return; 5822 } 5823 console.info('Succeeded in closing resultSet'); 5824 }) 5825 }); 5826} catch (e) { 5827 console.error(`Failed to get resultSet.code is ${e.code},message is ${e.message}`); 5828} 5829``` 5830 5831### getResultSet 5832 5833getResultSet(deviceId: string, keyPrefix: string): Promise<KVStoreResultSet> 5834 5835获取与指定设备ID和key前缀匹配的KVStoreResultSet对象，使用Promise异步回调。 5836 5837**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 5838 5839**参数：** 5840 5841| 参数名 | 类型 | 必填 | 说明 | 5842| --------- | -------- | ---- | ------------------------ | 5843| deviceId | string | 是 | 标识要查询其数据的设备。 | 5844| keyPrefix | string | 是 | 表示要匹配的键前缀。 | 5845 5846**返回值：** 5847 5848| 类型 | 说明 | 5849| ------------------------------------------------------ | ------------------------------------------------------------ | 5850| Promise<[KVStoreResultSet](#kvstoreresultset)> | Promise对象。返回与指定设备ID和key前缀匹配的KVStoreResultSet对象。 | 5851 5852**错误码：** 5853 5854以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 5855 5856| **错误码ID** | **错误信息** | 5857| ------------ | -------------------------------------- | 5858| 15100003 | Database corrupted. | 5859| 15100005 | Database or result set already closed. | 5860 5861**示例：** 5862 5863```js 5864let kvStore; 5865try { 5866 let resultSet; 5867 kvStore.getResultSet('localDeviceId', 'batch_test_string_key').then((result) => { 5868 console.info('Succeeded in getting resultSet'); 5869 resultSet = result; 5870 }).catch((err) => { 5871 console.error(`Failed to get resultSet.code is ${err.code},message is ${err.message}`); 5872 }); 5873 kvStore.closeResultSet(resultSet).then(() => { 5874 console.info('Succeeded in closing resultSet'); 5875 }).catch((err) => { 5876 console.error(`Failed to close resultSet.code is ${err.code},message is ${err.message}`); 5877 }); 5878} catch (e) { 5879 console.error(`Failed to get resultSet.code is ${e.code},message is ${e.message}`); 5880} 5881``` 5882 5883### getResultSet 5884 5885getResultSet(deviceId: string, query: Query, callback: AsyncCallback<KVStoreResultSet>): void 5886 5887获取与指定设备ID和Query对象匹配的KVStoreResultSet对象，使用callback异步回调。 5888 5889**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 5890 5891**参数：** 5892 5893| 参数名 | 类型 | 必填 | 说明 | 5894| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 5895| deviceId | string | 是 | KVStoreResultSet对象所属的设备ID。 | 5896| query | [Query](#query) | 是 | 表示查询对象。 | 5897| callback | AsyncCallback<[KVStoreResultSet](#kvstoreresultset)> | 是 | 回调函数。返回与指定设备ID和Query对象匹配的KVStoreResultSet对象。 | 5898 5899**错误码：** 5900 5901以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 5902 5903| **错误码ID** | **错误信息** | 5904| ------------ | -------------------------------------- | 5905| 15100003 | Database corrupted. | 5906| 15100005 | Database or result set already closed. | 5907 5908**示例：** 5909 5910```js 5911let kvStore; 5912try { 5913 let resultSet; 5914 let entries = []; 5915 for (var i = 0; i < 10; i++) { 5916 var key = 'batch_test_string_key'; 5917 var entry = { 5918 key: key + i, 5919 value: { 5920 type: distributedKVStore.ValueType.STRING, 5921 value: 'batch_test_string_value' 5922 } 5923 } 5924 entries.push(entry); 5925 } 5926 kvStore.putBatch(entries, async function (err) { 5927 if (err != undefined) { 5928 console.error(`Failed to put batch.code is ${err.code},message is ${err.message}`); 5929 return; 5930 } 5931 console.info('Succeeded in putting batch'); 5932 const query = new distributedKVStore.Query(); 5933 query.prefixKey("batch_test"); 5934 kvStore.getResultSet('localDeviceId', query, async function (err, result) { 5935 if (err != undefined) { 5936 console.error(`Failed to get resultSet.code is ${err.code},message is ${err.message}`); 5937 return; 5938 } 5939 console.info('Succeeded in getting resultSet'); 5940 resultSet = result; 5941 kvStore.closeResultSet(resultSet, function (err) { 5942 if (err != undefined) { 5943 console.error(`Failed to close resultSet.code is ${err.code},message is ${err.message}`); 5944 return; 5945 } 5946 console.info('Succeeded in closing resultSet'); 5947 }) 5948 }); 5949 }); 5950} catch (e) { 5951 console.error(`Failed to get resultSet.code is ${e.code},message is ${e.message}`); 5952} 5953``` 5954 5955### getResultSet 5956 5957getResultSet(deviceId: string, query: Query): Promise<KVStoreResultSet> 5958 5959获取与指定设备ID和Query对象匹配的KVStoreResultSet对象，使用Promise异步回调。 5960 5961**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 5962 5963**参数：** 5964 5965| 参数名 | 类型 | 必填 | 说明 | 5966| -------- | -------------- | ---- | ---------------------------------- | 5967| deviceId | string | 是 | KVStoreResultSet对象所属的设备ID。 | 5968| query | [Query](#query) | 是 | 表示查询对象。 | 5969 5970**返回值：** 5971 5972| 类型 | 说明 | 5973| ------------------------------------------------------ | ------------------------------------------------------------ | 5974| Promise<[KVStoreResultSet](#kvstoreresultset)> | Promise对象。返回与指定设备ID和Query对象匹配的KVStoreResultSet对象。 | 5975 5976**错误码：** 5977 5978以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 5979 5980| **错误码ID** | **错误信息** | 5981| ------------ | -------------------------------------- | 5982| 15100003 | Database corrupted. | 5983| 15100005 | Database or result set already closed. | 5984 5985**示例：** 5986 5987```js 5988let kvStore; 5989try { 5990 let resultSet; 5991 let entries = []; 5992 for (var i = 0; i < 10; i++) { 5993 var key = 'batch_test_string_key'; 5994 var entry = { 5995 key: key + i, 5996 value: { 5997 type: distributedKVStore.ValueType.STRING, 5998 value: 'batch_test_string_value' 5999 } 6000 } 6001 entries.push(entry); 6002 } 6003 kvStore.putBatch(entries).then(async () => { 6004 console.info('Succeeded in putting batch'); 6005 }).catch((err) => { 6006 console.error(`Failed to put batch.code is ${err.code},message is ${err.message}`); 6007 }); 6008 const query = new distributedKVStore.Query(); 6009 query.prefixKey("batch_test"); 6010 kvStore.getResultSet('localDeviceId', query).then((result) => { 6011 console.info('Succeeded in getting resultSet'); 6012 resultSet = result; 6013 }).catch((err) => { 6014 console.error(`Failed to get resultSet.code is ${err.code},message is ${err.message}`); 6015 }); 6016 query.deviceId('localDeviceId'); 6017 console.info("GetResultSet " + query.getSqlLike()); 6018 kvStore.closeResultSet(resultSet).then(() => { 6019 console.info('Succeeded in closing resultSet'); 6020 }).catch((err) => { 6021 console.error(`Failed to close resultSet.code is ${err.code},message is ${err.message}`); 6022 }); 6023 6024} catch (e) { 6025 console.error(`Failed to get resultSet.code is ${e.code},message is ${e.message}`); 6026} 6027``` 6028 6029### getResultSet 6030 6031getResultSet(query: Query): Promise<KVStoreResultSet> 6032 6033获取与本设备指定Query对象匹配的KVStoreResultSet对象，使用Promise异步回调。 6034 6035**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 6036 6037**参数：** 6038 6039| 参数名 | 类型 | 必填 | 说明 | 6040| ------ | -------------- | ---- | -------------- | 6041| query | [Query](#query) | 是 | 表示查询对象。 | 6042 6043**返回值：** 6044 6045| 类型 | 说明 | 6046| ---------------------------------------------------- | ------------------------------------------------------------ | 6047| Promise<[KVStoreResultSet](#kvstoreresultset)> | Promise对象。获取与本设备指定Query对象匹配的KVStoreResultSet对象。 | 6048 6049**错误码：** 6050 6051以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 6052 6053| **错误码ID** | **错误信息** | 6054| ------------ | -------------------------------------- | 6055| 15100003 | Database corrupted. | 6056| 15100005 | Database or result set already closed. | 6057 6058**示例：** 6059 6060```js 6061let kvStore; 6062try { 6063 let resultSet; 6064 let entries = []; 6065 for (var i = 0; i < 10; i++) { 6066 var key = 'batch_test_string_key'; 6067 var entry = { 6068 key: key + i, 6069 value: { 6070 type: distributedKVStore.ValueType.STRING, 6071 value: 'batch_test_string_value' 6072 } 6073 } 6074 entries.push(entry); 6075 } 6076 kvStore.putBatch(entries).then(async () => { 6077 console.info('Succeeded in putting batch'); 6078 }).catch((err) => { 6079 console.error(`Failed to put batch.code is ${err.code},message is ${err.message}`); 6080 }); 6081 const query = new distributedKVStore.Query(); 6082 query.prefixKey("batch_test"); 6083 kvStore.getResultSet(query).then((result) => { 6084 console.info('Succeeded in getting result set'); 6085 resultSet = result; 6086 }).catch((err) => { 6087 console.error(`Fail to get resultset.code is ${err.code},message is ${err.message}`); 6088 }); 6089} catch (e) { 6090 console.error(`An unexpected error occurred.code is ${e.code},message is ${e.code}`); 6091} 6092``` 6093 6094### getResultSet 6095 6096getResultSet(query: Query, callback:AsyncCallback<KVStoreResultSet>): void 6097 6098获取与本设备指定Query对象匹配的KVStoreResultSet对象，使用callback异步回调。 6099 6100**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 6101 6102**参数：** 6103 6104| 参数名 | 类型 | 必填 | 说明 | 6105| -------- | -------------- | ---- | ---------------------------------- | 6106| query | [Query](#query) | 是 | 表示查询对象。 | 6107| callback | AsyncCallback<[KVStoreResultSet](#kvstoreresultset)> | 是 | 回调函数，获取与指定Predicates对象匹配的KVStoreResultSet对象。 | 6108 6109**错误码：** 6110 6111以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 6112 6113| **错误码ID** | **错误信息** | 6114| ------------ | -------------------------------------- | 6115| 15100003 | Database corrupted. | 6116| 15100005 | Database or result set already closed. | 6117 6118**示例：** 6119 6120```js 6121let kvStore; 6122try { 6123 let resultSet; 6124 let entries = []; 6125 for (var i = 0; i < 10; i++) { 6126 var key = 'batch_test_string_key'; 6127 var entry = { 6128 key: key + i, 6129 value: { 6130 type: distributedKVStore.ValueType.STRING, 6131 value: 'batch_test_string_value' 6132 } 6133 } 6134 entries.push(entry); 6135 } 6136 kvStore.putBatch(entries, async function (err) { 6137 if (err != undefined) { 6138 console.error(`Failed to put batch.code is ${err.code},message is ${err.message}`); 6139 return; 6140 } 6141 console.info('Succeeded in putting batch'); 6142 const query = new distributedKVStore.Query(); 6143 query.prefixKey("batch_test"); 6144 kvStore.getResultSet(query, async function (err, result) { 6145 if (err != undefined) { 6146 console.error(`Failed to get resultSet.code is ${err.code},message is ${err.message}`); 6147 return; 6148 } 6149 console.info('Succeeded in getting resultSet'); 6150 resultSet = result; 6151 kvStore.closeResultSet(resultSet, function (err) { 6152 if (err != undefined) { 6153 console.error(`Failed to close resultSet.code is ${err.code},message is ${err.message}`); 6154 return; 6155 } 6156 console.info('Succeeded in closing resultSet'); 6157 }) 6158 }); 6159 }); 6160} catch (e) { 6161 console.error(`Failed to get resultSet.code is ${e.code},message is ${e.message}`); 6162} 6163``` 6164 6165### getResultSet 6166 6167getResultSet(predicates: dataSharePredicates.DataSharePredicates, callback: AsyncCallback<KVStoreResultSet>): void 6168 6169获取与本设备指定Predicate对象匹配的KVStoreResultSet对象，使用callback异步回调。 6170 6171**系统接口：** 此接口为系统接口。 6172 6173**系统能力：** SystemCapability.DistributedDataManager.DataShare.Provider 6174 6175**参数：** 6176 6177| 参数名 | 类型 | 必填 | 说明 | 6178| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 6179| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | 是 | 指示筛选条件,当此参数为null时，应定义处理逻辑。 | 6180| callback | AsyncCallback<[KVStoreResultSet](#kvstoreresultset)> | 是 | 回调函数，获取与指定Predicates对象匹配的KVStoreResultSet对象。 | 6181 6182**错误码：** 6183 6184以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 6185 6186| **错误码ID** | **错误信息** | 6187| ------------ | -------------------------------------- | 6188| 15100003 | Database corrupted. | 6189| 15100005 | Database or result set already closed. | 6190 6191**示例：** 6192 6193```js 6194import dataSharePredicates from '@ohos.data.dataSharePredicates'; 6195 6196let kvStore; 6197try { 6198 let resultSet; 6199 let predicates = new dataSharePredicates.DataSharePredicates(); 6200 predicates.prefixKey("batch_test_string_key"); 6201 kvStore.getResultSet(predicates, async function (err, result) { 6202 if (err != undefined) { 6203 console.error(`Failed to get resultset.code is ${err.code},message is ${err.message}`); 6204 return; 6205 } 6206 console.info('Succeeded in getting result set'); 6207 resultSet = result; 6208 kvStore.closeResultSet(resultSet, function (err) { 6209 if (err != undefined) { 6210 console.error(`Failed to close resultset.code is ${err.code},message is ${err.message}`); 6211 return; 6212 } 6213 console.info('Succeeded in closing result set'); 6214 }) 6215 }); 6216} catch (e) { 6217 console.error(`An unexpected error occurred.code is ${e.code},message is ${e.code}`); 6218} 6219``` 6220 6221### getResultSet 6222 6223getResultSet(predicates: dataSharePredicates.DataSharePredicates): Promise<KVStoreResultSet> 6224 6225获取与本设备指定Predicate对象匹配的KVStoreResultSet对象，使用Promise异步回调。 6226 6227**系统接口：** 此接口为系统接口。 6228 6229**系统能力：** SystemCapability.DistributedDataManager.DataShare.Provider 6230 6231**参数：** 6232 6233| 参数名 | 类型 | 必填 | 说明 | 6234| ---------- | ------------------------------------------------------------ | ---- | ----------------------------------------------- | 6235| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | 是 | 指示筛选条件,当此参数为null时，应定义处理逻辑。 | 6236 6237**返回值：** 6238 6239| 类型 | 说明 | 6240| ---------------------------------------------------- | ------------------------- | 6241| Promise<[KVStoreResultSet](#kvstoreresultset)> | 无返回结果的Promise对象。 | 6242 6243**错误码：** 6244 6245以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 6246 6247| **错误码ID** | **错误信息** | 6248| ------------ | -------------------------------------- | 6249| 15100003 | Database corrupted. | 6250| 15100005 | Database or result set already closed. | 6251 6252**示例：** 6253 6254```js 6255import dataSharePredicates from '@ohos.data.dataSharePredicates'; 6256 6257let kvStore; 6258try { 6259 let resultSet; 6260 let predicates = new dataSharePredicates.DataSharePredicates(); 6261 predicates.prefixKey("batch_test_string_key"); 6262 kvStore.getResultSet(predicates).then((result) => { 6263 console.info('Succeeded in getting result set'); 6264 resultSet = result; 6265 }).catch((err) => { 6266 console.error(`Failed to get resultset.code is ${err.code},message is ${err.message}`); 6267 }); 6268 kvStore.closeResultSet(resultSet).then(() => { 6269 console.info('Succeeded in closing result set'); 6270 }).catch((err) => { 6271 console.error(`Failed to close resultset.code is ${err.code},message is ${err.message}`); 6272 }); 6273} catch (e) { 6274 console.error(`An unexpected error occurred.code is ${e.code},message is ${e.code}`); 6275} 6276``` 6277 6278### getResultSet 6279 6280getResultSet(deviceId: string, predicates: dataSharePredicates.DataSharePredicates, callback: AsyncCallback<KVStoreResultSet>): void 6281 6282获取与指定Predicate对象匹配的KVStoreResultSet对象，使用callback异步回调。 6283 6284**系统接口：** 此接口为系统接口。 6285 6286**系统能力：** SystemCapability.DistributedDataManager.DataShare.Provider 6287 6288**参数：** 6289 6290| 参数名 | 类型 | 必填 | 说明 | 6291| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 6292| deviceId | string | 是 | 标识要查询其数据的设备。 | 6293| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | 是 | 指示筛选条件,当此参数为null时，应定义处理逻辑。 | 6294| callback | AsyncCallback<[KVStoreResultSet](#kvstoreresultset)> | 是 | 回调函数，获取与指定Predicates对象匹配的KVStoreResultSet对象。 | 6295 6296**错误码：** 6297 6298以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 6299 6300| **错误码ID** | **错误信息** | 6301| ------------ | -------------------------------------- | 6302| 15100003 | Database corrupted. | 6303| 15100005 | Database or result set already closed. | 6304 6305**示例：** 6306 6307```js 6308import dataSharePredicates from '@ohos.data.dataSharePredicates'; 6309 6310let kvStore; 6311try { 6312 let resultSet; 6313 let predicates = new dataSharePredicates.DataSharePredicates(); 6314 predicates.prefixKey("batch_test_string_key"); 6315 kvStore.getResultSet('localDeviceId', predicates, async function (err, result) { 6316 if (err != undefined) { 6317 console.error(`Failed to get resultset.code is ${err.code},message is ${err.message}`); 6318 return; 6319 } 6320 console.info('Succeeded in getting result set'); 6321 resultSet = result; 6322 kvStore.closeResultSet(resultSet, function (err) { 6323 if (err != undefined) { 6324 console.error(`Failed to close resultset.code is ${err.code},message is ${err.message}`); 6325 return; 6326 } 6327 console.info('Succeeded in closing result set'); 6328 }) 6329 }); 6330} catch (e) { 6331 console.error(`An unexpected error occurred.code is ${e.code},message is ${e.code}`); 6332} 6333``` 6334 6335### getResultSet 6336 6337getResultSet(deviceId: string, predicates: dataSharePredicates.DataSharePredicates): Promise<KVStoreResultSet> 6338 6339获取与指定Predicate对象匹配的KVStoreResultSet对象，使用Promise异步回调。 6340 6341**系统接口：** 此接口为系统接口。 6342 6343**系统能力：** SystemCapability.DistributedDataManager.DataShare.Provider 6344 6345**参数：** 6346 6347| 参数名 | 类型 | 必填 | 说明 | 6348| ---------- | ------------------------------------------------------------ | ---- | ----------------------------------------------- | 6349| deviceId | string | 是 | 标识要查询其数据的设备。 | 6350| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | 是 | 指示筛选条件,当此参数为null时，应定义处理逻辑。 | 6351 6352**返回值：** 6353 6354| 类型 | 说明 | 6355| ---------------------------------------------------- | ------------------------- | 6356| Promise<[KVStoreResultSet](#kvstoreresultset)> | 无返回结果的Promise对象。 | 6357 6358**错误码：** 6359 6360以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 6361 6362| **错误码ID** | **错误信息** | 6363| ------------ | -------------------------------------- | 6364| 15100003 | Database corrupted. | 6365| 15100005 | Database or result set already closed. | 6366 6367**示例：** 6368 6369```js 6370import dataSharePredicates from '@ohos.data.dataSharePredicates'; 6371let kvStore; 6372try { 6373 let resultSet; 6374 let predicates = new dataSharePredicates.DataSharePredicates(); 6375 predicates.prefixKey("batch_test_string_key"); 6376 kvStore.getResultSet('localDeviceId', predicates).then((result) => { 6377 console.info('Succeeded in getting result set'); 6378 resultSet = result; 6379 }).catch((err) => { 6380 console.error(`Failed to get resultset.code is ${err.code},message is ${err.message}`); 6381 }); 6382 kvStore.closeResultSet(resultSet).then(() => { 6383 console.info('Succeeded in closing result set'); 6384 }).catch((err) => { 6385 console.error(`Failed to close resultset.code is ${err.code},message is ${err.message}`); 6386 }); 6387} catch (e) { 6388 console.error(`An unexpected error occurred.code is ${e.code},message is ${e.code}`); 6389} 6390``` 6391 6392### getResultSize 6393 6394getResultSize(query: Query, callback: AsyncCallback<number>): void 6395 6396获取与本设备指定Query对象匹配的结果数，使用callback异步回调。 6397 6398**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 6399 6400**参数：** 6401 6402| 参数名 | 类型 | 必填 | 说明 | 6403| -------- | --------------------------- | ---- | ------------------------------------------------- | 6404| query | [Query](#query) | 是 | 表示查询对象。 | 6405| callback | AsyncCallback<number> | 是 | 回调函数。返回与本设备指定Query对象匹配的结果数。 | 6406 6407**错误码：** 6408 6409以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 6410 6411| **错误码ID** | **错误信息** | 6412| ------------ | -------------------------------------- | 6413| 15100003 | Database corrupted. | 6414| 15100005 | Database or result set already closed. | 6415 6416**示例：** 6417 6418```js 6419let kvStore; 6420try { 6421 let entries = []; 6422 for (var i = 0; i < 10; i++) { 6423 var key = 'batch_test_string_key'; 6424 var entry = { 6425 key: key + i, 6426 value: { 6427 type: distributedKVStore.ValueType.STRING, 6428 value: 'batch_test_string_value' 6429 } 6430 } 6431 entries.push(entry); 6432 } 6433 kvStore.putBatch(entries, async function (err) { 6434 console.info('Succeeded in putting batch'); 6435 const query = new distributedKVStore.Query(); 6436 query.prefixKey("batch_test"); 6437 kvStore.getResultSize(query, async function (err, resultSize) { 6438 if (err != undefined) { 6439 console.error(`Failed to get result size.code is ${err.code},message is ${err.message}`); 6440 return; 6441 } 6442 console.info('Succeeded in getting result set size'); 6443 }); 6444 }); 6445} catch (e) { 6446 console.error(`An unexpected error occurred.code is ${e.code},message is ${e.code}`); 6447} 6448``` 6449 6450### getResultSize 6451 6452getResultSize(query: Query): Promise<number> 6453 6454获取与本设备指定Query对象匹配的结果数，使用Promise异步回调。 6455 6456**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 6457 6458**参数：** 6459 6460| 参数名 | 类型 | 必填 | 说明 | 6461| ------ | -------------- | ---- | -------------- | 6462| query | [Query](#query) | 是 | 表示查询对象。 | 6463 6464**返回值：** 6465 6466| 类型 | 说明 | 6467| --------------------- | ---------------------------------------------------- | 6468| Promise<number> | Promise对象。获取与本设备指定Query对象匹配的结果数。 | 6469 6470**错误码：** 6471 6472以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 6473 6474| **错误码ID** | **错误信息** | 6475| ------------ | -------------------------------------- | 6476| 15100003 | Database corrupted. | 6477| 15100005 | Database or result set already closed. | 6478 6479**示例：** 6480 6481```js 6482let kvStore; 6483try { 6484 let entries = []; 6485 for (var i = 0; i < 10; i++) { 6486 var key = 'batch_test_string_key'; 6487 var entry = { 6488 key: key + i, 6489 value: { 6490 type: distributedKVStore.ValueType.STRING, 6491 value: 'batch_test_string_value' 6492 } 6493 } 6494 entries.push(entry); 6495 } 6496 kvStore.putBatch(entries).then(async () => { 6497 console.info('Succeeded in putting batch'); 6498 }).catch((err) => { 6499 console.error(`Failed to put batch.code is ${err.code},message is ${err.message}`); 6500 }); 6501 const query = new distributedKVStore.Query(); 6502 query.prefixKey("batch_test"); 6503 kvStore.getResultSize(query).then((resultSize) => { 6504 console.info('Succeeded in getting result set size'); 6505 }).catch((err) => { 6506 console.error(`Failed to get result size.code is ${err.code},message is ${err.message}`); 6507 }); 6508} catch (e) { 6509 console.error(`An unexpected error occurred.code is ${e.code},message is ${e.code}`); 6510} 6511``` 6512 6513### getResultSize 6514 6515getResultSize(deviceId: string, query: Query, callback: AsyncCallback<number>): void; 6516 6517获取与指定设备ID和Query对象匹配的结果数，使用callback异步回调。 6518 6519**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 6520 6521**参数：** 6522 6523| 参数名 | 类型 | 必填 | 说明 | 6524| -------- | --------------------------- | ---- | --------------------------------------------------- | 6525| deviceId | string | 是 | KVStoreResultSet对象所属的设备ID。 | 6526| query | [Query](#query) | 是 | 表示查询对象。 | 6527| callback | AsyncCallback<number> | 是 | 回调函数。返回与指定设备ID和Query对象匹配的结果数。 | 6528 6529**错误码：** 6530 6531以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 6532 6533| **错误码ID** | **错误信息** | 6534| ------------ | -------------------------------------- | 6535| 15100003 | Database corrupted. | 6536| 15100005 | Database or result set already closed. | 6537 6538**示例：** 6539 6540```js 6541let kvStore; 6542try { 6543 let entries = []; 6544 for (var i = 0; i < 10; i++) { 6545 var key = 'batch_test_string_key'; 6546 var entry = { 6547 key: key + i, 6548 value: { 6549 type: distributedKVStore.ValueType.STRING, 6550 value: 'batch_test_string_value' 6551 } 6552 } 6553 entries.push(entry); 6554 } 6555 kvStore.putBatch(entries, async function (err) { 6556 if (err != undefined) { 6557 console.error(`Failed to put batch.code is ${err.code},message is ${err.message}`); 6558 return; 6559 } 6560 console.info('Succeeded in putting batch'); 6561 const query = new distributedKVStore.Query(); 6562 query.prefixKey("batch_test"); 6563 kvStore.getResultSize('localDeviceId', query, async function (err, resultSize) { 6564 if (err != undefined) { 6565 console.error(`Failed to get resultSize.code is ${err.code},message is ${err.message}`); 6566 return; 6567 } 6568 console.info('Succeeded in getting resultSize'); 6569 }); 6570 }); 6571} catch (e) { 6572 console.error(`Failed to get resultSize.code is ${e.code},message is ${e.message}`); 6573} 6574``` 6575 6576### getResultSize 6577 6578getResultSize(deviceId: string, query: Query): Promise<number> 6579 6580获取与指定设备ID和Query对象匹配的结果数，使用Promise异步回调。 6581 6582**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 6583 6584**参数：** 6585 6586| 参数名 | 类型 | 必填 | 说明 | 6587| -------- | -------------- | ---- | ---------------------------------- | 6588| deviceId | string | 是 | KVStoreResultSet对象所属的设备ID。 | 6589| query | [Query](#query) | 是 | 表示查询对象。 | 6590 6591**返回值：** 6592 6593| 类型 | 说明 | 6594| --------------------- | ------------------------------------------------------ | 6595| Promise<number> | Promise对象。返回与指定设备ID和Query对象匹配的结果数。 | 6596 6597**错误码：** 6598 6599以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 6600 6601| **错误码ID** | **错误信息** | 6602| ------------ | -------------------------------------- | 6603| 15100003 | Database corrupted. | 6604| 15100005 | Database or result set already closed. | 6605 6606**示例：** 6607 6608```js 6609let kvStore; 6610try { 6611 let entries = []; 6612 for (var i = 0; i < 10; i++) { 6613 var key = 'batch_test_string_key'; 6614 var entry = { 6615 key: key + i, 6616 value: { 6617 type: distributedKVStore.ValueType.STRING, 6618 value: 'batch_test_string_value' 6619 } 6620 } 6621 entries.push(entry); 6622 } 6623 kvStore.putBatch(entries).then(async () => { 6624 console.info('Succeeded in putting batch'); 6625 }).catch((err) => { 6626 console.error(`Failed to put batch.code is ${err.code},message is ${err.message}`); 6627 }); 6628 var query = new distributedKVStore.Query(); 6629 query.prefixKey("batch_test"); 6630 kvStore.getResultSize('localDeviceId', query).then((resultSize) => { 6631 console.info('Succeeded in getting resultSize'); 6632 }).catch((err) => { 6633 console.error(`Failed to get resultSize.code is ${err.code},message is ${err.message}`); 6634 }); 6635} catch (e) { 6636 console.error(`Failed to get resultSize.code is ${e.code},message is ${e.message}`); 6637} 6638``` 6639