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