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