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