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). 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'; 71 72try { 73 let v8Arr: distributedKVStore.Entry[] = []; 74 let arr = new Uint8Array([4, 5, 6, 7]); 75 let vb1: distributedKVStore.Entry = { key: "name_1", value: {type: distributedKVStore.ValueType.INTEGER, value: 32} } 76 let vb2: distributedKVStore.Entry = { key: "name_2", value: {type: distributedKVStore.ValueType.BYTE_ARRAY, value: arr} }; 77 let vb3: distributedKVStore.Entry = { key: "name_3", value: {type: distributedKVStore.ValueType.STRING, value: "lisi"} }; 78 79 v8Arr.push(vb1); 80 v8Arr.push(vb2); 81 v8Arr.push(vb3); 82 kvStore.putBatch(v8Arr, async (err: BusinessError) => { 83 if (err != undefined) { 84 console.error(`Failed to put batch.code is ${err.code},message is ${err.message}`); 85 return; 86 } 87 console.info('Succeeded in putting batch'); 88 }) 89} catch (e) { 90 let error = e as BusinessError; 91 console.error(`Failed to put batch.code is ${error.code},message is ${error.message}`); 92} 93``` 94 95### putBatch 96 97putBatch(value: Array<ValuesBucket>): Promise<void> 98 99Writes batch data to this single KV store. This API uses a promise to return the result. 100 101**Model restriction**: This API can be used only in the stage model. 102 103**System API**: This is a system API. 104 105**System capability**: SystemCapability.DistributedDataManager.KVStore.Core 106 107**Parameters** 108 109| Name| Type | Mandatory| Description | 110| ------ | ------------------------------------------------------------ | ---- | ------------------ | 111| value | Array<[ValuesBucket](js-apis-data-valuesBucket.md#valuesbucket)> | Yes | Data to write.| 112 113**Return value** 114 115| Type | Description | 116| ------------------- | ------------------------- | 117| Promise<void> | Promise that returns no value.| 118 119**Error codes** 120 121For details about the error codes, see [Distributed KV Store Error Codes](errorcode-distributedKVStore.md). 122 123| ID| **Error Message** | 124| ------------ | ---------------------------------------- | 125| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified; 2.Incorrect parameters types.| 126| 202 | Permission verification failed, application which is not a system application uses system API.| 127| 15100003 | Database corrupted. | 128| 15100005 | Database or result set already closed. | 129 130For details about the error codes, see [RDB Error Codes](errorcode-data-rdb.md). 131 132| ID| **Error Message** | 133| ------------ | -------------------------------------------- | 134| 14800047 | The WAL file size exceeds the default limit. | 135 136**Example** 137 138```ts 139import { BusinessError } from '@kit.BasicServicesKit'; 140 141try { 142 let v8Arr: distributedKVStore.Entry[] = []; 143 let arr = new Uint8Array([4, 5, 6, 7]); 144 let vb1: distributedKVStore.Entry = { key: "name_1", value: {type: distributedKVStore.ValueType.INTEGER, value: 32} } 145 let vb2: distributedKVStore.Entry = { key: "name_2", value: {type: distributedKVStore.ValueType.BYTE_ARRAY, value: arr} }; 146 let vb3: distributedKVStore.Entry = { key: "name_3", value: {type: distributedKVStore.ValueType.STRING, value: "lisi"} }; 147 148 v8Arr.push(vb1); 149 v8Arr.push(vb2); 150 v8Arr.push(vb3); 151 kvStore.putBatch(v8Arr).then(async () => { 152 console.info(`Succeeded in putting patch`); 153 }).catch((err: BusinessError) => { 154 console.error(`putBatch fail.code is ${err.code},message is ${err.message}`); 155 }); 156} catch (e) { 157 let error = e as BusinessError; 158 console.error(`putBatch fail.code is ${error.code},message is ${error.message}`); 159} 160``` 161 162### delete 163 164delete(predicates: dataSharePredicates.DataSharePredicates, callback: AsyncCallback<void>) 165 166Deletes KV pairs from this KV store. This API uses an asynchronous callback to return the result. 167 168**Model restriction**: This API can be used only in the stage model. 169 170**System API**: This is a system API. 171 172**System capability**: SystemCapability.DistributedDataManager.DataShare.Provider 173 174**Parameters** 175 176| Name | Type | Mandatory| Description | 177| ---------- | ------------------------------------------------------------ | ---- | ----------------------------------------------- | 178| 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.| 179| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 180 181**Error codes** 182 183For details about the error codes, see [Distributed KV Store Error Codes](errorcode-distributedKVStore.md). 184 185| ID| **Error Message** | 186| ------------ | -------------------------------------- | 187| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified; 2.Incorrect parameters types.| 188| 202 | Permission verification failed, application which is not a system application uses system API.| 189| 15100003 | Database corrupted. | 190| 15100005 | Database or result set already closed. | 191 192For details about the error codes, see [RDB Error Codes](errorcode-data-rdb.md). 193 194| ID| **Error Message** | 195| ------------ | -------------------------------------------- | 196| 14800047 | The WAL file size exceeds the default limit. | 197 198**Example** 199 200```ts 201import { dataSharePredicates } from '@kit.ArkData'; 202import { BusinessError } from '@kit.BasicServicesKit'; 203 204try { 205 let predicates = new dataSharePredicates.DataSharePredicates(); 206 let arr = ["name"]; 207 predicates.inKeys(arr); 208 kvStore.put("name", "bob", (err:BusinessError) => { 209 if (err != undefined) { 210 console.error(`Failed to put.code is ${err.code},message is ${err.message}`); 211 return; 212 } 213 console.info("Succeeded in putting"); 214 if (kvStore != null) { 215 kvStore.delete(predicates, (err:BusinessError) => { 216 if (err == undefined) { 217 console.info('Succeeded in deleting'); 218 } else { 219 console.error(`Failed to delete.code is ${err.code},message is ${err.message}`); 220 } 221 }); 222 } 223 }); 224} catch (e) { 225 let error = e as BusinessError; 226 console.error(`An unexpected error occurred.code is ${error.code},message is ${error.message}`); 227} 228``` 229 230### delete 231 232delete(predicates: dataSharePredicates.DataSharePredicates): Promise<void> 233 234Deletes KV pairs from this KV store. This API uses a promise to return the result. 235 236**Model restriction**: This API can be used only in the stage model. 237 238**System API**: This is a system API. 239 240**System capability**: SystemCapability.DistributedDataManager.DataShare.Provider 241 242**Parameters** 243 244| Name | Type | Mandatory| Description | 245| ---------- | ------------------------------------------------------------ | ---- | ----------------------------------------------- | 246| 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.| 247 248**Return value** 249 250| Type | Description | 251| ------------------- | ------------------------- | 252| Promise<void> | Promise that returns no value.| 253 254**Error codes** 255 256For details about the error codes, see [Distributed KV Store Error Codes](errorcode-distributedKVStore.md). 257 258| ID| **Error Message** | 259| ------------ | ---------------------------------------- | 260| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified; 2.Incorrect parameters types.| 261| 202 | Permission verification failed, application which is not a system application uses system API.| 262| 15100003 | Database corrupted. | 263| 15100005 | Database or result set already closed. | 264 265For details about the error codes, see [RDB Error Codes](errorcode-data-rdb.md). 266 267| ID| **Error Message** | 268| ------------ | -------------------------------------------- | 269| 14800047 | The WAL file size exceeds the default limit. | 270 271**Example** 272 273```ts 274import { dataSharePredicates } from '@kit.ArkData'; 275import { BusinessError } from '@kit.BasicServicesKit'; 276 277try { 278 let predicates = new dataSharePredicates.DataSharePredicates(); 279 let arr = ["name"]; 280 predicates.inKeys(arr); 281 kvStore.put("name", "bob").then(() => { 282 console.info(`Succeeded in putting data`); 283 if (kvStore != null) { 284 kvStore.delete(predicates).then(() => { 285 console.info('Succeeded in deleting'); 286 }).catch((err: BusinessError) => { 287 console.error(`Failed to delete.code is ${err.code},message is ${err.message}`); 288 }); 289 } 290 }).catch((err: BusinessError) => { 291 console.error(`Failed to put.code is ${err.code},message is ${err.message}`); 292 }); 293} catch (e) { 294 let error = e as BusinessError; 295 console.error(`An unexpected error occurred.code is ${error.code},message is ${error.message}`); 296} 297``` 298 299### getResultSet 300 301getResultSet(predicates: dataSharePredicates.DataSharePredicates, callback: AsyncCallback<KVStoreResultSet>): void 302 303Obtains a **KVStoreResultSet** object that matches the specified conditions. This API uses an asynchronous callback to return the result. 304 305**Model restriction**: This API can be used only in the stage model. 306 307**System API**: This is a system API. 308 309**System capability**: SystemCapability.DistributedDataManager.DataShare.Provider 310 311**Parameters** 312 313| Name | Type | Mandatory| Description | 314| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 315| 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. | 316| callback | AsyncCallback<[KVStoreResultSet](js-apis-distributedKVStore.md#kvstoreresultset)> | Yes | Callback used to return the **KVStoreResultSet** object obtained.| 317 318**Error codes** 319 320For details about the error codes, see [Distributed KV Store Error Codes](errorcode-distributedKVStore.md). 321 322| ID| **Error Message** | 323| ------------ | -------------------------------------- | 324| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified; 2.Incorrect parameters types.| 325| 202 | Permission verification failed, application which is not a system application uses system API.| 326| 15100001 | Upper limit exceeded. | 327| 15100003 | Database corrupted. | 328| 15100005 | Database or result set already closed. | 329 330**Example** 331 332```ts 333import { dataSharePredicates } from '@kit.ArkData'; 334import { BusinessError } from '@kit.BasicServicesKit'; 335 336try { 337 let resultSet: distributedKVStore.KVStoreResultSet; 338 let predicates = new dataSharePredicates.DataSharePredicates(); 339 predicates.prefixKey("batch_test_string_key"); 340 kvStore.getResultSet(predicates, async (err: BusinessError, result: distributedKVStore.KVStoreResultSet) => { 341 if (err != undefined) { 342 console.error(`Failed to get resultset.code is ${err.code},message is ${err.message}`); 343 return; 344 } 345 console.info('Succeeded in getting result set'); 346 resultSet = result; 347 if (kvStore != null) { 348 kvStore.closeResultSet(resultSet, (err: BusinessError) => { 349 if (err != undefined) { 350 console.error(`Failed to close resultset.code is ${err.code},message is ${err.message}`); 351 return; 352 } 353 console.info('Succeeded in closing result set'); 354 }); 355 } 356 }); 357} catch (e) { 358 let error = e as BusinessError; 359 console.error(`An unexpected error occurred.code is ${error.code},message is ${error.code}`); 360} 361``` 362 363### getResultSet 364 365getResultSet(predicates: dataSharePredicates.DataSharePredicates): Promise<KVStoreResultSet> 366 367Obtains a **KVStoreResultSet** object that matches the specified conditions. This API uses a promise to return the result. 368 369**Model restriction**: This API can be used only in the stage model. 370 371**System API**: This is a system API. 372 373**System capability**: SystemCapability.DistributedDataManager.DataShare.Provider 374 375**Parameters** 376 377| Name | Type | Mandatory| Description | 378| ---------- | ------------------------------------------------------------ | ---- | ----------------------------------------------- | 379| 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.| 380 381**Return value** 382 383| Type | Description | 384| ---------------------------------------------------- | ------------------------- | 385| Promise<[KVStoreResultSet](js-apis-distributedKVStore.md#kvstoreresultset)> | Promise used to return the **KVStoreResultSet** object obtained.| 386 387**Error codes** 388 389For details about the error codes, see [Distributed KV Store Error Codes](errorcode-distributedKVStore.md). 390 391| ID| **Error Message** | 392| ------------ | -------------------------------------- | 393| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified; 2.Incorrect parameters types.| 394| 202 | Permission verification failed, application which is not a system application uses system API.| 395| 15100001 | Upper limit exceeded. | 396| 15100003 | Database corrupted. | 397| 15100005 | Database or result set already closed. | 398 399**Example** 400 401```ts 402import { dataSharePredicates } from '@kit.ArkData'; 403import { BusinessError } from '@kit.BasicServicesKit'; 404 405try { 406 let resultSet: distributedKVStore.KVStoreResultSet; 407 let predicates = new dataSharePredicates.DataSharePredicates(); 408 predicates.prefixKey("batch_test_string_key"); 409 kvStore.getResultSet(predicates).then((result: distributedKVStore.KVStoreResultSet) => { 410 console.info('Succeeded in getting result set'); 411 resultSet = result; 412 if (kvStore != null) { 413 kvStore.closeResultSet(resultSet).then(() => { 414 console.info('Succeeded in closing result set'); 415 }).catch((err: BusinessError) => { 416 console.error(`Failed to close resultset.code is ${err.code},message is ${err.message}`); 417 }); 418 } 419 }).catch((err: BusinessError) => { 420 console.error(`Failed to get resultset.code is ${err.code},message is ${err.message}`); 421 }); 422 423} catch (e) { 424 let error = e as BusinessError; 425 console.error(`An unexpected error occurred.code is ${error.code},message is ${error.code}`); 426} 427``` 428 429## DeviceKVStore 430 431Provides APIs for querying and synchronizing data in a device KV store. This class inherits from **SingleKVStore**. 432 433Data 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. 434 435For 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. 436 437Before calling **DeviceKVStore** APIs, you need to use [getKVStore](js-apis-distributedKVStore.md#getkvstore) to create a **DeviceKVStore** instance. 438 439### getResultSet 440 441getResultSet(predicates: dataSharePredicates.DataSharePredicates, callback: AsyncCallback<KVStoreResultSet>): void 442 443Obtains a **KVStoreResultSet** object that matches the specified conditions for this device. This API uses an asynchronous callback to return the result. 444 445**Model restriction**: This API can be used only in the stage model. 446 447**System API**: This is a system API. 448 449**System capability**: SystemCapability.DistributedDataManager.DataShare.Provider 450 451**Parameters** 452 453| Name | Type | Mandatory| Description | 454| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 455| 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. | 456| callback | AsyncCallback<[KVStoreResultSet](js-apis-distributedKVStore.md#kvstoreresultset)> | Yes | Callback used to return the **KVStoreResultSet** object obtained.| 457 458**Error codes** 459 460For details about the error codes, see [Distributed KV Store Error Codes](errorcode-distributedKVStore.md). 461 462| ID| **Error Message** | 463| ------------ | -------------------------------------- | 464| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified; 2.Incorrect parameters types.| 465| 202 | Permission verification failed, application which is not a system application uses system API.| 466| 15100001 | Upper limit exceeded. | 467| 15100003 | Database corrupted. | 468| 15100005 | Database or result set already closed. | 469 470**Example** 471 472```ts 473import { dataSharePredicates } from '@kit.ArkData'; 474import { BusinessError } from '@kit.BasicServicesKit'; 475 476try { 477 let resultSet: distributedKVStore.KVStoreResultSet; 478 let predicates = new dataSharePredicates.DataSharePredicates(); 479 predicates.prefixKey("batch_test_string_key"); 480 kvStore.getResultSet(predicates, async (err: BusinessError, result: distributedKVStore.KVStoreResultSet) => { 481 if (err != undefined) { 482 console.error(`Failed to get resultset.code is ${err.code},message is ${err.message}`); 483 return; 484 } 485 console.info('Succeeded in getting result set'); 486 resultSet = result; 487 if (kvStore != null) { 488 kvStore.closeResultSet(resultSet, (err: BusinessError) => { 489 if (err != undefined) { 490 console.error(`Failed to close resultset.code is ${err.code},message is ${err.message}`); 491 return; 492 } 493 console.info('Succeeded in closing result set'); 494 }) 495 } 496 }); 497} catch (e) { 498 let error = e as BusinessError; 499 console.error(`An unexpected error occurred.code is ${error.code},message is ${error.code}`); 500} 501``` 502 503### getResultSet 504 505getResultSet(predicates: dataSharePredicates.DataSharePredicates): Promise<KVStoreResultSet> 506 507Obtains a **KVStoreResultSet** object that matches the specified conditions for this device. This API uses a promise to return the result. 508 509**Model restriction**: This API can be used only in the stage model. 510 511**System API**: This is a system API. 512 513**System capability**: SystemCapability.DistributedDataManager.DataShare.Provider 514 515**Parameters** 516 517| Name | Type | Mandatory| Description | 518| ---------- | ------------------------------------------------------------ | ---- | ----------------------------------------------- | 519| 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.| 520 521**Return value** 522 523| Type | Description | 524| ---------------------------------------------------- | ------------------------- | 525| Promise<[KVStoreResultSet](js-apis-distributedKVStore.md#kvstoreresultset)> | Promise used to return the **KVStoreResultSet** object obtained.| 526 527**Error codes** 528 529For details about the error codes, see [Distributed KV Store Error Codes](errorcode-distributedKVStore.md). 530 531| ID| **Error Message** | 532| ------------ | -------------------------------------- | 533| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified; 2.Incorrect parameters types.| 534| 202 | Permission verification failed, application which is not a system application uses system API.| 535| 15100001 | Upper limit exceeded. | 536| 15100003 | Database corrupted. | 537| 15100005 | Database or result set already closed. | 538 539**Example** 540 541```ts 542import { dataSharePredicates } from '@kit.ArkData'; 543import { BusinessError } from '@kit.BasicServicesKit'; 544 545try { 546 let resultSet: distributedKVStore.KVStoreResultSet; 547 let predicates = new dataSharePredicates.DataSharePredicates(); 548 predicates.prefixKey("batch_test_string_key"); 549 kvStore.getResultSet(predicates).then((result: distributedKVStore.KVStoreResultSet) => { 550 console.info('Succeeded in getting result set'); 551 resultSet = result; 552 if (kvStore != null) { 553 kvStore.closeResultSet(resultSet).then(() => { 554 console.info('Succeeded in closing result set'); 555 }).catch((err: BusinessError) => { 556 console.error(`Failed to close resultset.code is ${err.code},message is ${err.message}`); 557 }); 558 } 559 }).catch((err: BusinessError) => { 560 console.error(`Failed to get resultset.code is ${err.code},message is ${err.message}`); 561 }); 562} catch (e) { 563 let error = e as BusinessError; 564 console.error(`An unexpected error occurred.code is ${error.code},message is ${error.code}`); 565} 566``` 567 568### getResultSet 569 570getResultSet(deviceId: string, predicates: dataSharePredicates.DataSharePredicates, callback: AsyncCallback<KVStoreResultSet>): void 571 572Obtains a **KVStoreResultSet** object that matches the specified conditions for a device. This API uses an asynchronous callback to return the result. 573> **NOTE** 574> 575> **deviceId** can be obtained by [deviceManager.getAvailableDeviceListSync](../apis-distributedservice-kit/js-apis-distributedDeviceManager.md#getavailabledevicelistsync). 576> For details about how to obtain **deviceId**, see the example of [sync](js-apis-distributedKVStore.md#sync). 577 578**Model restriction**: This API can be used only in the stage model. 579 580**System API**: This is a system API. 581 582**System capability**: SystemCapability.DistributedDataManager.DataShare.Provider 583 584**Parameters** 585 586| Name | Type | Mandatory| Description | 587| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 588| deviceId | string | Yes | ID of the target device. | 589| 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. | 590| callback | AsyncCallback<[KVStoreResultSet](js-apis-distributedKVStore.md#kvstoreresultset)> | Yes | Callback used to return the **KVStoreResultSet** object obtained.| 591 592**Error codes** 593 594For details about the error codes, see [Distributed KV Store Error Codes](errorcode-distributedKVStore.md). 595 596| ID| **Error Message** | 597| ------------ | -------------------------------------- | 598| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified; 2.Incorrect parameters types.| 599| 202 | Permission verification failed, application which is not a system application uses system API.| 600| 15100001 | Upper limit exceeded. | 601| 15100003 | Database corrupted. | 602| 15100005 | Database or result set already closed. | 603 604**Example** 605 606```ts 607import { dataSharePredicates } from '@kit.ArkData'; 608import { BusinessError } from '@kit.BasicServicesKit'; 609 610try { 611 let resultSet: distributedKVStore.KVStoreResultSet; 612 let predicates = new dataSharePredicates.DataSharePredicates(); 613 predicates.prefixKey("batch_test_string_key"); 614 kvStore.getResultSet('localDeviceId', predicates, async (err: BusinessError, result: distributedKVStore.KVStoreResultSet) => { 615 if (err != undefined) { 616 console.error(`Failed to get resultset.code is ${err.code},message is ${err.message}`); 617 return; 618 } 619 console.info('Succeeded in getting result set'); 620 resultSet = result; 621 if (kvStore != null) { 622 kvStore.closeResultSet(resultSet, (err: BusinessError) => { 623 if (err != undefined) { 624 console.error(`Failed to close resultset.code is ${err.code},message is ${err.message}`); 625 return; 626 } 627 console.info('Succeeded in closing result set'); 628 }) 629 } 630 }); 631} catch (e) { 632 let error = e as BusinessError; 633 console.error(`An unexpected error occurred.code is ${error.code},message is ${error.code}`); 634} 635``` 636 637### getResultSet 638 639getResultSet(deviceId: string, predicates: dataSharePredicates.DataSharePredicates): Promise<KVStoreResultSet> 640 641Obtains a **KVStoreResultSet** object that matches the specified conditions for a device. This API uses a promise to return the result. 642> **NOTE** 643> 644> **deviceId** can be obtained by [deviceManager.getAvailableDeviceListSync](../apis-distributedservice-kit/js-apis-distributedDeviceManager.md#getavailabledevicelistsync). 645> For details about how to obtain **deviceId**, see the example of [sync](js-apis-distributedKVStore.md#sync). 646 647**Model restriction**: This API can be used only in the stage model. 648 649**System API**: This is a system API. 650 651**System capability**: SystemCapability.DistributedDataManager.DataShare.Provider 652 653**Parameters** 654 655| Name | Type | Mandatory| Description | 656| ---------- | ------------------------------------------------------------ | ---- | ----------------------------------------------- | 657| deviceId | string | Yes | ID of the target device. | 658| 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.| 659 660**Return value** 661 662| Type | Description | 663| ---------------------------------------------------- | ------------------------- | 664| Promise<[KVStoreResultSet](js-apis-distributedKVStore.md#kvstoreresultset)> | Promise used to return the **KVStoreResultSet** object obtained.| 665 666**Error codes** 667 668For details about the error codes, see [Distributed KV Store Error Codes](errorcode-distributedKVStore.md). 669 670| ID| **Error Message** | 671| ------------ | -------------------------------------- | 672| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified; 2.Incorrect parameters types.| 673| 202 | Permission verification failed, application which is not a system application uses system API.| 674| 15100001 | Upper limit exceeded. | 675| 15100003 | Database corrupted. | 676| 15100005 | Database or result set already closed. | 677 678**Example** 679 680```ts 681import { dataSharePredicates } from '@kit.ArkData'; 682import { BusinessError } from '@kit.BasicServicesKit'; 683 684try { 685 let resultSet: distributedKVStore.KVStoreResultSet; 686 let predicates = new dataSharePredicates.DataSharePredicates(); 687 predicates.prefixKey("batch_test_string_key"); 688 kvStore.getResultSet('localDeviceId', predicates).then((result: distributedKVStore.KVStoreResultSet) => { 689 console.info('Succeeded in getting result set'); 690 resultSet = result; 691 if (kvStore != null) { 692 kvStore.closeResultSet(resultSet).then(() => { 693 console.info('Succeeded in closing result set'); 694 }).catch((err: BusinessError) => { 695 console.error(`Failed to close resultset.code is ${err.code},message is ${err.message}`); 696 }); 697 } 698 }).catch((err: BusinessError) => { 699 console.error(`Failed to get resultset.code is ${err.code},message is ${err.message}`); 700 }); 701} catch (e) { 702 let error = e as BusinessError; 703 console.error(`An unexpected error occurred.code is ${error.code},message is ${error.code}`); 704} 705``` 706