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