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