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