1# @ohos.data.rdb (关系型数据库) 2 3关系型数据库（Relational Database，RDB）是一种基于关系模型来管理数据的数据库。关系型数据库基于SQLite组件提供了一套完整的对本地数据库进行管理的机制，对外提供了一系列的增、删、改、查等接口，也可以直接运行用户输入的SQL语句来满足复杂的场景需要。 4 5该模块提供以下关系型数据库相关的常用功能： 6 7- [RdbPredicates](#rdbpredicates)： 数据库中用来代表数据实体的性质、特征或者数据实体之间关系的词项，主要用来定义数据库的操作条件。 8- [RdbStore](#rdbstore)：提供管理关系数据库(RDB)方法的接口。 9 10> **说明：** 11> 12> 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 13> 14> 从API Version 9开始，该接口不再维护，推荐使用新接口[@ohos.data.relationalStore](js-apis-data-relationalStore.md)。 15 16 17## 导入模块 18 19```js 20import data_rdb from '@ohos.data.rdb'; 21``` 22## data_rdb.getRdbStore 23 24getRdbStore(context: Context, config: StoreConfig, version: number, callback: AsyncCallback<RdbStore>): void 25 26获得一个相关的RdbStore，操作关系型数据库，用户可以根据自己的需求配置RdbStore的参数，然后通过RdbStore调用相关接口可以执行相关的数据操作，使用callback异步回调。 27 28**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 29 30**参数：** 31 32| 参数名 | 类型 | 必填 | 说明 | 33| -------- | ------------------------------------------ | ---- | ------------------------------------------------------------ | 34| context | Context | 是 | 应用的上下文。 <br>FA模型的应用Context定义见[Context](js-apis-inner-app-context.md)。<br>Stage模型的应用Context定义见[Context](js-apis-inner-app-context.md)。 | 35| config | [StoreConfig](#storeconfig) | 是 | 与此RDB存储相关的数据库配置。 | 36| version | number | 是 | 数据库版本。<br>目前暂不支持通过version自动识别数据库升级降级操作，只能由开发者自行维护。 | 37| callback | AsyncCallback<[RdbStore](#rdbstore)> | 是 | 指定callback回调函数，返回RdbStore对象。 | 38 39**示例：** 40 41FA模型示例： 42 43```js 44// 获取context 45import featureAbility from '@ohos.ability.featureAbility' 46let context = featureAbility.getContext() 47 48// 获取context后调用getRdbStore 49const STORE_CONFIG = { name: "RdbTest.db"} 50data_rdb.getRdbStore(context, STORE_CONFIG, 1, function (err, rdbStore) { 51 if (err) { 52 console.info("Get RdbStore failed, err: " + err) 53 return 54 } 55 console.log("Get RdbStore successfully.") 56}) 57``` 58 59Stage模型示例： 60 61```ts 62// 获取context 63import UIAbility from '@ohos.app.ability.UIAbility'; 64 65let context; 66class EntryAbility extends UIAbility { 67 onWindowStageCreate(windowStage){ 68 context = this.context 69 } 70} 71 72// 获取context后调用getRdbStore 73const STORE_CONFIG = { name: "RdbTest.db"} 74data_rdb.getRdbStore(context, STORE_CONFIG, 1, function (err, rdbStore) { 75 if (err) { 76 console.info("Get RdbStore failed, err: " + err) 77 return 78 } 79 console.log("Get RdbStore successfully.") 80}) 81``` 82 83## data_rdb.getRdbStore 84 85getRdbStore(context: Context, config: StoreConfig, version: number): Promise<RdbStore> 86 87获得一个相关的RdbStore，操作关系型数据库，用户可以根据自己的需求配置RdbStore的参数，然后通过RdbStore调用相关接口可以执行相关的数据操作，使用Promise异步回调。 88 89**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 90 91**参数：** 92 93| 参数名 | 类型 | 必填 | 说明 | 94| ------- | --------------------------- | ---- | ------------------------------------------------------------ | 95| context | Context | 是 | 应用的上下文。 <br>FA模型的应用Context定义见[Context](js-apis-inner-app-context.md)。<br>Stage模型的应用Context定义见[Context](js-apis-inner-app-context.md)。 | 96| config | [StoreConfig](#storeconfig) | 是 | 与此RDB存储相关的数据库配置。 | 97| version | number | 是 | 数据库版本。<br>目前暂不支持通过version自动识别数据库升级降级操作，只能由开发者自行维护。 | 98 99**返回值**： 100 101| 类型 | 说明 | 102| ------------------------------------ | ------------------------------- | 103| Promise<[RdbStore](#rdbstore)> | Promise对象。返回RdbStore对象。 | 104 105**示例：** 106 107FA模型示例： 108 109```js 110// 获取context 111import featureAbility from '@ohos.ability.featureAbility' 112let context = featureAbility.getContext() 113 114// 获取context后调用getRdbStore 115const STORE_CONFIG = { name: "RdbTest.db" } 116let promise = data_rdb.getRdbStore(context, STORE_CONFIG, 1); 117promise.then(async (rdbStore) => { 118 console.log("Get RdbStore successfully.") 119}).catch((err) => { 120 console.log("Get RdbStore failed, err: " + err) 121}) 122``` 123 124Stage模型示例： 125 126```ts 127// 获取context 128import UIAbility from '@ohos.app.ability.UIAbility'; 129 130let context; 131class EntryAbility extends UIAbility { 132 onWindowStageCreate(windowStage){ 133 context = this.context 134 } 135} 136 137// 获取context后调用getRdbStore 138const STORE_CONFIG = { name: "RdbTest.db" } 139let promise = data_rdb.getRdbStore(context, STORE_CONFIG, 1); 140promise.then(async (rdbStore) => { 141 console.log("Get RdbStore successfully.") 142}).catch((err) => { 143 console.log("Get RdbStore failed, err: " + err) 144}) 145``` 146 147## data_rdb.deleteRdbStore 148 149deleteRdbStore(context: Context, name: string, callback: AsyncCallback<void>): void 150 151删除数据库，使用callback异步回调。 152 153**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 154 155**参数：** 156 157| 参数名 | 类型 | 必填 | 说明 | 158| -------- | ------------------------- | ---- | ------------------------------------------------------------ | 159| context | Context | 是 | 应用的上下文。 <br>FA模型的应用Context定义见[Context](js-apis-inner-app-context.md)。<br>Stage模型的应用Context定义见[Context](js-apis-inner-app-context.md)。 | 160| name | string | 是 | 数据库名称。 | 161| callback | AsyncCallback<void> | 是 | 指定callback回调函数。 | 162 163**示例：** 164 165FA模型示例： 166 167```js 168// 获取context 169import featureAbility from '@ohos.ability.featureAbility' 170let context = featureAbility.getContext() 171 172// 获取context后调用deleteRdbStore 173data_rdb.deleteRdbStore(context, "RdbTest.db", function (err) { 174 if (err) { 175 console.info("Delete RdbStore failed, err: " + err) 176 return 177 } 178 console.log("Delete RdbStore successfully.") 179}) 180``` 181 182Stage模型示例： 183 184```ts 185// 获取context 186import UIAbility from '@ohos.app.ability.UIAbility'; 187 188let context; 189class EntryAbility extends UIAbility { 190 onWindowStageCreate(windowStage){ 191 context = this.context 192 } 193} 194 195// 获取context后调用deleteRdbStore 196data_rdb.deleteRdbStore(context, "RdbTest.db", function (err) { 197 if (err) { 198 console.info("Delete RdbStore failed, err: " + err) 199 return 200 } 201 console.log("Delete RdbStore successfully.") 202}) 203``` 204 205## data_rdb.deleteRdbStore 206 207deleteRdbStore(context: Context, name: string): Promise<void> 208 209使用指定的数据库文件配置删除数据库，使用Promise异步回调。 210 211**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 212 213**参数** 214 215| 参数名 | 类型 | 必填 | 说明 | 216| ------- | ------- | ---- | ------------------------------------------------------------ | 217| context | Context | 是 | 应用的上下文。 <br>FA模型的应用Context定义见[Context](js-apis-inner-app-context.md)。<br>Stage模型的应用Context定义见[Context](js-apis-inner-app-context.md)。 | 218| name | string | 是 | 数据库名称。 | 219 220**返回值**： 221 222| 类型 | 说明 | 223| ------------------- | ------------------------- | 224| Promise<void> | 无返回结果的Promise对象。 | 225 226**示例：** 227 228FA模型示例： 229 230```js 231// 获取context 232import featureAbility from '@ohos.ability.featureAbility' 233let context = featureAbility.getContext() 234 235// 获取context后调用deleteRdbStore 236let promise = data_rdb.deleteRdbStore(context, "RdbTest.db") 237promise.then(() => { 238 console.log("Delete RdbStore successfully.") 239}).catch((err) => { 240 console.info("Delete RdbStore failed, err: " + err) 241}) 242``` 243 244Stage模型示例： 245 246```ts 247// 获取context 248import UIAbility from '@ohos.app.ability.UIAbility'; 249 250let context; 251class EntryAbility extends UIAbility { 252 onWindowStageCreate(windowStage){ 253 context = this.context 254 } 255} 256 257// 获取context后调用deleteRdbStore 258let promise = data_rdb.deleteRdbStore(context, "RdbTest.db") 259promise.then(()=>{ 260 console.log("Delete RdbStore successfully.") 261}).catch((err) => { 262 console.info("Delete RdbStore failed, err: " + err) 263}) 264``` 265 266## ValueType 267 268用于表示允许的数据字段类型。 269 270**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 271 272| 类型 | 说明 | 273| ------- | -------------------- | 274| number | 表示值类型为数字。 | 275| string | 表示值类型为字符。 | 276| boolean | 表示值类型为布尔值。 | 277 278 279## ValuesBucket 280 281用于存储键值对的类型。 282 283**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 284 285| 键类型 | 值类型 | 286| ------ | ----------------------------------------------------------- | 287| string | [ValueType](#valuetype)\| Uint8Array \| null | 288 289## SyncMode<sup>8+</sup> 290 291指数据库同步模式。 292 293**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 294 295| 名称 | 值 | 说明 | 296| -------------- | ---- | ---------------------------------- | 297| SYNC_MODE_PUSH | 0 | 表示数据从本地设备推送到远程设备。 | 298| SYNC_MODE_PULL | 1 | 表示数据从远程设备拉至本地设备。 | 299 300## SubscribeType<sup>8+</sup> 301 302描述订阅类型。 303 304**需要权限：** ohos.permission.DISTRIBUTED_DATASYNC 305 306**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 307 308| 名称 | 值 | 说明 | 309| --------------------- | ---- | ------------------ | 310| SUBSCRIBE_TYPE_REMOTE | 0 | 订阅远程数据更改。 | 311 312## StoreConfig 313 314管理关系数据库配置。 315 316**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 317 318| 名称 | 类型 | 必填 | 说明 | 319| -------- | -------- | -------- | -------- | 320| name | string | 是 | 数据库文件名。 | 321 322## RdbPredicates 323 324表示关系型数据库（RDB）的谓词。该类确定RDB中条件表达式的值是true还是false。 325 326### constructor 327 328constructor(name: string) 329 330构造函数。 331 332**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 333 334**参数：** 335 336| 参数名 | 类型 | 必填 | 说明 | 337| -------- | -------- | -------- | -------- | 338| name | string | 是 | 数据库表名。 | 339 340**示例：** 341 342```js 343let predicates = new data_rdb.RdbPredicates("EMPLOYEE") 344``` 345 346### inDevices<sup>8+</sup> 347 348inDevices(devices: Array<string>): RdbPredicates 349 350同步分布式数据库时连接到组网内指定的远程设备。 351 352> **说明：** 353> 354> 其中devices通过调用[deviceManager.getTrustedDeviceListSync](js-apis-device-manager.md#gettrusteddevicelistsync)方法得到。deviceManager模块的接口均为系统接口，仅系统应用可用。 355 356**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 357 358**参数：** 359 360| 参数名 | 类型 | 必填 | 说明 | 361| -------- | -------- | -------- | -------- | 362| devices | Array<string> | 是 | 指定的组网内的远程设备ID。 | 363 364**返回值**： 365 366| 类型 | 说明 | 367| -------- | -------- | 368| [RdbPredicates](#rdbpredicates) | 返回与指定字段匹配的谓词。 | 369 370**示例：** 371 372```js 373import deviceManager from '@ohos.distributedHardware.deviceManager'; 374let dmInstance = null; 375 376deviceManager.createDeviceManager("com.example.appdatamgrverify", (err, manager) => { 377 if (err) { 378 console.log("create device manager failed, err=" + err); 379 return; 380 } 381 dmInstance = manager; 382 let devices = dmInstance.getTrustedDeviceListSync(); 383 let deviceIds = []; 384 for (var i = 0; i < devices.length; i++) { 385 deviceIds[i] = devices[i].deviceId; 386 } 387}) 388 389let predicates = new data_rdb.RdbPredicates("EMPLOYEE"); 390predicates.inDevices(deviceIds); 391``` 392 393### inAllDevices<sup>8+</sup> 394 395inAllDevices(): RdbPredicates 396 397同步分布式数据库时连接到组网内所有的远程设备。 398 399**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 400 401**返回值**： 402 403| 类型 | 说明 | 404| -------- | -------- | 405| [RdbPredicates](#rdbpredicates) | 返回与指定字段匹配的谓词。 | 406 407**示例：** 408 409```js 410let predicates = new data_rdb.RdbPredicates("EMPLOYEE") 411predicates.inAllDevices() 412``` 413 414### equalTo 415 416equalTo(field: string, value: ValueType): RdbPredicates 417 418配置谓词以匹配数据字段为ValueType且值等于指定值的字段。 419 420**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 421 422**参数：** 423 424| 参数名 | 类型 | 必填 | 说明 | 425| -------- | -------- | -------- | -------- | 426| field | string | 是 | 数据库表中的列名。 | 427| value | [ValueType](#valuetype) | 是 | 指示要与谓词匹配的值。 | 428 429**返回值**： 430 431| 类型 | 说明 | 432| -------- | -------- | 433| [RdbPredicates](#rdbpredicates) | 返回与指定字段匹配的谓词。 | 434 435**示例：** 436 437```js 438let predicates = new data_rdb.RdbPredicates("EMPLOYEE") 439predicates.equalTo("NAME", "lisi") 440``` 441 442 443### notEqualTo 444 445notEqualTo(field: string, value: ValueType): RdbPredicates 446 447配置谓词以匹配数据字段为ValueType且值不等于指定值的字段。 448 449**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 450 451**参数：** 452 453| 参数名 | 类型 | 必填 | 说明 | 454| -------- | -------- | -------- | -------- | 455| field | string | 是 | 数据库表中的列名。 | 456| value | [ValueType](#valuetype) | 是 | 指示要与谓词匹配的值。 | 457 458**返回值**： 459 460| 类型 | 说明 | 461| -------- | -------- | 462| [RdbPredicates](#rdbpredicates) | 返回与指定字段匹配的谓词。 | 463 464**示例：** 465 466```js 467let predicates = new data_rdb.RdbPredicates("EMPLOYEE") 468predicates.notEqualTo("NAME", "lisi") 469``` 470 471 472### beginWrap 473 474beginWrap(): RdbPredicates 475 476向谓词添加左括号。 477 478**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 479 480**返回值**： 481 482| 类型 | 说明 | 483| -------- | -------- | 484| [RdbPredicates](#rdbpredicates) | 返回带有左括号的Rdb谓词。 | 485 486**示例：** 487 488```js 489let predicates = new data_rdb.RdbPredicates("EMPLOYEE") 490predicates.equalTo("NAME", "lisi") 491 .beginWrap() 492 .equalTo("AGE", 18) 493 .or() 494 .equalTo("SALARY", 200.5) 495 .endWrap() 496``` 497 498### endWrap 499 500endWrap(): RdbPredicates 501 502向谓词添加右括号。 503 504**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 505 506**返回值**： 507 508| 类型 | 说明 | 509| -------- | -------- | 510| [RdbPredicates](#rdbpredicates) | 返回带有右括号的Rdb谓词。 | 511 512**示例：** 513 514```js 515let predicates = new data_rdb.RdbPredicates("EMPLOYEE") 516predicates.equalTo("NAME", "lisi") 517 .beginWrap() 518 .equalTo("AGE", 18) 519 .or() 520 .equalTo("SALARY", 200.5) 521 .endWrap() 522``` 523 524### or 525 526or(): RdbPredicates 527 528将或条件添加到谓词中。 529 530**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 531 532**返回值**： 533 534| 类型 | 说明 | 535| -------- | -------- | 536| [RdbPredicates](#rdbpredicates) | 返回带有或条件的Rdb谓词。 | 537 538**示例：** 539 540```js 541let predicates = new data_rdb.RdbPredicates("EMPLOYEE") 542predicates.equalTo("NAME", "Lisa") 543 .or() 544 .equalTo("NAME", "Rose") 545``` 546 547### and 548 549and(): RdbPredicates 550 551向谓词添加和条件。 552 553**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 554 555**返回值**： 556 557| 类型 | 说明 | 558| -------- | -------- | 559| [RdbPredicates](#rdbpredicates) | 返回带有和条件的Rdb谓词。 | 560 561**示例：** 562 563```js 564let predicates = new data_rdb.RdbPredicates("EMPLOYEE") 565predicates.equalTo("NAME", "Lisa") 566 .and() 567 .equalTo("SALARY", 200.5) 568``` 569 570### contains 571 572contains(field: string, value: string): RdbPredicates 573 574配置谓词以匹配数据字段为string且value包含指定值的字段。 575 576**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 577 578**参数：** 579 580| 参数名 | 类型 | 必填 | 说明 | 581| -------- | -------- | -------- | -------- | 582| field | string | 是 | 数据库表中的列名。 | 583| value | string | 是 | 指示要与谓词匹配的值。 | 584 585**返回值**： 586 587| 类型 | 说明 | 588| -------- | -------- | 589| [RdbPredicates](#rdbpredicates) | 返回与指定字段匹配的谓词。 | 590 591**示例：** 592 593```js 594let predicates = new data_rdb.RdbPredicates("EMPLOYEE") 595predicates.contains("NAME", "os") 596``` 597 598### beginsWith 599 600beginsWith(field: string, value: string): RdbPredicates 601 602配置谓词以匹配数据字段为string且值以指定字符串开头的字段。 603 604**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 605 606**参数：** 607 608| 参数名 | 类型 | 必填 | 说明 | 609| -------- | -------- | -------- | -------- | 610| field | string | 是 | 数据库表中的列名。 | 611| value | string | 是 | 指示要与谓词匹配的值。 | 612 613**返回值**： 614 615| 类型 | 说明 | 616| -------- | -------- | 617| [RdbPredicates](#rdbpredicates) | 返回与指定字段匹配的谓词。 | 618 619**示例：** 620 621```js 622let predicates = new data_rdb.RdbPredicates("EMPLOYEE") 623predicates.beginsWith("NAME", "os") 624``` 625 626### endsWith 627 628endsWith(field: string, value: string): RdbPredicates 629 630配置谓词以匹配数据字段为string且值以指定字符串结尾的字段。 631 632**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 633 634**参数：** 635 636| 参数名 | 类型 | 必填 | 说明 | 637| -------- | -------- | -------- | -------- | 638| field | string | 是 | 数据库表中的列名。 | 639| value | string | 是 | 指示要与谓词匹配的值。 | 640 641**返回值**： 642 643| 类型 | 说明 | 644| -------- | -------- | 645| [RdbPredicates](#rdbpredicates) | 返回与指定字段匹配的谓词。 | 646 647**示例：** 648 649```js 650let predicates = new data_rdb.RdbPredicates("EMPLOYEE") 651predicates.endsWith("NAME", "se") 652``` 653 654### isNull 655 656isNull(field: string): RdbPredicates 657 658配置谓词以匹配值为null的字段。 659 660**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 661 662**参数：** 663 664| 参数名 | 类型 | 必填 | 说明 | 665| -------- | -------- | -------- | -------- | 666| field | string | 是 | 数据库表中的列名。 | 667 668**返回值**： 669 670| 类型 | 说明 | 671| -------- | -------- | 672| [RdbPredicates](#rdbpredicates) | 返回与指定字段匹配的谓词。 | 673 674**示例**： 675```js 676let predicates = new data_rdb.RdbPredicates("EMPLOYEE") 677predicates.isNull("NAME") 678``` 679 680### isNotNull 681 682isNotNull(field: string): RdbPredicates 683 684配置谓词以匹配值不为null的指定字段。 685 686**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 687 688**参数：** 689 690| 参数名 | 类型 | 必填 | 说明 | 691| -------- | -------- | -------- | -------- | 692| field | string | 是 | 数据库表中的列名。 | 693 694**返回值**： 695 696| 类型 | 说明 | 697| -------- | -------- | 698| [RdbPredicates](#rdbpredicates) | 返回与指定字段匹配的谓词。 | 699 700**示例：** 701 702```js 703let predicates = new data_rdb.RdbPredicates("EMPLOYEE") 704predicates.isNotNull("NAME") 705``` 706 707### like 708 709like(field: string, value: string): RdbPredicates 710 711配置谓词以匹配数据字段为string且值类似于指定字符串的字段。 712 713**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 714 715**参数：** 716 717| 参数名 | 类型 | 必填 | 说明 | 718| -------- | -------- | -------- | -------- | 719| field | string | 是 | 数据库表中的列名。 | 720| value | string | 是 | 指示要与谓词匹配的值。 | 721 722**返回值**： 723 724| 类型 | 说明 | 725| -------- | -------- | 726| [RdbPredicates](#rdbpredicates) | 返回与指定字段匹配的谓词。 | 727 728**示例：** 729 730```js 731let predicates = new data_rdb.RdbPredicates("EMPLOYEE") 732predicates.like("NAME", "%os%") 733``` 734 735### glob 736 737glob(field: string, value: string): RdbPredicates 738 739配置RdbPredicates匹配数据字段为string的指定字段。 740 741**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 742 743**参数：** 744 745| 参数名 | 类型 | 必填 | 说明 | 746| -------- | -------- | -------- | -------- | 747| field | string | 是 | 数据库表中的列名。 | 748| value | string | 是 | 指示要与谓词匹配的值。<br>支持通配符，*表示0个、1个或多个数字或字符，?表示1个数字或字符。 | 749 750**返回值**： 751 752| 类型 | 说明 | 753| -------- | -------- | 754| [RdbPredicates](#rdbpredicates) | 返回与指定字段匹配的谓词。 | 755 756**示例：** 757 758```js 759let predicates = new data_rdb.RdbPredicates("EMPLOYEE") 760predicates.glob("NAME", "?h*g") 761``` 762 763### between 764 765between(field: string, low: ValueType, high: ValueType): RdbPredicates 766 767将谓词配置为匹配数据字段为ValueType且value在给定范围内的指定字段。 768 769**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 770 771**参数：** 772 773| 参数名 | 类型 | 必填 | 说明 | 774| -------- | -------- | -------- | -------- | 775| field | string | 是 | 数据库表中的列名。 | 776| low | [ValueType](#valuetype) | 是 | 指示与谓词匹配的最小值。 | 777| high | [ValueType](#valuetype) | 是 | 指示要与谓词匹配的最大值。 | 778 779**返回值**： 780 781| 类型 | 说明 | 782| -------- | -------- | 783| [RdbPredicates](#rdbpredicates) | 返回与指定字段匹配的谓词。 | 784 785**示例：** 786 787```js 788let predicates = new data_rdb.RdbPredicates("EMPLOYEE") 789predicates.between("AGE", 10, 50) 790``` 791 792### notBetween 793 794notBetween(field: string, low: ValueType, high: ValueType): RdbPredicates 795 796配置RdbPredicates以匹配数据字段为ValueType且value超出给定范围的指定字段。 797 798**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 799 800**参数：** 801 802| 参数名 | 类型 | 必填 | 说明 | 803| -------- | -------- | -------- | -------- | 804| field | string | 是 | 数据库表中的列名。 | 805| low | [ValueType](#valuetype) | 是 | 指示与谓词匹配的最小值。 | 806| high | [ValueType](#valuetype) | 是 | 指示要与谓词匹配的最大值。 | 807 808**返回值**： 809 810| 类型 | 说明 | 811| -------- | -------- | 812| [RdbPredicates](#rdbpredicates) | 返回与指定字段匹配的谓词。 | 813 814**示例：** 815 816```js 817let predicates = new data_rdb.RdbPredicates("EMPLOYEE") 818predicates.notBetween("AGE", 10, 50) 819``` 820 821### greaterThan 822 823greaterThan(field: string, value: ValueType): RdbPredicates 824 825配置谓词以匹配数据字段为ValueType且值大于指定值的字段。 826 827**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 828 829**参数：** 830 831| 参数名 | 类型 | 必填 | 说明 | 832| -------- | -------- | -------- | -------- | 833| field | string | 是 | 数据库表中的列名。 | 834| value | [ValueType](#valuetype) | 是 | 指示要与谓词匹配的值。 | 835 836**返回值**： 837 838| 类型 | 说明 | 839| -------- | -------- | 840| [RdbPredicates](#rdbpredicates) | 返回与指定字段匹配的谓词。 | 841 842**示例：** 843 844```js 845let predicates = new data_rdb.RdbPredicates("EMPLOYEE") 846predicates.greaterThan("AGE", 18) 847``` 848 849### lessThan 850 851lessThan(field: string, value: ValueType): RdbPredicates 852 853配置谓词以匹配数据字段为valueType且value小于指定值的字段。 854 855**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 856 857**参数：** 858 859| 参数名 | 类型 | 必填 | 说明 | 860| -------- | -------- | -------- | -------- | 861| field | string | 是 | 数据库表中的列名。 | 862| value | [ValueType](#valuetype) | 是 | 指示要与谓词匹配的值。 | 863 864**返回值**： 865 866| 类型 | 说明 | 867| -------- | -------- | 868| [RdbPredicates](#rdbpredicates) | 返回与指定字段匹配的谓词。 | 869 870**示例：** 871 872```js 873let predicates = new data_rdb.RdbPredicates("EMPLOYEE") 874predicates.lessThan("AGE", 20) 875``` 876 877### greaterThanOrEqualTo 878 879greaterThanOrEqualTo(field: string, value: ValueType): RdbPredicates 880 881配置谓词以匹配数据字段为ValueType且value大于或等于指定值的字段。 882 883**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 884 885**参数：** 886 887| 参数名 | 类型 | 必填 | 说明 | 888| -------- | -------- | -------- | -------- | 889| field | string | 是 | 数据库表中的列名。 | 890| value | [ValueType](#valuetype) | 是 | 指示要与谓词匹配的值。 | 891 892**返回值**： 893 894| 类型 | 说明 | 895| -------- | -------- | 896| [RdbPredicates](#rdbpredicates) | 返回与指定字段匹配的谓词。 | 897 898**示例：** 899 900```js 901let predicates = new data_rdb.RdbPredicates("EMPLOYEE") 902predicates.greaterThanOrEqualTo("AGE", 18) 903``` 904 905### lessThanOrEqualTo 906 907lessThanOrEqualTo(field: string, value: ValueType): RdbPredicates 908 909配置谓词以匹配数据字段为ValueType且value小于或等于指定值的字段。 910 911**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 912 913**参数：** 914 915| 参数名 | 类型 | 必填 | 说明 | 916| -------- | -------- | -------- | -------- | 917| field | string | 是 | 数据库表中的列名。 | 918| value | [ValueType](#valuetype) | 是 | 指示要与谓词匹配的值。 | 919 920**返回值**： 921 922| 类型 | 说明 | 923| -------- | -------- | 924| [RdbPredicates](#rdbpredicates) | 返回与指定字段匹配的谓词。 | 925 926**示例：** 927 928```js 929let predicates = new data_rdb.RdbPredicates("EMPLOYEE") 930predicates.lessThanOrEqualTo("AGE", 20) 931``` 932 933### orderByAsc 934 935orderByAsc(field: string): RdbPredicates 936 937配置谓词以匹配其值按升序排序的列。 938 939**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 940 941**参数：** 942 943| 参数名 | 类型 | 必填 | 说明 | 944| -------- | -------- | -------- | -------- | 945| field | string | 是 | 数据库表中的列名。 | 946 947**返回值**： 948 949| 类型 | 说明 | 950| -------- | -------- | 951| [RdbPredicates](#rdbpredicates) | 返回与指定字段匹配的谓词。 | 952 953**示例：** 954 955```js 956let predicates = new data_rdb.RdbPredicates("EMPLOYEE") 957predicates.orderByAsc("NAME") 958``` 959 960### orderByDesc 961 962orderByDesc(field: string): RdbPredicates 963 964配置谓词以匹配其值按降序排序的列。 965 966**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 967 968**参数：** 969 970| 参数名 | 类型 | 必填 | 说明 | 971| -------- | -------- | -------- | -------- | 972| field | string | 是 | 数据库表中的列名。 | 973 974**返回值**： 975 976| 类型 | 说明 | 977| -------- | -------- | 978| [RdbPredicates](#rdbpredicates) | 返回与指定字段匹配的谓词。 | 979 980**示例：** 981 982```js 983let predicates = new data_rdb.RdbPredicates("EMPLOYEE") 984predicates.orderByDesc("AGE") 985``` 986 987### distinct 988 989distinct(): RdbPredicates 990 991配置谓词以过滤重复记录并仅保留其中一个。 992 993**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 994 995**返回值**： 996 997| 类型 | 说明 | 998| -------- | -------- | 999| [RdbPredicates](#rdbpredicates) | 返回可用于过滤重复记录的谓词。 | 1000 1001**示例：** 1002 1003```js 1004let predicates = new data_rdb.RdbPredicates("EMPLOYEE") 1005predicates.equalTo("NAME", "Rose").distinct() 1006``` 1007 1008### limitAs 1009 1010limitAs(value: number): RdbPredicates 1011 1012设置最大数据记录数的谓词。 1013 1014**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 1015 1016**参数：** 1017 1018| 参数名 | 类型 | 必填 | 说明 | 1019| -------- | -------- | -------- | -------- | 1020| value | number | 是 | 最大数据记录数。 | 1021 1022**返回值**： 1023 1024| 类型 | 说明 | 1025| -------- | -------- | 1026| [RdbPredicates](#rdbpredicates) | 返回可用于设置最大数据记录数的谓词。 | 1027 1028**示例：** 1029 1030```js 1031let predicates = new data_rdb.RdbPredicates("EMPLOYEE") 1032predicates.equalTo("NAME", "Rose").limitAs(3) 1033``` 1034 1035### offsetAs 1036 1037offsetAs(rowOffset: number): RdbPredicates 1038 1039配置RdbPredicates以指定返回结果的起始位置。 1040 1041**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 1042 1043**参数：** 1044 1045| 参数名 | 类型 | 必填 | 说明 | 1046| -------- | -------- | -------- | -------- | 1047| rowOffset | number | 是 | 返回结果的起始位置，取值为正整数。 | 1048 1049**返回值**： 1050 1051| 类型 | 说明 | 1052| -------- | -------- | 1053| [RdbPredicates](#rdbpredicates) | 返回具有指定返回结果起始位置的谓词。 | 1054 1055**示例：** 1056 1057```js 1058let predicates = new data_rdb.RdbPredicates("EMPLOYEE") 1059predicates.equalTo("NAME", "Rose").offsetAs(3) 1060``` 1061 1062### groupBy 1063 1064groupBy(fields: Array<string>): RdbPredicates 1065 1066配置RdbPredicates按指定列分组查询结果。 1067 1068**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 1069 1070**参数：** 1071 1072| 参数名 | 类型 | 必填 | 说明 | 1073| -------- | -------- | -------- | -------- | 1074| fields | Array<string> | 是 | 指定分组依赖的列名。 | 1075 1076**返回值**： 1077 1078| 类型 | 说明 | 1079| -------- | -------- | 1080| [RdbPredicates](#rdbpredicates) | 返回分组查询列的谓词。 | 1081 1082**示例：** 1083 1084```js 1085let predicates = new data_rdb.RdbPredicates("EMPLOYEE") 1086predicates.groupBy(["AGE", "NAME"]) 1087``` 1088 1089### indexedBy 1090 1091indexedBy(field: string): RdbPredicates 1092 1093配置RdbPredicates以指定索引列。 1094 1095**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 1096 1097**参数：** 1098 1099| 参数名 | 类型 | 必填 | 说明 | 1100| -------- | -------- | -------- | -------- | 1101| field | string | 是 | 索引列的名称。 | 1102 1103**返回值**： 1104 1105 1106| 类型 | 说明 | 1107| -------- | -------- | 1108| [RdbPredicates](#rdbpredicates) | 返回具有指定索引列的RdbPredicates。 | 1109 1110**示例：** 1111 1112```js 1113let predicates = new data_rdb.RdbPredicates("EMPLOYEE") 1114predicates.indexedBy("SALARY_INDEX") 1115``` 1116 1117### in 1118 1119in(field: string, value: Array<ValueType>): RdbPredicates 1120 1121配置RdbPredicates以匹配数据字段为ValueType数组且值在给定范围内的指定字段。 1122 1123**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 1124 1125**参数：** 1126 1127| 参数名 | 类型 | 必填 | 说明 | 1128| -------- | -------- | -------- | -------- | 1129| field | string | 是 | 数据库表中的列名。 | 1130| value | Array<[ValueType](#valuetype)> | 是 | 以ValueType型数组形式指定的要匹配的值。 | 1131 1132**返回值**： 1133 1134| 类型 | 说明 | 1135| -------- | -------- | 1136| [RdbPredicates](#rdbpredicates) | 返回与指定字段匹配的谓词。 | 1137 1138**示例：** 1139 1140```js 1141let predicates = new data_rdb.RdbPredicates("EMPLOYEE") 1142predicates.in("AGE", [18, 20]) 1143``` 1144 1145### notIn 1146 1147notIn(field: string, value: Array<ValueType>): RdbPredicates 1148 1149将RdbPredicates配置为匹配数据字段为ValueType且值超出给定范围的指定字段。 1150 1151**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 1152 1153**参数：** 1154 1155| 参数名 | 类型 | 必填 | 说明 | 1156| -------- | -------- | -------- | -------- | 1157| field | string | 是 | 数据库表中的列名。 | 1158| value | Array<[ValueType](#valuetype)> | 是 | 以ValueType数组形式指定的要匹配的值。 | 1159 1160**返回值**： 1161 1162| 类型 | 说明 | 1163| -------- | -------- | 1164| [RdbPredicates](#rdbpredicates) | 返回与指定字段匹配的谓词。 | 1165 1166**示例：** 1167 1168```js 1169let predicates = new data_rdb.RdbPredicates("EMPLOYEE") 1170predicates.notIn("NAME", ["Lisa", "Rose"]) 1171``` 1172 1173## RdbStore 1174 1175提供管理关系数据库(RDB)方法的接口。 1176 1177在使用以下相关接口前，请使用[executeSql](#executesql8)接口初始化数据库表结构和相关数据，具体可见[关系型数据库开发指导](../../database/database-relational-guidelines.md)。 1178 1179### insert 1180 1181insert(table: string, values: ValuesBucket, callback: AsyncCallback<number>):void 1182 1183向目标表中插入一行数据，使用callback异步回调。 1184 1185**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 1186 1187**参数：** 1188 1189| 参数名 | 类型 | 必填 | 说明 | 1190| -------- | -------- | -------- | -------- | 1191| table | string | 是 | 指定的目标表名。 | 1192| values | [ValuesBucket](#valuesbucket) | 是 | 表示要插入到表中的数据行。 | 1193| callback | AsyncCallback<number> | 是 | 指定callback回调函数。如果操作成功，返回行ID；否则返回-1。 | 1194 1195**示例：** 1196 1197```js 1198const valueBucket = { 1199 "NAME": "Lisa", 1200 "AGE": 18, 1201 "SALARY": 100.5, 1202 "CODES": new Uint8Array([1, 2, 3, 4, 5]), 1203} 1204rdbStore.insert("EMPLOYEE", valueBucket, function (status, rowId) { 1205 if (status) { 1206 console.log("Insert is failed"); 1207 return; 1208 } 1209 console.log("Insert is successful, rowId = " + rowId); 1210}) 1211``` 1212 1213### insert 1214 1215insert(table: string, values: ValuesBucket):Promise<number> 1216 1217向目标表中插入一行数据，使用Promise异步回调。 1218 1219**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 1220 1221**参数：** 1222 1223| 参数名 | 类型 | 必填 | 说明 | 1224| -------- | -------- | -------- | -------- | 1225| table | string | 是 | 指定的目标表名。 | 1226| values | [ValuesBucket](#valuesbucket) | 是 | 表示要插入到表中的数据行。 | 1227 1228**返回值**： 1229 1230| 类型 | 说明 | 1231| -------- | -------- | 1232| Promise<number> | Promise对象。如果操作成功，返回行ID；否则返回-1。 | 1233 1234**示例：** 1235 1236```js 1237const valueBucket = { 1238 "NAME": "Lisa", 1239 "AGE": 18, 1240 "SALARY": 100.5, 1241 "CODES": new Uint8Array([1, 2, 3, 4, 5]), 1242} 1243let promise = rdbStore.insert("EMPLOYEE", valueBucket) 1244promise.then((rowId) => { 1245 console.log("Insert is successful, rowId = " + rowId); 1246}).catch((status) => { 1247 console.log("Insert is failed"); 1248}) 1249``` 1250 1251### batchInsert 1252 1253batchInsert(table: string, values: Array<ValuesBucket>, callback: AsyncCallback<number>):void 1254 1255向目标表中插入一组数据，使用callback异步回调。 1256 1257**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 1258 1259**参数：** 1260 1261| 参数名 | 类型 | 必填 | 说明 | 1262| -------- | -------- | -------- | -------- | 1263| table | string | 是 | 指定的目标表名。 | 1264| values | Array<[ValuesBucket](#valuesbucket)> | 是 | 表示要插入到表中的一组数据。 | 1265| callback | AsyncCallback<number> | 是 | 指定callback回调函数。如果操作成功，返回插入的数据个数，否则返回-1。 | 1266 1267**示例：** 1268 1269```js 1270const valueBucket1 = { 1271 "NAME": "Lisa", 1272 "AGE": 18, 1273 "SALARY": 100.5, 1274 "CODES": new Uint8Array([1, 2, 3, 4, 5]) 1275} 1276const valueBucket2 = { 1277 "NAME": "Jack", 1278 "AGE": 19, 1279 "SALARY": 101.5, 1280 "CODES": new Uint8Array([6, 7, 8, 9, 10]) 1281} 1282const valueBucket3 = { 1283 "NAME": "Tom", 1284 "AGE": 20, 1285 "SALARY": 102.5, 1286 "CODES": new Uint8Array([11, 12, 13, 14, 15]) 1287} 1288 1289let valueBuckets = new Array(valueBucket1, valueBucket2, valueBucket3); 1290rdbStore.batchInsert("EMPLOYEE", valueBuckets, function(status, insertNum) { 1291 if (status) { 1292 console.log("batchInsert is failed, status = " + status); 1293 return; 1294 } 1295 console.log("batchInsert is successful, the number of values that were inserted = " + insertNum); 1296}) 1297``` 1298 1299### batchInsert 1300 1301batchInsert(table: string, values: Array<ValuesBucket>):Promise<number> 1302 1303向目标表中插入一组数据，使用Promise异步回调。 1304 1305**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 1306 1307**参数：** 1308 1309| 参数名 | 类型 | 必填 | 说明 | 1310| -------- | -------- | -------- | -------- | 1311| table | string | 是 | 指定的目标表名。 | 1312| values | Array<[ValuesBucket](#valuesbucket)> | 是 | 表示要插入到表中的一组数据。 | 1313 1314**返回值**： 1315 1316| 类型 | 说明 | 1317| -------- | -------- | 1318| Promise<number> | Promise对象。如果操作成功，返回插入的数据个数，否则返回-1。 | 1319 1320**示例：** 1321 1322```js 1323const valueBucket1 = { 1324 "NAME": "Lisa", 1325 "AGE": 18, 1326 "SALARY": 100.5, 1327 "CODES": new Uint8Array([1, 2, 3, 4, 5]) 1328} 1329const valueBucket2 = { 1330 "NAME": "Jack", 1331 "AGE": 19, 1332 "SALARY": 101.5, 1333 "CODES": new Uint8Array([6, 7, 8, 9, 10]) 1334} 1335const valueBucket3 = { 1336 "NAME": "Tom", 1337 "AGE": 20, 1338 "SALARY": 102.5, 1339 "CODES": new Uint8Array([11, 12, 13, 14, 15]) 1340} 1341 1342let valueBuckets = new Array(valueBucket1, valueBucket2, valueBucket3); 1343let promise = rdbStore.batchInsert("EMPLOYEE", valueBuckets); 1344promise.then((insertNum) => { 1345 console.log("batchInsert is successful, the number of values that were inserted = " + insertNum); 1346}).catch((status) => { 1347 console.log("batchInsert is failed, status = " + status); 1348}) 1349``` 1350 1351### update 1352 1353update(values: ValuesBucket, predicates: RdbPredicates, callback: AsyncCallback<number>):void 1354 1355根据RdbPredicates的指定实例对象更新数据库中的数据，使用callback异步回调。 1356 1357**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 1358 1359**参数：** 1360 1361| 参数名 | 类型 | 必填 | 说明 | 1362| -------- | -------- | -------- | -------- | 1363| values | [ValuesBucket](#valuesbucket) | 是 | values指示数据库中要更新的数据行。键值对与数据库表的列名相关联。 | 1364| predicates | [RdbPredicates](#rdbpredicates) | 是 | RdbPredicates的实例对象指定的更新条件。 | 1365| callback | AsyncCallback<number> | 是 | 指定的callback回调方法。返回受影响的行数。 | 1366 1367**示例：** 1368 1369```js 1370const valueBucket = { 1371 "NAME": "Rose", 1372 "AGE": 22, 1373 "SALARY": 200.5, 1374 "CODES": new Uint8Array([1, 2, 3, 4, 5]), 1375} 1376let predicates = new data_rdb.RdbPredicates("EMPLOYEE") 1377predicates.equalTo("NAME", "Lisa") 1378rdbStore.update(valueBucket, predicates, function (err, rows) { 1379 if (err) { 1380 console.info("Updated failed, err: " + err) 1381 return 1382 } 1383 console.log("Updated row count: " + rows) 1384}) 1385``` 1386 1387### update 1388 1389update(values: ValuesBucket, predicates: RdbPredicates):Promise<number> 1390 1391根据RdbPredicates的指定实例对象更新数据库中的数据，使用Promise异步回调。 1392 1393**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 1394 1395**参数：** 1396 1397| 参数名 | 类型 | 必填 | 说明 | 1398| -------- | -------- | -------- | -------- | 1399| values | [ValuesBucket](#valuesbucket) | 是 | values指示数据库中要更新的数据行。键值对与数据库表的列名相关联。 | 1400| predicates | [RdbPredicates](#rdbpredicates) | 是 | RdbPredicates的实例对象指定的更新条件。 | 1401 1402**返回值**： 1403 1404| 类型 | 说明 | 1405| -------- | -------- | 1406| Promise<number> | 指定的Promise回调方法。返回受影响的行数。 | 1407 1408**示例：** 1409 1410```js 1411const valueBucket = { 1412 "NAME": "Rose", 1413 "AGE": 22, 1414 "SALARY": 200.5, 1415 "CODES": new Uint8Array([1, 2, 3, 4, 5]), 1416} 1417let predicates = new data_rdb.RdbPredicates("EMPLOYEE") 1418predicates.equalTo("NAME", "Lisa") 1419let promise = rdbStore.update(valueBucket, predicates) 1420promise.then(async (rows) => { 1421 console.log("Updated row count: " + rows) 1422}).catch((err) => { 1423 console.info("Updated failed, err: " + err) 1424}) 1425``` 1426 1427### delete 1428 1429delete(predicates: RdbPredicates, callback: AsyncCallback<number>):void 1430 1431根据RdbPredicates的指定实例对象从数据库中删除数据，使用callback异步回调。 1432 1433**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 1434 1435**参数：** 1436 1437| 参数名 | 类型 | 必填 | 说明 | 1438| -------- | -------- | -------- | -------- | 1439| predicates | [RdbPredicates](#rdbpredicates) | 是 | RdbPredicates的实例对象指定的删除条件。 | 1440| callback | AsyncCallback<number> | 是 | 指定callback回调函数。返回受影响的行数。 | 1441 1442**示例：** 1443 1444```js 1445let predicates = new data_rdb.RdbPredicates("EMPLOYEE") 1446predicates.equalTo("NAME", "Lisa") 1447rdbStore.delete(predicates, function (err, rows) { 1448 if (err) { 1449 console.info("Delete failed, err: " + err) 1450 return 1451 } 1452 console.log("Delete rows: " + rows) 1453}) 1454``` 1455 1456### delete 1457 1458delete(predicates: RdbPredicates):Promise<number> 1459 1460根据RdbPredicates的指定实例对象从数据库中删除数据，使用Promise异步回调。 1461 1462**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 1463 1464**参数：** 1465 1466| 参数名 | 类型 | 必填 | 说明 | 1467| -------- | -------- | -------- | -------- | 1468| predicates | [RdbPredicates](#rdbpredicates) | 是 | RdbPredicates的实例对象指定的删除条件。 | 1469 1470**返回值**： 1471 1472| 类型 | 说明 | 1473| -------- | -------- | 1474| Promise<number> | Promise对象。返回受影响的行数。 | 1475 1476**示例：** 1477 1478```js 1479let predicates = new data_rdb.RdbPredicates("EMPLOYEE") 1480predicates.equalTo("NAME", "Lisa") 1481let promise = rdbStore.delete(predicates) 1482promise.then((rows) => { 1483 console.log("Delete rows: " + rows) 1484}).catch((err) => { 1485 console.info("Delete failed, err: " + err) 1486}) 1487``` 1488 1489### query 1490 1491query(predicates: RdbPredicates, columns: Array<string>, callback: AsyncCallback<ResultSet>):void 1492 1493根据指定条件查询数据库中的数据，使用callback异步回调。 1494 1495**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 1496 1497**参数：** 1498 1499| 参数名 | 类型 | 必填 | 说明 | 1500| -------- | -------- | -------- | -------- | 1501| predicates | [RdbPredicates](#rdbpredicates) | 是 | RdbPredicates的实例对象指定的查询条件。 | 1502| columns | Array<string> | 是 | 表示要查询的列。如果值为空，则查询应用于所有列。 | 1503| callback | AsyncCallback<[ResultSet](js-apis-data-resultset.md)> | 是 | 指定callback回调函数。如果操作成功，则返回ResultSet对象。 | 1504 1505**示例：** 1506 1507```js 1508let predicates = new data_rdb.RdbPredicates("EMPLOYEE") 1509predicates.equalTo("NAME", "Rose") 1510rdbStore.query(predicates, ["ID", "NAME", "AGE", "SALARY", "CODES"], function (err, resultSet) { 1511 if (err) { 1512 console.info("Query failed, err: " + err) 1513 return 1514 } 1515 console.log("ResultSet column names: " + resultSet.columnNames) 1516 console.log("ResultSet column count: " + resultSet.columnCount) 1517}) 1518``` 1519 1520### query 1521 1522query(predicates: RdbPredicates, columns?: Array<string>):Promise<ResultSet> 1523 1524根据指定条件查询数据库中的数据，使用Promise异步回调。 1525 1526**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 1527 1528**参数：** 1529 1530| 参数名 | 类型 | 必填 | 说明 | 1531| -------- | -------- | -------- | -------- | 1532| predicates | [RdbPredicates](#rdbpredicates) | 是 | RdbPredicates的实例对象指定的查询条件。 | 1533| columns | Array<string> | 否 | 表示要查询的列。如果值为空，则查询应用于所有列。 | 1534 1535**返回值**： 1536 1537| 类型 | 说明 | 1538| -------- | -------- | 1539| Promise<[ResultSet](js-apis-data-resultset.md)> | Promise对象。如果操作成功，则返回ResultSet对象。 | 1540 1541**示例：** 1542 1543 ```js 1544 let predicates = new data_rdb.RdbPredicates("EMPLOYEE") 1545 predicates.equalTo("NAME", "Rose") 1546 let promise = rdbStore.query(predicates, ["ID", "NAME", "AGE", "SALARY", "CODES"]) 1547 promise.then((resultSet) => { 1548 console.log("ResultSet column names: " + resultSet.columnNames) 1549 console.log("ResultSet column count: " + resultSet.columnCount) 1550 }).catch((err) => { 1551 console.info("Query failed, err: " + err) 1552 }) 1553 ``` 1554 1555### querySql<sup>8+</sup> 1556 1557querySql(sql: string, bindArgs: Array<ValueType>, callback: AsyncCallback<ResultSet>):void 1558 1559根据指定SQL语句查询数据库中的数据，使用callback异步回调。 1560 1561**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 1562 1563**参数：** 1564 1565| 参数名 | 类型 | 必填 | 说明 | 1566| -------- | -------- | -------- | -------- | 1567| sql | string | 是 | 指定要执行的SQL语句。 | 1568| bindArgs | Array<[ValueType](#valuetype)> | 是 | SQL语句中参数的值。 | 1569| callback | AsyncCallback<[ResultSet](js-apis-data-resultset.md)> | 是 | 指定callback回调函数。如果操作成功，则返回ResultSet对象。 | 1570 1571**示例：** 1572 1573```js 1574rdbStore.querySql("SELECT * FROM EMPLOYEE CROSS JOIN BOOK WHERE BOOK.NAME = ?", ['sanguo'], function (err, resultSet) { 1575 if (err) { 1576 console.info("Query failed, err: " + err) 1577 return 1578 } 1579 console.log("ResultSet column names: " + resultSet.columnNames) 1580 console.log("ResultSet column count: " + resultSet.columnCount) 1581}) 1582``` 1583 1584### querySql<sup>8+</sup> 1585 1586querySql(sql: string, bindArgs?: Array<ValueType>):Promise<ResultSet> 1587 1588根据指定SQL语句查询数据库中的数据，使用Promise异步回调。 1589 1590**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 1591 1592**参数：** 1593 1594| 参数名 | 类型 | 必填 | 说明 | 1595| -------- | -------- | -------- | -------- | 1596| sql | string | 是 | 指定要执行的SQL语句。 | 1597| bindArgs | Array<[ValueType](#valuetype)> | 否 | SQL语句中参数的值。 | 1598 1599**返回值**： 1600 1601| 类型 | 说明 | 1602| -------- | -------- | 1603| Promise<[ResultSet](js-apis-data-resultset.md)> | Promise对象。如果操作成功，则返回ResultSet对象。 | 1604 1605**示例：** 1606 1607```js 1608let promise = rdbStore.querySql("SELECT * FROM EMPLOYEE CROSS JOIN BOOK WHERE BOOK.NAME = ?", ['sanguo']) 1609promise.then((resultSet) => { 1610 console.log("ResultSet column names: " + resultSet.columnNames) 1611 console.log("ResultSet column count: " + resultSet.columnCount) 1612}).catch((err) => { 1613 console.info("Query failed, err: " + err) 1614}) 1615``` 1616 1617### executeSql<sup>8+</sup> 1618 1619executeSql(sql: string, bindArgs: Array<ValueType>, callback: AsyncCallback<void>):void 1620 1621执行包含指定参数但不返回值的SQL语句，使用callback异步回调。 1622 1623**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 1624 1625**参数：** 1626 1627| 参数名 | 类型 | 必填 | 说明 | 1628| -------- | -------- | -------- | -------- | 1629| sql | string | 是 | 指定要执行的SQL语句。 | 1630| bindArgs | Array<[ValueType](#valuetype)> | 是 | SQL语句中参数的值。 | 1631| callback | AsyncCallback<void> | 是 | 指定callback回调函数。 | 1632 1633**示例：** 1634 1635```js 1636const SQL_CREATE_TABLE = "CREATE TABLE IF NOT EXISTS EMPLOYEE (ID INTEGER PRIMARY KEY AUTOINCREMENT, NAME TEXT NOT NULL, AGE INTEGER, SALARY REAL, CODES BLOB)" 1637rdbStore.executeSql(SQL_CREATE_TABLE, null, function(err) { 1638 if (err) { 1639 console.info("ExecuteSql failed, err: " + err) 1640 return 1641 } 1642 console.info('Create table done.') 1643}) 1644``` 1645 1646### executeSql<sup>8+</sup> 1647 1648executeSql(sql: string, bindArgs?: Array<ValueType>):Promise<void> 1649 1650执行包含指定参数但不返回值的SQL语句，使用Promise异步回调。 1651 1652**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 1653 1654**参数：** 1655 1656| 参数名 | 类型 | 必填 | 说明 | 1657| -------- | -------- | -------- | -------- | 1658| sql | string | 是 | 指定要执行的SQL语句。 | 1659| bindArgs | Array<[ValueType](#valuetype)> | 否 | SQL语句中参数的值。 | 1660 1661**返回值**： 1662 1663| 类型 | 说明 | 1664| -------- | -------- | 1665| Promise<void> | 无返回结果的Promise对象。 | 1666 1667**示例：** 1668 1669```js 1670const SQL_CREATE_TABLE = "CREATE TABLE IF NOT EXISTS EMPLOYEE (ID INTEGER PRIMARY KEY AUTOINCREMENT, NAME TEXT NOT NULL, AGE INTEGER, SALARY REAL, CODES BLOB)" 1671let promise = rdbStore.executeSql(SQL_CREATE_TABLE) 1672promise.then(() => { 1673 console.info('Create table done.') 1674}).catch((err) => { 1675 console.info("ExecuteSql failed, err: " + err) 1676}) 1677``` 1678 1679### beginTransaction<sup>8+</sup> 1680 1681beginTransaction():void 1682 1683在开始执行SQL语句之前，开始事务。 1684 1685**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 1686 1687**示例：** 1688 1689```js 1690import featureAbility from '@ohos.ability.featureAbility' 1691let context = featureAbility.getContext() 1692const STORE_CONFIG = { name: "RdbTest.db"} 1693data_rdb.getRdbStore(context, STORE_CONFIG, 1, async function (err, rdbStore) { 1694 rdbStore.beginTransaction() 1695 const valueBucket = { 1696 "name": "lisi", 1697 "age": 18, 1698 "salary": 100.5, 1699 "blobType": new Uint8Array([1, 2, 3]), 1700 } 1701 await rdbStore.insert("test", valueBucket) 1702 rdbStore.commit() 1703}) 1704``` 1705 1706### commit<sup>8+</sup> 1707 1708commit():void 1709 1710提交已执行的SQL语句。 1711 1712**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 1713 1714**示例：** 1715 1716```js 1717import featureAbility from '@ohos.ability.featureAbility' 1718let context = featureAbility.getContext() 1719const STORE_CONFIG = { name: "RdbTest.db"} 1720data_rdb.getRdbStore(context, STORE_CONFIG, 1, async function (err, rdbStore) { 1721 rdbStore.beginTransaction() 1722 const valueBucket = { 1723 "name": "lisi", 1724 "age": 18, 1725 "salary": 100.5, 1726 "blobType": new Uint8Array([1, 2, 3]), 1727 } 1728 await rdbStore.insert("test", valueBucket) 1729 rdbStore.commit() 1730}) 1731``` 1732 1733### rollBack<sup>8+</sup> 1734 1735rollBack():void 1736 1737回滚已经执行的SQL语句。 1738 1739**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 1740 1741**示例：** 1742 1743```js 1744import featureAbility from '@ohos.ability.featureAbility' 1745let context = featureAbility.getContext() 1746const STORE_CONFIG = { name: "RdbTest.db"} 1747data_rdb.getRdbStore(context, STORE_CONFIG, 1, async function (err, rdbStore) { 1748 try { 1749 rdbStore.beginTransaction() 1750 const valueBucket = { 1751 "id": 1, 1752 "name": "lisi", 1753 "age": 18, 1754 "salary": 100.5, 1755 "blobType": new Uint8Array([1, 2, 3]), 1756 } 1757 await rdbStore.insert("test", valueBucket) 1758 rdbStore.commit() 1759 } catch (e) { 1760 rdbStore.rollBack() 1761 } 1762}) 1763``` 1764 1765### setDistributedTables<sup>8+</sup> 1766 1767setDistributedTables(tables: Array<string>, callback: AsyncCallback<void>): void 1768 1769设置分布式列表，使用callback异步回调。 1770 1771**需要权限：** ohos.permission.DISTRIBUTED_DATASYNC 1772 1773**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 1774 1775**参数：** 1776 1777| 参数名 | 类型 | 必填 | 说明 | 1778| -------- | -------- | -------- | -------- | 1779| tables | Array<string> | 是 | 要设置的分布式列表表名 | 1780| callback | AsyncCallback<void> | 是 | 指定callback回调函数。 | 1781 1782**示例：** 1783 1784```js 1785rdbStore.setDistributedTables(["EMPLOYEE"], function (err) { 1786 if (err) { 1787 console.info('SetDistributedTables failed, err: ' + err) 1788 return 1789 } 1790 console.info('SetDistributedTables successfully.') 1791}) 1792``` 1793 1794### setDistributedTables<sup>8+</sup> 1795 1796 setDistributedTables(tables: Array<string>): Promise<void> 1797 1798设置分布式列表，使用Promise异步回调。 1799 1800**需要权限：** ohos.permission.DISTRIBUTED_DATASYNC 1801 1802**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 1803 1804**参数：** 1805 1806| 参数名 | 类型 | 必填 | 说明 | 1807| -------- | -------- | -------- | -------- | 1808| tables | Array<string> | 是 | 要设置的分布式列表表名。 | 1809 1810**返回值**： 1811 1812| 类型 | 说明 | 1813| -------- | -------- | 1814| Promise<void> | 无返回结果的Promise对象。 | 1815 1816**示例：** 1817 1818```js 1819let promise = rdbStore.setDistributedTables(["EMPLOYEE"]) 1820promise.then(() => { 1821 console.info("SetDistributedTables successfully.") 1822}).catch((err) => { 1823 console.info("SetDistributedTables failed, err: " + err) 1824}) 1825``` 1826 1827### obtainDistributedTableName<sup>8+</sup> 1828 1829obtainDistributedTableName(device: string, table: string, callback: AsyncCallback<string>): void 1830 1831根据远程设备的本地表名获取指定远程设备的分布式表名。在查询远程设备数据库时，需要使用分布式表名, 使用callback异步回调。 1832 1833> **说明：** 1834> 1835> 其中device通过调用[deviceManager.getTrustedDeviceListSync](js-apis-device-manager.md#gettrusteddevicelistsync)方法得到。deviceManager模块的接口均为系统接口，仅系统应用可用。 1836 1837**需要权限：** ohos.permission.DISTRIBUTED_DATASYNC 1838 1839**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 1840 1841**参数：** 1842 1843| 参数名 | 类型 | 必填 | 说明 | 1844| -------- | -------- | -------- | -------- | 1845| device | string | 是 | 远程设备ID 。 | 1846| table | string | 是 | 远程设备的本地表名 | 1847| callback | AsyncCallback<string> | 是 | 指定的callback回调函数。如果操作成功，返回远程设备的分布式表名。 | 1848 1849**示例：** 1850 1851```js 1852import deviceManager from '@ohos.distributedHardware.deviceManager'; 1853let dmInstance = null; 1854 1855deviceManager.createDeviceManager("com.example.appdatamgrverify", (err, manager) => { 1856 if (err) { 1857 console.log("create device manager failed, err=" + err); 1858 return; 1859 } 1860 dmInstance = manager; 1861 let devices = dmInstance.getTrustedDeviceListSync(); 1862 let deviceId = devices[0].deviceId; 1863}) 1864 1865 1866rdbStore.obtainDistributedTableName(deviceId, "EMPLOYEE", function (err, tableName) { 1867 if (err) { 1868 console.info('ObtainDistributedTableName failed, err: ' + err) 1869 return 1870 } 1871 console.info('ObtainDistributedTableName successfully, tableName=.' + tableName) 1872}) 1873``` 1874 1875### obtainDistributedTableName<sup>8+</sup> 1876 1877 obtainDistributedTableName(device: string, table: string): Promise<string> 1878 1879根据远程设备的本地表名获取指定远程设备的分布式表名。在查询远程设备数据库时，需要使用分布式表名，使用Promise异步回调。 1880 1881> **说明：** 1882> 1883> 其中device通过调用[deviceManager.getTrustedDeviceListSync](js-apis-device-manager.md#gettrusteddevicelistsync)方法得到。deviceManager模块的接口均为系统接口，仅系统应用可用。 1884 1885**需要权限：** ohos.permission.DISTRIBUTED_DATASYNC 1886 1887**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 1888 1889**参数：** 1890 1891| 参数名 | 类型 | 必填 | 说明 | 1892| -------- | -------- | -------- | -------- | 1893| device | string | 是 | 远程设备ID。 | 1894| table | string | 是 | 远程设备的本地表名。 | 1895 1896**返回值**： 1897 1898| 类型 | 说明 | 1899| -------- | -------- | 1900| Promise<string> | Promise对象。如果操作成功，返回远程设备的分布式表名。 | 1901 1902**示例：** 1903 1904```js 1905import deviceManager from '@ohos.distributedHardware.deviceManager'; 1906let dmInstance = null; 1907 1908deviceManager.createDeviceManager("com.example.appdatamgrverify", (err, manager) => { 1909 if (err) { 1910 console.log("create device manager failed, err=" + err); 1911 return; 1912 } 1913 dmInstance = manager; 1914 let devices = dmInstance.getTrustedDeviceListSync(); 1915 let deviceId = devices[0].deviceId; 1916}) 1917 1918let promise = rdbStore.obtainDistributedTableName(deviceId, "EMPLOYEE") 1919promise.then((tableName) => { 1920 console.info('ObtainDistributedTableName successfully, tableName= ' + tableName) 1921}).catch((err) => { 1922 console.info('ObtainDistributedTableName failed, err: ' + err) 1923}) 1924``` 1925 1926### sync<sup>8+</sup> 1927 1928sync(mode: SyncMode, predicates: RdbPredicates, callback: AsyncCallback<Array<[string, number]>>): void 1929 1930在设备之间同步数据, 使用callback异步回调。 1931 1932**需要权限：** ohos.permission.DISTRIBUTED_DATASYNC 1933 1934**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 1935 1936**参数：** 1937 1938| 参数名 | 类型 | 必填 | 说明 | 1939| -------- | -------- | -------- | -------- | 1940| mode | [SyncMode](#syncmode8) | 是 | 指同步模式。该值可以是推、拉。 | 1941| predicates | [RdbPredicates](#rdbpredicates) | 是 | 约束同步数据和设备。 | 1942| callback | AsyncCallback<Array<[string, number]>> | 是 | 指定的callback回调函数，用于向调用者发送同步结果。string：设备ID；number：每个设备同步状态，0表示成功，其他值表示失败。| 1943 1944**示例：** 1945 1946```js 1947import deviceManager from '@ohos.distributedHardware.deviceManager'; 1948let dmInstance = null; 1949 1950deviceManager.createDeviceManager("com.example.appdatamgrverify", (err, manager) => { 1951 if (err) { 1952 console.log("create device manager failed, err=" + err); 1953 return; 1954 } 1955 dmInstance = manager; 1956 let devices = dmInstance.getTrustedDeviceListSync(); 1957 let deviceIds = []; 1958 for (var i = 0; i < devices.length; i++) { 1959 deviceIds[i] = devices[i].deviceId; 1960 } 1961}) 1962 1963let predicates = new data_rdb.RdbPredicates('EMPLOYEE') 1964predicates.inDevices(deviceIds) 1965rdbStore.sync(data_rdb.SyncMode.SYNC_MODE_PUSH, predicates, function (err, result) { 1966 if (err) { 1967 console.log('Sync failed, err: ' + err) 1968 return 1969 } 1970 console.log('Sync done.') 1971 for (let i = 0; i < result.length; i++) { 1972 console.log('device=' + result[i][0] + ' status=' + result[i][1]) 1973 } 1974}) 1975``` 1976 1977### sync<sup>8+</sup> 1978 1979 sync(mode: SyncMode, predicates: RdbPredicates): Promise<Array<[string, number]>> 1980 1981在设备之间同步数据，使用Promise异步回调。 1982 1983**需要权限：** ohos.permission.DISTRIBUTED_DATASYNC 1984 1985**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 1986 1987**参数：** 1988 1989| 参数名 | 类型 | 必填 | 说明 | 1990| -------- | -------- | -------- | -------- | 1991| mode | [SyncMode](#syncmode8) | 是 | 指同步模式。该值可以是推、拉。 | 1992| predicates | [RdbPredicates](#rdbpredicates) | 是 | 约束同步数据和设备。 | 1993 1994**返回值**： 1995 1996| 类型 | 说明 | 1997| -------- | -------- | 1998| Promise<Array<[string, number]>> | Promise对象，用于向调用者发送同步结果。string：设备ID；number：每个设备同步状态，0表示成功，其他值表示失败。 | 1999 2000**示例：** 2001 2002```js 2003import deviceManager from '@ohos.distributedHardware.deviceManager'; 2004let dmInstance = null; 2005 2006deviceManager.createDeviceManager("com.example.appdatamgrverify", (err, manager) => { 2007 if (err) { 2008 console.log("create device manager failed, err=" + err); 2009 return; 2010 } 2011 dmInstance = manager; 2012 let devices = dmInstance.getTrustedDeviceListSync(); 2013 let deviceIds = []; 2014 for (var i = 0; i < devices.length; i++) { 2015 deviceIds[i] = devices[i].deviceId; 2016 } 2017}) 2018 2019let predicates = new data_rdb.RdbPredicates('EMPLOYEE') 2020predicates.inDevices(deviceIds) 2021let promise = rdbStore.sync(data_rdb.SyncMode.SYNC_MODE_PUSH, predicates) 2022promise.then((result) =>{ 2023 console.log('Sync done.') 2024 for (let i = 0; i < result.length; i++) { 2025 console.log('device=' + result[i][0] + ' status=' + result[i][1]) 2026 } 2027}).catch((err) => { 2028 console.log('Sync failed') 2029}) 2030``` 2031 2032### on('dataChange')<sup>8+</sup> 2033 2034on(event: 'dataChange', type: SubscribeType, observer: Callback<Array<string>>): void 2035 2036注册数据库的观察者。当分布式数据库中的数据发生更改时，将调用回调。 2037 2038**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 2039 2040**参数：** 2041 2042| 参数名 | 类型 | 必填 | 说明 | 2043| -------- | -------- | -------- | -------- | 2044| event | string | 是 | 取值为'dataChange'，表示数据更改。 | 2045| type | [SubscribeType](#subscribetype8) | 是 | 订阅类型。 | 2046| observer | Callback<Array<string>> | 是 | 指分布式数据库中数据更改事件的观察者。 | 2047 2048**示例：** 2049 2050```js 2051function storeObserver(devices) { 2052 for (let i = 0; i < devices.length; i++) { 2053 console.log('device=' + devices[i] + ' data changed') 2054 } 2055} 2056try { 2057 rdbStore.on('dataChange', data_rdb.SubscribeType.SUBSCRIBE_TYPE_REMOTE, storeObserver) 2058} catch (err) { 2059 console.log('Register observer failed') 2060} 2061``` 2062 2063### off('dataChange')<sup>8+</sup> 2064 2065off(event:'dataChange', type: SubscribeType, observer: Callback<Array<string>>): void 2066 2067从数据库中删除指定类型的指定观察者, 使用callback异步回调。 2068 2069**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 2070 2071**参数：** 2072 2073| 参数名 | 类型 | 必填 | 说明 | 2074| -------- | -------- | -------- | -------- | 2075| event | string | 是 | 取值为'dataChange'，表示数据更改。 | 2076| type | [SubscribeType](#subscribetype8) | 是 | 订阅类型。 | 2077| observer | Callback<Array<string>> | 是 | 指已注册的数据更改观察者。| 2078 2079**示例：** 2080 2081```js 2082function storeObserver(devices) { 2083 for (let i = 0; i < devices.length; i++) { 2084 console.log('device=' + devices[i] + ' data changed') 2085 } 2086} 2087try { 2088 rdbStore.off('dataChange', data_rdb.SubscribeType.SUBSCRIBE_TYPE_REMOTE, storeObserver) 2089} catch (err) { 2090 console.log('Unregister observer failed') 2091} 2092``` 2093