1# @ohos.data.distributedKVStore (分布式键值数据库)(系统接口) 2<!--Kit: ArkData--> 3<!--Subsystem: DistributedDataManager--> 4<!--Owner: @ding_dong_dong--> 5<!--Designer: @dboy190; @houpengtao1--> 6<!--Tester: @logic42--> 7<!--Adviser: @ge-yafang--> 8 9分布式键值数据库为应用程序提供不同设备间数据库的分布式协同能力。通过调用分布式键值数据库各个接口，应用程序可将数据保存到分布式键值数据库中，并可对分布式键值数据库中的数据进行增加、删除、修改、查询、同步等操作。 10 11该模块提供以下分布式键值数据库相关的常用功能： 12 13- [KVManager](js-apis-distributedKVStore.md#kvmanager)：分布式键值数据库管理实例，用于获取数据库的相关信息。 14- [KVStoreResultSet](js-apis-distributedKVStore.md#kvstoreresultset)：提供获取数据库结果集的相关方法，包括查询和移动数据读取位置等。 15- [Query](js-apis-distributedKVStore.md#query)：使用谓词表示数据库查询，提供创建Query实例、查询数据库中的数据和添加谓词的方法。 16- [SingleKVStore](#singlekvstore)：单版本分布式键值数据库，不对数据所属设备进行区分，提供查询数据和同步数据的方法。 17- [DeviceKVStore](#devicekvstore)：设备协同数据库，继承自[SingleKVStore](#singlekvstore)，以设备维度对数据进行区分，提供查询数据和同步数据的方法。 18 19> **说明：** 20> 21> - 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 22> 23> - 当前页面仅包含本模块的系统接口，其他公开接口参见[@ohos.data.distributedKVStore (分布式键值数据库)](js-apis-distributedKVStore.md)。 24 25## 导入模块 26 27```ts 28import { distributedKVStore } from '@kit.ArkData'; 29``` 30 31## SingleKVStore 32 33SingleKVStore数据库实例，提供增加数据、删除数据和订阅数据变更、订阅数据同步完成的方法。 34 35在调用SingleKVStore的方法前，需要先通过[getKVStore](js-apis-distributedKVStore.md#getkvstore)构建一个SingleKVStore实例。 36 37### putBatch 38 39putBatch(value: Array<ValuesBucket>, callback: AsyncCallback<void>): void 40 41将值写入SingleKVStore数据库，使用callback异步回调。 42 43**模型约束：** 此接口仅可在Stage模型下使用。 44 45**系统接口：** 此接口为系统接口。 46 47**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 48 49**参数：** 50 51| 参数名 | 类型 | 必填 | 说明 | 52| -------- | ------------------------------------------------------------ | ---- | ------------------ | 53| value | Array<[ValuesBucket](js-apis-data-valuesBucket.md#valuesbucket)> | 是 | 表示要插入的数据。 | 54| callback | AsyncCallback<void> | 是 | 回调函数。 | 55 56**错误码：** 57 58以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)和[通用错误码](../errorcode-universal.md)。 59 60| **错误码ID** | **错误信息** | 61| ------------ | ---------------------------------------- | 62| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified; 2.Incorrect parameters types.| 63| 202 | Permission verification failed, application which is not a system application uses system API.| 64| 15100003 | Database corrupted. | 65| 15100005 | Database or result set already closed. | 66 67以下错误码的详细介绍请参见[关系型数据库错误码](errorcode-data-rdb.md)。 68 69| **错误码ID** | **错误信息** | 70| ------------ | -------------------------------------------- | 71| 14800047 | The WAL file size exceeds the default limit. | 72 73**示例：** 74 75```ts 76import { BusinessError } from '@kit.BasicServicesKit'; 77import { ValuesBucket } from '@kit.ArkData'; 78 79try { 80 let bucket1: ValuesBucket = {key:"name", value: "LiSi"}; 81 let bucket2: ValuesBucket = {key:"age", value: 20}; 82 let bucket3: ValuesBucket = {key:"deposits", value: 12.34}; 83 let people: Array<ValuesBucket> = new Array(bucket1, bucket2, bucket3); 84 kvStore.putBatch(people, (err: BusinessError) => { 85 if (err != undefined) { 86 console.error(`Failed to put batch.code is ${err.code},message is ${err.message}`); 87 return; 88 } 89 console.info('Succeeded in putting batch'); 90 }) 91} catch (e) { 92 let error = e as BusinessError; 93 console.error(`Failed to do putBatch error.code is ${error.code},message is ${error.message}`); 94} 95``` 96 97### putBatch 98 99putBatch(value: Array<ValuesBucket>): Promise<void> 100 101将valuesbucket类型的值写入SingleKVStore数据库，使用Promise异步回调。 102 103**模型约束：** 此接口仅可在Stage模型下使用。 104 105**系统接口：** 此接口为系统接口。 106 107**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 108 109**参数：** 110 111| 参数名 | 类型 | 必填 | 说明 | 112| ------ | ------------------------------------------------------------ | ---- | ------------------ | 113| value | Array<[ValuesBucket](js-apis-data-valuesBucket.md#valuesbucket)> | 是 | 表示要插入的数据。 | 114 115**返回值：** 116 117| 类型 | 说明 | 118| ------------------- | ------------------------- | 119| Promise<void> | 无返回结果的Promise对象。 | 120 121**错误码：** 122 123以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)和[通用错误码](../errorcode-universal.md)。 124 125| **错误码ID** | **错误信息** | 126| ------------ | ---------------------------------------- | 127| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified; 2.Incorrect parameters types.| 128| 202 | Permission verification failed, application which is not a system application uses system API.| 129| 15100003 | Database corrupted. | 130| 15100005 | Database or result set already closed. | 131 132以下错误码的详细介绍请参见[关系型数据库错误码](errorcode-data-rdb.md)。 133 134| **错误码ID** | **错误信息** | 135| ------------ | -------------------------------------------- | 136| 14800047 | The WAL file size exceeds the default limit. | 137 138**示例：** 139 140```ts 141import { BusinessError } from '@kit.BasicServicesKit'; 142import { ValuesBucket } from '@kit.ArkData'; 143 144try { 145 let bucket1: ValuesBucket = {key:"name", value: "LiSi"}; 146 let bucket2: ValuesBucket = {key:"age", value: 20}; 147 let bucket3: ValuesBucket = {key:"deposits", value: 12.34}; 148 let people: Array<ValuesBucket> = new Array(bucket1, bucket2, bucket3); 149 kvStore.putBatch(people).then(() => { 150 console.info(`Succeeded in putting patch`); 151 }).catch((err: BusinessError) => { 152 console.error(`Failed to do putBatch error.code is ${err.code},message is ${err.message}`); 153 }); 154} catch (e) { 155 let error = e as BusinessError; 156 console.error(`Failed to do putBatch error.code is ${error.code},message is ${error.message}`); 157} 158``` 159 160### delete 161 162delete(predicates: dataSharePredicates.DataSharePredicates, callback: AsyncCallback<void>): void 163 164从数据库中删除符合predicates条件的键值对，使用callback异步回调。 165 166**模型约束：** 此接口仅可在Stage模型下使用。 167 168**系统接口：** 此接口为系统接口。 169 170**系统能力：** SystemCapability.DistributedDataManager.DataShare.Provider 171 172**参数：** 173 174| 参数名 | 类型 | 必填 | 说明 | 175| ---------- | ------------------------------------------------------------ | ---- | ----------------------------------------------- | 176| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | 是 | 指示筛选条件，当此参数为null时，应定义处理逻辑。 | 177| callback | AsyncCallback<void> | 是 | 回调函数。 | 178 179**错误码：** 180 181以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)和[通用错误码](../errorcode-universal.md)。 182 183| **错误码ID** | **错误信息** | 184| ------------ | -------------------------------------- | 185| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified; 2.Incorrect parameters types.| 186| 202 | Permission verification failed, application which is not a system application uses system API.| 187| 15100003 | Database corrupted. | 188| 15100005 | Database or result set already closed. | 189 190以下错误码的详细介绍请参见[关系型数据库错误码](errorcode-data-rdb.md)。 191 192| **错误码ID** | **错误信息** | 193| ------------ | -------------------------------------------- | 194| 14800047 | The WAL file size exceeds the default limit. | 195 196**示例：** 197 198```ts 199import { dataSharePredicates } from '@kit.ArkData'; 200import { BusinessError } from '@kit.BasicServicesKit'; 201 202try { 203 let predicates = new dataSharePredicates.DataSharePredicates(); 204 let arr = ["name"]; 205 predicates.inKeys(arr); 206 kvStore.put("name", "bob", (err:BusinessError) => { 207 if (err != undefined) { 208 console.error(`Failed to put.code is ${err.code},message is ${err.message}`); 209 return; 210 } 211 console.info("Succeeded in putting"); 212 if (kvStore != null) { 213 kvStore.delete(predicates, (err:BusinessError) => { 214 if (err == undefined) { 215 console.info('Succeeded in deleting'); 216 } else { 217 console.error(`Failed to delete.code is ${err.code},message is ${err.message}`); 218 } 219 }); 220 } 221 }); 222} catch (e) { 223 let error = e as BusinessError; 224 console.error(`An unexpected error occurred.code is ${error.code},message is ${error.message}`); 225} 226``` 227 228### delete 229 230delete(predicates: dataSharePredicates.DataSharePredicates): Promise<void> 231 232从数据库中删除符合predicates条件的键值对，使用Promise异步回调。 233 234**模型约束：** 此接口仅可在Stage模型下使用。 235 236**系统接口：** 此接口为系统接口。 237 238**系统能力：** SystemCapability.DistributedDataManager.DataShare.Provider 239 240**参数：** 241 242| 参数名 | 类型 | 必填 | 说明 | 243| ---------- | ------------------------------------------------------------ | ---- | ----------------------------------------------- | 244| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | 是 | 指示筛选条件，当此参数为null时，应定义处理逻辑。 | 245 246**返回值：** 247 248| 类型 | 说明 | 249| ------------------- | ------------------------- | 250| Promise<void> | 无返回结果的Promise对象。 | 251 252**错误码：** 253 254以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)和[通用错误码](../errorcode-universal.md)。 255 256| **错误码ID** | **错误信息** | 257| ------------ | ---------------------------------------- | 258| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified; 2.Incorrect parameters types.| 259| 202 | Permission verification failed, application which is not a system application uses system API.| 260| 15100003 | Database corrupted. | 261| 15100005 | Database or result set already closed. | 262 263以下错误码的详细介绍请参见[关系型数据库错误码](errorcode-data-rdb.md)。 264 265| **错误码ID** | **错误信息** | 266| ------------ | -------------------------------------------- | 267| 14800047 | The WAL file size exceeds the default limit. | 268 269**示例：** 270 271```ts 272import { dataSharePredicates } from '@kit.ArkData'; 273import { BusinessError } from '@kit.BasicServicesKit'; 274 275try { 276 let predicates = new dataSharePredicates.DataSharePredicates(); 277 let arr = ["name"]; 278 predicates.inKeys(arr); 279 kvStore.put("name", "bob").then(() => { 280 console.info(`Succeeded in putting data`); 281 if (kvStore != null) { 282 kvStore.delete(predicates).then(() => { 283 console.info('Succeeded in deleting'); 284 }).catch((err: BusinessError) => { 285 console.error(`Failed to delete.code is ${err.code},message is ${err.message}`); 286 }); 287 } 288 }).catch((err: BusinessError) => { 289 console.error(`Failed to put.code is ${err.code},message is ${err.message}`); 290 }); 291} catch (e) { 292 let error = e as BusinessError; 293 console.error(`An unexpected error occurred.code is ${error.code},message is ${error.message}`); 294} 295``` 296 297### getResultSet 298 299getResultSet(predicates: dataSharePredicates.DataSharePredicates, callback: AsyncCallback<KVStoreResultSet>): void 300 301获取与指定Predicate对象匹配的KVStoreResultSet对象，使用callback异步回调。 302 303**模型约束：** 此接口仅可在Stage模型下使用。 304 305**系统接口：** 此接口为系统接口。 306 307**系统能力：** SystemCapability.DistributedDataManager.DataShare.Provider 308 309**参数：** 310 311| 参数名 | 类型 | 必填 | 说明 | 312| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 313| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | 是 | 指示筛选条件，当此参数为null时，应定义处理逻辑。 | 314| callback | AsyncCallback<[KVStoreResultSet](js-apis-distributedKVStore.md#kvstoreresultset)> | 是 | 回调函数，获取与指定Predicates对象匹配的KVStoreResultSet对象。 | 315 316**错误码：** 317 318以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)和[通用错误码](../errorcode-universal.md)。 319 320| **错误码ID** | **错误信息** | 321| ------------ | -------------------------------------- | 322| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified; 2.Incorrect parameters types.| 323| 202 | Permission verification failed, application which is not a system application uses system API.| 324| 15100001 | Over max limits. | 325| 15100003 | Database corrupted. | 326| 15100005 | Database or result set already closed. | 327 328**示例：** 329 330```ts 331import { dataSharePredicates } from '@kit.ArkData'; 332import { BusinessError } from '@kit.BasicServicesKit'; 333 334try { 335 let resultSet: distributedKVStore.KVStoreResultSet; 336 let predicates = new dataSharePredicates.DataSharePredicates(); 337 predicates.prefixKey("batch_test_string_key"); 338 kvStore.getResultSet(predicates, async (err: BusinessError, result: distributedKVStore.KVStoreResultSet) => { 339 if (err != undefined) { 340 console.error(`Failed to get resultset.code is ${err.code},message is ${err.message}`); 341 return; 342 } 343 console.info('Succeeded in getting result set'); 344 resultSet = result; 345 if (kvStore != null) { 346 kvStore.closeResultSet(resultSet, (err: BusinessError) => { 347 if (err != undefined) { 348 console.error(`Failed to close resultset.code is ${err.code},message is ${err.message}`); 349 return; 350 } 351 console.info('Succeeded in closing result set'); 352 }); 353 } 354 }); 355} catch (e) { 356 let error = e as BusinessError; 357 console.error(`An unexpected error occurred. Code is ${error.code},message is ${error.message}`); 358} 359``` 360 361### getResultSet 362 363getResultSet(predicates: dataSharePredicates.DataSharePredicates): Promise<KVStoreResultSet> 364 365获取与指定Predicate对象匹配的KVStoreResultSet对象，使用Promise异步回调。 366 367**模型约束：** 此接口仅可在Stage模型下使用。 368 369**系统接口：** 此接口为系统接口。 370 371**系统能力：** SystemCapability.DistributedDataManager.DataShare.Provider 372 373**参数：** 374 375| 参数名 | 类型 | 必填 | 说明 | 376| ---------- | ------------------------------------------------------------ | ---- | ----------------------------------------------- | 377| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | 是 | 指示筛选条件，当此参数为null时，应定义处理逻辑。 | 378 379**返回值：** 380 381| 类型 | 说明 | 382| ---------------------------------------------------- | ------------------------- | 383| Promise<[KVStoreResultSet](js-apis-distributedKVStore.md#kvstoreresultset)> | 无返回结果的Promise对象。 | 384 385**错误码：** 386 387以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)和[通用错误码](../errorcode-universal.md)。 388 389| **错误码ID** | **错误信息** | 390| ------------ | -------------------------------------- | 391| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified; 2.Incorrect parameters types.| 392| 202 | Permission verification failed, application which is not a system application uses system API.| 393| 15100001 | Over max limits. | 394| 15100003 | Database corrupted. | 395| 15100005 | Database or result set already closed. | 396 397**示例：** 398 399```ts 400import { dataSharePredicates } from '@kit.ArkData'; 401import { BusinessError } from '@kit.BasicServicesKit'; 402 403try { 404 let resultSet: distributedKVStore.KVStoreResultSet; 405 let predicates = new dataSharePredicates.DataSharePredicates(); 406 predicates.prefixKey("batch_test_string_key"); 407 kvStore.getResultSet(predicates).then((result: distributedKVStore.KVStoreResultSet) => { 408 console.info('Succeeded in getting result set'); 409 resultSet = result; 410 if (kvStore != null) { 411 kvStore.closeResultSet(resultSet).then(() => { 412 console.info('Succeeded in closing result set'); 413 }).catch((err: BusinessError) => { 414 console.error(`Failed to close resultset.code is ${err.code},message is ${err.message}`); 415 }); 416 } 417 }).catch((err: BusinessError) => { 418 console.error(`Failed to get resultset.code is ${err.code},message is ${err.message}`); 419 }); 420 421} catch (e) { 422 let error = e as BusinessError; 423 console.error(`An unexpected error occurred.code is ${error.code},message is ${error.message}`); 424} 425``` 426 427## DeviceKVStore 428 429设备协同数据库，继承自SingleKVStore，提供查询数据和同步数据的方法。 430 431设备协同数据库，以设备维度对数据进行区分，每台设备仅能写入和修改本设备的数据，其它设备的数据对其是只读的，无法修改其它设备的数据。 432 433比如，可以使用设备协同数据库实现设备间的图片分享，可以查看其他设备的图片，但无法修改和删除其他设备的图片。 434 435在调用DeviceKVStore的方法前，需要先通过[getKVStore](js-apis-distributedKVStore.md#getkvstore)构建一个DeviceKVStore实例。 436 437### getResultSet 438 439getResultSet(predicates: dataSharePredicates.DataSharePredicates, callback: AsyncCallback<KVStoreResultSet>): void 440 441获取与本设备指定Predicate对象匹配的KVStoreResultSet对象，使用callback异步回调。 442 443**模型约束：** 此接口仅可在Stage模型下使用。 444 445**系统接口：** 此接口为系统接口。 446 447**系统能力：** SystemCapability.DistributedDataManager.DataShare.Provider 448 449**参数：** 450 451| 参数名 | 类型 | 必填 | 说明 | 452| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 453| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | 是 | 指示筛选条件，当此参数为null时，应定义处理逻辑。 | 454| callback | AsyncCallback<[KVStoreResultSet](js-apis-distributedKVStore.md#kvstoreresultset)> | 是 | 回调函数，获取与指定Predicates对象匹配的KVStoreResultSet对象。 | 455 456**错误码：** 457 458以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)和[通用错误码](../errorcode-universal.md)。 459 460| **错误码ID** | **错误信息** | 461| ------------ | -------------------------------------- | 462| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified; 2.Incorrect parameters types.| 463| 202 | Permission verification failed, application which is not a system application uses system API.| 464| 15100001 | Over max limits. | 465| 15100003 | Database corrupted. | 466| 15100005 | Database or result set already closed. | 467 468**示例：** 469 470```ts 471import { dataSharePredicates } from '@kit.ArkData'; 472import { BusinessError } from '@kit.BasicServicesKit'; 473 474try { 475 let resultSet: distributedKVStore.KVStoreResultSet; 476 let predicates = new dataSharePredicates.DataSharePredicates(); 477 predicates.prefixKey("batch_test_string_key"); 478 kvStore.getResultSet(predicates, async (err: BusinessError, result: distributedKVStore.KVStoreResultSet) => { 479 if (err != undefined) { 480 console.error(`Failed to get resultset.code is ${err.code},message is ${err.message}`); 481 return; 482 } 483 console.info('Succeeded in getting result set'); 484 resultSet = result; 485 if (kvStore != null) { 486 kvStore.closeResultSet(resultSet, (err: BusinessError) => { 487 if (err != undefined) { 488 console.error(`Failed to close resultset.code is ${err.code},message is ${err.message}`); 489 return; 490 } 491 console.info('Succeeded in closing result set'); 492 }) 493 } 494 }); 495} catch (e) { 496 let error = e as BusinessError; 497 console.error(`An unexpected error occurred.code is ${error.code},message is ${error.message}`); 498} 499``` 500 501### getResultSet 502 503getResultSet(predicates: dataSharePredicates.DataSharePredicates): Promise<KVStoreResultSet> 504 505获取与本设备指定Predicate对象匹配的KVStoreResultSet对象，使用Promise异步回调。 506 507**模型约束：** 此接口仅可在Stage模型下使用。 508 509**系统接口：** 此接口为系统接口。 510 511**系统能力：** SystemCapability.DistributedDataManager.DataShare.Provider 512 513**参数：** 514 515| 参数名 | 类型 | 必填 | 说明 | 516| ---------- | ------------------------------------------------------------ | ---- | ----------------------------------------------- | 517| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | 是 | 指示筛选条件，当此参数为null时，应定义处理逻辑。 | 518 519**返回值：** 520 521| 类型 | 说明 | 522| ---------------------------------------------------- | ------------------------- | 523| Promise<[KVStoreResultSet](js-apis-distributedKVStore.md#kvstoreresultset)> | 无返回结果的Promise对象。 | 524 525**错误码：** 526 527以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)和[通用错误码](../errorcode-universal.md)。 528 529| **错误码ID** | **错误信息** | 530| ------------ | -------------------------------------- | 531| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified; 2.Incorrect parameters types.| 532| 202 | Permission verification failed, application which is not a system application uses system API.| 533| 15100001 | Over max limits. | 534| 15100003 | Database corrupted. | 535| 15100005 | Database or result set already closed. | 536 537**示例：** 538 539```ts 540import { dataSharePredicates } from '@kit.ArkData'; 541import { BusinessError } from '@kit.BasicServicesKit'; 542 543try { 544 let resultSet: distributedKVStore.KVStoreResultSet; 545 let predicates = new dataSharePredicates.DataSharePredicates(); 546 predicates.prefixKey("batch_test_string_key"); 547 kvStore.getResultSet(predicates).then((result: distributedKVStore.KVStoreResultSet) => { 548 console.info('Succeeded in getting result set'); 549 resultSet = result; 550 if (kvStore != null) { 551 kvStore.closeResultSet(resultSet).then(() => { 552 console.info('Succeeded in closing result set'); 553 }).catch((err: BusinessError) => { 554 console.error(`Failed to close resultset.code is ${err.code},message is ${err.message}`); 555 }); 556 } 557 }).catch((err: BusinessError) => { 558 console.error(`Failed to get resultset.code is ${err.code},message is ${err.message}`); 559 }); 560} catch (e) { 561 let error = e as BusinessError; 562 console.error(`An unexpected error occurred.code is ${error.code},message is ${error.message}`); 563} 564``` 565 566### getResultSet 567 568getResultSet(deviceId: string, predicates: dataSharePredicates.DataSharePredicates, callback: AsyncCallback<KVStoreResultSet>): void 569 570获取与指定Predicate对象匹配的KVStoreResultSet对象，使用callback异步回调。 571> **说明：** 572> 573> 其中deviceId通过调用[deviceManager.getAvailableDeviceListSync](../apis-distributedservice-kit/js-apis-distributedDeviceManager.md#getavailabledevicelistsync)方法得到。 574> deviceId具体获取方式请参考[sync接口示例](js-apis-distributedKVStore.md#sync)。 575 576**模型约束：** 此接口仅可在Stage模型下使用。 577 578**系统接口：** 此接口为系统接口。 579 580**系统能力：** SystemCapability.DistributedDataManager.DataShare.Provider 581 582**参数：** 583 584| 参数名 | 类型 | 必填 | 说明 | 585| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 586| deviceId | string | 是 | 标识要查询其数据的设备。 | 587| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | 是 | 指示筛选条件，当此参数为null时，应定义处理逻辑。 | 588| callback | AsyncCallback<[KVStoreResultSet](js-apis-distributedKVStore.md#kvstoreresultset)> | 是 | 回调函数，获取与指定Predicates对象匹配的KVStoreResultSet对象。 | 589 590**错误码：** 591 592以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)和[通用错误码](../errorcode-universal.md)。 593 594| **错误码ID** | **错误信息** | 595| ------------ | -------------------------------------- | 596| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified; 2.Incorrect parameters types.| 597| 202 | Permission verification failed, application which is not a system application uses system API.| 598| 15100001 | Over max limits. | 599| 15100003 | Database corrupted. | 600| 15100005 | Database or result set already closed. | 601 602**示例：** 603 604```ts 605import { dataSharePredicates } from '@kit.ArkData'; 606import { BusinessError } from '@kit.BasicServicesKit'; 607 608try { 609 let resultSet: distributedKVStore.KVStoreResultSet; 610 let predicates = new dataSharePredicates.DataSharePredicates(); 611 predicates.prefixKey("batch_test_string_key"); 612 kvStore.getResultSet('localDeviceId', predicates, async (err: BusinessError, result: distributedKVStore.KVStoreResultSet) => { 613 if (err != undefined) { 614 console.error(`Failed to get resultset.code is ${err.code},message is ${err.message}`); 615 return; 616 } 617 console.info('Succeeded in getting result set'); 618 resultSet = result; 619 if (kvStore != null) { 620 kvStore.closeResultSet(resultSet, (err: BusinessError) => { 621 if (err != undefined) { 622 console.error(`Failed to close resultset.code is ${err.code},message is ${err.message}`); 623 return; 624 } 625 console.info('Succeeded in closing result set'); 626 }) 627 } 628 }); 629} catch (e) { 630 let error = e as BusinessError; 631 console.error(`An unexpected error occurred.code is ${error.code},message is ${error.message}`); 632} 633``` 634 635### getResultSet 636 637getResultSet(deviceId: string, predicates: dataSharePredicates.DataSharePredicates): Promise<KVStoreResultSet> 638 639获取与指定Predicate对象匹配的KVStoreResultSet对象，使用Promise异步回调。 640> **说明：** 641> 642> 其中deviceId通过调用[deviceManager.getAvailableDeviceListSync](../apis-distributedservice-kit/js-apis-distributedDeviceManager.md#getavailabledevicelistsync)方法得到。 643> deviceId具体获取方式请参考[sync接口示例](js-apis-distributedKVStore.md#sync)。 644 645**模型约束：** 此接口仅可在Stage模型下使用。 646 647**系统接口：** 此接口为系统接口。 648 649**系统能力：** SystemCapability.DistributedDataManager.DataShare.Provider 650 651**参数：** 652 653| 参数名 | 类型 | 必填 | 说明 | 654| ---------- | ------------------------------------------------------------ | ---- | ----------------------------------------------- | 655| deviceId | string | 是 | 标识要查询其数据的设备。 | 656| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | 是 | 指示筛选条件，当此参数为null时，应定义处理逻辑。 | 657 658**返回值：** 659 660| 类型 | 说明 | 661| ---------------------------------------------------- | ------------------------- | 662| Promise<[KVStoreResultSet](js-apis-distributedKVStore.md#kvstoreresultset)> | 无返回结果的Promise对象。 | 663 664**错误码：** 665 666以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)和[通用错误码](../errorcode-universal.md)。 667 668| **错误码ID** | **错误信息** | 669| ------------ | -------------------------------------- | 670| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified; 2.Incorrect parameters types.| 671| 202 | Permission verification failed, application which is not a system application uses system API.| 672| 15100001 | Over max limits. | 673| 15100003 | Database corrupted. | 674| 15100005 | Database or result set already closed. | 675 676**示例：** 677 678```ts 679import { dataSharePredicates } from '@kit.ArkData'; 680import { BusinessError } from '@kit.BasicServicesKit'; 681 682try { 683 let resultSet: distributedKVStore.KVStoreResultSet; 684 let predicates = new dataSharePredicates.DataSharePredicates(); 685 predicates.prefixKey("batch_test_string_key"); 686 kvStore.getResultSet('localDeviceId', predicates).then((result: distributedKVStore.KVStoreResultSet) => { 687 console.info('Succeeded in getting result set'); 688 resultSet = result; 689 if (kvStore != null) { 690 kvStore.closeResultSet(resultSet).then(() => { 691 console.info('Succeeded in closing result set'); 692 }).catch((err: BusinessError) => { 693 console.error(`Failed to close resultset.code is ${err.code},message is ${err.message}`); 694 }); 695 } 696 }).catch((err: BusinessError) => { 697 console.error(`Failed to get resultset.code is ${err.code},message is ${err.message}`); 698 }); 699} catch (e) { 700 let error = e as BusinessError; 701 console.error(`An unexpected error occurred.code is ${error.code},message is ${error.message}`); 702} 703```