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