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