• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# @ohos.data.dataSharePredicates (DataShare Predicates) (System API)
2
3You can use **DataSharePredicates** to specify conditions for [updating](js-apis-data-dataShare-sys.md#update), [deleting](js-apis-data-dataShare-sys.md#delete), and [querying](js-apis-data-dataShare-sys.md#query) data when **DataShare** is used to manage data.
4
5The APIs provided by **DataSharePredicates** correspond to the filter criteria of the database. Before using the APIs, you need to have basic database knowledge.
6
7**DataSharePredicates** applies to the following scenario:
8
9- It is used as a search criteria when APIs of the [RDB store](js-apis-data-relationalStore-sys.md) and [KV store](js-apis-distributedKVStore-sys.md) are called. In this scenario, use the corresponding predicate based on the database type.
10
11> **NOTE**
12>
13> - 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.
14>
15> - The APIs of this module can be used only in the stage model.
16>
17> - This topic describes only the system APIs provided by the module. For details about its public APIs, see [@ohos.data.dataSharePredicates (Data Share Predicates)](js-apis-data-dataSharePredicates.md).
18
19
20
21## Modules to Import
22
23```ts
24import { dataSharePredicates } from '@kit.ArkData';
25```
26
27## DataSharePredicates
28Provides methods for setting different **DataSharePredicates** objects. This type is not multi-thread safe. If a **DataSharePredicates** instance is operated by multiple threads at the same time in an application, use a lock for the instance.
29
30### notEqualTo
31
32notEqualTo(field: string, value: ValueType): DataSharePredicates
33
34Sets a **DataSharePredicates** object to match the data that is not equal to the specified value.
35
36Currently, both the RDB stote and KV store support this predicate.
37
38**System API**: This is a system API.
39
40**System capability**: SystemCapability.DistributedDataManager.DataShare.Core
41
42**Parameters**
43
44| Name| Type                                               | Mandatory| Description                  |
45| ------ | --------------------------------------------------- | ---- | ---------------------- |
46| field  | string                                              | Yes  | Column name in the database table.    |
47| value  | [ValueType](js-apis-data-valuesBucket.md#valuetype) | Yes  | Value to match.|
48
49**Return value**
50
51| Type                                       | Description                      |
52| ------------------------------------------- | -------------------------- |
53| [DataSharePredicates](#datasharepredicates) | **DataSharePredicates** object created.|
54
55**Example**
56
57```ts
58let predicates = new dataSharePredicates.DataSharePredicates();
59predicates.notEqualTo("NAME", "Rose");
60```
61
62### beginWrap
63
64beginWrap(): DataSharePredicates
65
66Adds a left parenthesis to this **DataSharePredicates**. This API is similar to "(" in an SQL statement and must be used with **endWrap**.
67
68Currently, only RDB store supports this predicate.
69
70**System API**: This is a system API.
71
72**System capability**: SystemCapability.DistributedDataManager.DataShare.Core
73
74**Return value**
75
76| Type                                       | Description                  |
77| ------------------------------------------- | ---------------------- |
78| [DataSharePredicates](#datasharepredicates) | **DataSharePredicates** object with a left parenthesis.|
79
80**Example**
81
82```ts
83let predicates = new dataSharePredicates.DataSharePredicates();
84predicates.equalTo("NAME", "lisi")
85    .beginWrap()
86    .equalTo("AGE", 18)
87    .or()
88    .equalTo("SALARY", 200.5)
89    .endWrap();
90```
91
92### endWrap
93
94endWrap(): DataSharePredicates
95
96Adds a right parenthesis to this **DataSharePredicates** object.
97
98Currently, only RDB store supports this predicate.
99
100**System API**: This is a system API.
101
102**System capability**: SystemCapability.DistributedDataManager.DataShare.Core
103
104**Return value**
105
106| Type                                       | Description                  |
107| ------------------------------------------- | ---------------------- |
108| [DataSharePredicates](#datasharepredicates) | **DataSharePredicates** object with a right parenthesis.|
109
110**Example**
111
112```ts
113let predicates = new dataSharePredicates.DataSharePredicates();
114predicates.equalTo("NAME", "lisi")
115    .beginWrap()
116    .equalTo("AGE", 18)
117    .or()
118    .equalTo("SALARY", 200.5)
119    .endWrap();
120```
121
122### or
123
124or(): DataSharePredicates
125
126Adds the OR condition to this **DataSharePredicates** object.
127
128Currently, both the RDB stote and KV store support this predicate.
129
130**System API**: This is a system API.
131
132**System capability**: SystemCapability.DistributedDataManager.DataShare.Core
133
134**Return value**
135
136| Type                                       | Description                  |
137| ------------------------------------------- | ---------------------- |
138| [DataSharePredicates](#datasharepredicates) | **DataSharePredicates** object with the OR condition.|
139
140**Example**
141
142```ts
143let predicates = new dataSharePredicates.DataSharePredicates()
144predicates.equalTo("NAME", "lisi")
145    .or()
146    .equalTo("NAME", "Rose");
147```
148
149### contains
150
151contains(field: string, value: string): DataSharePredicates
152
153Sets a **DataSharePredicates** object to match the data that contains the specified value.
154
155Currently, only RDB store supports this predicate.
156
157**System API**: This is a system API.
158
159**System capability**: SystemCapability.DistributedDataManager.DataShare.Core
160
161**Parameters**
162
163| Name| Type  | Mandatory| Description                |
164| ------ | ------ | ---- | -------------------- |
165| field  | string | Yes  | Column name in the database table.  |
166| value  | string | Yes  | Value to match.|
167
168**Return value**
169
170| Type                                       | Description                      |
171| ------------------------------------------- | -------------------------- |
172| [DataSharePredicates](#datasharepredicates) | **DataSharePredicates** object created.|
173
174**Example**
175
176```ts
177let predicates = new dataSharePredicates.DataSharePredicates();
178predicates.contains("NAME", "os");
179```
180
181### beginsWith
182
183beginsWith(field: string, value: string): DataSharePredicates
184
185Sets a **DataSharePredicates** object to match the data that begins with the specified value.
186
187Currently, only RDB store supports this predicate.
188
189**System API**: This is a system API.
190
191**System capability**: SystemCapability.DistributedDataManager.DataShare.Core
192
193**Parameters**
194
195| Name| Type  | Mandatory| Description                  |
196| ------ | ------ | ---- | ---------------------- |
197| field  | string | Yes  | Column name in the database table.    |
198| value  | string | Yes  | Start value to match.|
199
200**Return value**
201
202| Type                                       | Description                      |
203| ------------------------------------------- | -------------------------- |
204| [DataSharePredicates](#datasharepredicates) | **DataSharePredicates** object created.|
205
206**Example**
207
208```ts
209let predicates = new dataSharePredicates.DataSharePredicates();
210predicates.beginsWith("NAME", "os");
211```
212
213### endsWith
214
215endsWith(field: string, value: string): DataSharePredicates
216
217Sets a **DataSharePredicates** object to match the data that ends with the specified value.
218
219Currently, only RDB store supports this predicate.
220
221**System API**: This is a system API.
222
223**System capability**: SystemCapability.DistributedDataManager.DataShare.Core
224
225**Parameters**
226
227| Name| Type  | Mandatory| Description                  |
228| ------ | ------ | ---- | ---------------------- |
229| field  | string | Yes  | Column name in the database table.    |
230| value  | string | Yes  | End value to match.|
231
232**Return value**
233
234| Type                                       | Description                      |
235| ------------------------------------------- | -------------------------- |
236| [DataSharePredicates](#datasharepredicates) | **DataSharePredicates** object created.|
237
238**Example**
239
240```ts
241let predicates = new dataSharePredicates.DataSharePredicates();
242predicates.endsWith("NAME", "os");
243```
244
245### isNull
246
247isNull(field: string): DataSharePredicates
248
249Sets a **DataSharePredicates** object to match the data whose value is null.
250
251Currently, both the RDB stote and KV store support this predicate.
252
253**System API**: This is a system API.
254
255**System capability**: SystemCapability.DistributedDataManager.DataShare.Core
256
257**Parameters**
258
259| Name| Type  | Mandatory| Description              |
260| ------ | ------ | ---- | ------------------ |
261| field  | string | Yes  | Column name in the database table.|
262
263**Return value**
264
265| Type                                       | Description                      |
266| ------------------------------------------- | -------------------------- |
267| [DataSharePredicates](#datasharepredicates) | **DataSharePredicates** object created.|
268
269**Example**
270
271```ts
272let predicates = new dataSharePredicates.DataSharePredicates();
273predicates.isNull("NAME");
274```
275
276### isNotNull
277
278isNotNull(field: string): DataSharePredicates
279
280Sets a **DataSharePredicates** object to match the data whose value is not null.
281
282Currently, both the RDB stote and KV store support this predicate.
283
284**System API**: This is a system API.
285
286**System capability**: SystemCapability.DistributedDataManager.DataShare.Core
287
288**Parameters**
289
290| Name| Type  | Mandatory| Description              |
291| ------ | ------ | ---- | ------------------ |
292| field  | string | Yes  | Column name in the database table.|
293
294**Return value**
295
296| Type                                       | Description                      |
297| ------------------------------------------- | -------------------------- |
298| [DataSharePredicates](#datasharepredicates) | **DataSharePredicates** object created.|
299
300**Example**
301
302```ts
303let predicates = new dataSharePredicates.DataSharePredicates();
304predicates.isNotNull("NAME");
305```
306
307### like
308
309like(field: string, value: string): DataSharePredicates
310
311Sets a **DataSharePredicates** object to match the data that matches the specified wildcard expression.
312
313Currently, both the RDB stote and KV store support this predicate.
314
315**System API**: This is a system API.
316
317**System capability**: SystemCapability.DistributedDataManager.DataShare.Core
318
319**Parameters**
320
321| Name| Type  | Mandatory| Description                  |
322| ------ | ------ | ---- | ---------------------- |
323| field  | string | Yes  | Column name in the database table.    |
324| value  | string | Yes  | Wildcard expression to match.<br>In the expression, '%' represents zero, one, or more digits or characters, and '_' represents a single digit or character. It is case insensitive.|
325
326**Return value**
327
328| Type                                       | Description                      |
329| ------------------------------------------- | -------------------------- |
330| [DataSharePredicates](#datasharepredicates) | **DataSharePredicates** object created.|
331
332**Example**
333
334```ts
335let predicates = new dataSharePredicates.DataSharePredicates();
336predicates.like("NAME", "%os%");
337```
338
339### unlike
340
341unlike(field: string, value: string): DataSharePredicates
342
343Sets a **DataSharePredicates** object to match the data that does not match the specified wildcard expression.
344
345Currently, both the RDB stote and KV store support this predicate.
346
347**System API**: This is a system API.
348
349**System capability**: SystemCapability.DistributedDataManager.DataShare.Core
350
351**Parameters**
352
353| Name| Type  | Mandatory| Description                  |
354| ------ | ------ | ---- | ---------------------- |
355| field  | string | Yes  | Column name in the database table.    |
356| value  | string | Yes  | Wildcard expression to match.<br>In the expression, '%' represents zero, one, or more digits or characters, and '_' represents a single digit or character. It is case insensitive.|
357
358**Return value**
359
360| Type                                       | Description                      |
361| ------------------------------------------- | -------------------------- |
362| [DataSharePredicates](#datasharepredicates) | **DataSharePredicates** object created.|
363
364**Example**
365
366```ts
367let predicates = new dataSharePredicates.DataSharePredicates();
368predicates.unlike("NAME", "%os%");
369```
370
371### glob
372
373glob(field: string, value: string): DataSharePredicates
374
375Sets a **DataSharePredicates** object to match the data that matches the specified wildcard expression.
376
377Currently, only RDB store supports this predicate.
378
379**System API**: This is a system API.
380
381**System capability**: SystemCapability.DistributedDataManager.DataShare.Core
382
383**Parameters**
384
385| Name| Type  | Mandatory| Description                  |
386| ------ | ------ | ---- | ---------------------- |
387| field  | string | Yes  | Column name in the database table.    |
388| value  | string | Yes  | Wildcard expression to match.<br>In the expression, '*' represents zero, one, or more digits or characters, and '?' represents a single digit or character. It is case sensitive.|
389
390**Return value**
391
392| Type                                       | Description                      |
393| ------------------------------------------- | -------------------------- |
394| [DataSharePredicates](#datasharepredicates) | **DataSharePredicates** object created.|
395
396**Example**
397
398```ts
399let predicates = new dataSharePredicates.DataSharePredicates();
400predicates.glob("NAME", "?h*g");
401```
402
403### between
404
405between(field: string, low: ValueType, high: ValueType): DataSharePredicates
406
407Sets a **DataSharePredicates** object to match the data that is within the specified range, including the start and end values. The data type must be int.
408
409Currently, only RDB store supports this predicate.
410
411**System API**: This is a system API.
412
413**System capability**: SystemCapability.DistributedDataManager.DataShare.Core
414
415**Parameters**
416
417| Name| Type                                               | Mandatory| Description                    |
418| ------ | --------------------------------------------------- | ---- | ------------------------ |
419| field  | string                                              | Yes  | Column name in the database table.      |
420| low    | [ValueType](js-apis-data-valuesBucket.md#valuetype) | Yes  | The lowest value of the range.|
421| high   | [ValueType](js-apis-data-valuesBucket.md#valuetype) | Yes  | The highest value of the range.|
422
423**Return value**
424
425| Type                                       | Description                      |
426| ------------------------------------------- | -------------------------- |
427| [DataSharePredicates](#datasharepredicates) | **DataSharePredicates** object created.|
428
429**Example**
430
431```ts
432let predicates = new dataSharePredicates.DataSharePredicates();
433predicates.between("AGE", 10, 50);
434```
435
436### notBetween
437
438notBetween(field: string, low: ValueType, high: ValueType): DataSharePredicates
439
440Sets a **DataSharePredicates** object to match the data that is out of the specified range, excluding the start and end values. The data type must be int.
441
442Currently, only RDB store supports this predicate.
443
444**System API**: This is a system API.
445
446**System capability**: SystemCapability.DistributedDataManager.DataShare.Core
447
448**Parameters**
449
450| Name| Type                                               | Mandatory| Description                    |
451| ------ | --------------------------------------------------- | ---- | ------------------------ |
452| field  | string                                              | Yes  | Column name in the database table.      |
453| low    | [ValueType](js-apis-data-valuesBucket.md#valuetype) | Yes  | The lowest value of the range.|
454| high   | [ValueType](js-apis-data-valuesBucket.md#valuetype) | Yes  | The highest value of the range.|
455
456**Return value**
457
458| Type                                       | Description                      |
459| ------------------------------------------- | -------------------------- |
460| [DataSharePredicates](#datasharepredicates) | **DataSharePredicates** object created.|
461
462**Example**
463
464```ts
465let predicates = new dataSharePredicates.DataSharePredicates();
466predicates.notBetween("AGE", 10, 50);
467```
468
469### greaterThan
470
471greaterThan(field: string, value: ValueType): DataSharePredicates
472
473Sets a **DataSharePredicates** object to match the data that is greater than the specified value.
474
475Currently, both the RDB stote and KV store support this predicate.
476
477**System API**: This is a system API.
478
479**System capability**: SystemCapability.DistributedDataManager.DataShare.Core
480
481**Parameters**
482
483| Name | Type     | Mandatory| Description                  |
484| ------- | --------- | ---- | ---------------------- |
485| field   | string    | Yes  | Column name in the database table.    |
486| value | [ValueType](js-apis-data-valuesBucket.md#valuetype) | Yes  | Value to match.|
487
488**Return value**
489
490| Type                                       | Description                      |
491| ------------------------------------------- | -------------------------- |
492| [DataSharePredicates](#datasharepredicates) | **DataSharePredicates** object created.|
493
494**Example**
495
496```ts
497let predicates = new dataSharePredicates.DataSharePredicates();
498predicates.greaterThan("AGE", 10);
499```
500
501### lessThan
502
503lessThan(field: string, value: ValueType): DataSharePredicates
504
505Sets a **DataSharePredicates** object to match the data that is less than the specified value.
506
507Currently, both the RDB stote and KV store support this predicate.
508
509**System API**: This is a system API.
510
511**System capability**: SystemCapability.DistributedDataManager.DataShare.Core
512
513**Parameters**
514
515| Name| Type                                               | Mandatory| Description                  |
516| ------ | --------------------------------------------------- | ---- | ---------------------- |
517| field  | string                                              | Yes  | Column name in the database table.    |
518| value  | [ValueType](js-apis-data-valuesBucket.md#valuetype) | Yes  | Value to match.|
519
520**Return value**
521
522| Type                                       | Description                      |
523| ------------------------------------------- | -------------------------- |
524| [DataSharePredicates](#datasharepredicates) | **DataSharePredicates** object created.|
525
526**Example**
527
528```ts
529let predicates = new dataSharePredicates.DataSharePredicates();
530predicates.lessThan("AGE", 50);
531```
532
533### greaterThanOrEqualTo
534
535greaterThanOrEqualTo(field: string, value: ValueType): DataSharePredicates
536
537Sets a **DataSharePredicates** object to match the data that is greater than or equal to the specified value.
538
539Currently, both the RDB stote and KV store support this predicate.
540
541**System API**: This is a system API.
542
543**System capability**: SystemCapability.DistributedDataManager.DataShare.Core
544
545**Parameters**
546
547| Name | Type     | Mandatory| Description                  |
548| ------- | --------- | ---- | ---------------------- |
549| field   | string    | Yes  | Column name in the database table.    |
550| value | [ValueType](js-apis-data-valuesBucket.md#valuetype) | Yes  | Value to match.|
551
552**Return value**
553
554| Type                                       | Description                      |
555| ------------------------------------------- | -------------------------- |
556| [DataSharePredicates](#datasharepredicates) | **DataSharePredicates** object created.|
557
558**Example**
559
560```ts
561let predicates = new dataSharePredicates.DataSharePredicates();
562predicates.greaterThanOrEqualTo("AGE", 10);
563```
564
565### lessThanOrEqualTo
566
567lessThanOrEqualTo(field: string, value: ValueType): DataSharePredicates
568
569Sets a **DataSharePredicates** object to match the data that is less than or equal to the specified value.
570
571Currently, both the RDB stote and KV store support this predicate.
572
573**System API**: This is a system API.
574
575**System capability**: SystemCapability.DistributedDataManager.DataShare.Core
576
577**Parameters**
578
579| Name | Type     | Mandatory| Description                  |
580| ------- | --------- | ---- | ---------------------- |
581| field   | string    | Yes  | Column name in the database table.    |
582| value | [ValueType](js-apis-data-valuesBucket.md#valuetype) | Yes  | Value to match.|
583
584**Return value**
585
586| Type                                       | Description                      |
587| ------------------------------------------- | -------------------------- |
588| [DataSharePredicates](#datasharepredicates) | **DataSharePredicates** object created.|
589
590**Example**
591
592```ts
593let predicates = new dataSharePredicates.DataSharePredicates();
594predicates.lessThanOrEqualTo("AGE", 50);
595```
596
597### distinct
598
599distinct(): DataSharePredicates
600
601Sets a **DataSharePredicates** object to filter out duplicate data records.
602
603Currently, only RDB store supports this predicate.
604
605**System API**: This is a system API.
606
607**System capability**: SystemCapability.DistributedDataManager.DataShare.Core
608
609**Return value**
610
611| Type                                       | Description                      |
612| ------------------------------------------- | -------------------------- |
613| [DataSharePredicates](#datasharepredicates) | **DataSharePredicates** object created.|
614
615**Example**
616
617```ts
618let predicates = new dataSharePredicates.DataSharePredicates();
619predicates.equalTo("NAME", "Rose").distinct();
620```
621
622### groupBy
623
624groupBy(fields: Array&lt;string&gt;): DataSharePredicates
625
626Sets a **DataSharePredicates** object group the records according to the specified fields.
627
628Currently, only RDB store supports this predicate.
629
630**System API**: This is a system API.
631
632**System capability**: SystemCapability.DistributedDataManager.DataShare.Core
633
634**Parameters**
635
636| Name| Type         | Mandatory| Description                |
637| ------ | ------------- | ---- | -------------------- |
638| fields | Array&lt;string&gt; | Yes  | Names of the columns by which the records are grouped.|
639
640**Return value**
641
642| Type                                       | Description                      |
643| ------------------------------------------- | -------------------------- |
644| [DataSharePredicates](#datasharepredicates) | **DataSharePredicates** object created.|
645
646**Example**
647
648```ts
649let predicates = new dataSharePredicates.DataSharePredicates();
650predicates.groupBy(["AGE", "NAME"]);
651```
652
653### indexedBy
654
655indexedBy(field: string): DataSharePredicates
656
657Sets a **DataSharePredicates** object to list data by the specified index. Before using this API, ensure that the index column exists.
658
659Currently, only RDB store supports this predicate.
660
661**System API**: This is a system API.
662
663**System capability**: SystemCapability.DistributedDataManager.DataShare.Core
664
665**Parameters**
666
667| Name| Type  | Mandatory| Description          |
668| ------ | ------ | ---- | -------------- |
669| field  | string | Yes  | Name of the index column.|
670
671**Return value**
672
673| Type                                       | Description                      |
674| ------------------------------------------- | -------------------------- |
675| [DataSharePredicates](#datasharepredicates) | **DataSharePredicates** object created.|
676
677**Example**
678
679```ts
680let predicates = new dataSharePredicates.DataSharePredicates();
681predicates.indexedBy("SALARY_INDEX");
682```
683
684### notIn
685
686notIn(field: string, value: Array&lt;ValueType&gt;): DataSharePredicates
687
688Sets a **DataSharePredicates** object to match the data that is not in the specified value.
689
690Currently, both the RDB stote and KV store support this predicate.
691
692**System API**: This is a system API.
693
694**System capability**: SystemCapability.DistributedDataManager.DataShare.Core
695
696**Parameters**
697
698| Name | Type            | Mandatory| Description                                   |
699| ------- | ---------------- | ---- | --------------------------------------- |
700| field   | string           | Yes  | Column name in the database table.                     |
701| value | Array&lt;[ValueType](js-apis-data-valuesBucket.md#valuetype)&gt; | Yes  | Array of the values to match.|
702
703**Return value**
704
705| Type                                       | Description                      |
706| ------------------------------------------- | -------------------------- |
707| [DataSharePredicates](#datasharepredicates) | **DataSharePredicates** object created.|
708
709**Example**
710
711```ts
712let predicates = new dataSharePredicates.DataSharePredicates();
713predicates.notIn("NAME", ["Lisa", "Rose"]);
714```
715
716### prefixKey
717
718prefixKey(prefix: string): DataSharePredicates
719
720Sets a **DataSharePredicates** object to match the data with the specified key prefix.
721
722Currently, only the KVDB supports this **DataSharePredicates** object.
723
724**System API**: This is a system API.
725
726**System capability**: SystemCapability.DistributedDataManager.DataShare.Core
727
728**Parameters**
729
730| Name| Type  | Mandatory| Description          |
731| ------ | ------ | ---- | -------------- |
732| prefix | string | Yes  | Key prefix to match.|
733
734**Return value**
735
736| Type                                       | Description                      |
737| ------------------------------------------- | -------------------------- |
738| [DataSharePredicates](#datasharepredicates) | **DataSharePredicates** object created.|
739
740**Example**
741
742```ts
743let predicates = new dataSharePredicates.DataSharePredicates();
744predicates.prefixKey("NAME");
745```
746
747### inKeys
748
749inKeys(keys: Array&lt;string&gt;): DataSharePredicates
750
751Sets a **DataSharePredicates** object to match the data whose keys are within the given range.
752
753Currently, only the KVDB supports this **DataSharePredicates** object.
754
755**System API**: This is a system API.
756
757**System capability**: SystemCapability.DistributedDataManager.DataShare.Core
758
759**Parameters**
760
761| Name| Type         | Mandatory| Description              |
762| ------ | ------------- | ---- | ------------------ |
763| keys | Array&lt;string&gt; | Yes  | Array of the keys to match.|
764
765**Return value**
766
767| Type                                       | Description                      |
768| ------------------------------------------- | -------------------------- |
769| [DataSharePredicates](#datasharepredicates) | **DataSharePredicates** object created.|
770
771**Example**
772
773```ts
774let predicates = new dataSharePredicates.DataSharePredicates();
775predicates.inKeys(["Lisa", "Rose"]);
776```
777