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 { ResultSet } from './data/rdb/resultSet'; 17 18/** 19 * Provides methods for rdbStore create and delete. 20 * 21 * @since 7 22 * @sysCap SystemCapability.Data.DATA_APPDATAMGR 23 * @devices phone, tablet, tv, wearable, car 24 * @import import data_rdb from '@ohos.data.rdb'; 25 * @permission N/A 26 */ 27declare namespace rdb { 28 /** 29 * Obtains an RDB store. 30 * 31 * You can set parameters of the RDB store as required. In general, this method is recommended 32 * to obtain a rdb store. 33 * 34 * @note N/A 35 * @since 7 36 * @sysCap SystemCapability.Data.DATA_APPDATAMGR 37 * @devices phone, tablet, tv, wearable, car 38 * @param config Indicates the configuration of the database related to this RDB store. The configurations include 39 * the database path, storage mode, and whether the database is read-only. 40 * @param version Indicates the database version for upgrade or downgrade. 41 * @return Returns an RDB store {@link ohos.data.rdb.RdbStore}. 42 */ 43 function getRdbStore(config: StoreConfig, version: number, callback: AsyncCallback<RdbStore>): void; 44 function getRdbStore(config: StoreConfig, version: number): Promise<RdbStore>; 45 46 /** 47 * Deletes the database with a specified name. 48 * 49 * @note N/A 50 * @since 7 51 * @sysCap SystemCapability.Data.DATA_APPDATAMGR 52 * @devices phone, tablet, tv, wearable, car 53 * @param name Indicates the database name. 54 * @return Returns true if the database is deleted; returns false otherwise. 55 */ 56 function deleteRdbStore(name: string, callback: AsyncCallback<void>): void; 57 function deleteRdbStore(name: string): Promise<void>; 58 59 /** 60 * Provides methods for managing the relational database (RDB). 61 * 62 * This class provides methods for creating, querying, updating, and deleting RDBs. 63 * 64 * @since 7 65 * @sysCap SystemCapability.Data.DATA_APPDATAMGR 66 * @devices phone, tablet, tv, wearable, car 67 * @import import data_rdb from '@ohos.data.rdb'; 68 * @permission N/A 69 */ 70 interface RdbStore { 71 /** 72 * Inserts a row of data into the target table. 73 * 74 * @note N/A 75 * @since 7 76 * @sysCap SystemCapability.Data.DATA_APPDATAMGR 77 * @devices phone, tablet, tv, wearable, car 78 * @param name Indicates the target table. 79 * @param values Indicates the row of data to be inserted into the table. 80 * @return Returns the row ID if the operation is successful; returns -1 otherwise. 81 */ 82 insert(name: string, values: ValuesBucket, callback: AsyncCallback<number>): void; 83 insert(name: string, values: ValuesBucket): Promise<number>; 84 85 /** 86 * Updates data in the database based on a a specified instance object of rdbPredicates. 87 * 88 * @note N/A 89 * @since 7 90 * @sysCap SystemCapability.Data.DATA_APPDATAMGR 91 * @devices phone, tablet, tv, wearable, car 92 * @param values Indicates the row of data to be updated in the database.The key-value pairs are associated with column names of the database table. 93 * @param rdbPredicates Indicates the specified update condition by the instance object of RdbPredicates. 94 * @return Returns the number of affected rows. 95 */ 96 update(values: ValuesBucket, rdbPredicates: RdbPredicates, callback: AsyncCallback<number>): void; 97 update(values: ValuesBucket, rdbPredicates: RdbPredicates): Promise<number>; 98 99 /** 100 * Deletes data from the database based on a specified instance object of rdbPredicates. 101 * 102 * @note N/A 103 * @since 7 104 * @sysCap SystemCapability.Data.DATA_APPDATAMGR 105 * @devices phone, tablet, tv, wearable, car 106 * @param rdbPredicates Indicates the specified delete condition by the instance object of RdbPredicates. 107 * @return Returns the number of affected rows. 108 */ 109 delete(rdbPredicates: RdbPredicates, callback: AsyncCallback<number>): void; 110 delete(rdbPredicates: RdbPredicates): Promise<number>; 111 112 /** 113 * Queries data in the database based on specified conditions. 114 * 115 * @note N/A 116 * @since 7 117 * @sysCap SystemCapability.Data.DATA_APPDATAMGR 118 * @devices phone, tablet, tv, wearable, car 119 * @param rdbPredicates Indicates the specified query condition by the instance object of RdbPredicates. 120 * @param columns Indicates the columns to query. If the value is null, the query applies to all columns. 121 * @return Returns a ResultSet object if the operation is successful; 122 */ 123 query(rdbPredicates: RdbPredicates, columns: Array<string>, callback: AsyncCallback<ResultSet>): void; 124 query(rdbPredicates: RdbPredicates, columns: Array<string>): Promise<ResultSet>; 125 126 /** 127 * Executes an SQL statement that contains specified parameters but returns no value. 128 * 129 * @note N/A 130 * @since 7 131 * @sysCap SystemCapability.Data.DATA_APPDATAMGR 132 * @devices phone, tablet, tv, wearable, car 133 * @param sql Indicates the SQL statement to execute. 134 * @param bindArgs Indicates the values of the parameters in the SQL statement. The values are strings. 135 */ 136 executeSql(sql: string, bindArgs: Array<ValueType>, callback: AsyncCallback<void>): void; 137 executeSql(sql: string, bindArgs: Array<ValueType>): Promise<void>; 138 } 139 140 /** 141 * Indicates possible value types 142 * 143 * @since 7 144 * @sysCap SystemCapability.Data.DATA_APPDATAMGR 145 * @devices phone, tablet, tv, wearable, car 146 * @import import data_rdb from '@ohos.data.rdb'; 147 * @permission N/A 148 */ 149 type ValueType = number | string | boolean; 150 151 /** 152 * Values in buckets are stored in key-value pairs 153 * 154 * @since 7 155 * @sysCap SystemCapability.Data.DATA_APPDATAMGR 156 * @devices phone, tablet, tv, wearable, car 157 * @import import data_rdb from '@ohos.data.rdb'; 158 * @permission N/A 159 */ 160 type ValuesBucket = { 161 [key: string]: ValueType | Uint8Array | null; 162 } 163 164 /** 165 * Manages relational database configurations. 166 * 167 * @since 7 168 * @sysCap SystemCapability.Data.DATA_APPDATAMGR 169 * @devices phone, tablet, tv, wearable, car 170 * @import import data_rdb from '@ohos.data.rdb'; 171 * @permission N/A 172 */ 173 interface StoreConfig { 174 /** 175 * Indicates the name of the database file 176 * 177 * @since 7 178 * @sysCap SystemCapability.Data.DATA_APPDATAMGR 179 */ 180 name: string; 181 } 182 183 /** 184 * Manages relational database configurations. 185 * 186 * @since 7 187 * @sysCap SystemCapability.Data.DATA_APPDATAMGR 188 * @devices phone, tablet, tv, wearable, car 189 * @import import data_rdb from '@ohos.data.rdb'; 190 * @permission N/A 191 */ 192 class RdbPredicates { 193 /** 194 * A parameterized constructor used to create an RdbPredicates instance. 195 * name Indicates the table name of the database. 196 * 197 * @note N/A 198 * @since 7 199 * @sysCap SystemCapability.Data.DATA_APPDATAMGR 200 * @devices phone, tablet, tv, wearable, car 201 */ 202 constructor(name: string) 203 204 /** 205 * Configures the RdbPredicates to match the field whose data type is ValueType and value is equal 206 * to a specified value. 207 * 208 * @note This method is similar to = of the SQL statement. 209 * @since 7 210 * @sysCap SystemCapability.Data.DATA_APPDATAMGR 211 * @devices phone, tablet, tv, wearable, car 212 * @param field Indicates the column name in the database table. 213 * @param value Indicates the value to match with the RdbPredicates. 214 * @return Returns the RdbPredicates that match the specified field. 215 */ 216 equalTo(field: string, value: ValueType): RdbPredicates; 217 218 /** 219 * Configures the RdbPredicates to match the field whose data type is ValueType and value is unequal to 220 * a specified value. 221 * 222 * @note This method is similar to != of the SQL statement. 223 * @since 7 224 * @sysCap SystemCapability.Data.DATA_APPDATAMGR 225 * @devices phone, tablet, tv, wearable, car 226 * @param field Indicates the column name in the database table. 227 * @param value Indicates the value to match with the RdbPredicates. 228 * @return Returns the RdbPredicates that match the specified field. 229 */ 230 notEqualTo(field: string, value: ValueType): RdbPredicates; 231 232 /** 233 * Adds a left parenthesis to the RdbPredicates. 234 * 235 * @note This method is similar to ( of the SQL statement and needs to be used together with endWrap(). 236 * @since 7 237 * @sysCap SystemCapability.Data.DATA_APPDATAMGR 238 * @devices phone, tablet, tv, wearable, car 239 * @return Returns the RdbPredicates with the left parenthesis. 240 */ 241 beginWrap(): RdbPredicates; 242 243 /** 244 * Adds a right parenthesis to the RdbPredicates. 245 * 246 * @note This method is similar to ) of the SQL statement and needs to be used together 247 * with beginWrap(). 248 * @since 7 249 * @sysCap SystemCapability.Data.DATA_APPDATAMGR 250 * @devices phone, tablet, tv, wearable, car 251 * @return Returns the RdbPredicates with the right parenthesis. 252 */ 253 endWrap(): RdbPredicates; 254 255 /** 256 * Adds an or condition to the RdbPredicates. 257 * 258 * @note This method is similar to or of the SQL statement. 259 * @since 7 260 * @sysCap SystemCapability.Data.DATA_APPDATAMGR 261 * @devices phone, tablet, tv, wearable, car 262 * @return Returns the RdbPredicates with the or condition. 263 */ 264 or(): RdbPredicates; 265 266 /** 267 * Adds an and condition to the RdbPredicates. 268 * 269 * @note This method is similar to and of the SQL statement. 270 * @since 7 271 * @sysCap SystemCapability.Data.DATA_APPDATAMGR 272 * @devices phone, tablet, tv, wearable, car 273 * @return Returns the RdbPredicates with the and condition. 274 */ 275 and(): RdbPredicates; 276 277 /** 278 * Configures the RdbPredicates to match the field whose data type is string and value 279 * contains a specified value. 280 * 281 * @note This method is similar to contains of the SQL statement. 282 * @since 7 283 * @sysCap SystemCapability.Data.DATA_APPDATAMGR 284 * @devices phone, tablet, tv, wearable, car 285 * @param field Indicates the column name in the database table. 286 * @param value Indicates the value to match with the RdbPredicates. 287 * @return Returns the RdbPredicates that match the specified field. 288 */ 289 contains(field: string, value: string): RdbPredicates; 290 291 /** 292 * Configures the RdbPredicates to match the field whose data type is string and value starts 293 * with a specified string. 294 * 295 * @note This method is similar to value% of the SQL statement. 296 * @since 7 297 * @sysCap SystemCapability.Data.DATA_APPDATAMGR 298 * @devices phone, tablet, tv, wearable, car 299 * @param field Indicates the column name in the database table. 300 * @param value Indicates the value to match with the RdbPredicates. 301 * @return Returns the RdbPredicates that match the specified field. 302 */ 303 beginsWith(field: string, value: string): RdbPredicates; 304 305 /** 306 * Configures the RdbPredicates to match the field whose data type is string and value 307 * ends with a specified string. 308 * 309 * @note This method is similar to %value of the SQL statement. 310 * @since 7 311 * @sysCap SystemCapability.Data.DATA_APPDATAMGR 312 * @devices phone, tablet, tv, wearable, car 313 * @param field Indicates the column name in the database table. 314 * @param value Indicates the value to match with the RdbPredicates. 315 * @return Returns the RdbPredicates that match the specified field. 316 */ 317 endsWith(field: string, value: string): RdbPredicates; 318 319 /** 320 * Configures the RdbPredicates to match the fields whose value is null. 321 * 322 * @note This method is similar to is null of the SQL statement. 323 * @since 7 324 * @sysCap SystemCapability.Data.DATA_APPDATAMGR 325 * @devices phone, tablet, tv, wearable, car 326 * @param field Indicates the column name in the database table. 327 * @return Returns the RdbPredicates that match the specified field. 328 */ 329 isNull(field: string): RdbPredicates; 330 331 /** 332 * Configures the RdbPredicates to match the specified fields whose value is not null. 333 * 334 * @note This method is similar to is not null of the SQL statement. 335 * @since 7 336 * @sysCap SystemCapability.Data.DATA_APPDATAMGR 337 * @devices phone, tablet, tv, wearable, car 338 * @param field Indicates the column name in the database table. 339 * @return Returns the RdbPredicates that match the specified field. 340 */ 341 isNotNull(field: string): RdbPredicates; 342 343 /** 344 * Configures the RdbPredicates to match the fields whose data type is string and value is 345 * similar to a specified string. 346 * 347 * @note This method is similar to like of the SQL statement. 348 * @since 7 349 * @sysCap SystemCapability.Data.DATA_APPDATAMGR 350 * @devices phone, tablet, tv, wearable, car 351 * @param field Indicates the column name in the database table. 352 * @param value Indicates the value to match with the RdbPredicates. The percent sign (%) in the value 353 * is a wildcard (like * in a regular expression). 354 * @return Returns the RdbPredicates that match the specified field. 355 */ 356 like(field: string, value: string): RdbPredicates; 357 358 /** 359 * Configures RdbPredicates to match the specified field whose data type is string and the value contains 360 * a wildcard. 361 * 362 * @note Different from like, the input parameters of this method are case-sensitive. 363 * @since 7 364 * @sysCap SystemCapability.Data.DATA_APPDATAMGR 365 * @devices phone, tablet, tv, wearable, car 366 * @param field Indicates the column name in the database table. 367 * @param value Indicates the value to match with RdbPredicates. 368 * @return Returns the SQL statement with the specified RdbPredicates. 369 */ 370 glob(field: string, value: string): RdbPredicates; 371 372 /** 373 * Restricts the value of the field to the range between low value and high value. 374 * 375 * @note N/A 376 * @since 7 377 * @sysCap SystemCapability.Data.DATA_APPDATAMGR 378 * @devices phone, tablet, tv, wearable, car 379 * @param field Indicates the column name. 380 * @param low Indicates the minimum value. 381 * @param high Indicates the maximum value. 382 * @return Returns the SQL query statement with the specified RdbPredicates. 383 */ 384 between(field: string, low: ValueType, high: ValueType): RdbPredicates; 385 386 /** 387 * Configures RdbPredicates to match the specified field whose data type is int and value is 388 * out of 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 low Indicates the minimum value to match with DataAbilityPredicates. 396 * @param high Indicates the maximum value to match with DataAbilityPredicates. 397 * @return Returns the SQL query statement with the specified RdbPredicates. 398 */ 399 notBetween(field: string, low: ValueType, high: ValueType): RdbPredicates; 400 401 /** 402 * Restricts the value of the field to be greater than the specified value. 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. 409 * @param value Indicates the String field. 410 * @return Returns the SQL query statement with the specified RdbPredicates. 411 */ 412 greaterThan(field: string, value: ValueType): RdbPredicates; 413 414 /** 415 * Restricts the value of the field to be smaller than the specified value. 416 * 417 * @note N/A 418 * @since 7 419 * @sysCap SystemCapability.Data.DATA_APPDATAMGR 420 * @devices phone, tablet, tv, wearable, car 421 * @param field Indicates the column name. 422 * @param value Indicates the String field. 423 * @return Returns the SQL query statement with the specified RdbPredicates. 424 */ 425 lessThan(field: string, value: ValueType): RdbPredicates; 426 427 /** 428 * Restricts the value of the field to be greater than or equal to the specified value. 429 * 430 * @note N/A 431 * @since 7 432 * @sysCap SystemCapability.Data.DATA_APPDATAMGR 433 * @devices phone, tablet, tv, wearable, car 434 * @param field Indicates the column name. 435 * @param value Indicates the String field. 436 * @return Returns the SQL query statement with the specified RdbPredicates. 437 */ 438 greaterThanOrEqualTo(field: string, value: ValueType): RdbPredicates; 439 440 /** 441 * Restricts the value of the field to be smaller than or equal to the specified value. 442 * 443 * @note N/A 444 * @since 7 445 * @sysCap SystemCapability.Data.DATA_APPDATAMGR 446 * @devices phone, tablet, tv, wearable, car 447 * @param field Indicates the column name. 448 * @param value Indicates the String field. 449 * @return Returns the SQL query statement with the specified RdbPredicates. 450 */ 451 lessThanOrEqualTo(field: string, value: ValueType): RdbPredicates; 452 453 /** 454 * Restricts the ascending order of the return list. When there are several orders, 455 * the one close to the head has the highest priority. 456 * 457 * @note N/A 458 * @since 7 459 * @sysCap SystemCapability.Data.DATA_APPDATAMGR 460 * @devices phone, tablet, tv, wearable, car 461 * @param field Indicates the column name for sorting the return list. 462 * @return Returns the SQL query statement with the specified RdbPredicates. 463 */ 464 orderByAsc(field: string): RdbPredicates; 465 466 /** 467 * Restricts the descending order of the return list. When there are several orders, 468 * the one close to the head has the highest priority. 469 * 470 * @note N/A 471 * @since 7 472 * @sysCap SystemCapability.Data.DATA_APPDATAMGR 473 * @devices phone, tablet, tv, wearable, car 474 * @param field Indicates the column name for sorting the return list. 475 * @return Returns the SQL query statement with the specified RdbPredicates. 476 */ 477 orderByDesc(field: string): RdbPredicates; 478 479 /** 480 * Restricts each row of the query result to be unique. 481 * 482 * @note N/A 483 * @since 7 484 * @sysCap SystemCapability.Data.DATA_APPDATAMGR 485 * @devices phone, tablet, tv, wearable, car 486 * @return Returns the SQL query statement with the specified RdbPredicates. 487 */ 488 distinct(): RdbPredicates; 489 490 /** 491 * Restricts the max number of return records. 492 * 493 * @note N/A 494 * @since 7 495 * @sysCap SystemCapability.Data.DATA_APPDATAMGR 496 * @devices phone, tablet, tv, wearable, car 497 * @param value Indicates the max length of the return list. 498 * @return Returns the SQL query statement with the specified RdbPredicates. 499 */ 500 limitAs(value: number): RdbPredicates; 501 502 /** 503 * Configures RdbPredicates to specify the start position of the returned result. 504 * 505 * @note Use this method together with limit(int). 506 * @since 7 507 * @sysCap SystemCapability.Data.DATA_APPDATAMGR 508 * @devices phone, tablet, tv, wearable, car 509 * @param rowOffset Indicates the start position of the returned result. The value is a positive integer. 510 * @return Returns the SQL query statement with the specified AbsPredicates. 511 */ 512 offsetAs(rowOffset: number): RdbPredicates; 513 514 /** 515 * Configures RdbPredicates to group query results by specified columns. 516 * 517 * @note N/A 518 * @since 7 519 * @sysCap SystemCapability.Data.DATA_APPDATAMGR 520 * @devices phone, tablet, tv, wearable, car 521 * @param fields Indicates the specified columns by which query results are grouped. 522 * @return Returns the RdbPredicates with the specified columns by which query results are grouped. 523 */ 524 groupBy(fields: Array<string>): RdbPredicates; 525 526 /** 527 * Configures RdbPredicates to specify the index column. 528 * 529 * @note Before using this method, you need to create an index column. 530 * @since 7 531 * @sysCap SystemCapability.Data.DATA_APPDATAMGR 532 * @devices phone, tablet, tv, wearable, car 533 * @param indexName Indicates the name of the index column. 534 * @return Returns RdbPredicates with the specified index column. 535 */ 536 indexedBy(field: string): RdbPredicates; 537 538 /** 539 * Configures RdbPredicates to match the specified field whose data type is ValueType array and values 540 * are within a given range. 541 * 542 * @note N/A 543 * @since 7 544 * @sysCap SystemCapability.Data.DATA_APPDATAMGR 545 * @devices phone, tablet, tv, wearable, car 546 * @param field Indicates the column name in the database table. 547 * @param values Indicates the values to match with RdbPredicates. 548 * @return Returns RdbPredicates that matches the specified field. 549 */ 550 in(field: string, value: Array<ValueType>): RdbPredicates; 551 552 /** 553 * Configures RdbPredicates to match the specified field whose data type is ValueType array and values 554 * are out of a given range. 555 * 556 * @note N/A 557 * @since 7 558 * @sysCap SystemCapability.Data.DATA_APPDATAMGR 559 * @devices phone, tablet, tv, wearable, car 560 * @param field Indicates the column name in the database table. 561 * @param values Indicates the values to match with RdbPredicates. 562 * @return Returns RdbPredicates that matches the specified field. 563 */ 564 notIn(field: string, value: Array<ValueType>): RdbPredicates; 565 } 566} 567 568export default rdb; 569