1# @ohos.data.dataAbility (DataAbility谓词) 2 3DataAbility 谓词用于构造关系型数据库的谓词，提供用于实现不同查询方法的谓词。 4 5> **说明：** 6> 7> 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8 9 10## 导入模块 11 12```js 13import dataAbility from '@ohos.data.dataAbility'; 14``` 15 16## dataAbility.createRdbPredicates 17 18createRdbPredicates(name: string, dataAbilityPredicates: DataAbilityPredicates): rdb.RdbPredicates 19 20从DataAbilityPredicates对象创建RdbPredicates对象。 21 22**系统能力：** SystemCapability.DistributedDataManager.DataShare.Core。 23 24**参数：** 25 26 | 参数名 | 类型 | 必填 | 说明 | 27 | -------- | -------- | -------- | -------- | 28 | name | string | 是 | 数据库表中的表名。 | 29 | dataAbilityPredicates | [DataAbilityPredicates](#dataabilitypredicates) | 是 | DataAbility谓词。 | 30 31**返回值：** 32 33 | 类型 | 说明 | 34 | -------- | -------- | 35 | rdb.[RdbPredicates](js-apis-data-rdb.md#rdbpredicates) | 返回RdbPredicates对象。 | 36 37**示例：** 38 39 ```js 40 let dataAbilityPredicates = new dataAbility.DataAbilityPredicates() 41 dataAbilityPredicates.equalTo("NAME", "Rose") 42 let predicates = dataAbility.createRdbPredicates("EMPLOYEE", dataAbilityPredicates) 43 ``` 44 45## DataAbilityPredicates 46 47提供用于实现不同查询方法的谓词。 48 49### equalTo 50 51equalTo(field: string, value: ValueType): DataAbilityPredicates 52 53配置谓词以匹配数据类型为ValueType且值等于指定值的字段。 54 55**系统能力：** SystemCapability.DistributedDataManager.DataShare.Core。 56 57**参数：** 58 59 | 参数名 | 类型 | 必填 | 说明 | 60 | -------- | -------- | -------- | -------- | 61 | field | string | 是 | 数据库表中的列名。 | 62 | value | [ValueType](#valuetype) | 是 | 指示要与谓词匹配的值。 | 63 64**返回值：** 65 66 | 类型 | 说明 | 67 | -------- | -------- | 68 | [DataAbilityPredicates](#dataabilitypredicates) | 返回与指定字段匹配的谓词。 | 69 70**示例：** 71 72 ```js 73 dataAbilityPredicates.equalTo("NAME", "lisi") 74 ``` 75 76### notEqualTo 77 78notEqualTo(field: string, value: ValueType): DataAbilityPredicates 79 80配置谓词以匹配数据类型为ValueType且值不等于指定值的字段。 81 82**系统能力：** SystemCapability.DistributedDataManager.DataShare.Core。 83 84**参数：** 85 86 | 参数名 | 类型 | 必填 | 说明 | 87 | -------- | -------- | -------- | -------- | 88 | field | string | 是 | 数据库表中的列名。 | 89 | value | [ValueType](#valuetype) | 是 | 指示要与谓词匹配的值。 | 90 91**返回值：** 92 93 | 类型 | 说明 | 94 | -------- | -------- | 95 | [DataAbilityPredicates](#dataabilitypredicates) | 返回与指定字段匹配的谓词。 | 96 97**示例：** 98 99 ```js 100 dataAbilityPredicates.notEqualTo("NAME", "lisi") 101 ``` 102 103### beginWrap 104 105beginWrap(): DataAbilityPredicates 106 107向谓词添加左括号。 108 109**系统能力：** SystemCapability.DistributedDataManager.DataShare.Core。 110 111**返回值：** 112 113 | 类型 | 说明 | 114 | -------- | -------- | 115 | [DataAbilityPredicates](#dataabilitypredicates) | 返回带有左括号的DataAbility谓词。 | 116 117**示例：** 118 119 ```js 120 dataAbilityPredicates.equalTo("NAME", "lisi") 121 .beginWrap() 122 .equalTo("AGE", 18) 123 .or() 124 .equalTo("SALARY", 200.5) 125 .endWrap() 126 ``` 127 128### endWrap 129 130endWrap(): DataAbilityPredicates 131 132向谓词添加右括号。 133 134**系统能力：** SystemCapability.DistributedDataManager.DataShare.Core。 135 136**返回值：** 137 138 | 类型 | 说明 | 139 | -------- | -------- | 140 | [DataAbilityPredicates](#dataabilitypredicates) | 返回带有右括号的DataAbility谓词。 | 141 142**示例：** 143 144 ```js 145 dataAbilityPredicates.equalTo("NAME", "lisi") 146 .beginWrap() 147 .equalTo("AGE", 18) 148 .or() 149 .equalTo("SALARY", 200.5) 150 .endWrap() 151 ``` 152 153### or 154 155or(): DataAbilityPredicates 156 157将或条件添加到谓词中。 158 159**系统能力：** SystemCapability.DistributedDataManager.DataShare.Core。 160 161**返回值：** 162 163 | 类型 | 说明 | 164 | -------- | -------- | 165 | [DataAbilityPredicates](#dataabilitypredicates) | 返回带有或条件的DataAbility谓词。 | 166 167**示例：** 168 169 ```js 170 dataAbilityPredicates.equalTo("NAME", "Lisa") 171 .or() 172 .equalTo("NAME", "Rose") 173 ``` 174 175### and 176 177and(): DataAbilityPredicates 178 179将和条件添加到谓词中。 180 181**系统能力：** SystemCapability.DistributedDataManager.DataShare.Core。 182 183**返回值：** 184 185 | 类型 | 说明 | 186 | -------- | -------- | 187 | [DataAbilityPredicates](#dataabilitypredicates) | 返回带有和条件的DataAbility谓词。 | 188 189**示例：** 190 191 ```js 192 dataAbilityPredicates.equalTo("NAME", "Lisa") 193 .and() 194 .equalTo("SALARY", 200.5) 195 ``` 196 197### contains 198 199contains(field: string, value: string): DataAbilityPredicates 200 201配置谓词以匹配数据类型为string且value包含指定值的字段。 202 203**系统能力：** SystemCapability.DistributedDataManager.DataShare.Core。 204 205**参数：** 206 207 | 参数名 | 类型 | 必填 | 说明 | 208 | -------- | -------- | -------- | -------- | 209 | field | string | 是 | 数据库表中的列名。 | 210 | value | string | 是 | 指示要与谓词匹配的值。 | 211 212**返回值：** 213 214 | 类型 | 说明 | 215 | -------- | -------- | 216 | [DataAbilityPredicates](#dataabilitypredicates) | 返回与指定字段匹配的谓词。 | 217 218**示例：** 219 220 ```js 221 dataAbilityPredicates.contains("NAME", "os") 222 ``` 223 224### beginsWith 225 226beginsWith(field: string, value: string): DataAbilityPredicates 227 228配置谓词以匹配数据类型为string且值以指定字符串开头的字段。 229 230**系统能力：** SystemCapability.DistributedDataManager.DataShare.Core。 231 232**参数：** 233 234 | 参数名 | 类型 | 必填 | 说明 | 235 | -------- | -------- | -------- | -------- | 236 | field | string | 是 | 数据库表中的列名。 | 237 | value | string | 是 | 指示要与谓词匹配的值。 | 238 239**返回值：** 240 241 | 类型 | 说明 | 242 | -------- | -------- | 243 | [DataAbilityPredicates](#dataabilitypredicates) | 返回与指定字段匹配的谓词。 | 244 245**示例：** 246 247 ```js 248 dataAbilityPredicates.beginsWith("NAME", "os") 249 ``` 250 251### endsWith 252 253endsWith(field: string, value: string): DataAbilityPredicates 254 255配置谓词以匹配数据类型为string且值以指定字符串结尾的字段。 256 257**系统能力：** SystemCapability.DistributedDataManager.DataShare.Core。 258 259**参数：** 260 261 | 参数名 | 类型 | 必填 | 说明 | 262 | -------- | -------- | -------- | -------- | 263 | field | string | 是 | 数据库表中的列名。 | 264 | value | string | 是 | 指示要与谓词匹配的值。 | 265 266**返回值：** 267 268 | 类型 | 说明 | 269 | -------- | -------- | 270 | [DataAbilityPredicates](#dataabilitypredicates) | 返回与指定字段匹配的谓词。 | 271 272**示例：** 273 274 ``` 275 dataAbilityPredicates.endsWith("NAME", "se") 276 ``` 277 278### isNull 279 280isNull(field: string): DataAbilityPredicates 281 282配置谓词以匹配值为null的字段。 283 284**系统能力：** SystemCapability.DistributedDataManager.DataShare.Core。 285 286**参数：** 287 288 | 参数名 | 类型 | 必填 | 说明 | 289 | -------- | -------- | -------- | -------- | 290 | field | string | 是 | 数据库表中的列名。 | 291 292**返回值：** 293 294 | 类型 | 说明 | 295 | -------- | -------- | 296 | [DataAbilityPredicates](#dataabilitypredicates) | 返回与指定字段匹配的谓词。 | 297 298**示例：** 299 300 ```js 301 dataAbilityPredicates.isNull("NAME") 302 ``` 303 304### isNotNull 305 306isNotNull(field: string): DataAbilityPredicates 307 308配置谓词以匹配值不为null的指定字段。 309 310**系统能力：** SystemCapability.DistributedDataManager.DataShare.Core。 311 312**参数：** 313 314 | 参数名 | 类型 | 必填 | 说明 | 315 | -------- | -------- | -------- | -------- | 316 | field | string | 是 | 数据库表中的列名。 | 317 318**返回值：** 319 320 | 类型 | 说明 | 321 | -------- | -------- | 322 | [DataAbilityPredicates](#dataabilitypredicates) | 返回与指定字段匹配的谓词。 | 323 324**示例：** 325 326 ```js 327 dataAbilityPredicates.isNotNull("NAME") 328 ``` 329 330### like 331 332like(field: string, value: string): DataAbilityPredicates 333 334配置谓词以匹配数据类型为string且值类似于指定字符串的字段。 335 336**系统能力：** SystemCapability.DistributedDataManager.DataShare.Core。 337 338**参数：** 339 340 | 参数名 | 类型 | 必填 | 说明 | 341 | -------- | -------- | -------- | -------- | 342 | field | string | 是 | 数据库表中的列名。 | 343 | value | string | 是 | 指示要与谓词匹配的值。 | 344 345**返回值：** 346 347 | 类型 | 说明 | 348 | -------- | -------- | 349 | [DataAbilityPredicates](#dataabilitypredicates) | 返回与指定字段匹配的谓词。 | 350 351**示例：** 352 353 ```js 354 dataAbilityPredicates.like("NAME", "%os%") 355 ``` 356 357### glob 358 359glob(field: string, value: string): DataAbilityPredicates 360 361配置谓词以匹配数据类型为string的指定字段。 362 363**系统能力：** SystemCapability.DistributedDataManager.DataShare.Core。 364 365**参数：** 366 367 | 参数名 | 类型 | 必填 | 说明 | 368 | -------- | -------- | -------- | -------- | 369 | field | string | 是 | 数据库表中的列名。 | 370 | value | string | 是 | 指示要与谓词匹配的值。 | 371 372**返回值：** 373 374 | 类型 | 说明 | 375 | -------- | -------- | 376 | [DataAbilityPredicates](#dataabilitypredicates) | 返回与指定字段匹配的谓词。 | 377 378**示例：** 379 380 ```js 381 dataAbilityPredicates.glob("NAME", "?h*g") 382 ``` 383 384### between 385 386between(field: string, low: ValueType, high: ValueType): DataAbilityPredicates 387 388配置谓词以匹配数据类型为ValueType且value在指定范围内的指定字段。 389 390**系统能力：** SystemCapability.DistributedDataManager.DataShare.Core。 391 392**参数：** 393 394 | 参数名 | 类型 | 必填 | 说明 | 395 | -------- | -------- | -------- | -------- | 396 | field | string | 是 | 数据库表中的列名。 | 397 | low | [ValueType](#valuetype) | 是 | 指示与谓词匹配的最小值。 | 398 | high | [ValueType](#valuetype) | 是 | 指示与谓词匹配的最大值。 | 399 400**返回值：** 401 402 | 类型 | 说明 | 403 | -------- | -------- | 404 | [DataAbilityPredicates](#dataabilitypredicates) | 返回与指定字段匹配的谓词。 | 405 406**示例：** 407 408 ```js 409 dataAbilityPredicates.between("AGE", 10, 50) 410 ``` 411 412### notBetween 413 414notBetween(field: string, low: ValueType, high: ValueType): DataAbilityPredicates 415 416配置谓词以匹配数据类型为ValueType且value超出给定范围的指定字段。 417 418**系统能力：** SystemCapability.DistributedDataManager.DataShare.Core。 419 420**参数：** 421 422 | 参数名 | 类型 | 必填 | 说明 | 423 | -------- | -------- | -------- | -------- | 424 | field | string | 是 | 数据库表中的列名。 | 425 | low | [ValueType](#valuetype) | 是 | 指示与谓词匹配的最小值。 | 426 | high | [ValueType](#valuetype) | 是 | 指示与谓词匹配的最大值。 | 427 428**返回值：** 429 430 | 类型 | 说明 | 431 | -------- | -------- | 432 | [DataAbilityPredicates](#dataabilitypredicates) | 返回与指定字段匹配的谓词。 | 433 434**示例：** 435 436 ```js 437 dataAbilityPredicates.notBetween("AGE", 10, 50) 438 ``` 439 440### greaterThan 441 442greaterThan(field: string, value: ValueType): DataAbilityPredicates 443 444配置谓词以匹配数据类型为ValueType且值大于指定值的字段。 445 446**系统能力：** SystemCapability.DistributedDataManager.DataShare.Core。 447 448**参数：** 449 450 | 参数名 | 类型 | 必填 | 说明 | 451 | -------- | -------- | -------- | -------- | 452 | field | string | 是 | 数据库表中的列名。 | 453 | value | [ValueType](#valuetype) | 是 | 指示要与谓词匹配的值。 | 454 455**返回值：** 456 457 | 类型 | 说明 | 458 | -------- | -------- | 459 | [DataAbilityPredicates](#dataabilitypredicates) | 返回与指定字段匹配的谓词。 | 460 461**示例：** 462 463 ```js 464 dataAbilityPredicates.greaterThan("AGE", 18) 465 ``` 466 467### lessThan 468 469lessThan(field: string, value: ValueType): DataAbilityPredicates 470 471配置谓词以匹配数据类型为valueType且value小于指定值的字段。 472 473**系统能力：** SystemCapability.DistributedDataManager.DataShare.Core。 474 475**参数：** 476 477 | 参数名 | 类型 | 必填 | 说明 | 478 | -------- | -------- | -------- | -------- | 479 | field | string | 是 | 数据库表中的列名。 | 480 | value | [ValueType](#valuetype) | 是 | 指示要与谓词匹配的值。 | 481 482**返回值：** 483 484 | 类型 | 说明 | 485 | -------- | -------- | 486 | [DataAbilityPredicates](#dataabilitypredicates) | 返回与指定字段匹配的谓词。 | 487 488**示例：** 489 490 ```js 491 dataAbilityPredicates.lessThan("AGE", 20) 492 ``` 493 494### greaterThanOrEqualTo 495 496greaterThanOrEqualTo(field: string, value: ValueType): DataAbilityPredicates 497 498配置谓词以匹配数据类型为ValueType且value大于或等于指定值的字段。 499 500**系统能力：** SystemCapability.DistributedDataManager.DataShare.Core。 501 502**参数：** 503 504 | 参数名 | 类型 | 必填 | 说明 | 505 | -------- | -------- | -------- | -------- | 506 | field | string | 是 | 数据库表中的列名。 | 507 | value | [ValueType](#valuetype) | 是 | 指示要与谓词匹配的值。 | 508 509**返回值：** 510 511 | 类型 | 说明 | 512 | -------- | -------- | 513 | [DataAbilityPredicates](#dataabilitypredicates) | 返回与指定字段匹配的谓词。 | 514 515**示例：** 516 517 ```js 518 dataAbilityPredicates.greaterThanOrEqualTo("AGE", 18) 519 ``` 520 521### lessThanOrEqualTo 522 523lessThanOrEqualTo(field: string, value: ValueType): DataAbilityPredicates 524 525配置谓词以匹配数据类型为ValueType且value小于或等于指定值的字段。 526 527**系统能力：** SystemCapability.DistributedDataManager.DataShare.Core。 528 529**参数：** 530 531 | 参数名 | 类型 | 必填 | 说明 | 532 | -------- | -------- | -------- | -------- | 533 | field | string | 是 | 数据库表中的列名。 | 534 | value | [ValueType](#valuetype) | 是 | 指示要与谓词匹配的值。 | 535 536**返回值：** 537 538 | 类型 | 说明 | 539 | -------- | -------- | 540 | [DataAbilityPredicates](#dataabilitypredicates) | 返回与指定字段匹配的谓词。 | 541 542**示例：** 543 544 ```js 545 dataAbilityPredicates.lessThanOrEqualTo("AGE", 20) 546 ``` 547 548### orderByAsc 549 550orderByAsc(field: string): DataAbilityPredicates 551 552配置谓词以匹配其值按升序排序的列。 553 554**系统能力：** SystemCapability.DistributedDataManager.DataShare.Core。 555 556**参数：** 557 558 | 参数名 | 类型 | 必填 | 说明 | 559 | -------- | -------- | -------- | -------- | 560 | field | string | 是 | 数据库表中的列名。 | 561 562**返回值：** 563 564 | 类型 | 说明 | 565 | -------- | -------- | 566 | [DataAbilityPredicates](#dataabilitypredicates) | 返回与指定字段匹配的谓词。 | 567 568**示例：** 569 570 ```js 571 dataAbilityPredicates.orderByAsc("NAME") 572 ``` 573 574### orderByDesc 575 576orderByDesc(field: string): DataAbilityPredicates 577 578配置谓词以匹配其值按降序排序的列。 579 580**系统能力：** SystemCapability.DistributedDataManager.DataShare.Core。 581 582**参数：** 583 584 | 参数名 | 类型 | 必填 | 说明 | 585 | -------- | -------- | -------- | -------- | 586 | field | string | 是 | 数据库表中的列名。 | 587 588**返回值：** 589 590 | 类型 | 说明 | 591 | -------- | -------- | 592 | [DataAbilityPredicates](#dataabilitypredicates) | 返回与指定字段匹配的谓词。 | 593 594**示例：** 595 596 ```js 597 dataAbilityPredicates.orderByDesc("AGE") 598 ``` 599 600### distinct 601 602distinct(): DataAbilityPredicates 603 604配置谓词以过滤重复记录并仅保留其中一个。 605 606**系统能力：** SystemCapability.DistributedDataManager.DataShare.Core。 607 608**返回值：** 609 610 | 类型 | 说明 | 611 | -------- | -------- | 612 | [DataAbilityPredicates](#dataabilitypredicates) | 返回可用于过滤重复记录的谓词。 | 613 614**示例：** 615 616 ```js 617 dataAbilityPredicates.equalTo("NAME", "Rose").distinct() 618 ``` 619 620### limitAs 621 622limitAs(value: number): DataAbilityPredicates 623 624设置最大数据记录数的谓词。 625 626**系统能力：** SystemCapability.DistributedDataManager.DataShare.Core。 627 628**参数：** 629 630 | 参数名 | 类型 | 必填 | 说明 | 631 | -------- | -------- | -------- | -------- | 632 | value | number | 是 | 最大数据记录数。 | 633 634**返回值：** 635 636 | 类型 | 说明 | 637 | -------- | -------- | 638 | [DataAbilityPredicates](#dataabilitypredicates) | 返回可用于设置最大数据记录数的谓词。 | 639 640**示例：** 641 642 ```js 643 dataAbilityPredicates.equalTo("NAME", "Rose").limitAs(3) 644 ``` 645 646### offsetAs 647 648offsetAs(rowOffset: number): DataAbilityPredicates 649 650配置谓词以指定返回结果的起始位置。 651 652**系统能力：** SystemCapability.DistributedDataManager.DataShare.Core。 653 654**参数：** 655 656 | 参数名 | 类型 | 必填 | 说明 | 657 | -------- | -------- | -------- | -------- | 658 | rowOffset | number | 是 | 返回结果的起始位置，取值为正整数。 | 659 660**返回值：** 661 662 | 类型 | 说明 | 663 | -------- | -------- | 664 | [DataAbilityPredicates](#dataabilitypredicates) | 返回具有指定返回结果起始位置的谓词。 | 665 666**示例：** 667 668 ```js 669 dataAbilityPredicates.equalTo("NAME", "Rose").offsetAs(3) 670 ``` 671 672 673### groupBy 674 675groupBy(fields: Array<string>): DataAbilityPredicates 676 677配置谓词按指定列分组查询结果。 678 679**系统能力：** SystemCapability.DistributedDataManager.DataShare.Core。 680 681**参数：** 682 683 | 参数名 | 类型 | 必填 | 说明 | 684 | -------- | -------- | -------- | -------- | 685 | fields | Array<string> | 是 | 指定分组依赖的列名。 | 686 687**返回值：** 688 689 | 类型 | 说明 | 690 | -------- | -------- | 691 | [DataAbilityPredicates](#dataabilitypredicates) | 返回分组查询列的谓词。 | 692 693**示例：** 694 695 ```js 696 dataAbilityPredicates.groupBy(["AGE", "NAME"]) 697 ``` 698 699### indexedBy 700 701indexedBy(field: string): DataAbilityPredicates 702 703配置谓词以指定索引列。 704 705**系统能力：** SystemCapability.DistributedDataManager.DataShare.Core。 706 707**参数：** 708 709 | 参数名 | 类型 | 必填 | 说明 | 710 | -------- | -------- | -------- | -------- | 711 | indexName | string | 是 | 索引列的名称。 | 712 713**返回值：** 714 715 | 类型 | 说明 | 716 | -------- | -------- | 717 | [DataAbilityPredicates](#dataabilitypredicates) | 返回具有指定索引列的谓词。 | 718 719**示例：** 720 721 ```js 722 dataAbilityPredicates.indexedBy("SALARY_INDEX") 723 ``` 724 725### in 726 727in(field: string, value: Array<ValueType>): DataAbilityPredicates 728 729配置谓词以匹配数据类型为ValueType数组且值在给定范围内的指定字段。 730 731**系统能力：** SystemCapability.DistributedDataManager.DataShare.Core。 732 733**参数：** 734 735 | 参数名 | 类型 | 必填 | 说明 | 736 | -------- | -------- | -------- | -------- | 737 | field | string | 是 | 数据库表中的列名。 | 738 | value | Array<[ValueType](#valuetype)> | 是 | 以ValueType类型数组形式指定的要匹配的值。 | 739 740 741**返回值：** 742 743 | 类型 | 说明 | 744 | -------- | -------- | 745 | [DataAbilityPredicates](#dataabilitypredicates) | 返回与指定字段匹配的谓词。 | 746 747**示例：** 748 749 ```js 750 dataAbilityPredicates.in("AGE", [18, 20]) 751 ``` 752 753### notIn 754 755notIn(field: string, value: Array<ValueType>): DataAbilityPredicates 756 757配置谓词以匹配数据类型为ValueType数组且值不在给定范围内的指定字段。 758 759**系统能力：** SystemCapability.DistributedDataManager.DataShare.Core。 760 761**参数：** 762 763 | 参数名 | 类型 | 必填 | 说明 | 764 | -------- | -------- | -------- | -------- | 765 | field | string | 是 | 数据库表中的列名。 | 766 | value | Array<[ValueType](#valuetype)> | 是 | 以ValueType类型数组形式指定的要匹配的值。 | 767 768**返回值：** 769 770 | 类型 | 说明 | 771 | -------- | -------- | 772 | [DataAbilityPredicates](#dataabilitypredicates) | 返回与指定字段匹配的谓词。 | 773 774**示例：** 775 776 ```js 777 dataAbilityPredicates.notIn("NAME", ["Lisa", "Rose"]) 778 ``` 779 780## ValueType 781 782用于表示允许的数据字段类型。 783 784**系统能力：** SystemCapability.DistributedDataManager.DataShare.Core。 785 786| 类型 | 说明 | 787| ------- | -------------------- | 788| number | 表示值类型为数字。 | 789| string | 表示值类型为字符。 | 790| boolean | 表示值类型为布尔值。 | 791