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';
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
99将valuesbucket类型的值写入SingleKVStore数据库，使用Promise异步回调。
100
101**模型约束：** 此接口仅可在Stage模型下使用
102
103**系统接口：** 此接口为系统接口。
104
105**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core
106
107**参数：**
108
109| 参数名 | 类型                                                     | 必填 | 说明               |
110| ------ | ------------------------------------------------------------ | ---- | ------------------ |
111| value  | Array<[ValuesBucket](js-apis-data-valuesBucket.md#valuesbucket)> | 是   | 表示要插入的数据。 |
112
113**返回值：**
114
115| 类型                | 说明                      |
116| ------------------- | ------------------------- |
117| Promise<void> | 无返回结果的Promise对象。 |
118
119**错误码：**
120
121以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)。
122
123| **错误码ID** | **错误信息**                             |
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
130以下错误码的详细介绍请参见[关系型数据库错误码](errorcode-data-rdb.md)。
131
132| **错误码ID** | **错误信息**                                 |
133| ------------ | -------------------------------------------- |
134| 14800047     | The WAL file size exceeds the default limit. |
135
136**示例：**
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
166从数据库中删除符合predicates条件的键值对，使用callback异步回调。
167
168**模型约束：** 此接口仅可在Stage模型下使用
169
170**系统接口：** 此接口为系统接口。
171
172**系统能力：** SystemCapability.DistributedDataManager.DataShare.Provider
173
174**参数：**
175
176| 参数名     | 类型                                                     | 必填 | 说明                                            |
177| ---------- | ------------------------------------------------------------ | ---- | ----------------------------------------------- |
178| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | 是   | 指示筛选条件，当此参数为null时，应定义处理逻辑。 |
179| callback   | AsyncCallback<void>                                    | 是   | 回调函数。                                      |
180
181**错误码：**
182
183以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)。
184
185| **错误码ID** | **错误信息**                           |
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
192以下错误码的详细介绍请参见[关系型数据库错误码](errorcode-data-rdb.md)。
193
194| **错误码ID** | **错误信息**                                 |
195| ------------ | -------------------------------------------- |
196| 14800047     | The WAL file size exceeds the default limit. |
197
198**示例：**
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
234从数据库中删除符合predicates条件的键值对，使用Promise异步回调。
235
236**模型约束：** 此接口仅可在Stage模型下使用
237
238**系统接口：** 此接口为系统接口。
239
240**系统能力：** SystemCapability.DistributedDataManager.DataShare.Provider
241
242**参数：**
243
244| 参数名     | 类型                                                     | 必填 | 说明                                            |
245| ---------- | ------------------------------------------------------------ | ---- | ----------------------------------------------- |
246| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | 是   | 指示筛选条件,当此参数为null时，应定义处理逻辑。 |
247
248**返回值：**
249
250| 类型                | 说明                      |
251| ------------------- | ------------------------- |
252| Promise<void> | 无返回结果的Promise对象。 |
253
254**错误码：**
255
256以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)。
257
258| **错误码ID** | **错误信息**                             |
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
265以下错误码的详细介绍请参见[关系型数据库错误码](errorcode-data-rdb.md)。
266
267| **错误码ID** | **错误信息**                                 |
268| ------------ | -------------------------------------------- |
269| 14800047     | The WAL file size exceeds the default limit. |
270
271**示例：**
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
303获取与指定Predicate对象匹配的KVStoreResultSet对象，使用callback异步回调。
304
305**模型约束：** 此接口仅可在Stage模型下使用
306
307**系统接口：** 此接口为系统接口。
308
309**系统能力：** SystemCapability.DistributedDataManager.DataShare.Provider
310
311**参数：**
312
313| 参数名     | 类型                                                     | 必填 | 说明                                                         |
314| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
315| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | 是   | 指示筛选条件,当此参数为null时，应定义处理逻辑。              |
316| callback   | AsyncCallback<[KVStoreResultSet](js-apis-distributedKVStore.md#kvstoreresultset)>   | 是   | 回调函数，获取与指定Predicates对象匹配的KVStoreResultSet对象。 |
317
318**错误码：**
319
320以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)。
321
322| **错误码ID** | **错误信息**                           |
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     | Over max  limits.                      |
327| 15100003     | Database corrupted.                    |
328| 15100005     | Database or result set already closed. |
329
330**示例：**
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
367获取与指定Predicate对象匹配的KVStoreResultSet对象，使用Promise异步回调。
368
369**模型约束：** 此接口仅可在Stage模型下使用
370
371**系统接口：** 此接口为系统接口。
372
373**系统能力：** SystemCapability.DistributedDataManager.DataShare.Provider
374
375**参数：**
376
377| 参数名     | 类型                                                     | 必填 | 说明                                            |
378| ---------- | ------------------------------------------------------------ | ---- | ----------------------------------------------- |
379| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | 是   | 指示筛选条件,当此参数为null时，应定义处理逻辑。 |
380
381**返回值：**
382
383| 类型                                                 | 说明                      |
384| ---------------------------------------------------- | ------------------------- |
385| Promise<[KVStoreResultSet](js-apis-distributedKVStore.md#kvstoreresultset)> | 无返回结果的Promise对象。 |
386
387**错误码：**
388
389以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)。
390
391| **错误码ID** | **错误信息**                           |
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     | Over max  limits.                      |
396| 15100003     | Database corrupted.                    |
397| 15100005     | Database or result set already closed. |
398
399**示例：**
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
431设备协同数据库，继承自SingleKVStore，提供查询数据和同步数据的方法。
432
433设备协同数据库，以设备维度对数据进行区分，每台设备仅能写入和修改本设备的数据，其它设备的数据对其是只读的，无法修改其它设备的数据。
434
435比如，可以使用设备协同数据库实现设备间的图片分享，可以查看其他设备的图片，但无法修改和删除其他设备的图片。
436
437在调用DeviceKVStore的方法前，需要先通过[getKVStore](js-apis-distributedKVStore.md#getkvstore)构建一个DeviceKVStore实例。
438
439### getResultSet
440
441getResultSet(predicates: dataSharePredicates.DataSharePredicates, callback: AsyncCallback<KVStoreResultSet>): void
442
443获取与本设备指定Predicate对象匹配的KVStoreResultSet对象，使用callback异步回调。
444
445**模型约束：** 此接口仅可在Stage模型下使用
446
447**系统接口：** 此接口为系统接口。
448
449**系统能力：** SystemCapability.DistributedDataManager.DataShare.Provider
450
451**参数：**
452
453| 参数名     | 类型                                                         | 必填 | 说明                                                         |
454| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
455| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | 是   | 指示筛选条件,当此参数为null时，应定义处理逻辑。              |
456| callback   | AsyncCallback<[KVStoreResultSet](js-apis-distributedKVStore.md#kvstoreresultset)>   | 是   | 回调函数，获取与指定Predicates对象匹配的KVStoreResultSet对象。 |
457
458**错误码：**
459
460以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)。
461
462| **错误码ID** | **错误信息**                           |
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     | Over max  limits.                      |
467| 15100003     | Database corrupted.                    |
468| 15100005     | Database or result set already closed. |
469
470**示例：**
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
507获取与本设备指定Predicate对象匹配的KVStoreResultSet对象，使用Promise异步回调。
508
509**模型约束：** 此接口仅可在Stage模型下使用
510
511**系统接口：** 此接口为系统接口。
512
513**系统能力：** SystemCapability.DistributedDataManager.DataShare.Provider
514
515**参数：**
516
517| 参数名     | 类型                                                         | 必填 | 说明                                            |
518| ---------- | ------------------------------------------------------------ | ---- | ----------------------------------------------- |
519| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | 是   | 指示筛选条件,当此参数为null时，应定义处理逻辑。 |
520
521**返回值：**
522
523| 类型                                                 | 说明                      |
524| ---------------------------------------------------- | ------------------------- |
525| Promise<[KVStoreResultSet](js-apis-distributedKVStore.md#kvstoreresultset)> | 无返回结果的Promise对象。 |
526
527**错误码：**
528
529以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)。
530
531| **错误码ID** | **错误信息**                           |
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     | Over max  limits.                      |
536| 15100003     | Database corrupted.                    |
537| 15100005     | Database or result set already closed. |
538
539**示例：**
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
572获取与指定Predicate对象匹配的KVStoreResultSet对象，使用callback异步回调。
573> **说明：** 
574>
575> 其中deviceId通过调用[deviceManager.getAvailableDeviceListSync](../apis-distributedservice-kit/js-apis-distributedDeviceManager.md#getavailabledevicelistsync)方法得到。
576> deviceId具体获取方式请参考[sync接口示例](js-apis-distributedKVStore.md#sync)。
577
578**模型约束：** 此接口仅可在Stage模型下使用
579
580**系统接口：** 此接口为系统接口。
581
582**系统能力：** SystemCapability.DistributedDataManager.DataShare.Provider
583
584**参数：**
585
586| 参数名     | 类型                                                     | 必填 | 说明                                                         |
587| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
588| deviceId  | string                                                       | 是   | 标识要查询其数据的设备。                                     |
589| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | 是   | 指示筛选条件,当此参数为null时，应定义处理逻辑。              |
590| callback   | AsyncCallback<[KVStoreResultSet](js-apis-distributedKVStore.md#kvstoreresultset)>   | 是   | 回调函数，获取与指定Predicates对象匹配的KVStoreResultSet对象。 |
591
592**错误码：**
593
594以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)。
595
596| **错误码ID** | **错误信息**                           |
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     | Over max  limits.                      |
601| 15100003     | Database corrupted.                    |
602| 15100005     | Database or result set already closed. |
603
604**示例：**
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
641获取与指定Predicate对象匹配的KVStoreResultSet对象，使用Promise异步回调。
642> **说明：** 
643>
644> 其中deviceId通过调用[deviceManager.getAvailableDeviceListSync](../apis-distributedservice-kit/js-apis-distributedDeviceManager.md#getavailabledevicelistsync)方法得到。
645> deviceId具体获取方式请参考[sync接口示例](js-apis-distributedKVStore.md#sync)。
646
647**模型约束：** 此接口仅可在Stage模型下使用
648
649**系统接口：** 此接口为系统接口。
650
651**系统能力：** SystemCapability.DistributedDataManager.DataShare.Provider
652
653**参数：**
654
655| 参数名     | 类型                                                     | 必填 | 说明                                            |
656| ---------- | ------------------------------------------------------------ | ---- | ----------------------------------------------- |
657| deviceId  | string                                                       | 是   | 标识要查询其数据的设备。                                     |
658| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | 是   | 指示筛选条件,当此参数为null时，应定义处理逻辑。 |
659
660**返回值：**
661
662| 类型                                                 | 说明                      |
663| ---------------------------------------------------- | ------------------------- |
664| Promise<[KVStoreResultSet](js-apis-distributedKVStore.md#kvstoreresultset)> | 无返回结果的Promise对象。 |
665
666**错误码：**
667
668以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)。
669
670| **错误码ID** | **错误信息**                           |
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     | Over max  limits.                      |
675| 15100003     | Database corrupted.                    |
676| 15100005     | Database or result set already closed. |
677
678**示例：**
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```