1# @ohos.data.relationalStore (RDB Store) 2 3The relational database (RDB) store manages data based on relational models. With the underlying SQLite database, the RDB store provides a complete mechanism for managing local databases. To satisfy different needs in complicated scenarios, the RDB store offers a series of APIs for performing operations such as adding, deleting, modifying, and querying data, and supports direct execution of SQL statements. 4 5The **relationalStore** module provides the following functions: 6 7- [RdbPredicates](#rdbpredicates): provides predicates indicating the nature, feature, or relationship of a data entity in an RDB store. It is used to define the operation conditions for an RDB store. 8- [RdbStore](#rdbstore): provides APIs for managing data in an RDB store. 9- [ResultSet](#resultset): provides APIs for accessing the result set obtained from the RDB store. 10 11> **NOTE** 12> 13> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. 14 15## Modules to Import 16 17```js 18import relationalStore from '@ohos.data.relationalStore' 19``` 20 21## relationalStore.getRdbStore 22 23getRdbStore(context: Context, config: StoreConfig, callback: AsyncCallback<RdbStore>): void 24 25Obtains an RDB store. This API uses an asynchronous callback to return the result. You can set parameters for the RDB store based on service requirements and call APIs to perform data operations. 26 27**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 28 29**Parameters** 30 31| Name | Type | Mandatory| Description | 32| -------- | ---------------------------------------------- | ---- | ------------------------------------------------------------ | 33| context | Context | Yes | Application context.<br>For details about the application context of the FA model, see [Context](js-apis-inner-app-context.md).<br>For details about the application context of the stage model, see [Context](js-apis-inner-application-uiAbilityContext.md).| 34| config | [StoreConfig](#storeconfig) | Yes | Configuration of the RDB store. | 35| callback | AsyncCallback<[RdbStore](#rdbstore)> | Yes | Callback invoked to return the RDB store obtained. | 36 37**Error codes** 38 39For details about the error codes, see [RDB Error Codes](../errorcodes/errorcode-data-rdb.md). 40 41| **ID**| **Error Message** | 42| ------------ | ----------------------- | 43| 14800010 | If failed delete database by invalid database name. | 44| 14800011 | If failed open database by database corrupted. | 45 46**Example** 47 48FA model: 49 50```js 51 52import featureAbility from '@ohos.ability.featureAbility' 53 54var store; 55 56// Obtain the context. 57let context = featureAbility.getContext(); 58 59const STORE_CONFIG = { 60 name: "RdbTest.db", 61 securityLevel: relationalStore.SecurityLevel.S1 62}; 63 64relationalStore.getRdbStore(context, STORE_CONFIG, function (err, rdbStore) { 65 store = rdbStore; 66 if (err) { 67 console.error(`Get RdbStore failed, err: ${err}`); 68 return; 69 } 70 console.info(`Get RdbStore successfully.`); 71}) 72``` 73 74Stage model: 75 76```ts 77import UIAbility from '@ohos.app.ability.UIAbility' 78 79class EntryAbility extends UIAbility { 80 onWindowStageCreate(windowStage) { 81 var store; 82 const STORE_CONFIG = { 83 name: "RdbTest.db", 84 securityLevel: relationalStore.SecurityLevel.S1 85 }; 86 87 relationalStore.getRdbStore(this.context, STORE_CONFIG, function (err, rdbStore) { 88 store = rdbStore; 89 if (err) { 90 console.error(`Get RdbStore failed, err: ${err}`); 91 return; 92 } 93 console.info(`Get RdbStore successfully.`); 94 }) 95 } 96} 97``` 98 99## relationalStore.getRdbStore 100 101getRdbStore(context: Context, config: StoreConfig): Promise<RdbStore> 102 103Obtains an RDB store. This API uses a promise to return the result. You can set parameters for the RDB store based on service requirements and call APIs to perform data operations. 104 105**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 106 107**Parameters** 108 109| Name | Type | Mandatory| Description | 110| ------- | -------------------------------- | ---- | ------------------------------------------------------------ | 111| context | Context | Yes | Application context.<br>For details about the application context of the FA model, see [Context](js-apis-inner-app-context.md).<br>For details about the application context of the stage model, see [Context](js-apis-inner-application-uiAbilityContext.md).| 112| config | [StoreConfig](#storeconfig) | Yes | Configuration of the RDB store. | 113 114**Return value** 115 116| Type | Description | 117| ----------------------------------------- | --------------------------------- | 118| Promise<[RdbStore](#rdbstore)> | Promise used to return the **RdbStore** object.| 119 120**Error codes** 121 122For details about the error codes, see [RDB Error Codes](../errorcodes/errorcode-data-rdb.md). 123 124| **ID**| **Error Message** | 125| ------------ | ----------------------- | 126| 14800010 | If failed delete database by invalid database name. | 127| 14800011 | If failed open database by database corrupted. | 128 129**Example** 130 131FA model: 132 133```js 134import featureAbility from '@ohos.ability.featureAbility' 135 136var store; 137 138// Obtain the context. 139let context = featureAbility.getContext(); 140 141const STORE_CONFIG = { 142 name: "RdbTest.db", 143 securityLevel: relationalStore.SecurityLevel.S1 144}; 145 146let promise = relationalStore.getRdbStore(context, STORE_CONFIG); 147promise.then(async (rdbStore) => { 148 store = rdbStore; 149 console.info(`Get RdbStore successfully.`); 150}).catch((err) => { 151 console.error(`Get RdbStore failed, err: ${err}`); 152}) 153``` 154 155Stage model: 156 157```ts 158import UIAbility from '@ohos.app.ability.UIAbility' 159 160class EntryAbility extends UIAbility { 161 onWindowStageCreate(windowStage) { 162 var store; 163 const STORE_CONFIG = { 164 name: "RdbTest.db", 165 securityLevel: relationalStore.SecurityLevel.S1 166 }; 167 168 let promise = relationalStore.getRdbStore(this.context, STORE_CONFIG); 169 promise.then(async (rdbStore) => { 170 store = rdbStore; 171 console.info(`Get RdbStore successfully.`) 172 }).catch((err) => { 173 console.error(`Get RdbStore failed, err: ${err}`); 174 }) 175 } 176} 177``` 178 179## relationalStore.deleteRdbStore 180 181deleteRdbStore(context: Context, name: string, callback: AsyncCallback<void>): void 182 183Deletes an RDB store. This API uses an asynchronous callback to return the result. 184 185**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 186 187**Parameters** 188 189| Name | Type | Mandatory| Description | 190| -------- | ------------------------- | ---- | ------------------------------------------------------------ | 191| context | Context | Yes | Application context.<br>For details about the application context of the FA model, see [Context](js-apis-inner-app-context.md).<br>For details about the application context of the stage model, see [Context](js-apis-inner-application-uiAbilityContext.md).| 192| name | string | Yes | Name of the RDB store to delete. | 193| callback | AsyncCallback<void> | Yes | Callback invoked to return the result. | 194 195**Error codes** 196 197For details about the error codes, see [RDB Error Codes](../errorcodes/errorcode-data-rdb.md). 198 199| **ID**| **Error Message** | 200| ------------ | ----------------------- | 201| 14800010 | If failed delete database by invalid database name. | 202 203**Example** 204 205FA model: 206 207```js 208import featureAbility from '@ohos.ability.featureAbility' 209 210// Obtain the context. 211let context = featureAbility.getContext() 212 213relationalStore.deleteRdbStore(context, "RdbTest.db", function (err) { 214 if (err) { 215 console.error(`Delete RdbStore failed, err: ${err}`); 216 return; 217 } 218 console.info(`Delete RdbStore successfully.`); 219}) 220``` 221 222Stage model: 223 224```ts 225import UIAbility from '@ohos.app.ability.UIAbility' 226 227class EntryAbility extends UIAbility { 228 onWindowStageCreate(windowStage){ 229 relationalStore.deleteRdbStore(this.context, "RdbTest.db", function (err) { 230 if (err) { 231 console.error(`Delete RdbStore failed, err: ${err}`); 232 return; 233 } 234 console.info(`Delete RdbStore successfully.`); 235 }) 236 } 237} 238``` 239 240## relationalStore.deleteRdbStore 241 242deleteRdbStore(context: Context, name: string): Promise<void> 243 244Deletes an RDB store. This API uses a promise to return the result. 245 246**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 247 248**Parameters** 249 250| Name | Type | Mandatory| Description | 251| ------- | ------- | ---- | ------------------------------------------------------------ | 252| context | Context | Yes | Application context.<br>For details about the application context of the FA model, see [Context](js-apis-inner-app-context.md).<br>For details about the application context of the stage model, see [Context](js-apis-inner-application-uiAbilityContext.md).| 253| name | string | Yes | Name of the RDB store to delete. | 254 255**Return value** 256 257| Type | Description | 258| ------------------- | ------------------------- | 259| Promise<void> | Promise that returns no value.| 260 261**Error codes** 262 263For details about the error codes, see [RDB Error Codes](../errorcodes/errorcode-data-rdb.md). 264 265| **ID**| **Error Message** | 266| ------------ | ----------------------- | 267| 14800010 | If failed delete database by invalid database name. | 268 269**Example** 270 271FA model: 272 273```js 274import featureAbility from '@ohos.ability.featureAbility' 275 276// Obtain the context. 277let context = featureAbility.getContext(); 278 279let promise = relationalStore.deleteRdbStore(context, "RdbTest.db"); 280promise.then(()=>{ 281 console.info(`Delete RdbStore successfully.`); 282}).catch((err) => { 283 console.error(`Delete RdbStore failed, err: ${err}`); 284}) 285``` 286 287Stage model: 288 289```ts 290import UIAbility from '@ohos.app.ability.UIAbility' 291 292class EntryAbility extends UIAbility { 293 onWindowStageCreate(windowStage){ 294 let promise = relationalStore.deleteRdbStore(this.context, "RdbTest.db"); 295 promise.then(()=>{ 296 console.info(`Delete RdbStore successfully.`); 297 }).catch((err) => { 298 console.error(`Delete RdbStore failed, err: ${err}`); 299 }) 300 } 301} 302``` 303 304## StoreConfig 305 306Defines the RDB store configuration. 307 308**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 309 310| Name | Type | Mandatory| Description | 311| ------------- | ------------- | ---- | --------------------------------------------------------- | 312| name | string | Yes | Database file name. | 313| securityLevel | [SecurityLevel](#securitylevel) | Yes | Security level of the RDB store. | 314| encrypt | boolean | No | Whether to encrypt the RDB store.<br> The value **true** means to encrypt the RDB store;<br> the value **false** means the opposite.| 315 316## SecurityLevel 317 318Enumerates the RDB store security levels. 319 320**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 321 322| Name| Value | Description | 323| ---- | ---- | ------------------------------------------------------------ | 324| S1 | 1 | The RDB store security level is low. If data leakage occurs, minor impact will be caused on the database. For example, an RDB store that contains system data such as wallpapers.| 325| S2 | 2 | The RDB store security level is medium. If data leakage occurs, moderate impact will be caused on the database. For example, an RDB store that contains information created by users or call records, such as audio or video clips.| 326| S3 | 3 | The RDB store security level is high. If data leakage occurs, major impact will be caused on the database. For example, an RDB store that contains information such as user fitness, health, and location data.| 327| S4 | 4 | The RDB store security level is critical. If data leakage occurs, severe impact will be caused on the database. For example, an RDB store that contains information such as authentication credentials and financial data.| 328 329## ValueType 330 331Defines the data types allowed. 332 333**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 334 335| Type | Description | 336| ------- | -------------------- | 337| number | Number. | 338| string | String. | 339| boolean | Boolean.| 340 341## ValuesBucket 342 343Defines the types of the key and value in a KV pair. 344 345**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 346 347| Key Type| Value Type | 348| ------ | ----------------------------------------------------------- | 349| string | [ValueType](#valuetype)\| Uint8Array \| null | 350 351## SyncMode 352 353Defines the database synchronization mode. 354 355**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 356 357| Name | Value | Description | 358| -------------- | ---- | ---------------------------------- | 359| SYNC_MODE_PUSH | 0 | Data is pushed from a local device to a remote device.| 360| SYNC_MODE_PULL | 1 | Data is pulled from a remote device to a local device. | 361 362## SubscribeType 363 364Defines the subscription type. 365 366**Required permissions**: ohos.permission.DISTRIBUTED_DATASYNC 367 368**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 369 370| Name | Value | Description | 371| --------------------- | ---- | ------------------ | 372| SUBSCRIBE_TYPE_REMOTE | 0 | Subscribe to remote data changes.| 373 374## RdbPredicates 375 376Defines the predicates for an RDB store. This class determines whether the conditional expression for the RDB store is true or false. 377 378### constructor 379 380constructor(name: string) 381 382A constructor used to create an **RdbPredicates** object. 383 384**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 385 386**Parameters** 387 388| Name| Type | Mandatory| Description | 389| ------ | ------ | ---- | ------------ | 390| name | string | Yes | Database table name.| 391 392**Example** 393 394```js 395let predicates = new relationalStore.RdbPredicates("EMPLOYEE"); 396``` 397 398### inDevices 399 400inDevices(devices: Array<string>): RdbPredicates 401 402Sets an **RdbPredicates** to specify the remote devices to connect on the network during distributed database synchronization. 403 404> **NOTE** 405> 406> The value of **devices** is obtained by [deviceManager.getTrustedDeviceListSync](js-apis-device-manager.md#gettrusteddevicelistsync). The APIs of the **deviceManager** module are system interfaces and available only to system applications. 407 408**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 409 410**Parameters** 411 412| Name | Type | Mandatory| Description | 413| ------- | ------------------- | ---- | -------------------------- | 414| devices | Array<string> | Yes | IDs of the remote devices in the same network.| 415 416**Return value** 417 418| Type | Description | 419| ------------------------------------ | -------------------------- | 420| [RdbPredicates](#rdbpredicates) | **RdbPredicates** object created.| 421 422**Example** 423 424```js 425import deviceManager from '@ohos.distributedHardware.deviceManager'; 426let dmInstance = null; 427 428deviceManager.createDeviceManager("com.example.appdatamgrverify", (err, manager) => { 429 if (err) { 430 console.log("create device manager failed, err=" + err); 431 return; 432 } 433 dmInstance = manager; 434 let devices = dmInstance.getTrustedDeviceListSync(); 435 let deviceIds = []; 436 for (var i = 0; i < devices.length; i++) { 437 deviceIds[i] = devices[i].deviceId; 438 } 439}) 440 441let predicates = new relationalStore.RdbPredicates("EMPLOYEE"); 442predicates.inDevices(deviceIds); 443``` 444 445### inAllDevices 446 447inAllDevices(): RdbPredicates 448 449 450Sets an **RdbPredicates** to specify all remote devices on the network to connect during distributed database synchronization. 451 452**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 453 454**Return value** 455 456| Type | Description | 457| ------------------------------------ | -------------------------- | 458| [RdbPredicates](#rdbpredicates) | **RdbPredicates** object created.| 459 460**Example** 461 462```js 463let predicates = new relationalStore.RdbPredicates("EMPLOYEE"); 464predicates.inAllDevices(); 465``` 466 467### equalTo 468 469equalTo(field: string, value: ValueType): RdbPredicates 470 471 472Sets an **RdbPredicates** to match the field with data type **ValueType** and value equal to the specified value. 473 474**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 475 476**Parameters** 477 478| Name| Type | Mandatory| Description | 479| ------ | ----------------------- | ---- | ---------------------- | 480| field | string | Yes | Column name in the database table. | 481| value | [ValueType](#valuetype) | Yes | Value to match the **RdbPredicates**.| 482 483**Return value** 484 485| Type | Description | 486| ------------------------------------ | -------------------------- | 487| [RdbPredicates](#rdbpredicates) | **RdbPredicates** object created.| 488 489**Example** 490 491```js 492let predicates = new relationalStore.RdbPredicates("EMPLOYEE"); 493predicates.equalTo("NAME", "lisi"); 494``` 495 496 497### notEqualTo 498 499notEqualTo(field: string, value: ValueType): RdbPredicates 500 501 502Sets an **RdbPredicates** to match the field with data type **ValueType** and value not equal to the specified value. 503 504**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 505 506**Parameters** 507 508| Name| Type | Mandatory| Description | 509| ------ | ----------------------- | ---- | ---------------------- | 510| field | string | Yes | Column name in the database table. | 511| value | [ValueType](#valuetype) | Yes | Value to match the **RdbPredicates**.| 512 513**Return value** 514 515| Type | Description | 516| ------------------------------------ | -------------------------- | 517| [RdbPredicates](#rdbpredicates) | **RdbPredicates** object created.| 518 519**Example** 520 521```js 522let predicates = new relationalStore.RdbPredicates("EMPLOYEE"); 523predicates.notEqualTo("NAME", "lisi"); 524``` 525 526 527### beginWrap 528 529beginWrap(): RdbPredicates 530 531 532Adds a left parenthesis to the **RdbPredicates**. 533 534**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 535 536**Return value** 537 538| Type | Description | 539| ------------------------------------ | ------------------------- | 540| [RdbPredicates](#rdbpredicates) | **RdbPredicates** with a left parenthesis.| 541 542**Example** 543 544```js 545let predicates = new relationalStore.RdbPredicates("EMPLOYEE"); 546predicates.equalTo("NAME", "lisi") 547 .beginWrap() 548 .equalTo("AGE", 18) 549 .or() 550 .equalTo("SALARY", 200.5) 551 .endWrap() 552``` 553 554### endWrap 555 556endWrap(): RdbPredicates 557 558Adds a right parenthesis to the **RdbPredicates**. 559 560**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 561 562**Return value** 563 564| Type | Description | 565| ------------------------------------ | ------------------------- | 566| [RdbPredicates](#rdbpredicates) | **RdbPredicates** with a right parenthesis.| 567 568**Example** 569 570```js 571let predicates = new relationalStore.RdbPredicates("EMPLOYEE"); 572predicates.equalTo("NAME", "lisi") 573 .beginWrap() 574 .equalTo("AGE", 18) 575 .or() 576 .equalTo("SALARY", 200.5) 577 .endWrap() 578``` 579 580### or 581 582or(): RdbPredicates 583 584Adds the OR condition to the **RdbPredicates**. 585 586**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 587 588**Return value** 589 590| Type | Description | 591| ------------------------------------ | ------------------------- | 592| [RdbPredicates](#rdbpredicates) | **RdbPredicates** with the OR condition.| 593 594**Example** 595 596```js 597let predicates = new relationalStore.RdbPredicates("EMPLOYEE"); 598predicates.equalTo("NAME", "Lisa") 599 .or() 600 .equalTo("NAME", "Rose") 601``` 602 603### and 604 605and(): RdbPredicates 606 607Adds the AND condition to the **RdbPredicates**. 608 609**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 610 611**Return value** 612 613| Type | Description | 614| ------------------------------------ | ------------------------- | 615| [RdbPredicates](#rdbpredicates) | **RdbPredicates** with the AND condition.| 616 617**Example** 618 619```js 620let predicates = new relationalStore.RdbPredicates("EMPLOYEE"); 621predicates.equalTo("NAME", "Lisa") 622 .and() 623 .equalTo("SALARY", 200.5) 624``` 625 626### contains 627 628contains(field: string, value: string): RdbPredicates 629 630Sets an **RdbPredicates** to match a string containing the specified value. 631 632**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 633 634**Parameters** 635 636| Name| Type | Mandatory| Description | 637| ------ | ------ | ---- | ---------------------- | 638| field | string | Yes | Column name in the database table. | 639| value | string | Yes | Value to match the **RdbPredicates**.| 640 641**Return value** 642 643| Type | Description | 644| ------------------------------------ | -------------------------- | 645| [RdbPredicates](#rdbpredicates) | **RdbPredicates** object created.| 646 647**Example** 648 649```js 650let predicates = new relationalStore.RdbPredicates("EMPLOYEE"); 651predicates.contains("NAME", "os"); 652``` 653 654### beginsWith 655 656beginsWith(field: string, value: string): RdbPredicates 657 658Sets an **RdbPredicates** to match a string that starts with the specified value. 659 660**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 661 662**Parameters** 663 664| Name| Type | Mandatory| Description | 665| ------ | ------ | ---- | ---------------------- | 666| field | string | Yes | Column name in the database table. | 667| value | string | Yes | Value to match the **RdbPredicates**.| 668 669**Return value** 670 671| Type | Description | 672| ------------------------------------ | -------------------------- | 673| [RdbPredicates](#rdbpredicates) | **RdbPredicates** object created.| 674 675**Example** 676 677```js 678let predicates = new relationalStore.RdbPredicates("EMPLOYEE"); 679predicates.beginsWith("NAME", "os"); 680``` 681 682### endsWith 683 684endsWith(field: string, value: string): RdbPredicates 685 686Sets an **RdbPredicates** to match a string that ends with the specified value. 687 688**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 689 690**Parameters** 691 692| Name| Type | Mandatory| Description | 693| ------ | ------ | ---- | ---------------------- | 694| field | string | Yes | Column name in the database table. | 695| value | string | Yes | Value to match the **RdbPredicates**.| 696 697**Return value** 698 699| Type | Description | 700| ------------------------------------ | -------------------------- | 701| [RdbPredicates](#rdbpredicates) | **RdbPredicates** object created.| 702 703**Example** 704 705```js 706let predicates = new relationalStore.RdbPredicates("EMPLOYEE"); 707predicates.endsWith("NAME", "se"); 708``` 709 710### isNull 711 712isNull(field: string): RdbPredicates 713 714Sets an **RdbPredicates** to match the field whose value is null. 715 716**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 717 718**Parameters** 719 720| Name| Type | Mandatory| Description | 721| ------ | ------ | ---- | ------------------ | 722| field | string | Yes | Column name in the database table.| 723 724**Return value** 725 726| Type | Description | 727| ------------------------------------ | -------------------------- | 728| [RdbPredicates](#rdbpredicates) | **RdbPredicates** object created.| 729 730**Example** 731 732```js 733let predicates = new relationalStore.RdbPredicates("EMPLOYEE"); 734predicates.isNull("NAME"); 735``` 736 737### isNotNull 738 739isNotNull(field: string): RdbPredicates 740 741Sets an **RdbPredicates** to match the field whose value is not null. 742 743**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 744 745**Parameters** 746 747| Name| Type | Mandatory| Description | 748| ------ | ------ | ---- | ------------------ | 749| field | string | Yes | Column name in the database table.| 750 751**Return value** 752 753| Type | Description | 754| ------------------------------------ | -------------------------- | 755| [RdbPredicates](#rdbpredicates) | **RdbPredicates** object created.| 756 757**Example** 758 759```js 760let predicates = new relationalStore.RdbPredicates("EMPLOYEE"); 761predicates.isNotNull("NAME"); 762``` 763 764### like 765 766like(field: string, value: string): RdbPredicates 767 768Sets an **RdbPredicates** to match a string that is similar to the specified value. 769 770**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 771 772**Parameters** 773 774| Name| Type | Mandatory| Description | 775| ------ | ------ | ---- | ---------------------- | 776| field | string | Yes | Column name in the database table. | 777| value | string | Yes | Value to match the **RdbPredicates**.| 778 779**Return value** 780 781| Type | Description | 782| ------------------------------------ | -------------------------- | 783| [RdbPredicates](#rdbpredicates) | **RdbPredicates** object created.| 784 785**Example** 786 787```js 788let predicates = new relationalStore.RdbPredicates("EMPLOYEE"); 789predicates.like("NAME", "%os%"); 790``` 791 792### glob 793 794glob(field: string, value: string): RdbPredicates 795 796Sets an **RdbPredicates** to match the specified string. 797 798**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 799 800**Parameters** 801 802| Name| Type | Mandatory| Description | 803| ------ | ------ | ---- | ------------------------------------------------------------ | 804| field | string | Yes | Column name in the database table. | 805| value | string | Yes | Value to match the **RdbPredicates**.<br><br>Wildcards are supported. * indicates zero, one, or multiple digits or characters. **?** indicates a single digit or character.| 806 807**Return value** 808 809| Type | Description | 810| ------------------------------------ | -------------------------- | 811| [RdbPredicates](#rdbpredicates) | **RdbPredicates** object created.| 812 813**Example** 814 815```js 816let predicates = new relationalStore.RdbPredicates("EMPLOYEE"); 817predicates.glob("NAME", "?h*g"); 818``` 819 820### between 821 822between(field: string, low: ValueType, high: ValueType): RdbPredicates 823 824Sets an **RdbPredicates** to match the field with data type **ValueType** and value within the specified range. 825 826**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 827 828**Parameters** 829 830| Name| Type | Mandatory| Description | 831| ------ | ----------------------- | ---- | -------------------------- | 832| field | string | Yes | Column name in the database table. | 833| low | [ValueType](#valuetype) | Yes | Minimum value to match the **RdbPredicates**. | 834| high | [ValueType](#valuetype) | Yes | Maximum value to match the **RdbPredicates**.| 835 836**Return value** 837 838| Type | Description | 839| ------------------------------------ | -------------------------- | 840| [RdbPredicates](#rdbpredicates) | **RdbPredicates** object created.| 841 842**Example** 843 844```js 845let predicates = new relationalStore.RdbPredicates("EMPLOYEE"); 846predicates.between("AGE", 10, 50); 847``` 848 849### notBetween 850 851notBetween(field: string, low: ValueType, high: ValueType): RdbPredicates 852 853Sets an **RdbPredicates** to match the field with data type **ValueType** and value out of the specified range. 854 855**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 856 857**Parameters** 858 859| Name| Type | Mandatory| Description | 860| ------ | ----------------------- | ---- | -------------------------- | 861| field | string | Yes | Column name in the database table. | 862| low | [ValueType](#valuetype) | Yes | Minimum value to match the **RdbPredicates**. | 863| high | [ValueType](#valuetype) | Yes | Maximum value to match the **RdbPredicates**.| 864 865**Return value** 866 867| Type | Description | 868| ------------------------------------ | -------------------------- | 869| [RdbPredicates](#rdbpredicates) | **RdbPredicates** object created.| 870 871**Example** 872 873```js 874let predicates = new relationalStore.RdbPredicates("EMPLOYEE"); 875predicates.notBetween("AGE", 10, 50); 876``` 877 878### greaterThan 879 880greaterThan(field: string, value: ValueType): RdbPredicates 881 882Sets an **RdbPredicates** to match the field with data type **ValueType** and value greater than the specified value. 883 884**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 885 886**Parameters** 887 888| Name| Type | Mandatory| Description | 889| ------ | ----------------------- | ---- | ---------------------- | 890| field | string | Yes | Column name in the database table. | 891| value | [ValueType](#valuetype) | Yes | Value to match the **RdbPredicates**.| 892 893**Return value** 894 895| Type | Description | 896| ------------------------------------ | -------------------------- | 897| [RdbPredicates](#rdbpredicates) | **RdbPredicates** object created.| 898 899**Example** 900 901```js 902let predicates = new relationalStore.RdbPredicates("EMPLOYEE"); 903predicates.greaterThan("AGE", 18); 904``` 905 906### lessThan 907 908lessThan(field: string, value: ValueType): RdbPredicates 909 910Sets an **RdbPredicates** to match the field with data type **ValueType** and value less than the specified value. 911 912**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 913 914**Parameters** 915 916| Name| Type | Mandatory| Description | 917| ------ | ----------------------- | ---- | ---------------------- | 918| field | string | Yes | Column name in the database table. | 919| value | [ValueType](#valuetype) | Yes | Value to match the **RdbPredicates**.| 920 921**Return value** 922 923| Type | Description | 924| ------------------------------------ | -------------------------- | 925| [RdbPredicates](#rdbpredicates) | **RdbPredicates** object created.| 926 927**Example** 928 929```js 930let predicates = new relationalStore.RdbPredicates("EMPLOYEE"); 931predicates.lessThan("AGE", 20); 932``` 933 934### greaterThanOrEqualTo 935 936greaterThanOrEqualTo(field: string, value: ValueType): RdbPredicates 937 938Sets an **RdbPredicates** to match the field with data type **ValueType** and value greater than or equal to the specified value. 939 940**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 941 942**Parameters** 943 944| Name| Type | Mandatory| Description | 945| ------ | ----------------------- | ---- | ---------------------- | 946| field | string | Yes | Column name in the database table. | 947| value | [ValueType](#valuetype) | Yes | Value to match the **RdbPredicates**.| 948 949**Return value** 950 951| Type | Description | 952| ------------------------------------ | -------------------------- | 953| [RdbPredicates](#rdbpredicates) | **RdbPredicates** object created.| 954 955**Example** 956 957```js 958let predicates = new relationalStore.RdbPredicates("EMPLOYEE"); 959predicates.greaterThanOrEqualTo("AGE", 18); 960``` 961 962### lessThanOrEqualTo 963 964lessThanOrEqualTo(field: string, value: ValueType): RdbPredicates 965 966Sets an **RdbPredicates** to match the field with data type **ValueType** and value less than or equal to the specified value. 967 968**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 969 970**Parameters** 971 972| Name| Type | Mandatory| Description | 973| ------ | ----------------------- | ---- | ---------------------- | 974| field | string | Yes | Column name in the database table. | 975| value | [ValueType](#valuetype) | Yes | Value to match the **RdbPredicates**.| 976 977**Return value** 978 979| Type | Description | 980| ------------------------------------ | -------------------------- | 981| [RdbPredicates](#rdbpredicates) | **RdbPredicates** object created.| 982 983**Example** 984 985```js 986let predicates = new relationalStore.RdbPredicates("EMPLOYEE"); 987predicates.lessThanOrEqualTo("AGE", 20); 988``` 989 990### orderByAsc 991 992orderByAsc(field: string): RdbPredicates 993 994Sets an **RdbPredicates** to match the column with values sorted in ascending order. 995 996**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 997 998**Parameters** 999 1000| Name| Type | Mandatory| Description | 1001| ------ | ------ | ---- | ------------------ | 1002| field | string | Yes | Column name in the database table.| 1003 1004**Return value** 1005 1006| Type | Description | 1007| ------------------------------------ | -------------------------- | 1008| [RdbPredicates](#rdbpredicates) | **RdbPredicates** object created.| 1009 1010**Example** 1011 1012```js 1013let predicates = new relationalStore.RdbPredicates("EMPLOYEE"); 1014predicates.orderByAsc("NAME"); 1015``` 1016 1017### orderByDesc 1018 1019orderByDesc(field: string): RdbPredicates 1020 1021Sets an **RdbPredicates** to match the column with values sorted in descending order. 1022 1023**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 1024 1025**Parameters** 1026 1027| Name| Type | Mandatory| Description | 1028| ------ | ------ | ---- | ------------------ | 1029| field | string | Yes | Column name in the database table.| 1030 1031**Return value** 1032 1033| Type | Description | 1034| ------------------------------------ | -------------------------- | 1035| [RdbPredicates](#rdbpredicates) | **RdbPredicates** object created.| 1036 1037**Example** 1038 1039```js 1040let predicates = new relationalStore.RdbPredicates("EMPLOYEE"); 1041predicates.orderByDesc("AGE"); 1042``` 1043 1044### distinct 1045 1046distinct(): RdbPredicates 1047 1048Sets an **RdbPredicates** to filter out duplicate records. 1049 1050**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 1051 1052**Return value** 1053 1054| Type | Description | 1055| ------------------------------------ | ------------------------------ | 1056| [RdbPredicates](#rdbpredicates) | **RdbPredicates** object that can filter out duplicate records.| 1057 1058**Example** 1059 1060```js 1061let predicates = new relationalStore.RdbPredicates("EMPLOYEE"); 1062predicates.equalTo("NAME", "Rose").distinct(); 1063``` 1064 1065### limitAs 1066 1067limitAs(value: number): RdbPredicates 1068 1069Sets an **RdbPredicates** to specify the maximum number of records. 1070 1071**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 1072 1073**Parameters** 1074 1075| Name| Type | Mandatory| Description | 1076| ------ | ------ | ---- | ---------------- | 1077| value | number | Yes | Maximum number of records.| 1078 1079**Return value** 1080 1081| Type | Description | 1082| ------------------------------------ | ------------------------------------ | 1083| [RdbPredicates](#rdbpredicates) | **RdbPredicates** object that specifies the maximum number of records.| 1084 1085**Example** 1086 1087```js 1088let predicates = new relationalStore.RdbPredicates("EMPLOYEE"); 1089predicates.equalTo("NAME", "Rose").limitAs(3); 1090``` 1091 1092### offsetAs 1093 1094offsetAs(rowOffset: number): RdbPredicates 1095 1096Sets an **RdbPredicates** to specify the start position of the returned result. 1097 1098**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 1099 1100**Parameters** 1101 1102| Name | Type | Mandatory| Description | 1103| --------- | ------ | ---- | ---------------------------------- | 1104| rowOffset | number | Yes | Number of rows to offset from the beginning. The value is a positive integer.| 1105 1106**Return value** 1107 1108| Type | Description | 1109| ------------------------------------ | ------------------------------------ | 1110| [RdbPredicates](#rdbpredicates) | **RdbPredicates** object that specifies the start position of the returned result.| 1111 1112**Example** 1113 1114```js 1115let predicates = new relationalStore.RdbPredicates("EMPLOYEE"); 1116predicates.equalTo("NAME", "Rose").offsetAs(3); 1117``` 1118 1119### groupBy 1120 1121groupBy(fields: Array<string>): RdbPredicates 1122 1123Sets an **RdbPredicates** to group rows that have the same value into summary rows. 1124 1125**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 1126 1127**Parameters** 1128 1129| Name| Type | Mandatory| Description | 1130| ------ | ------------------- | ---- | -------------------- | 1131| fields | Array<string> | Yes | Names of columns to group.| 1132 1133**Return value** 1134 1135| Type | Description | 1136| ------------------------------------ | ---------------------- | 1137| [RdbPredicates](#rdbpredicates) | **RdbPredicates** object that groups rows with the same value.| 1138 1139**Example** 1140 1141```js 1142let predicates = new relationalStore.RdbPredicates("EMPLOYEE"); 1143predicates.groupBy(["AGE", "NAME"]); 1144``` 1145 1146### indexedBy 1147 1148indexedBy(field: string): RdbPredicates 1149 1150Sets an **RdbPredicates** object to specify the index column. 1151 1152**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 1153 1154**Parameters** 1155 1156| Name| Type | Mandatory| Description | 1157| ------ | ------ | ---- | -------------- | 1158| field | string | Yes | Name of the index column.| 1159 1160**Return value** 1161 1162 1163| Type | Description | 1164| ------------------------------------ | ------------------------------------- | 1165| [RdbPredicates](#rdbpredicates) | **RdbPredicates** object that specifies the index column.| 1166 1167**Example** 1168 1169```js 1170let predicates = new relationalStore.RdbPredicates("EMPLOYEE"); 1171predicates.indexedBy("SALARY_INDEX"); 1172``` 1173 1174### in 1175 1176in(field: string, value: Array<ValueType>): RdbPredicates 1177 1178Sets an **RdbPredicates** to match the field with data type **Array<ValueType>** and value within the specified range. 1179 1180**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 1181 1182**Parameters** 1183 1184| Name| Type | Mandatory| Description | 1185| ------ | ------------------------------------ | ---- | --------------------------------------- | 1186| field | string | Yes | Column name in the database table. | 1187| value | Array<[ValueType](#valuetype)> | Yes | Array of **ValueType**s to match.| 1188 1189**Return value** 1190 1191| Type | Description | 1192| ------------------------------------ | -------------------------- | 1193| [RdbPredicates](#rdbpredicates) | **RdbPredicates** object created.| 1194 1195**Example** 1196 1197```js 1198let predicates = new relationalStore.RdbPredicates("EMPLOYEE"); 1199predicates.in("AGE", [18, 20]); 1200``` 1201 1202### notIn 1203 1204notIn(field: string, value: Array<ValueType>): RdbPredicates 1205 1206Sets an **RdbPredicates** to match the field with data type **Array<ValueType>** and value out of the specified range. 1207 1208**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 1209 1210**Parameters** 1211 1212| Name| Type | Mandatory| Description | 1213| ------ | ------------------------------------ | ---- | ------------------------------------- | 1214| field | string | Yes | Column name in the database table. | 1215| value | Array<[ValueType](#valuetype)> | Yes | Array of **ValueType**s to match.| 1216 1217**Return value** 1218 1219| Type | Description | 1220| ------------------------------------ | -------------------------- | 1221| [RdbPredicates](#rdbpredicates) | **RdbPredicates** object created.| 1222 1223**Example** 1224 1225```js 1226let predicates = new relationalStore.RdbPredicates("EMPLOYEE"); 1227predicates.notIn("NAME", ["Lisa", "Rose"]); 1228``` 1229 1230## RdbStore 1231 1232Provides methods to manage an RDB store. 1233 1234Before using the following APIs, use [executeSql](#executesql) to initialize the database table structure and related data. For details, see [RDB Development](../../database/database-relational-guidelines.md). 1235 1236### insert 1237 1238insert(table: string, values: ValuesBucket, callback: AsyncCallback<number>):void 1239 1240Inserts a row of data into a table. This API uses an asynchronous callback to return the result. 1241 1242**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 1243 1244**Parameters** 1245 1246| Name | Type | Mandatory| Description | 1247| -------- | ----------------------------- | ---- | ---------------------------------------------------------- | 1248| table | string | Yes | Name of the target table. | 1249| values | [ValuesBucket](#valuesbucket) | Yes | Row of data to insert. | 1250| callback | AsyncCallback<number> | Yes | Callback invoked to return the result. If the operation is successful, the row ID will be returned. Otherwise, **-1** will be returned.| 1251 1252**Example** 1253 1254```js 1255const valueBucket = { 1256 "NAME": "Lisa", 1257 "AGE": 18, 1258 "SALARY": 100.5, 1259 "CODES": new Uint8Array([1, 2, 3, 4, 5]), 1260}; 1261store.insert("EMPLOYEE", valueBucket, function (err, rowId) { 1262 if (err) { 1263 console.error(`Insert is failed, err: ${err}`); 1264 return; 1265 } 1266 console.info(`Insert is successful, rowId = ${rowId}`); 1267}) 1268``` 1269 1270 1271### insert 1272 1273insert(table: string, values: ValuesBucket):Promise<number> 1274 1275Inserts a row of data into a table. This API uses a promise to return the result. 1276 1277**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 1278 1279**Parameters** 1280 1281| Name| Type | Mandatory| Description | 1282| ------ | ----------------------------- | ---- | -------------------------- | 1283| table | string | Yes | Name of the target table. | 1284| values | [ValuesBucket](#valuesbucket) | Yes | Row of data to insert.| 1285 1286**Return value** 1287 1288| Type | Description | 1289| --------------------- | ------------------------------------------------- | 1290| Promise<number> | Promise used to return the result. If the operation is successful, the row ID will be returned. Otherwise, **-1** will be returned.| 1291 1292**Example** 1293 1294```js 1295const valueBucket = { 1296 "NAME": "Lisa", 1297 "AGE": 18, 1298 "SALARY": 100.5, 1299 "CODES": new Uint8Array([1, 2, 3, 4, 5]), 1300}; 1301let promise = store.insert("EMPLOYEE", valueBucket); 1302promise.then((rowId) => { 1303 console.info(`Insert is successful, rowId = ${rowId}`); 1304}).catch((err) => { 1305 console.error(`Insert is failed, err: ${err}`); 1306}) 1307``` 1308 1309 1310### batchInsert 1311 1312batchInsert(table: string, values: Array<ValuesBucket>, callback: AsyncCallback<number>):void 1313 1314Batch inserts data into a table. This API uses an asynchronous callback to return the result. 1315 1316**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 1317 1318**Parameters** 1319 1320| Name | Type | Mandatory| Description | 1321| -------- | ------------------------------------------ | ---- | ------------------------------------------------------------ | 1322| table | string | Yes | Name of the target table. | 1323| values | Array<[ValuesBucket](#valuesbucket)> | Yes | An array of data to insert. | 1324| callback | AsyncCallback<number> | Yes | Callback invoked to return the result. If the operation is successful, the number of inserted data records is returned. Otherwise, **-1** is returned.| 1325 1326**Example** 1327 1328```js 1329const valueBucket1 = { 1330 "NAME": "Lisa", 1331 "AGE": 18, 1332 "SALARY": 100.5, 1333 "CODES": new Uint8Array([1, 2, 3, 4, 5]) 1334}; 1335const valueBucket2 = { 1336 "NAME": "Jack", 1337 "AGE": 19, 1338 "SALARY": 101.5, 1339 "CODES": new Uint8Array([6, 7, 8, 9, 10]) 1340}; 1341const valueBucket3 = { 1342 "NAME": "Tom", 1343 "AGE": 20, 1344 "SALARY": 102.5, 1345 "CODES": new Uint8Array([11, 12, 13, 14, 15]) 1346}; 1347 1348let valueBuckets = new Array(valueBucket1, valueBucket2, valueBucket3); 1349store.batchInsert("EMPLOYEE", valueBuckets, function(err, insertNum) { 1350 if (err) { 1351 console.error(`batchInsert is failed, err: ${err}`); 1352 return; 1353 } 1354 console.info(`batchInsert is successful, the number of values that were inserted = ${insertNum}`); 1355}) 1356``` 1357 1358### batchInsert 1359 1360batchInsert(table: string, values: Array<ValuesBucket>):Promise<number> 1361 1362Batch inserts data into a table. This API uses a promise to return the result. 1363 1364**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 1365 1366**Parameters** 1367 1368| Name| Type | Mandatory| Description | 1369| ------ | ------------------------------------------ | ---- | ---------------------------- | 1370| table | string | Yes | Name of the target table. | 1371| values | Array<[ValuesBucket](#valuesbucket)> | Yes | An array of data to insert.| 1372 1373**Return value** 1374 1375| Type | Description | 1376| --------------------- | ----------------------------------------------------------- | 1377| Promise<number> | Promise used to return the result. If the operation is successful, the number of inserted data records is returned. Otherwise, **-1** is returned.| 1378 1379**Example** 1380 1381```js 1382const valueBucket1 = { 1383 "NAME": "Lisa", 1384 "AGE": 18, 1385 "SALARY": 100.5, 1386 "CODES": new Uint8Array([1, 2, 3, 4, 5]) 1387}; 1388const valueBucket2 = { 1389 "NAME": "Jack", 1390 "AGE": 19, 1391 "SALARY": 101.5, 1392 "CODES": new Uint8Array([6, 7, 8, 9, 10]) 1393}; 1394const valueBucket3 = { 1395 "NAME": "Tom", 1396 "AGE": 20, 1397 "SALARY": 102.5, 1398 "CODES": new Uint8Array([11, 12, 13, 14, 15]) 1399}; 1400 1401let valueBuckets = new Array(valueBucket1, valueBucket2, valueBucket3); 1402let promise = store.batchInsert("EMPLOYEE", valueBuckets); 1403promise.then((insertNum) => { 1404 console.info(`batchInsert is successful, the number of values that were inserted = ${insertNum}`); 1405}).catch((err) => { 1406 console.error(`batchInsert is failed, err: ${err}`); 1407}) 1408``` 1409 1410### update 1411 1412update(values: ValuesBucket, predicates: RdbPredicates, callback: AsyncCallback<number>):void 1413 1414Updates data in the RDB store based on the specified **RdbPredicates** object. This API uses an asynchronous callback to return the result. 1415 1416**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 1417 1418**Parameters** 1419 1420| Name | Type | Mandatory| Description | 1421| ---------- | ------------------------------------ | ---- | ------------------------------------------------------------ | 1422| values | [ValuesBucket](#valuesbucket) | Yes | Rows of data to update in the RDB store. The key-value pair is associated with the column name in the target table.| 1423| predicates | [RdbPredicates](#rdbpredicates) | Yes | Update conditions specified by the **RdbPredicates** object. | 1424| callback | AsyncCallback<number> | Yes | Callback invoked to return the number of rows updated. | 1425 1426**Example** 1427 1428```js 1429const valueBucket = { 1430 "NAME": "Rose", 1431 "AGE": 22, 1432 "SALARY": 200.5, 1433 "CODES": new Uint8Array([1, 2, 3, 4, 5]), 1434}; 1435let predicates = new relationalStore.RdbPredicates("EMPLOYEE"); 1436predicates.equalTo("NAME", "Lisa"); 1437store.update(valueBucket, predicates, function (err, rows) { 1438 if (err) { 1439 console.error(`Updated failed, err: ${err}`); 1440 return; 1441 } 1442 console.info(`Updated row count: ${rows}`); 1443}) 1444``` 1445 1446 1447### update 1448 1449update(values: ValuesBucket, predicates: RdbPredicates):Promise<number> 1450 1451Updates data based on the specified **RdbPredicates** object. This API uses a promise to return the result. 1452 1453**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 1454 1455**Parameters** 1456 1457| Name | Type | Mandatory| Description | 1458| ------------ | ------------------------------------ | ---- | ------------------------------------------------------------ | 1459| values | [ValuesBucket](#valuesbucket) | Yes | Rows of data to update in the RDB store. The key-value pair is associated with the column name in the target table.| 1460| predicates | [RdbPredicates](#rdbpredicates) | Yes | Update conditions specified by the **RdbPredicates** object. | 1461 1462**Return value** 1463 1464| Type | Description | 1465| --------------------- | ----------------------------------------- | 1466| Promise<number> | Promise used to return the number of rows updated.| 1467 1468**Example** 1469 1470```js 1471const valueBucket = { 1472 "NAME": "Rose", 1473 "AGE": 22, 1474 "SALARY": 200.5, 1475 "CODES": new Uint8Array([1, 2, 3, 4, 5]), 1476}; 1477let predicates = new relationalStore.RdbPredicates("EMPLOYEE"); 1478predicates.equalTo("NAME", "Lisa"); 1479let promise = store.update(valueBucket, predicates); 1480promise.then(async (rows) => { 1481 console.info(`Updated row count: ${rows}`); 1482}).catch((err) => { 1483 console.error(`Updated failed, err: ${err}`); 1484}) 1485``` 1486 1487 1488### update 1489 1490update(table: string, values: ValuesBucket, predicates: dataSharePredicates.DataSharePredicates, callback: AsyncCallback<number>):void 1491 1492Updates data based on the specified **DataSharePredicates** object. This API uses an asynchronous callback to return the result. 1493 1494**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 1495 1496**System API**: This is a system API. 1497 1498**Parameters** 1499 1500| Name | Type | Mandatory| Description | 1501| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 1502| table | string | Yes | Name of the target table. | 1503| values | [ValuesBucket](#valuesbucket) | Yes | Rows of data to update in the RDB store. The key-value pair is associated with the column name in the target table.| 1504| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | Yes | Update conditions specified by the **DataSharePredicates** object. | 1505| callback | AsyncCallback<number> | Yes | Callback invoked to return the number of rows updated. | 1506 1507**Example** 1508 1509```js 1510import dataSharePredicates from '@ohos.data.dataSharePredicates' 1511const valueBucket = { 1512 "NAME": "Rose", 1513 "AGE": 22, 1514 "SALARY": 200.5, 1515 "CODES": new Uint8Array([1, 2, 3, 4, 5]), 1516}; 1517let predicates = new dataSharePredicates.DataSharePredicates(); 1518predicates.equalTo("NAME", "Lisa"); 1519store.update("EMPLOYEE", valueBucket, predicates, function (err, rows) { 1520 if (err) { 1521 console.error(`Updated failed, err: ${err}`); 1522 return; 1523 } 1524 console.info(`Updated row count: ${rows}`); 1525}) 1526``` 1527 1528### update 1529 1530update(table: string, values: ValuesBucket, predicates: dataSharePredicates.DataSharePredicates):Promise<number> 1531 1532Updates data based on the specified **DataSharePredicates** object. This API uses a promise to return the result. 1533 1534**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 1535 1536**System API**: This is a system API. 1537 1538**Parameters** 1539 1540| Name | Type | Mandatory| Description | 1541| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 1542| table | string | Yes | Name of the target table. | 1543| values | [ValuesBucket](#valuesbucket) | Yes | Rows of data to update in the RDB store. The key-value pair is associated with the column name in the target table.| 1544| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | Yes | Update conditions specified by the **DataSharePredicates** object. | 1545 1546**Return value** 1547 1548| Type | Description | 1549| --------------------- | ----------------------------------------- | 1550| Promise<number> | Promise used to return the number of rows updated.| 1551 1552**Example** 1553 1554```js 1555import dataSharePredicates from '@ohos.data.dataSharePredicates' 1556const valueBucket = { 1557 "NAME": "Rose", 1558 "AGE": 22, 1559 "SALARY": 200.5, 1560 "CODES": new Uint8Array([1, 2, 3, 4, 5]), 1561}; 1562let predicates = new dataSharePredicates.DataSharePredicates(); 1563predicates.equalTo("NAME", "Lisa"); 1564let promise = store.update("EMPLOYEE", valueBucket, predicates); 1565promise.then(async (rows) => { 1566 console.info(`Updated row count: ${rows}`); 1567}).catch((err) => { 1568 console.error(`Updated failed, err: ${err}`); 1569}) 1570``` 1571 1572### delete 1573 1574delete(predicates: RdbPredicates, callback: AsyncCallback<number>):void 1575 1576Deletes data from the RDB store based on the specified **RdbPredicates** object. This API uses an asynchronous callback to return the result. 1577 1578**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 1579 1580**Parameters** 1581 1582| Name | Type | Mandatory| Description | 1583| ---------- | ------------------------------------ | ---- | ----------------------------------------- | 1584| predicates | [RdbPredicates](#rdbpredicates) | Yes | Conditions specified by the **RdbPredicates** object for deleting data.| 1585| callback | AsyncCallback<number> | Yes | Callback invoked to return the number of rows deleted. | 1586 1587**Example** 1588 1589```js 1590let predicates = new relationalStore.RdbPredicates("EMPLOYEE"); 1591predicates.equalTo("NAME", "Lisa"); 1592store.delete(predicates, function (err, rows) { 1593 if (err) { 1594 console.error(`Delete failed, err: ${err}`); 1595 return; 1596 } 1597 console.info(`Delete rows: ${rows}`); 1598}) 1599``` 1600 1601### delete 1602 1603delete(predicates: RdbPredicates):Promise<number> 1604 1605Deletes data from the RDB store based on the specified **RdbPredicates** object. This API uses a promise to return the result. 1606 1607**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 1608 1609**Parameters** 1610 1611| Name | Type | Mandatory| Description | 1612| ---------- | ------------------------------------ | ---- | ----------------------------------------- | 1613| predicates | [RdbPredicates](#rdbpredicates) | Yes | Conditions specified by the **RdbPredicates** object for deleting data.| 1614 1615**Return value** 1616 1617| Type | Description | 1618| --------------------- | ------------------------------- | 1619| Promise<number> | Promise used to return the number of rows deleted. | 1620 1621**Example** 1622 1623```js 1624let predicates = new relationalStore.RdbPredicates("EMPLOYEE"); 1625predicates.equalTo("NAME", "Lisa"); 1626let promise = store.delete(predicates); 1627promise.then((rows) => { 1628 console.info(`Delete rows: ${rows}`); 1629}).catch((err) => { 1630 console.error(`Delete failed, err: ${err}`); 1631}) 1632``` 1633 1634### delete 1635 1636delete(table: string, predicates: dataSharePredicates.DataSharePredicates, callback: AsyncCallback<number>):void 1637 1638Deletes data from the RDB store based on the specified **DataSharePredicates** object. This API uses an asynchronous callback to return the result. 1639 1640**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 1641 1642**System API**: This is a system API. 1643 1644**Parameters** 1645 1646| Name | Type | Mandatory| Description | 1647| ---------- | ------------------------------------------------------------ | ---- | --------------------------------------------- | 1648| table | string | Yes | Name of the target table. | 1649| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | Yes | Conditions specified by the **DataSharePredicates** object for deleting data.| 1650| callback | AsyncCallback<number> | Yes | Callback invoked to return the number of rows deleted. | 1651 1652**Example** 1653 1654```js 1655import dataSharePredicates from '@ohos.data.dataSharePredicates' 1656let predicates = new dataSharePredicates.DataSharePredicates(); 1657predicates.equalTo("NAME", "Lisa"); 1658store.delete("EMPLOYEE", predicates, function (err, rows) { 1659 if (err) { 1660 console.error(`Delete failed, err: ${err}`); 1661 return; 1662 } 1663 console.info(`Delete rows: ${rows}`); 1664}) 1665``` 1666 1667### delete 1668 1669delete(table: string, predicates: dataSharePredicates.DataSharePredicates):Promise<number> 1670 1671Deletes data from the RDB store based on the specified **DataSharePredicates** object. This API uses a promise to return the result. 1672 1673**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 1674 1675**System API**: This is a system API. 1676 1677**Parameters** 1678 1679| Name | Type | Mandatory| Description | 1680| ---------- | ------------------------------------------------------------ | ---- | --------------------------------------------- | 1681| table | string | Yes | Name of the target table. | 1682| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | Yes | Conditions specified by the **DataSharePredicates** object for deleting data.| 1683 1684**Return value** 1685 1686| Type | Description | 1687| --------------------- | ------------------------------- | 1688| Promise<number> | Promise used to return the number of rows deleted.| 1689 1690**Example** 1691 1692```js 1693import dataSharePredicates from '@ohos.data.dataSharePredicates' 1694let predicates = new dataSharePredicates.DataSharePredicates(); 1695predicates.equalTo("NAME", "Lisa"); 1696let promise = store.delete("EMPLOYEE", predicates); 1697promise.then((rows) => { 1698 console.info(`Delete rows: ${rows}`); 1699}).catch((err) => { 1700 console.error(`Delete failed, err: ${err}`); 1701}) 1702``` 1703 1704### query 1705 1706query(predicates: RdbPredicates, columns: Array<string>, callback: AsyncCallback<ResultSet>):void 1707 1708Queries data from the RDB store based on specified conditions. This API uses an asynchronous callback to return the result. 1709 1710**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 1711 1712**Parameters** 1713 1714| Name | Type | Mandatory| Description | 1715| ---------- | ------------------------------------------------------------ | ---- | ----------------------------------------------------------- | 1716| predicates | [RdbPredicates](#rdbpredicates) | Yes | Query conditions specified by the **RdbPredicates** object. | 1717| columns | Array<string> | Yes | Columns to query. If this parameter is not specified, the query applies to all columns. | 1718| callback | AsyncCallback<[ResultSet](#resultset)> | Yes | Callback invoked to return the result. If the operation is successful, a **ResultSet** object will be returned.| 1719 1720**Example** 1721 1722```js 1723let predicates = new relationalStore.RdbPredicates("EMPLOYEE"); 1724predicates.equalTo("NAME", "Rose"); 1725store.query(predicates, ["ID", "NAME", "AGE", "SALARY", "CODES"], function (err, resultSet) { 1726 if (err) { 1727 console.error(`Query failed, err: ${err}`); 1728 return; 1729 } 1730 console.info(`ResultSet column names: ${resultSet.columnNames}`); 1731 console.info(`ResultSet column count: ${resultSet.columnCount}`); 1732}) 1733``` 1734 1735### query 1736 1737query(predicates: RdbPredicates, columns?: Array<string>):Promise<ResultSet> 1738 1739Queries data from the RDB store based on specified conditions. This API uses a promise to return the result. 1740 1741**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 1742 1743**Parameters** 1744 1745| Name | Type | Mandatory| Description | 1746| ---------- | ------------------------------------ | ---- | ------------------------------------------------ | 1747| predicates | [RdbPredicates](#rdbpredicates) | Yes | Query conditions specified by the **RdbPredicates** object. | 1748| columns | Array<string> | No | Columns to query. If this parameter is not specified, the query applies to all columns.| 1749 1750**Return value** 1751 1752| Type | Description | 1753| ------------------------------------------------------- | -------------------------------------------------- | 1754| Promise<[ResultSet](#resultset)> | Promise used to return the result. If the operation is successful, a **ResultSet** object will be returned.| 1755 1756**Example** 1757 1758 ```js 1759let predicates = new relationalStore.RdbPredicates("EMPLOYEE"); 1760predicates.equalTo("NAME", "Rose"); 1761let promise = store.query(predicates, ["ID", "NAME", "AGE", "SALARY", "CODES"]); 1762promise.then((resultSet) => { 1763 console.info(`ResultSet column names: ${resultSet.columnNames}`); 1764 console.info(`ResultSet column count: ${resultSet.columnCount}`); 1765}).catch((err) => { 1766 console.error(`Query failed, err: ${err}`); 1767}) 1768 ``` 1769 1770### query 1771 1772query(table: string, predicates: dataSharePredicates.DataSharePredicates, columns: Array<string>, callback: AsyncCallback<ResultSet>):void 1773 1774Queries data from the RDB store based on specified conditions. This API uses an asynchronous callback to return the result. 1775 1776**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 1777 1778**System API**: This is a system API. 1779 1780**Parameters** 1781 1782| Name | Type | Mandatory| Description | 1783| ---------- | ------------------------------------------------------------ | ---- | ----------------------------------------------------------- | 1784| table | string | Yes | Name of the target table. | 1785| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | Yes | Query conditions specified by the **DataSharePredicates** object. | 1786| columns | Array<string> | Yes | Columns to query. If this parameter is not specified, the query applies to all columns. | 1787| callback | AsyncCallback<[ResultSet](#resultset)> | Yes | Callback invoked to return the result. If the operation is successful, a **ResultSet** object will be returned.| 1788 1789**Example** 1790 1791```js 1792import dataSharePredicates from '@ohos.data.dataSharePredicates' 1793let predicates = new dataSharePredicates.DataSharePredicates(); 1794predicates.equalTo("NAME", "Rose"); 1795store.query("EMPLOYEE", predicates, ["ID", "NAME", "AGE", "SALARY", "CODES"], function (err, resultSet) { 1796 if (err) { 1797 console.error(`Query failed, err: ${err}`); 1798 return; 1799 } 1800 console.info(`ResultSet column names: ${resultSet.columnNames}`); 1801 console.info(`ResultSet column count: ${resultSet.columnCount}`); 1802}) 1803``` 1804 1805### query 1806 1807query(table: string, predicates: dataSharePredicates.DataSharePredicates, columns?: Array<string>):Promise<ResultSet> 1808 1809Queries data from the RDB store based on specified conditions. This API uses a promise to return the result. 1810 1811**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 1812 1813**System API**: This is a system API. 1814 1815**Parameters** 1816 1817| Name | Type | Mandatory| Description | 1818| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------ | 1819| table | string | Yes | Name of the target table. | 1820| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | Yes | Query conditions specified by the **DataSharePredicates** object. | 1821| columns | Array<string> | No | Columns to query. If this parameter is not specified, the query applies to all columns.| 1822 1823**Return value** 1824 1825| Type | Description | 1826| ------------------------------------------------------- | -------------------------------------------------- | 1827| Promise<[ResultSet](#resultset)> | Promise used to return the result. If the operation is successful, a **ResultSet** object will be returned.| 1828 1829**Example** 1830 1831```js 1832import dataSharePredicates from '@ohos.data.dataSharePredicates' 1833let predicates = new dataSharePredicates.DataSharePredicates(); 1834predicates.equalTo("NAME", "Rose"); 1835let promise = store.query("EMPLOYEE", predicates, ["ID", "NAME", "AGE", "SALARY", "CODES"]); 1836promise.then((resultSet) => { 1837 console.info(`ResultSet column names: ${resultSet.columnNames}`); 1838 console.info(`ResultSet column count: ${resultSet.columnCount}`); 1839}).catch((err) => { 1840 console.error(`Query failed, err: ${err}`); 1841}) 1842``` 1843 1844### remoteQuery 1845 1846remoteQuery(device: string, table: string, predicates: RdbPredicates, columns: Array<string> , callback: AsyncCallback<ResultSet>): void 1847 1848Queries data from the RDB store of a remote device based on specified conditions. This API uses an asynchronous callback to return the result. 1849 1850> **NOTE** 1851> 1852> The value of **device** is obtained by [deviceManager.getTrustedDeviceListSync](js-apis-device-manager.md#gettrusteddevicelistsync). The APIs of the **deviceManager** module are system interfaces and available only to system applications. 1853 1854**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 1855 1856**Parameters** 1857 1858| Name | Type | Mandatory| Description | 1859| ---------- | -------------------------------------------- | ---- | --------------------------------------------------------- | 1860| device | string | Yes | ID of the remote device. | 1861| table | string | Yes | Name of the target table. | 1862| predicates | [RdbPredicates](#rdbpredicates) | Yes | Query conditions specified by the **RdbPredicates** object. | 1863| columns | Array<string> | Yes | Columns to query. If this parameter is not specified, the query applies to all columns. | 1864| callback | AsyncCallback<[ResultSet](#resultset)> | Yes | Callback invoked to return the result. If the operation is successful, a **ResultSet** object will be returned.| 1865 1866**Example** 1867 1868```js 1869import deviceManager from '@ohos.distributedHardware.deviceManager'; 1870let dmInstance = null; 1871 1872deviceManager.createDeviceManager("com.example.appdatamgrverify", (err, manager) => { 1873 if (err) { 1874 console.log("create device manager failed, err=" + err); 1875 return; 1876 } 1877 dmInstance = manager; 1878 let devices = dmInstance.getTrustedDeviceListSync(); 1879 let deviceId = devices[0].deviceId; 1880}) 1881 1882let predicates = new relationalStore.RdbPredicates('EMPLOYEE'); 1883predicates.greaterThan("id", 0); 1884store.remoteQuery(deviceId, "EMPLOYEE", predicates, ["ID", "NAME", "AGE", "SALARY", "CODES"], 1885 function(err, resultSet) { 1886 if (err) { 1887 console.error(`Failed to remoteQuery, err: ${err}`); 1888 return; 1889 } 1890 console.info(`ResultSet column names: ${resultSet.columnNames}`); 1891 console.info(`ResultSet column count: ${resultSet.columnCount}`); 1892 } 1893) 1894``` 1895 1896### remoteQuery 1897 1898remoteQuery(device: string, table: string, predicates: RdbPredicates, columns: Array<string>): Promise<ResultSet> 1899 1900Queries data from the RDB store of a remote device based on specified conditions. This API uses a promise to return the result. 1901 1902> **NOTE** 1903> 1904> The value of **device** is obtained by [deviceManager.getTrustedDeviceListSync](js-apis-device-manager.md#gettrusteddevicelistsync). The APIs of the **deviceManager** module are system interfaces and available only to system applications. 1905 1906**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 1907 1908**Parameters** 1909 1910| Name | Type | Mandatory| Description | 1911| ---------- | ------------------------------------ | ---- | ------------------------------------------------ | 1912| device | string | Yes | ID of the remote device. | 1913| table | string | Yes | Name of the target table. | 1914| predicates | [RdbPredicates](#rdbpredicates) | Yes | Query conditions specified by the **RdbPredicates** object. | 1915| columns | Array<string> | Yes | Columns to query. If this parameter is not specified, the query applies to all columns.| 1916 1917**Return value** 1918 1919| Type | Description | 1920| ------------------------------------------------------------ | -------------------------------------------------- | 1921| Promise<[ResultSet](#resultset)> | Promise used to return the result. If the operation is successful, a **ResultSet** object will be returned.| 1922 1923**Example** 1924 1925```js 1926import deviceManager from '@ohos.distributedHardware.deviceManager'; 1927let dmInstance = null; 1928 1929deviceManager.createDeviceManager("com.example.appdatamgrverify", (err, manager) => { 1930 if (err) { 1931 console.log("create device manager failed, err=" + err); 1932 return; 1933 } 1934 dmInstance = manager; 1935 let devices = dmInstance.getTrustedDeviceListSync(); 1936 let deviceId = devices[0].deviceId; 1937}) 1938 1939let predicates = new relationalStore.RdbPredicates('EMPLOYEE'); 1940predicates.greaterThan("id", 0); 1941let promise = store.remoteQuery("deviceId", "EMPLOYEE", predicates, ["ID", "NAME", "AGE", "SALARY", "CODES"]); 1942promise.then((resultSet) => { 1943 console.info(`ResultSet column names: ${resultSet.columnNames}`); 1944 console.info(`ResultSet column count: ${resultSet.columnCount}`); 1945}).catch((err) => { 1946 console.error(`Failed to remoteQuery, err: ${err}`); 1947}) 1948``` 1949 1950### querySql 1951 1952querySql(sql: string, bindArgs: Array<ValueType>, callback: AsyncCallback<ResultSet>):void 1953 1954Queries data using the specified SQL statement. This API uses an asynchronous callback to return the result. 1955 1956**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 1957 1958**Parameters** 1959 1960| Name | Type | Mandatory| Description | 1961| -------- | ------------------------------------------------------------ | ---- | ----------------------------------------------------------- | 1962| sql | string | Yes | SQL statement to run. | 1963| bindArgs | Array<[ValueType](#valuetype)> | Yes | Arguments in the SQL statement. | 1964| callback | AsyncCallback<[ResultSet](#resultset)> | Yes | Callback invoked to return the result. If the operation is successful, a **ResultSet** object will be returned.| 1965 1966**Example** 1967 1968```js 1969store.querySql("SELECT * FROM EMPLOYEE CROSS JOIN BOOK WHERE BOOK.NAME = ?", ['sanguo'], function (err, resultSet) { 1970 if (err) { 1971 console.error(`Query failed, err: ${err}`); 1972 return; 1973 } 1974 console.info(`ResultSet column names: ${resultSet.columnNames}`); 1975 console.info(`ResultSet column count: ${resultSet.columnCount}`); 1976}) 1977``` 1978 1979### querySql 1980 1981querySql(sql: string, bindArgs?: Array<ValueType>):Promise<ResultSet> 1982 1983Queries data using the specified SQL statement. This API uses a promise to return the result. 1984 1985**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 1986 1987**Parameters** 1988 1989| Name | Type | Mandatory| Description | 1990| -------- | ------------------------------------ | ---- | --------------------- | 1991| sql | string | Yes | SQL statement to run.| 1992| bindArgs | Array<[ValueType](#valuetype)> | No | Arguments in the SQL statement. | 1993 1994**Return value** 1995 1996| Type | Description | 1997| ------------------------------------------------------- | -------------------------------------------------- | 1998| Promise<[ResultSet](#resultset)> | Promise used to return the result. If the operation is successful, a **ResultSet** object will be returned.| 1999 2000**Example** 2001 2002```js 2003let promise = store.querySql("SELECT * FROM EMPLOYEE CROSS JOIN BOOK WHERE BOOK.NAME = ?", ['sanguo']); 2004promise.then((resultSet) => { 2005 console.info(`ResultSet column names: ${resultSet.columnNames}`); 2006 console.info(`ResultSet column count: ${resultSet.columnCount}`); 2007}).catch((err) => { 2008 console.error(`Query failed, err: ${err}`); 2009}) 2010``` 2011 2012### executeSql 2013 2014executeSql(sql: string, bindArgs: Array<ValueType>, callback: AsyncCallback<void>):void 2015 2016Executes an SQL statement that contains specified arguments but returns no value. This API uses an asynchronous callback to return the result. 2017 2018**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 2019 2020**Parameters** 2021 2022| Name | Type | Mandatory| Description | 2023| -------- | ------------------------------------ | ---- | ---------------------- | 2024| sql | string | Yes | SQL statement to run. | 2025| bindArgs | Array<[ValueType](#valuetype)> | Yes | Arguments in the SQL statement. | 2026| callback | AsyncCallback<void> | Yes | Callback invoked to return the result.| 2027 2028**Example** 2029 2030```js 2031const SQL_CREATE_TABLE = "CREATE TABLE IF NOT EXISTS EMPLOYEE (ID INTEGER PRIMARY KEY AUTOINCREMENT, NAME TEXT NOT NULL, AGE INTEGER, SALARY REAL, CODES BLOB)" 2032store.executeSql(SQL_CREATE_TABLE, null, function(err) { 2033 if (err) { 2034 console.error(`ExecuteSql failed, err: ${err}`); 2035 return; 2036 } 2037 console.info(`Create table done.`); 2038}) 2039``` 2040 2041### executeSql 2042 2043executeSql(sql: string, bindArgs?: Array<ValueType>):Promise<void> 2044 2045Executes an SQL statement that contains specified arguments but returns no value. This API uses a promise to return the result. 2046 2047**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 2048 2049**Parameters** 2050 2051| Name | Type | Mandatory| Description | 2052| -------- | ------------------------------------ | ---- | --------------------- | 2053| sql | string | Yes | SQL statement to run.| 2054| bindArgs | Array<[ValueType](#valuetype)> | No | Arguments in the SQL statement. | 2055 2056**Return value** 2057 2058| Type | Description | 2059| ------------------- | ------------------------- | 2060| Promise<void> | Promise that returns no value.| 2061 2062**Example** 2063 2064```js 2065const SQL_CREATE_TABLE = "CREATE TABLE IF NOT EXISTS EMPLOYEE (ID INTEGER PRIMARY KEY AUTOINCREMENT, NAME TEXT NOT NULL, AGE INTEGER, SALARY REAL, CODES BLOB)" 2066let promise = store.executeSql(SQL_CREATE_TABLE); 2067promise.then(() => { 2068 console.info(`Create table done.`); 2069}).catch((err) => { 2070 console.error(`ExecuteSql failed, err: ${err}`); 2071}) 2072``` 2073 2074### beginTransaction 2075 2076beginTransaction():void 2077 2078Starts the transaction before executing an SQL statement. 2079 2080**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 2081 2082**Example** 2083 2084```js 2085import featureAbility from '@ohos.ability.featureAbility' 2086let context = featureAbility.getContext(); 2087const STORE_CONFIG = { 2088 name: "RdbTest.db", 2089 securityLevel: relationalStore.SecurityLevel.S1 2090}; 2091relationalStore.getRdbStore(context, STORE_CONFIG, async function (err, store) { 2092 if (err) { 2093 console.error(`GetRdbStore failed, err: ${err}`); 2094 return; 2095 } 2096 store.beginTransaction(); 2097 const valueBucket = { 2098 "name": "lisi", 2099 "age": 18, 2100 "salary": 100.5, 2101 "blobType": new Uint8Array([1, 2, 3]), 2102 }; 2103 await store.insert("test", valueBucket); 2104 store.commit(); 2105}) 2106``` 2107 2108### commit 2109 2110commit():void 2111 2112Commits the executed SQL statements. 2113 2114**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 2115 2116**Example** 2117 2118```js 2119import featureAbility from '@ohos.ability.featureAbility' 2120let context = featureAbility.getContext(); 2121const STORE_CONFIG = { 2122 name: "RdbTest.db", 2123 securityLevel: relationalStore.SecurityLevel.S1 2124}; 2125relationalStore.getRdbStore(context, STORE_CONFIG, async function (err, store) { 2126 if (err) { 2127 console.error(`GetRdbStore failed, err: ${err}`); 2128 return; 2129 } 2130 store.beginTransaction(); 2131 const valueBucket = { 2132 "name": "lisi", 2133 "age": 18, 2134 "salary": 100.5, 2135 "blobType": new Uint8Array([1, 2, 3]), 2136 }; 2137 await store.insert("test", valueBucket); 2138 store.commit(); 2139}) 2140``` 2141 2142### rollBack 2143 2144rollBack():void 2145 2146Rolls back the SQL statements that have been executed. 2147 2148**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 2149 2150**Example** 2151 2152```js 2153import featureAbility from '@ohos.ability.featureAbility' 2154let context = featureAbility.getContext(); 2155const STORE_CONFIG = { 2156 name: "RdbTest.db", 2157 securityLevel: relationalStore.SecurityLevel.S1 2158}; 2159relationalStore.getRdbStore(context, STORE_CONFIG, async function (err, store) { 2160 if (err) { 2161 console.error(`GetRdbStore failed, err: ${err}`); 2162 return; 2163 } 2164 try { 2165 store.beginTransaction() 2166 const valueBucket = { 2167 "id": 1, 2168 "name": "lisi", 2169 "age": 18, 2170 "salary": 100.5, 2171 "blobType": new Uint8Array([1, 2, 3]), 2172 }; 2173 await store.insert("test", valueBucket); 2174 store.commit(); 2175 } catch (err) { 2176 console.error(`Transaction failed, err: ${err}`); 2177 store.rollBack(); 2178 } 2179}) 2180``` 2181 2182### backup 2183 2184backup(destName:string, callback: AsyncCallback<void>):void 2185 2186Backs up an RDB store. This API uses an asynchronous callback to return the result. 2187 2188**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 2189 2190**Parameters** 2191 2192| Name | Type | Mandatory| Description | 2193| -------- | ------------------------- | ---- | ------------------------ | 2194| destName | string | Yes | Name of the RDB store backup file.| 2195| callback | AsyncCallback<void> | Yes | Callback invoked to return the result. | 2196 2197**Example** 2198 2199```js 2200store.backup("dbBackup.db", function(err) { 2201 if (err) { 2202 console.error(`Backup failed, err: ${err}`); 2203 return; 2204 } 2205 console.info(`Backup success.`); 2206}) 2207``` 2208 2209### backup 2210 2211backup(destName:string): Promise<void> 2212 2213Backs up an RDB store. This API uses a promise to return the result. 2214 2215**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 2216 2217**Parameters** 2218 2219| Name | Type | Mandatory| Description | 2220| -------- | ------ | ---- | ------------------------ | 2221| destName | string | Yes | Name of the RDB store backup file.| 2222 2223**Return value** 2224 2225| Type | Description | 2226| ------------------- | ------------------------- | 2227| Promise<void> | Promise that returns no value.| 2228 2229**Example** 2230 2231```js 2232let promiseBackup = store.backup("dbBackup.db"); 2233promiseBackup.then(()=>{ 2234 console.info(`Backup success.`); 2235}).catch((err)=>{ 2236 console.error(`Backup failed, err: ${err}`); 2237}) 2238``` 2239 2240### restore 2241 2242restore(srcName:string, callback: AsyncCallback<void>):void 2243 2244Restores an RDB store from a backup file. This API uses an asynchronous callback to return the result. 2245 2246**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 2247 2248**Parameters** 2249 2250| Name | Type | Mandatory| Description | 2251| -------- | ------------------------- | ---- | ------------------------ | 2252| srcName | string | Yes | Name of the RDB store backup file.| 2253| callback | AsyncCallback<void> | Yes | Callback invoked to return the result. | 2254 2255**Example** 2256 2257```js 2258store.restore("dbBackup.db", function(err) { 2259 if (err) { 2260 console.error(`Restore failed, err: ${err}`); 2261 return; 2262 } 2263 console.info(`Restore success.`); 2264}) 2265``` 2266 2267### restore 2268 2269restore(srcName:string): Promise<void> 2270 2271Restores an RDB store from a backup file. This API uses a promise to return the result. 2272 2273**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 2274 2275**Parameters** 2276 2277| Name | Type | Mandatory| Description | 2278| ------- | ------ | ---- | ------------------------ | 2279| srcName | string | Yes | Name of the RDB store backup file.| 2280 2281**Return value** 2282 2283| Type | Description | 2284| ------------------- | ------------------------- | 2285| Promise<void> | Promise that returns no value.| 2286 2287**Example** 2288 2289```js 2290let promiseRestore = store.restore("dbBackup.db"); 2291promiseRestore.then(()=>{ 2292 console.info(`Restore success.`); 2293}).catch((err)=>{ 2294 console.error(`Restore failed, err: ${err}`); 2295}) 2296``` 2297 2298### setDistributedTables 2299 2300setDistributedTables(tables: Array<string>, callback: AsyncCallback<void>): void 2301 2302Sets distributed tables. This API uses an asynchronous callback to return the result. 2303 2304**Required permissions**: ohos.permission.DISTRIBUTED_DATASYNC 2305 2306**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 2307 2308**Parameters** 2309 2310| Name | Type | Mandatory| Description | 2311| -------- | ------------------------- | ---- | ---------------------- | 2312| tables | Array<string> | Yes | Names of the distributed tables to set.| 2313| callback | AsyncCallback<void> | Yes | Callback invoked to return the result.| 2314 2315**Example** 2316 2317```js 2318store.setDistributedTables(["EMPLOYEE"], function (err) { 2319 if (err) { 2320 console.error(`SetDistributedTables failed, err: ${err}`); 2321 return; 2322 } 2323 console.info(`SetDistributedTables successfully.`); 2324}) 2325``` 2326 2327### setDistributedTables 2328 2329 setDistributedTables(tables: Array<string>): Promise<void> 2330 2331Sets distributed tables. This API uses a promise to return the result. 2332 2333**Required permissions**: ohos.permission.DISTRIBUTED_DATASYNC 2334 2335**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 2336 2337**Parameters** 2338 2339| Name| Type | Mandatory| Description | 2340| ------ | ------------------- | ---- | ------------------------ | 2341| tables | Array<string> | Yes | Names of the distributed tables to set.| 2342 2343**Return value** 2344 2345| Type | Description | 2346| ------------------- | ------------------------- | 2347| Promise<void> | Promise that returns no value.| 2348 2349**Example** 2350 2351```js 2352let promise = store.setDistributedTables(["EMPLOYEE"]); 2353promise.then(() => { 2354 console.info(`SetDistributedTables successfully.`); 2355}).catch((err) => { 2356 console.error(`SetDistributedTables failed, err: ${err}`); 2357}) 2358``` 2359 2360### obtainDistributedTableName 2361 2362obtainDistributedTableName(device: string, table: string, callback: AsyncCallback<string>): void 2363 2364Obtains the distributed table name of a remote device based on the local table name of the device. The distributed table name is required when the RDB store of a remote device is queried. 2365 2366> **NOTE** 2367> 2368> The value of **device** is obtained by [deviceManager.getTrustedDeviceListSync](js-apis-device-manager.md#gettrusteddevicelistsync). The APIs of the **deviceManager** module are system interfaces and available only to system applications. 2369 2370**Required permissions**: ohos.permission.DISTRIBUTED_DATASYNC 2371 2372**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 2373 2374**Parameters** 2375 2376| Name | Type | Mandatory| Description | 2377| -------- | --------------------------- | ---- | ------------------------------------------------------------ | 2378| device | string | Yes | ID of the remote device. | 2379| table | string | Yes | Local table name of the remote device. | 2380| callback | AsyncCallback<string> | Yes | Callback invoked to return the result. If the operation succeeds, the distributed table name of the remote device is returned.| 2381 2382**Example** 2383 2384```js 2385import deviceManager from '@ohos.distributedHardware.deviceManager'; 2386let dmInstance = null; 2387 2388deviceManager.createDeviceManager("com.example.appdatamgrverify", (err, manager) => { 2389 if (err) { 2390 console.log("create device manager failed, err=" + err); 2391 return; 2392 } 2393 dmInstance = manager; 2394 let devices = dmInstance.getTrustedDeviceListSync(); 2395 let deviceId = devices[0].deviceId; 2396}) 2397 2398store.obtainDistributedTableName(deviceId, "EMPLOYEE", function (err, tableName) { 2399 if (err) { 2400 console.error(`ObtainDistributedTableName failed, err: ${err}`); 2401 return; 2402 } 2403 console.info(`ObtainDistributedTableName successfully, tableName= ${tableName}`); 2404}) 2405``` 2406 2407### obtainDistributedTableName 2408 2409 obtainDistributedTableName(device: string, table: string): Promise<string> 2410 2411Obtains the distributed table name of a remote device based on the local table name of the device. The distributed table name is required when the RDB store of a remote device is queried. 2412 2413> **NOTE** 2414> 2415> The value of **device** is obtained by [deviceManager.getTrustedDeviceListSync](js-apis-device-manager.md#gettrusteddevicelistsync). The APIs of the **deviceManager** module are system interfaces and available only to system applications. 2416 2417**Required permissions**: ohos.permission.DISTRIBUTED_DATASYNC 2418 2419**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 2420 2421**Parameters** 2422 2423| Name| Type | Mandatory| Description | 2424| ------ | ------ | ---- | -------------------- | 2425| device | string | Yes | ID of the remote device. | 2426| table | string | Yes | Local table name of the remote device.| 2427 2428**Return value** 2429 2430| Type | Description | 2431| --------------------- | ----------------------------------------------------- | 2432| Promise<string> | Promise used to return the result. If the operation succeeds, the distributed table name of the remote device is returned.| 2433 2434**Example** 2435 2436```js 2437import deviceManager from '@ohos.distributedHardware.deviceManager'; 2438let dmInstance = null; 2439 2440deviceManager.createDeviceManager("com.example.appdatamgrverify", (err, manager) => { 2441 if (err) { 2442 console.log("create device manager failed, err=" + err); 2443 return; 2444 } 2445 dmInstance = manager; 2446 let devices = dmInstance.getTrustedDeviceListSync(); 2447 let deviceId = devices[0].deviceId; 2448}) 2449 2450let promise = store.obtainDistributedTableName(deviceId, "EMPLOYEE"); 2451promise.then((tableName) => { 2452 console.info(`ObtainDistributedTableName successfully, tableName= ${tableName}`); 2453}).catch((err) => { 2454 console.error(`ObtainDistributedTableName failed, err: ${err}`); 2455}) 2456``` 2457 2458### sync 2459 2460sync(mode: SyncMode, predicates: RdbPredicates, callback: AsyncCallback<Array<[string, number]>>): void 2461 2462Synchronizes data between devices. This API uses an asynchronous callback to return the result. 2463 2464**Required permissions**: ohos.permission.DISTRIBUTED_DATASYNC 2465 2466**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 2467 2468**Parameters** 2469 2470| Name | Type | Mandatory| Description | 2471| ---------- | -------------------------------------------------- | ---- | ------------------------------------------------------------ | 2472| mode | [SyncMode](#syncmode) | Yes | Data synchronization mode. The value can be **push** or **pull**. | 2473| predicates | [RdbPredicates](#rdbpredicates) | Yes | **RdbPredicates** object that specifies the data and devices to synchronize. | 2474| callback | AsyncCallback<Array<[string, number]>> | Yes | Callback invoked to send the synchronization result to the caller. <br>**string** indicates the device ID. <br>**number** indicates the synchronization status of that device. The value **0** indicates a successful synchronization. Other values indicate a synchronization failure. | 2475 2476**Example** 2477 2478```js 2479import deviceManager from '@ohos.distributedHardware.deviceManager'; 2480let dmInstance = null; 2481 2482deviceManager.createDeviceManager("com.example.appdatamgrverify", (err, manager) => { 2483 if (err) { 2484 console.log("create device manager failed, err=" + err); 2485 return; 2486 } 2487 dmInstance = manager; 2488 let devices = dmInstance.getTrustedDeviceListSync(); 2489 let deviceIds = []; 2490 for (var i = 0; i < devices.length; i++) { 2491 deviceIds[i] = devices[i].deviceId; 2492 } 2493}) 2494 2495let predicates = new relationalStore.RdbPredicates('EMPLOYEE'); 2496predicates.inDevices(deviceIds); 2497store.sync(relationalStore.SyncMode.SYNC_MODE_PUSH, predicates, function (err, result) { 2498 if (err) { 2499 console.error(`Sync failed, err: ${err}`); 2500 return; 2501 } 2502 console.info(`Sync done.`); 2503 for (let i = 0; i < result.length; i++) { 2504 console.info(`device= ${result[i][0]}, status= ${result[i][1]}`); 2505 } 2506}) 2507``` 2508 2509### sync 2510 2511 sync(mode: SyncMode, predicates: RdbPredicates): Promise<Array<[string, number]>> 2512 2513Synchronizes data between devices. This API uses a promise to return the result. 2514 2515**Required permissions**: ohos.permission.DISTRIBUTED_DATASYNC 2516 2517**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 2518 2519**Parameters** 2520 2521| Name | Type | Mandatory| Description | 2522| ---------- | ------------------------------------ | ---- | ------------------------------ | 2523| mode | [SyncMode](#syncmode) | Yes | Data synchronization mode. The value can be **push** or **pull**.| 2524| predicates | [RdbPredicates](#rdbpredicates) | Yes | **RdbPredicates** object that specifies the data and devices to synchronize. | 2525 2526**Return value** 2527 2528| Type | Description | 2529| -------------------------------------------- | ------------------------------------------------------------ | 2530| Promise<Array<[string, number]>> | Promise used to send the synchronization result. <br>**string** indicates the device ID. <br>**number** indicates the synchronization status of that device. The value **0** indicates a successful synchronization. Other values indicate a synchronization failure. | 2531 2532**Example** 2533 2534```js 2535import deviceManager from '@ohos.distributedHardware.deviceManager'; 2536let dmInstance = null; 2537 2538deviceManager.createDeviceManager("com.example.appdatamgrverify", (err, manager) => { 2539 if (err) { 2540 console.log("create device manager failed, err=" + err); 2541 return; 2542 } 2543 dmInstance = manager; 2544 let devices = dmInstance.getTrustedDeviceListSync(); 2545 let deviceIds = []; 2546 for (var i = 0; i < devices.length; i++) { 2547 deviceIds[i] = devices[i].deviceId; 2548 } 2549}) 2550 2551let predicates = new relationalStore.RdbPredicates('EMPLOYEE'); 2552predicates.inDevices(deviceIds); 2553let promise = store.sync(relationalStore.SyncMode.SYNC_MODE_PUSH, predicates); 2554promise.then((result) =>{ 2555 console.info(`Sync done.`); 2556 for (let i = 0; i < result.length; i++) { 2557 console.info(`device= ${result[i][0]}, status= ${result[i][1]}`); 2558 } 2559}).catch((err) => { 2560 console.error(`Sync failed, err: ${err}`); 2561}) 2562``` 2563 2564### on('dataChange') 2565 2566on(event: 'dataChange', type: SubscribeType, observer: Callback<Array<string>>): void 2567 2568Registers an observer for this RDB store. When the data in the RDB store changes, a callback is invoked to return the data changes. 2569 2570**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 2571 2572**Parameters** 2573 2574| Name | Type | Mandatory| Description | 2575| -------- | ----------------------------------- | ---- | ------------------------------------------- | 2576| event | string | Yes | Event to observe. The value is **dataChange**, which indicates a data change event. | 2577| type | [SubscribeType](#subscribetype) | Yes | Subscription type to register.| 2578| observer | Callback<Array<string>> | Yes | Callback invoked to return the data change. | 2579 2580**Example** 2581 2582```js 2583function storeObserver(devices) { 2584 for (let i = 0; i < devices.length; i++) { 2585 console.info(`device= ${devices[i]} data changed`); 2586 } 2587} 2588try { 2589 store.on('dataChange', relationalStore.SubscribeType.SUBSCRIBE_TYPE_REMOTE, storeObserver); 2590} catch (err) { 2591 console.error(`Register observer failed, err: ${err}`); 2592} 2593``` 2594 2595### off('dataChange') 2596 2597off(event:'dataChange', type: SubscribeType, observer: Callback<Array<string>>): void 2598 2599Unregisters the observer of the specified type from the RDB store. This API uses a callback to return the result. 2600 2601**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 2602 2603**Parameters** 2604 2605| Name | Type | Mandatory| Description | 2606| -------- | ---------------------------------- | ---- | ------------------------------------------ | 2607| event | string | Yes | Event to observe. The value is **dataChange**, which indicates a data change event. | 2608| type | [SubscribeType](#subscribetype) | Yes | Subscription type to unregister. | 2609| observer | Callback<Array<string>> | Yes | Callback for the data change. | 2610 2611**Example** 2612 2613```js 2614function storeObserver(devices) { 2615 for (let i = 0; i < devices.length; i++) { 2616 console.info(`device= ${devices[i]} data changed`); 2617 } 2618} 2619try { 2620 store.off('dataChange', relationalStore.SubscribeType.SUBSCRIBE_TYPE_REMOTE, storeObserver); 2621} catch (err) { 2622 console.error(`Unregister observer failed, err: ${err}`); 2623} 2624``` 2625 2626## ResultSet 2627 2628Provides APIs to access the result set obtained by querying the RDB store. A result set is a set of results returned after **query()** is called. 2629 2630### Usage 2631 2632Obtain the **resultSet** object first. 2633 2634```js 2635let resultSet = null; 2636let predicates = new relationalStore.RdbPredicates("EMPLOYEE"); 2637predicates.equalTo("AGE", 18); 2638let promise = store.query(predicates, ["ID", "NAME", "AGE", "SALARY", "CODES"]); 2639promise.then((result) => { 2640 resultSet = result; 2641 console.info(`resultSet columnNames: ${resultSet.columnNames}`); 2642 console.info(`resultSet columnCount: ${resultSet.columnCount}`); 2643}); 2644``` 2645 2646### Attributes 2647 2648**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 2649 2650| Name | Type | Mandatory| Description | 2651| ------------ | ------------------- | ---- | -------------------------------- | 2652| columnNames | Array<string> | Yes | Names of all columns in the result set. | 2653| columnCount | number | Yes | Number of columns in the result set. | 2654| rowCount | number | Yes | Number of rows in the result set. | 2655| rowIndex | number | Yes | Index of the current row in the result set. | 2656| isAtFirstRow | boolean | Yes | Whether the cursor is in the first row of the result set. | 2657| isAtLastRow | boolean | Yes | Whether the cursor is in the last row of the result set. | 2658| isEnded | boolean | Yes | Whether the cursor is after the last row of the result set.| 2659| isStarted | boolean | Yes | Whether the cursor has been moved. | 2660| isClosed | boolean | Yes | Whether the result set is closed. | 2661 2662### getColumnIndex 2663 2664getColumnIndex(columnName: string): number 2665 2666Obtains the column index based on the column name. 2667 2668**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 2669 2670**Parameters** 2671 2672| Name | Type | Mandatory| Description | 2673| ---------- | ------ | ---- | -------------------------- | 2674| columnName | string | Yes | Column name.| 2675 2676**Return value** 2677 2678| Type | Description | 2679| ------ | ------------------ | 2680| number | Column index obtained.| 2681 2682**Error codes** 2683 2684For details about the error codes, see [RDB Error Codes](../errorcodes/errorcode-data-rdb.md). 2685 2686| **ID**| **Error Message** | 2687| ------------ | ------------------------------------------------------------ | 2688| 14800013 | The column value is null or the column type is incompatible. | 2689 2690**Example** 2691 2692 ```js 2693resultSet.goToFirstRow(); 2694const id = resultSet.getLong(resultSet.getColumnIndex("ID")); 2695const name = resultSet.getString(resultSet.getColumnIndex("NAME")); 2696const age = resultSet.getLong(resultSet.getColumnIndex("AGE")); 2697const salary = resultSet.getDouble(resultSet.getColumnIndex("SALARY")); 2698 ``` 2699 2700### getColumnName 2701 2702getColumnName(columnIndex: number): string 2703 2704Obtains the column name based on the specified column index. 2705 2706**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 2707 2708**Parameters** 2709 2710| Name | Type | Mandatory| Description | 2711| ----------- | ------ | ---- | -------------------------- | 2712| columnIndex | number | Yes | Column index.| 2713 2714**Return value** 2715 2716| Type | Description | 2717| ------ | ------------------ | 2718| string | Column name obtained.| 2719 2720**Error codes** 2721 2722For details about the error codes, see [RDB Error Codes](../errorcodes/errorcode-data-rdb.md). 2723 2724| **ID**| **Error Message** | 2725| ------------ | ------------------------------------------------------------ | 2726| 14800013 | The column value is null or the column type is incompatible. | 2727 2728**Example** 2729 2730 ```js 2731const id = resultSet.getColumnName(0); 2732const name = resultSet.getColumnName(1); 2733const age = resultSet.getColumnName(2); 2734 ``` 2735 2736### goTo 2737 2738goTo(offset:number): boolean 2739 2740Moves the cursor to the row based on the specified offset. 2741 2742**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 2743 2744**Parameters** 2745 2746| Name| Type | Mandatory| Description | 2747| ------ | ------ | ---- | ---------------------------- | 2748| offset | number | Yes | Offset relative to the current position.| 2749 2750**Return value** 2751 2752| Type | Description | 2753| ------- | --------------------------------------------- | 2754| boolean | Returns **true** if the operation is successful; returns **false** otherwise.| 2755 2756**Error codes** 2757 2758For details about the error codes, see [RDB Error Codes](../errorcodes/errorcode-data-rdb.md). 2759 2760| **ID**| **Error Message** | 2761| ------------ | ------------------------------------------------------------ | 2762| 14800012 | The result set is empty or the specified location is invalid. | 2763 2764**Example** 2765 2766 ```js 2767let predicates = new relationalStore.RdbPredicates("EMPLOYEE"); 2768let promise= store.query(predicates, ["ID", "NAME", "AGE", "SALARY", "CODES"]); 2769promise.then((resultSet) => { 2770 resultSet.goTo(1); 2771 resultSet.close(); 2772}).catch((err) => { 2773 console.error(`query failed, err: ${err}`); 2774}); 2775 ``` 2776 2777### goToRow 2778 2779goToRow(position: number): boolean 2780 2781Moves to the specified row in the result set. 2782 2783**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 2784 2785**Parameters** 2786 2787| Name | Type | Mandatory| Description | 2788| -------- | ------ | ---- | ------------------------ | 2789| position | number | Yes | Destination position to move to.| 2790 2791**Return value** 2792 2793| Type | Description | 2794| ------- | --------------------------------------------- | 2795| boolean | Returns **true** if the operation is successful; returns **false** otherwise.| 2796 2797**Error codes** 2798 2799For details about the error codes, see [RDB Error Codes](../errorcodes/errorcode-data-rdb.md). 2800 2801| **ID**| **Error Message** | 2802| ------------ | ------------------------------------------------------------ | 2803| 14800012 | The result set is empty or the specified location is invalid. | 2804 2805**Example** 2806 2807 ```js 2808let predicates = new relationalStore.RdbPredicates("EMPLOYEE"); 2809let promise = store.query(predicates, ["ID", "NAME", "AGE", "SALARY", "CODES"]); 2810promise.then((resultSet) => { 2811 resultSet.goToRow(5); 2812 resultSet.close(); 2813}).catch((err) => { 2814 console.error(`query failed, err: ${err}`); 2815}); 2816 ``` 2817 2818### goToFirstRow 2819 2820goToFirstRow(): boolean 2821 2822 2823Moves to the first row of the result set. 2824 2825**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 2826 2827**Return value** 2828 2829| Type | Description | 2830| ------- | --------------------------------------------- | 2831| boolean | Returns **true** if the operation is successful; returns **false** otherwise.| 2832 2833**Error codes** 2834 2835For details about the error codes, see [RDB Error Codes](../errorcodes/errorcode-data-rdb.md). 2836 2837| **ID**| **Error Message** | 2838| ------------ | ------------------------------------------------------------ | 2839| 14800012 | The result set is empty or the specified location is invalid. | 2840 2841**Example** 2842 2843 ```js 2844let predicates = new relationalStore.RdbPredicates("EMPLOYEE"); 2845let promise = store.query(predicates, ["ID", "NAME", "AGE", "SALARY", "CODES"]); 2846promise.then((resultSet) => { 2847 resultSet.goToFirstRow(); 2848 resultSet.close(); 2849}).catch((err) => { 2850 console.error(`query failed, err: ${err}`); 2851}); 2852 ``` 2853 2854### goToLastRow 2855 2856goToLastRow(): boolean 2857 2858Moves to the last row of the result set. 2859 2860**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 2861 2862**Return value** 2863 2864| Type | Description | 2865| ------- | --------------------------------------------- | 2866| boolean | Returns **true** if the operation is successful; returns **false** otherwise.| 2867 2868**Error codes** 2869 2870For details about the error codes, see [RDB Error Codes](../errorcodes/errorcode-data-rdb.md). 2871 2872| **ID**| **Error Message** | 2873| ------------ | ------------------------------------------------------------ | 2874| 14800012 | The result set is empty or the specified location is invalid. | 2875 2876**Example** 2877 2878 ```js 2879let predicates = new relationalStore.RdbPredicates("EMPLOYEE"); 2880let promise = store.query(predicates, ["ID", "NAME", "AGE", "SALARY", "CODES"]); 2881promise.then((resultSet) => { 2882 resultSet.goToLastRow(); 2883 resultSet.close(); 2884}).catch((err) => { 2885 console.error(`query failed, err: ${err}`); 2886}); 2887 ``` 2888 2889### goToNextRow 2890 2891goToNextRow(): boolean 2892 2893Moves to the next row in the result set. 2894 2895**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 2896 2897**Return value** 2898 2899| Type | Description | 2900| ------- | --------------------------------------------- | 2901| boolean | Returns **true** if the operation is successful; returns **false** otherwise.| 2902 2903**Error codes** 2904 2905For details about the error codes, see [RDB Error Codes](../errorcodes/errorcode-data-rdb.md). 2906 2907| **ID**| **Error Message** | 2908| ------------ | ------------------------------------------------------------ | 2909| 14800012 | The result set is empty or the specified location is invalid. | 2910 2911**Example** 2912 2913 ```js 2914let predicates = new relationalStore.RdbPredicates("EMPLOYEE"); 2915let promise = store.query(predicates, ["ID", "NAME", "AGE", "SALARY", "CODES"]); 2916promise.then((resultSet) => { 2917 resultSet.goToNextRow(); 2918 resultSet.close(); 2919}).catch((err) => { 2920 console.error(`query failed, err: ${err}`); 2921}); 2922 ``` 2923 2924### goToPreviousRow 2925 2926goToPreviousRow(): boolean 2927 2928Moves to the previous row in the result set. 2929 2930**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 2931 2932**Return value** 2933 2934| Type | Description | 2935| ------- | --------------------------------------------- | 2936| boolean | Returns **true** if the operation is successful; returns **false** otherwise.| 2937 2938**Error codes** 2939 2940For details about the error codes, see [RDB Error Codes](../errorcodes/errorcode-data-rdb.md). 2941 2942| **ID**| **Error Message** | 2943| ------------ | ------------------------------------------------------------ | 2944| 14800012 | The result set is empty or the specified location is invalid. | 2945 2946**Example** 2947 2948 ```js 2949let predicates = new relationalStore.RdbPredicates("EMPLOYEE"); 2950let promise = store.query(predicates, ["ID", "NAME", "AGE", "SALARY", "CODES"]); 2951promise.then((resultSet) => { 2952 resultSet.goToPreviousRow(); 2953 resultSet.close(); 2954}).catch((err) => { 2955 console.error(`query failed, err: ${err}`); 2956}); 2957 ``` 2958 2959### getBlob 2960 2961getBlob(columnIndex: number): Uint8Array 2962 2963Obtains the value in the form of a byte array based on the specified column and the current row. 2964 2965**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 2966 2967**Parameters** 2968 2969| Name | Type | Mandatory| Description | 2970| ----------- | ------ | ---- | ----------------------- | 2971| columnIndex | number | Yes | Index of the target column, starting from 0.| 2972 2973**Return value** 2974 2975| Type | Description | 2976| ---------- | -------------------------------- | 2977| Uint8Array | Value obtained.| 2978 2979**Error codes** 2980 2981For details about the error codes, see [RDB Error Codes](../errorcodes/errorcode-data-rdb.md). 2982 2983| **ID**| **Error Message** | 2984| ------------ | ------------------------------------------------------------ | 2985| 14800013 | The column value is null or the column type is incompatible. | 2986 2987**Example** 2988 2989 ```js 2990const codes = resultSet.getBlob(resultSet.getColumnIndex("CODES")); 2991 ``` 2992 2993### getString 2994 2995getString(columnIndex: number): string 2996 2997Obtains the value in the form of a string based on the specified column and the current row. 2998 2999**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 3000 3001**Parameters** 3002 3003| Name | Type | Mandatory| Description | 3004| ----------- | ------ | ---- | ----------------------- | 3005| columnIndex | number | Yes | Index of the target column, starting from 0.| 3006 3007**Return value** 3008 3009| Type | Description | 3010| ------ | ---------------------------- | 3011| string | String obtained.| 3012 3013**Error codes** 3014 3015For details about the error codes, see [RDB Error Codes](../errorcodes/errorcode-data-rdb.md). 3016 3017| **ID**| **Error Message** | 3018| ------------ | ------------------------------------------------------------ | 3019| 14800013 | The column value is null or the column type is incompatible. | 3020 3021**Example** 3022 3023 ```js 3024const name = resultSet.getString(resultSet.getColumnIndex("NAME")); 3025 ``` 3026 3027### getLong 3028 3029getLong(columnIndex: number): number 3030 3031Obtains the value of the Long type based on the specified column and the current row. 3032 3033**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 3034 3035**Parameters** 3036 3037| Name | Type | Mandatory| Description | 3038| ----------- | ------ | ---- | ----------------------- | 3039| columnIndex | number | Yes | Index of the target column, starting from 0.| 3040 3041**Return value** 3042 3043| Type | Description | 3044| ------ | ------------------------------------------------------------ | 3045| number | Value obtained.<br>The value range supported by this API is **Number.MIN_SAFE_INTEGER** to **Number.MAX_SAFE_INTEGER**. If the value is out of this range, use [getDouble](#getdouble).| 3046 3047**Error codes** 3048 3049For details about the error codes, see [RDB Error Codes](../errorcodes/errorcode-data-rdb.md). 3050 3051| **ID**| **Error Message** | 3052| ------------ | ------------------------------------------------------------ | 3053| 14800013 | The column value is null or the column type is incompatible. | 3054 3055**Example** 3056 3057 ```js 3058const age = resultSet.getLong(resultSet.getColumnIndex("AGE")); 3059 ``` 3060 3061### getDouble 3062 3063getDouble(columnIndex: number): number 3064 3065Obtains the value of the double type based on the specified column and the current row. 3066 3067**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 3068 3069**Parameters** 3070 3071| Name | Type | Mandatory| Description | 3072| ----------- | ------ | ---- | ----------------------- | 3073| columnIndex | number | Yes | Index of the target column, starting from 0.| 3074 3075**Return value** 3076 3077| Type | Description | 3078| ------ | ---------------------------- | 3079| number | Value obtained.| 3080 3081**Error codes** 3082 3083For details about the error codes, see [RDB Error Codes](../errorcodes/errorcode-data-rdb.md). 3084 3085| **ID**| **Error Message** | 3086| ------------ | ------------------------------------------------------------ | 3087| 14800013 | The column value is null or the column type is incompatible. | 3088 3089**Example** 3090 3091 ```js 3092const salary = resultSet.getDouble(resultSet.getColumnIndex("SALARY")); 3093 ``` 3094 3095### isColumnNull 3096 3097isColumnNull(columnIndex: number): boolean 3098 3099Checks whether the value in the specified column is null. 3100 3101**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 3102 3103**Parameters** 3104 3105| Name | Type | Mandatory| Description | 3106| ----------- | ------ | ---- | ----------------------- | 3107| columnIndex | number | Yes | Index of the target column, starting from 0.| 3108 3109**Return value** 3110 3111| Type | Description | 3112| ------- | --------------------------------------------------------- | 3113| boolean | Returns **true** if the value is null; returns **false** otherwise.| 3114 3115**Error codes** 3116 3117For details about the error codes, see [RDB Error Codes](../errorcodes/errorcode-data-rdb.md). 3118 3119| **ID**| **Error Message** | 3120| ------------ | ------------------------------------------------------------ | 3121| 14800013 | The column value is null or the column type is incompatible. | 3122 3123**Example** 3124 3125 ```js 3126const isColumnNull = resultSet.isColumnNull(resultSet.getColumnIndex("CODES")); 3127 ``` 3128 3129### close 3130 3131close(): void 3132 3133Closes this result set. 3134 3135**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 3136 3137**Example** 3138 3139 ```js 3140let predicatesClose = new relationalStore.RdbPredicates("EMPLOYEE"); 3141let promiseClose = store.query(predicatesClose, ["ID", "NAME", "AGE", "SALARY", "CODES"]); 3142promiseClose.then((resultSet) => { 3143 resultSet.close(); 3144}).catch((err) => { 3145 console.error(`resultset close failed, err: ${err}`); 3146}); 3147 ``` 3148 3149**Error codes** 3150 3151For details about the error codes, see [RDB Error Codes](../errorcodes/errorcode-data-rdb.md). 3152 3153| **ID**| **Error Message** | 3154| ------------ | ------------------------------------------------------------ | 3155| 14800012 | The result set is empty or the specified location is invalid. | 3156