1# @ohos.data.distributedKVStore (Distributed KV Store) (System API) 2 3The **distributedKVStore** module implements collaboration between databases for different devices that forms a Super Device. You can use the APIs provided by this module to save application data to a distributed key-value (KV) store and perform operations, such as adding, deleting, modifying, querying, and synchronizing data in distributed KV stores. 4 5The **distributedKVStore** module provides the following functionalities: 6 7- [KVManager](js-apis-distributedKVStore.md#kvmanager): provides a **KVManager** instance to obtain KV store information. 8- [KVStoreResultSet](js-apis-distributedKVStore.md#kvstoreresultset): provides APIs for accessing the results obtained from a KV store. 9- [Query](js-apis-distributedKVStore.md#query): provides APIs for setting predicates for data query. 10- [SingleKVStore](#singlekvstore): provides APIs for querying and synchronizing data in single KV stores. The single KV stores manage data without distinguishing devices. 11- [DeviceKVStore](#devicekvstore): provides APIs for querying and synchronizing data in device KV stores. This class inherits from [SingleKVStore](#singlekvstore). The device KV stores manage data by device. 12 13> **NOTE** 14> 15> - The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. 16> 17> - This topic describes only the system APIs provided by the module. For details about its public APIs, see [@ohos.data.distributedKVStore](js-apis-distributedKVStore.md). 18 19## Modules to Import 20 21```ts 22import { distributedKVStore } from '@kit.ArkData'; 23``` 24 25## SingleKVStore 26 27Implements data management in a single KV store, such as adding data, deleting data, and subscribing to data changes or data sync completion. 28 29Before calling **SingleKVStore** APIs, you need to use [getKVStore](js-apis-distributedKVStore.md#getkvstore) to create a **SingleKVStore** instance. 30 31### putBatch 32 33putBatch(value: Array<ValuesBucket>, callback: AsyncCallback<void>): void 34 35Writes batch data to this single KV store. This API uses an asynchronous callback to return the result. 36 37**Model restriction**: This API can be used only in the stage model. 38 39**System API**: This is a system API. 40 41**System capability**: SystemCapability.DistributedDataManager.KVStore.Core 42 43**Parameters** 44 45| Name | Type | Mandatory| Description | 46| -------- | ------------------------------------------------------------ | ---- | ------------------ | 47| value | Array<[ValuesBucket](js-apis-data-valuesBucket.md#valuesbucket)> | Yes | Data to write.| 48| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 49 50**Error codes** 51 52For details about the error codes, see [Distributed KV Store Error Codes](errorcode-distributedKVStore.md) and [Universal Error Codes](../errorcode-universal.md). 53 54| ID| **Error Message** | 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 61For details about the error codes, see [RDB Error Codes](errorcode-data-rdb.md). 62 63| ID| **Error Message** | 64| ------------ | -------------------------------------------- | 65| 14800047 | The WAL file size exceeds the default limit. | 66 67**Example** 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 95Writes batch data to this single KV store. This API uses a promise to return the result. 96 97**Model restriction**: This API can be used only in the stage model. 98 99**System API**: This is a system API. 100 101**System capability**: SystemCapability.DistributedDataManager.KVStore.Core 102 103**Parameters** 104 105| Name| Type | Mandatory| Description | 106| ------ | ------------------------------------------------------------ | ---- | ------------------ | 107| value | Array<[ValuesBucket](js-apis-data-valuesBucket.md#valuesbucket)> | Yes | Data to write.| 108 109**Return value** 110 111| Type | Description | 112| ------------------- | ------------------------- | 113| Promise<void> | Promise that returns no value.| 114 115**Error codes** 116 117For details about the error codes, see [Distributed KV Store Error Codes](errorcode-distributedKVStore.md) and [Universal Error Codes](../errorcode-universal.md). 118 119| ID| **Error Message** | 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 126For details about the error codes, see [RDB Error Codes](errorcode-data-rdb.md). 127 128| ID| **Error Message** | 129| ------------ | -------------------------------------------- | 130| 14800047 | The WAL file size exceeds the default limit. | 131 132**Example** 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 158Deletes KV pairs from this KV store. This API uses an asynchronous callback to return the result. 159 160**Model restriction**: This API can be used only in the stage model. 161 162**System API**: This is a system API. 163 164**System capability**: SystemCapability.DistributedDataManager.DataShare.Provider 165 166**Parameters** 167 168| Name | Type | Mandatory| Description | 169| ---------- | ------------------------------------------------------------ | ---- | ----------------------------------------------- | 170| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | Yes | **DataSharePredicates** object that specifies the KV pairs to delete. If this parameter is **null**, define the processing logic.| 171| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 172 173**Error codes** 174 175For details about the error codes, see [Distributed KV Store Error Codes](errorcode-distributedKVStore.md) and [Universal Error Codes](../errorcode-universal.md). 176 177| ID| **Error Message** | 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 184For details about the error codes, see [RDB Error Codes](errorcode-data-rdb.md). 185 186| ID| **Error Message** | 187| ------------ | -------------------------------------------- | 188| 14800047 | The WAL file size exceeds the default limit. | 189 190**Example** 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 226Deletes KV pairs from this KV store. This API uses a promise to return the result. 227 228**Model restriction**: This API can be used only in the stage model. 229 230**System API**: This is a system API. 231 232**System capability**: SystemCapability.DistributedDataManager.DataShare.Provider 233 234**Parameters** 235 236| Name | Type | Mandatory| Description | 237| ---------- | ------------------------------------------------------------ | ---- | ----------------------------------------------- | 238| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | Yes | **DataSharePredicates** object that specifies the KV pairs to delete. If this parameter is **null**, define the processing logic.| 239 240**Return value** 241 242| Type | Description | 243| ------------------- | ------------------------- | 244| Promise<void> | Promise that returns no value.| 245 246**Error codes** 247 248For details about the error codes, see [Distributed KV Store Error Codes](errorcode-distributedKVStore.md) and [Universal Error Codes](../errorcode-universal.md). 249 250| ID| **Error Message** | 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 257For details about the error codes, see [RDB Error Codes](errorcode-data-rdb.md). 258 259| ID| **Error Message** | 260| ------------ | -------------------------------------------- | 261| 14800047 | The WAL file size exceeds the default limit. | 262 263**Example** 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 295Obtains a **KVStoreResultSet** object that matches the specified conditions. This API uses an asynchronous callback to return the result. 296 297**Model restriction**: This API can be used only in the stage model. 298 299**System API**: This is a system API. 300 301**System capability**: SystemCapability.DistributedDataManager.DataShare.Provider 302 303**Parameters** 304 305| Name | Type | Mandatory| Description | 306| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 307| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | Yes | **DataSharePredicates** object that specifies the **KVStoreResultSet** object to obtain. If this parameter is **null**, define the processing logic. | 308| callback | AsyncCallback<[KVStoreResultSet](js-apis-distributedKVStore.md#kvstoreresultset)> | Yes | Callback used to return the **KVStoreResultSet** object obtained.| 309 310**Error codes** 311 312For details about the error codes, see [Distributed KV Store Error Codes](errorcode-distributedKVStore.md) and [Universal Error Codes](../errorcode-universal.md). 313 314| ID| **Error Message** | 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 | Over max limits. | 319| 15100003 | Database corrupted. | 320| 15100005 | Database or result set already closed. | 321 322**Example** 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 359Obtains a **KVStoreResultSet** object that matches the specified conditions. This API uses a promise to return the result. 360 361**Model restriction**: This API can be used only in the stage model. 362 363**System API**: This is a system API. 364 365**System capability**: SystemCapability.DistributedDataManager.DataShare.Provider 366 367**Parameters** 368 369| Name | Type | Mandatory| Description | 370| ---------- | ------------------------------------------------------------ | ---- | ----------------------------------------------- | 371| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | Yes | **DataSharePredicates** object that specifies the **KVStoreResultSet** object to obtain. If this parameter is **null**, define the processing logic.| 372 373**Return value** 374 375| Type | Description | 376| ---------------------------------------------------- | ------------------------- | 377| Promise<[KVStoreResultSet](js-apis-distributedKVStore.md#kvstoreresultset)> | Promise used to return the **KVStoreResultSet** object obtained.| 378 379**Error codes** 380 381For details about the error codes, see [Distributed KV Store Error Codes](errorcode-distributedKVStore.md) and [Universal Error Codes](../errorcode-universal.md). 382 383| ID| **Error Message** | 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 | Over max limits. | 388| 15100003 | Database corrupted. | 389| 15100005 | Database or result set already closed. | 390 391**Example** 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 423Provides APIs for querying and synchronizing data in a device KV store. This class inherits from **SingleKVStore**. 424 425Data is distinguished by device in a device KV store. Each device can only write and modify its own data. Data of other devices is read-only and cannot be modified. 426 427For example, a device KV store can be used to implement image sharing between devices. The images of other devices can be viewed, but not be modified or deleted. 428 429Before calling **DeviceKVStore** APIs, you need to use [getKVStore](js-apis-distributedKVStore.md#getkvstore) to create a **DeviceKVStore** instance. 430 431### getResultSet 432 433getResultSet(predicates: dataSharePredicates.DataSharePredicates, callback: AsyncCallback<KVStoreResultSet>): void 434 435Obtains a **KVStoreResultSet** object that matches the specified conditions for this device. This API uses an asynchronous callback to return the result. 436 437**Model restriction**: This API can be used only in the stage model. 438 439**System API**: This is a system API. 440 441**System capability**: SystemCapability.DistributedDataManager.DataShare.Provider 442 443**Parameters** 444 445| Name | Type | Mandatory| Description | 446| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 447| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | Yes | **DataSharePredicates** object that specifies the **KVStoreResultSet** object to obtain. If this parameter is **null**, define the processing logic. | 448| callback | AsyncCallback<[KVStoreResultSet](js-apis-distributedKVStore.md#kvstoreresultset)> | Yes | Callback used to return the **KVStoreResultSet** object obtained.| 449 450**Error codes** 451 452For details about the error codes, see [Distributed KV Store Error Codes](errorcode-distributedKVStore.md) and [Universal Error Codes](../errorcode-universal.md). 453 454| ID| **Error Message** | 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 | Over max limits. | 459| 15100003 | Database corrupted. | 460| 15100005 | Database or result set already closed. | 461 462**Example** 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 499Obtains a **KVStoreResultSet** object that matches the specified conditions for this device. This API uses a promise to return the result. 500 501**Model restriction**: This API can be used only in the stage model. 502 503**System API**: This is a system API. 504 505**System capability**: SystemCapability.DistributedDataManager.DataShare.Provider 506 507**Parameters** 508 509| Name | Type | Mandatory| Description | 510| ---------- | ------------------------------------------------------------ | ---- | ----------------------------------------------- | 511| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | Yes | **DataSharePredicates** object that specifies the **KVStoreResultSet** object to obtain. If this parameter is **null**, define the processing logic. | 512 513**Return value** 514 515| Type | Description | 516| ---------------------------------------------------- | ------------------------- | 517| Promise<[KVStoreResultSet](js-apis-distributedKVStore.md#kvstoreresultset)> | Promise used to return the **KVStoreResultSet** object obtained.| 518 519**Error codes** 520 521For details about the error codes, see [Distributed KV Store Error Codes](errorcode-distributedKVStore.md) and [Universal Error Codes](../errorcode-universal.md). 522 523| ID| **Error Message** | 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 | Over max limits. | 528| 15100003 | Database corrupted. | 529| 15100005 | Database or result set already closed. | 530 531**Example** 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 564Obtains a **KVStoreResultSet** object that matches the specified conditions for a device. This API uses an asynchronous callback to return the result. 565> **NOTE** 566> 567> **deviceId** can be obtained by [deviceManager.getAvailableDeviceListSync](../apis-distributedservice-kit/js-apis-distributedDeviceManager.md#getavailabledevicelistsync). 568> For details about how to obtain **deviceId**, see the example of [sync](js-apis-distributedKVStore.md#sync). 569 570**Model restriction**: This API can be used only in the stage model. 571 572**System API**: This is a system API. 573 574**System capability**: SystemCapability.DistributedDataManager.DataShare.Provider 575 576**Parameters** 577 578| Name | Type | Mandatory| Description | 579| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 580| deviceId | string | Yes | ID of the target device. | 581| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | Yes | **DataSharePredicates** object that specifies the **KVStoreResultSet** object to obtain. If this parameter is **null**, define the processing logic. | 582| callback | AsyncCallback<[KVStoreResultSet](js-apis-distributedKVStore.md#kvstoreresultset)> | Yes | Callback used to return the **KVStoreResultSet** object obtained.| 583 584**Error codes** 585 586For details about the error codes, see [Distributed KV Store Error Codes](errorcode-distributedKVStore.md) and [Universal Error Codes](../errorcode-universal.md). 587 588| ID| **Error Message** | 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 | Over max limits. | 593| 15100003 | Database corrupted. | 594| 15100005 | Database or result set already closed. | 595 596**Example** 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 633Obtains a **KVStoreResultSet** object that matches the specified conditions for a device. This API uses a promise to return the result. 634> **NOTE** 635> 636> **deviceId** can be obtained by [deviceManager.getAvailableDeviceListSync](../apis-distributedservice-kit/js-apis-distributedDeviceManager.md#getavailabledevicelistsync). 637> For details about how to obtain **deviceId**, see the example of [sync](js-apis-distributedKVStore.md#sync). 638 639**Model restriction**: This API can be used only in the stage model. 640 641**System API**: This is a system API. 642 643**System capability**: SystemCapability.DistributedDataManager.DataShare.Provider 644 645**Parameters** 646 647| Name | Type | Mandatory| Description | 648| ---------- | ------------------------------------------------------------ | ---- | ----------------------------------------------- | 649| deviceId | string | Yes | ID of the target device. | 650| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | Yes | **DataSharePredicates** object that specifies the **KVStoreResultSet** object to obtain. If this parameter is **null**, define the processing logic. | 651 652**Return value** 653 654| Type | Description | 655| ---------------------------------------------------- | ------------------------- | 656| Promise<[KVStoreResultSet](js-apis-distributedKVStore.md#kvstoreresultset)> | Promise used to return the **KVStoreResultSet** object obtained.| 657 658**Error codes** 659 660For details about the error codes, see [Distributed KV Store Error Codes](errorcode-distributedKVStore.md) and [Universal Error Codes](../errorcode-universal.md). 661 662| ID| **Error Message** | 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 | Over max limits. | 667| 15100003 | Database corrupted. | 668| 15100005 | Database or result set already closed. | 669 670**Example** 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``` 698