1/* 2 * Copyright (c) 2021 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15import { AsyncCallback } from './basic'; 16import rdb from './@ohos.data.rdb'; 17 18/** 19 * Provides predicates for implementing diverse query methods. 20 * 21 * @since 7 22 * @sysCap SystemCapability.Data.DATA_APPDATAMGR 23 * @devices phone, tablet, tv, wearable, car 24 * @import import data_dataAbility from '@ohos.data.dataAbility'; 25 * @permission N/A 26 */ 27declare namespace dataAbility { 28 /** 29 * Create an RdbPredicates by table name and DataAbilityPredicates. 30 * 31 * @note This method is similar to = of the SQL statement. 32 * @since 7 33 * @sysCap SystemCapability.Data.DATA_APPDATAMGR 34 * @devices phone, tablet, tv, wearable, car 35 * @param name Indicates the table name. 36 * @param dataAbilityPredicates Indicates the dataAbility predicates. 37 * @return Returns an RdbPredicates. 38 */ 39 function createRdbPredicates(name: string, dataAbilityPredicates: DataAbilityPredicates): rdb.RdbPredicates; 40 41 /** 42 * Manages relational database configurations. 43 * 44 * @since 7 45 * @sysCap SystemCapability.Data.DATA_APPDATAMGR 46 * @devices phone, tablet, tv, wearable, car 47 * @import import data_dataAbility from '@ohos.data.dataAbility'; 48 * @permission N/A 49 */ 50 class DataAbilityPredicates { 51 /** 52 * Configures the DataAbilityPredicates to match the field whose data type is ValueType and value is equal 53 * to a specified value. 54 * 55 * @note This method is similar to = of the SQL statement. 56 * @since 7 57 * @sysCap SystemCapability.Data.DATA_APPDATAMGR 58 * @devices phone, tablet, tv, wearable, car 59 * @param field Indicates the column name in the database table. 60 * @param value Indicates the value to match with the DataAbilityPredicates. 61 * @return Returns the DataAbilityPredicates that match the specified field. 62 */ 63 equalTo(field: string, value: ValueType): DataAbilityPredicates; 64 65 /** 66 * Configures the DataAbilityPredicates to match the field whose data type is ValueType and value is unequal to 67 * a specified value. 68 * 69 * @note This method is similar to != of the SQL statement. 70 * @since 7 71 * @sysCap SystemCapability.Data.DATA_APPDATAMGR 72 * @devices phone, tablet, tv, wearable, car 73 * @param field Indicates the column name in the database table. 74 * @param value Indicates the value to match with the DataAbilityPredicates. 75 * @return Returns the DataAbilityPredicates that match the specified field. 76 */ 77 notEqualTo(field: string, value: ValueType): DataAbilityPredicates; 78 79 /** 80 * Adds a left parenthesis to the DataAbilityPredicates. 81 * 82 * @note This method is similar to ( of the SQL statement and needs to be used together with endWrap(). 83 * @since 7 84 * @sysCap SystemCapability.Data.DATA_APPDATAMGR 85 * @devices phone, tablet, tv, wearable, car 86 * @return Returns the DataAbilityPredicates with the left parenthesis. 87 */ 88 beginWrap(): DataAbilityPredicates; 89 90 /** 91 * Adds a right parenthesis to the DataAbilityPredicates. 92 * 93 * @note This method is similar to ) of the SQL statement and needs to be used together 94 * with beginWrap(). 95 * @since 7 96 * @sysCap SystemCapability.Data.DATA_APPDATAMGR 97 * @devices phone, tablet, tv, wearable, car 98 * @return Returns the DataAbilityPredicates with the right parenthesis. 99 */ 100 endWrap(): DataAbilityPredicates; 101 102 /** 103 * Adds an or condition to the DataAbilityPredicates. 104 * 105 * @note This method is similar to or of the SQL statement. 106 * @since 7 107 * @sysCap SystemCapability.Data.DATA_APPDATAMGR 108 * @devices phone, tablet, tv, wearable, car 109 * @return Returns the DataAbilityPredicates with the or condition. 110 */ 111 or(): DataAbilityPredicates; 112 113 /** 114 * Adds an and condition to the DataAbilityPredicates. 115 * 116 * @note This method is similar to and of the SQL statement. 117 * @since 7 118 * @sysCap SystemCapability.Data.DATA_APPDATAMGR 119 * @devices phone, tablet, tv, wearable, car 120 * @return Returns the DataAbilityPredicates with the and condition. 121 */ 122 and(): DataAbilityPredicates; 123 124 /** 125 * Configures the DataAbilityPredicates to match the field whose data type is string and value 126 * contains a specified value. 127 * 128 * @note This method is similar to contains of the SQL statement. 129 * @since 7 130 * @sysCap SystemCapability.Data.DATA_APPDATAMGR 131 * @devices phone, tablet, tv, wearable, car 132 * @param field Indicates the column name in the database table. 133 * @param value Indicates the value to match with the DataAbilityPredicates. 134 * @return Returns the DataAbilityPredicates that match the specified field. 135 */ 136 contains(field: string, value: string): DataAbilityPredicates; 137 138 /** 139 * Configures the DataAbilityPredicates to match the field whose data type is string and value starts 140 * with a specified string. 141 * 142 * @note This method is similar to value% of the SQL statement. 143 * @since 7 144 * @sysCap SystemCapability.Data.DATA_APPDATAMGR 145 * @devices phone, tablet, tv, wearable, car 146 * @param field Indicates the column name in the database table. 147 * @param value Indicates the value to match with the DataAbilityPredicates. 148 * @return Returns the DataAbilityPredicates that match the specified field. 149 */ 150 beginsWith(field: string, value: string): DataAbilityPredicates; 151 152 /** 153 * Configures the DataAbilityPredicates to match the field whose data type is string and value 154 * ends with a specified string. 155 * 156 * @note This method is similar to %value of the SQL statement. 157 * @since 7 158 * @sysCap SystemCapability.Data.DATA_APPDATAMGR 159 * @devices phone, tablet, tv, wearable, car 160 * @param field Indicates the column name in the database table. 161 * @param value Indicates the value to match with the DataAbilityPredicates. 162 * @return Returns the DataAbilityPredicates that match the specified field. 163 */ 164 endsWith(field: string, value: string): DataAbilityPredicates; 165 166 /** 167 * Configures the DataAbilityPredicates to match the fields whose value is null. 168 * 169 * @note This method is similar to is null of the SQL statement. 170 * @since 7 171 * @sysCap SystemCapability.Data.DATA_APPDATAMGR 172 * @devices phone, tablet, tv, wearable, car 173 * @param field Indicates the column name in the database table. 174 * @return Returns the DataAbilityPredicates that match the specified field. 175 */ 176 isNull(field: string): DataAbilityPredicates; 177 178 /** 179 * Configures the DataAbilityPredicates to match the specified fields whose value is not null. 180 * 181 * @note This method is similar to is not null of the SQL statement. 182 * @since 7 183 * @sysCap SystemCapability.Data.DATA_APPDATAMGR 184 * @devices phone, tablet, tv, wearable, car 185 * @param field Indicates the column name in the database table. 186 * @return Returns the DataAbilityPredicates that match the specified field. 187 */ 188 isNotNull(field: string): DataAbilityPredicates; 189 190 /** 191 * Configures the DataAbilityPredicates to match the fields whose data type is string and value is 192 * similar to a specified string. 193 * 194 * @note This method is similar to like of the SQL statement. 195 * @since 7 196 * @sysCap SystemCapability.Data.DATA_APPDATAMGR 197 * @devices phone, tablet, tv, wearable, car 198 * @param field Indicates the column name in the database table. 199 * @param value Indicates the value to match with the DataAbilityPredicates. The percent sign (%) in the value 200 * is a wildcard (like * in a regular expression). 201 * @return Returns the DataAbilityPredicates that match the specified field. 202 */ 203 like(field: string, value: string): DataAbilityPredicates; 204 205 /** 206 * Configures DataAbilityPredicates to match the specified field whose data type is string and the value contains 207 * a wildcard. 208 * 209 * @note Different from like, the input parameters of this method are case-sensitive. 210 * @since 7 211 * @sysCap SystemCapability.Data.DATA_APPDATAMGR 212 * @devices phone, tablet, tv, wearable, car 213 * @param field Indicates the column name in the database table. 214 * @param value Indicates the value to match with DataAbilityPredicates. 215 * @return Returns the SQL statement with the specified DataAbilityPredicates. 216 */ 217 glob(field: string, value: string): DataAbilityPredicates; 218 219 /** 220 * Restricts the value of the field to the range between low value and high value. 221 * 222 * @note N/A 223 * @since 7 224 * @sysCap SystemCapability.Data.DATA_APPDATAMGR 225 * @devices phone, tablet, tv, wearable, car 226 * @param field Indicates the column name. 227 * @param low Indicates the minimum value. 228 * @param high Indicates the maximum value. 229 * @return Returns the SQL query statement with the specified DataAbilityPredicates. 230 */ 231 between(field: string, low: ValueType, high: ValueType): DataAbilityPredicates; 232 233 /** 234 * Configures DataAbilityPredicates to match the specified field whose data type is int and value is 235 * out of a given range. 236 * 237 * @note N/A 238 * @since 7 239 * @sysCap SystemCapability.Data.DATA_APPDATAMGR 240 * @devices phone, tablet, tv, wearable, car 241 * @param field Indicates the column name in the database table. 242 * @param low Indicates the minimum value to match with DataAbilityPredicates}. 243 * @param high Indicates the maximum value to match with DataAbilityPredicates}. 244 * @return Returns the SQL query statement with the specified DataAbilityPredicates. 245 */ 246 notBetween(field: string, low: ValueType, high: ValueType): DataAbilityPredicates; 247 248 /** 249 * Restricts the value of the field to be greater than the specified value. 250 * 251 * @note N/A 252 * @since 7 253 * @sysCap SystemCapability.Data.DATA_APPDATAMGR 254 * @devices phone, tablet, tv, wearable, car 255 * @param field Indicates the column name. 256 * @param value Indicates the String field. 257 * @return Returns the SQL query statement with the specified DataAbilityPredicates. 258 */ 259 greaterThan(field: string, value: ValueType): DataAbilityPredicates; 260 261 /** 262 * Restricts the value of the field to be smaller than the specified value. 263 * 264 * @note N/A 265 * @since 7 266 * @sysCap SystemCapability.Data.DATA_APPDATAMGR 267 * @devices phone, tablet, tv, wearable, car 268 * @param field Indicates the column name. 269 * @param value Indicates the String field. 270 * @return Returns the SQL query statement with the specified DataAbilityPredicates. 271 */ 272 lessThan(field: string, value: ValueType): DataAbilityPredicates; 273 274 /** 275 * Restricts the value of the field to be greater than or equal to the specified value. 276 * 277 * @note N/A 278 * @since 7 279 * @sysCap SystemCapability.Data.DATA_APPDATAMGR 280 * @devices phone, tablet, tv, wearable, car 281 * @param field Indicates the column name. 282 * @param value Indicates the String field. 283 * @return Returns the SQL query statement with the specified DataAbilityPredicates. 284 */ 285 greaterThanOrEqualTo(field: string, value: ValueType): DataAbilityPredicates; 286 287 /** 288 * Restricts the value of the field to be smaller than or equal to the specified value. 289 * 290 * @note N/A 291 * @since 7 292 * @sysCap SystemCapability.Data.DATA_APPDATAMGR 293 * @devices phone, tablet, tv, wearable, car 294 * @param field Indicates the column name. 295 * @param value Indicates the String field. 296 * @return Returns the SQL query statement with the specified DataAbilityPredicates. 297 */ 298 lessThanOrEqualTo(field: string, value: ValueType): DataAbilityPredicates; 299 300 /** 301 * Restricts the ascending order of the return list. When there are several orders, 302 * the one close to the head has the highest priority. 303 * 304 * @note N/A 305 * @since 7 306 * @sysCap SystemCapability.Data.DATA_APPDATAMGR 307 * @devices phone, tablet, tv, wearable, car 308 * @param field Indicates the column name for sorting the return list. 309 * @return Returns the SQL query statement with the specified DataAbilityPredicates. 310 */ 311 orderByAsc(field: string): DataAbilityPredicates; 312 313 /** 314 * Restricts the descending order of the return list. When there are several orders, 315 * the one close to the head has the highest priority. 316 * 317 * @note N/A 318 * @since 7 319 * @sysCap SystemCapability.Data.DATA_APPDATAMGR 320 * @devices phone, tablet, tv, wearable, car 321 * @param field Indicates the column name for sorting the return list. 322 * @return Returns the SQL query statement with the specified DataAbilityPredicates. 323 */ 324 orderByDesc(field: string): DataAbilityPredicates; 325 326 /** 327 * Restricts each row of the query result to be unique. 328 * 329 * @note N/A 330 * @since 7 331 * @sysCap SystemCapability.Data.DATA_APPDATAMGR 332 * @devices phone, tablet, tv, wearable, car 333 * @return Returns the SQL query statement with the specified DataAbilityPredicates. 334 */ 335 distinct(): DataAbilityPredicates; 336 337 /** 338 * Restricts the max number of return records. 339 * 340 * @note N/A 341 * @since 7 342 * @sysCap SystemCapability.Data.DATA_APPDATAMGR 343 * @devices phone, tablet, tv, wearable, car 344 * @param value Indicates the max length of the return list. 345 * @return Returns the SQL query statement with the specified DataAbilityPredicates. 346 * @throws IllegalPredicateException Throws this exception if DataAbilityPredicates are added to a wrong position. 347 */ 348 limitAs(value: number): DataAbilityPredicates; 349 350 /** 351 * Configures DataAbilityPredicates to specify the start position of the returned result. 352 * 353 * @note Use this method together with limit(int). 354 * @since 7 355 * @sysCap SystemCapability.Data.DATA_APPDATAMGR 356 * @devices phone, tablet, tv, wearable, car 357 * @param rowOffset Indicates the start position of the returned result. The value is a positive integer. 358 * @return Returns the SQL query statement with the specified AbsPredicates. 359 */ 360 offsetAs(rowOffset: number): DataAbilityPredicates; 361 362 /** 363 * Configures DataAbilityPredicates to group query results by specified columns. 364 * 365 * @note N/A 366 * @since 7 367 * @sysCap SystemCapability.Data.DATA_APPDATAMGR 368 * @devices phone, tablet, tv, wearable, car 369 * @param fields Indicates the specified columns by which query results are grouped. 370 * @return Returns the DataAbilityPredicates with the specified columns by which query results are grouped. 371 */ 372 groupBy(fields: Array<string>): DataAbilityPredicates; 373 374 /** 375 * Configures DataAbilityPredicates to specify the index column. 376 * 377 * @note Before using this method, you need to create an index column. 378 * @since 7 379 * @sysCap SystemCapability.Data.DATA_APPDATAMGR 380 * @devices phone, tablet, tv, wearable, car 381 * @param indexName Indicates the name of the index column. 382 * @return Returns DataAbilityPredicates with the specified index column. 383 */ 384 indexedBy(field: string): DataAbilityPredicates; 385 386 /** 387 * Configures DataAbilityPredicates to match the specified field whose data type is ValueType array and values 388 * are within a given range. 389 * 390 * @note N/A 391 * @since 7 392 * @sysCap SystemCapability.Data.DATA_APPDATAMGR 393 * @devices phone, tablet, tv, wearable, car 394 * @param field Indicates the column name in the database table. 395 * @param values Indicates the values to match with DataAbilityPredicates. 396 * @return Returns DataAbilityPredicates that matches the specified field. 397 */ 398 in(field: string, value: Array<ValueType>): DataAbilityPredicates; 399 400 /** 401 * Configures {@code DataAbilityPredicates} to match the specified field whose data type is String array and values 402 * are out of a given range. 403 * 404 * @note N/A 405 * @since 7 406 * @sysCap SystemCapability.Data.DATA_APPDATAMGR 407 * @devices phone, tablet, tv, wearable, car 408 * @param field Indicates the column name in the database table. 409 * @param values Indicates the values to match with DataAbilityPredicates. 410 * @return Returns DataAbilityPredicates that matches the specified field. 411 */ 412 notIn(field: string, value: Array<ValueType>): DataAbilityPredicates; 413 } 414 /** 415 * Indicates possible value types 416 * @since 7 417 * @sysCap SystemCapability.Data.DATA_APPDATAMGR 418 * @devices phone, tablet, tv, wearable, car 419 * @import import data_rdb from '@ohos.data.rdb'; 420 * @permission N/A 421 */ 422 type ValueType = number | string | boolean; 423} 424 425export default dataAbility; 426