• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# @ohos.data.dataSharePredicates (DataShare Predicates)
2
3**DataSharePredicates** provides a filter object to query data in a database by using **DataShare** APIs. It is often used to update, delete, and query 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 criterion in the media file management service. For details, see [Fetch Options of the Album Management](../apis-media-library-kit/arkts-apis-photoAccessHelper-i.md#fetchoptions). In this scenario, you do not need to pay attention to the database type.
10
11<!--Del-->
12- 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.
13<!--DelEnd-->
14
15> **NOTE**
16>
17> - 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.
18>
19> - The APIs of this module can be used only in the stage model.
20
21
22
23## Modules to Import
24
25```ts
26import { dataSharePredicates } from '@kit.ArkData';
27```
28
29## DataSharePredicates
30Provides APIs 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 it.
31
32### equalTo<sup>10+</sup>
33
34equalTo(field: string, value: ValueType): DataSharePredicates
35
36Creates a **DataSharePredicates** object to search for the records in the specified column that are equal to the given value.
37
38Currently, both the RDB stote and KV store support this predicate.
39
40**System capability**: SystemCapability.DistributedDataManager.DataShare.Core
41
42**Atomic service API**: This API can be used in atomic services since API version 20.
43
44**Parameters**
45
46| Name| Type                                               | Mandatory| Description                  |
47| ------ | --------------------------------------------------- | ---- | ---------------------- |
48| field  | string                                              | Yes  | Column name in the database table.<br>If this parameter is set to **undefined** or **null**, the predicate used is invalid.    |
49| value  | [ValueType](js-apis-data-valuesBucket.md#valuetype) | Yes  | Value to match.<br>If this parameter is set to **undefined** or **null**, the predicate used is invalid. |
50
51**Return value**
52
53| Type                                       | Description                      |
54| ------------------------------------------- | -------------------------- |
55| [DataSharePredicates](#datasharepredicates) | **DataSharePredicates** object created.|
56
57**Example**
58
59```ts
60let predicates = new dataSharePredicates.DataSharePredicates();
61predicates.equalTo("NAME", "Rose");
62```
63
64
65### and<sup>10+</sup>
66
67and(): DataSharePredicates
68
69Creates a **DataSharePredicates** object to add the AND condition.
70
71Currently, both the RDB stote and KV store support this predicate.
72
73**System capability**: SystemCapability.DistributedDataManager.DataShare.Core
74
75**Atomic service API**: This API can be used in atomic services since API version 20.
76
77**Return value**
78
79| Type                                       | Description                  |
80| ------------------------------------------- | ---------------------- |
81| [DataSharePredicates](#datasharepredicates) | **DataSharePredicates** object with the AND condition.|
82
83**Example**
84
85```ts
86let predicates = new dataSharePredicates.DataSharePredicates();
87predicates.equalTo("NAME", "lisi")
88    .and()
89    .equalTo("SALARY", 200.5);
90```
91
92### orderByAsc<sup>10+</sup>
93
94orderByAsc(field: string): DataSharePredicates
95
96Creates a **DataSharePredicates** object that sorts records in ascending order.
97
98Currently, both the RDB stote and KV store support this predicate.
99
100**System capability**: SystemCapability.DistributedDataManager.DataShare.Core
101
102**Atomic service API**: This API can be used in atomic services since API version 20.
103
104**Parameters**
105
106| Name| Type  | Mandatory| Description              |
107| ------ | ------ | ---- | ------------------ |
108| field  | string | Yes  | Column name in the database table.<br>If this parameter is set to **undefined** or **null**, the predicate used is invalid.|
109
110**Return value**
111
112| Type                                       | Description                      |
113| ------------------------------------------- | -------------------------- |
114| [DataSharePredicates](#datasharepredicates) | **DataSharePredicates** object created.|
115
116**Example**
117
118```ts
119let predicates = new dataSharePredicates.DataSharePredicates();
120predicates.orderByAsc("AGE");
121```
122
123### orderByDesc<sup>10+</sup>
124
125orderByDesc(field: string): DataSharePredicates
126
127Creates a **DataSharePredicates** object that sorts data in descending order.
128
129Currently, both the RDB stote and KV store support this predicate.
130
131**System capability**: SystemCapability.DistributedDataManager.DataShare.Core
132
133**Atomic service API**: This API can be used in atomic services since API version 20.
134
135**Parameters**
136
137| Name| Type  | Mandatory| Description              |
138| ------ | ------ | ---- | ------------------ |
139| field  | string | Yes  | Column name in the database table.<br>If this parameter is set to **undefined** or **null**, the predicate used is invalid. |
140
141**Return value**
142
143| Type                                       | Description                      |
144| ------------------------------------------- | -------------------------- |
145| [DataSharePredicates](#datasharepredicates) | **DataSharePredicates** object created.|
146
147**Example**
148
149```ts
150let predicates = new dataSharePredicates.DataSharePredicates();
151predicates.orderByDesc("AGE");
152```
153
154### limit<sup>10+</sup>
155
156limit(total: number, offset: number): DataSharePredicates
157
158Creates a **DataSharePredicates** object to specify the number of records in the result and the start position.
159
160Currently, both the RDB stote and KV store support this predicate.
161
162**System capability**: SystemCapability.DistributedDataManager.DataShare.Core
163
164**Atomic service API**: This API can be used in atomic services since API version 20.
165
166**Parameters**
167
168| Name  | Type  | Mandatory| Description          |
169| -------- | ------ | ---- | -------------- |
170| total    | number | Yes  | Maximum number of records.<br>If the KV store is used and **total** is **undefined** or **null**, the maximum number of records is 0. For details about the value range, see the description of this parameter in [limit](./js-apis-distributedKVStore.md#limit).<br>If the RDB store is used and **total** is **undefined** or **null**, the maximum number of records is not limited. For details about the value range, see the description of this parameter in [limitAs](./js-apis-distributedKVStore.md#limit). |
171| offset | number | Yes  | Start position of the query result.<br>If this parameter is set to **undefined** or **null**, the start position is the beginning of the result set.<br>For details about the value range in a KV store, see the description of this parameter in [limit](./js-apis-distributedKVStore.md#limit).<br>For details about the value range in an RDB store, see the description of the **rowOffset** parameter in [offsetAs](arkts-apis-data-relationalStore-RdbPredicates.md#offsetas).|
172
173**Return value**
174
175| Type                                       | Description                      |
176| ------------------------------------------- | -------------------------- |
177| [DataSharePredicates](#datasharepredicates) | **DataSharePredicates** object created.|
178
179**Example**
180
181```ts
182let predicates = new dataSharePredicates.DataSharePredicates();
183predicates.equalTo("NAME", "Rose").limit(10, 3);
184```
185
186### in<sup>10+</sup>
187
188in(field: string, value: Array&lt;ValueType&gt;): DataSharePredicates
189
190Sets a **DataSharePredicates** object to match the data that is within the specified range.
191
192Currently, both the RDB stote and KV store support this predicate.
193
194**System capability**: SystemCapability.DistributedDataManager.DataShare.Core
195
196**Atomic service API**: This API can be used in atomic services since API version 20.
197
198**Parameters**
199
200| Name | Type            | Mandatory| Description                                   |
201| ------- | ---------------- | ---- | --------------------------------------- |
202| field   | string           | Yes| Column name in the database table.<br>If this parameter is set to **undefined** or **null**, the predicate used is invalid.                  |
203| value | Array&lt;[ValueType](js-apis-data-valuesBucket.md#valuetype)&gt; | Yes  | Array of the values to match.|
204
205**Return value**
206
207| Type                                       | Description                      |
208| ------------------------------------------- | -------------------------- |
209| [DataSharePredicates](#datasharepredicates) | **DataSharePredicates** object created.|
210
211**Example**
212
213```ts
214let predicates = new dataSharePredicates.DataSharePredicates();
215predicates.in("AGE", [18, 20]);
216```
217
218 <!--no_check-->