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