1# @ohos.data.dataAbility (DataAbility Predicates) 2 3**DataAbility** provides APIs for creating predicates, which implement different query methods for relational database (RDB) stores. 4 5> **NOTE**<br/> 6> 7> The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version. 8 9 10## Modules to Import 11 12```js 13import dataAbility from '@ohos.data.dataAbility'; 14``` 15 16## dataAbility.createRdbPredicates 17 18createRdbPredicates(name: string, dataAbilityPredicates: DataAbilityPredicates): rdb.RdbPredicates 19 20Creates an **RdbPredicates** object from a **DataAbilityPredicates** object. 21 22**System capability**: SystemCapability.DistributedDataManager.DataShare.Core 23 24**Parameters** 25 26| Name| Type| Mandatory| Description| 27| -------- | -------- | -------- | -------- | 28| name | string | Yes| Name of a database table.| 29| dataAbilityPredicates | [DataAbilityPredicates](#dataabilitypredicates) | Yes| **DataAbilityPredicates** object. | 30 31**Return value** 32 33| Type| Description| 34| -------- | -------- | 35| rdb.[RdbPredicates](js-apis-data-rdb.md#rdbpredicates) | **RdbPredicates** object created.| 36 37**Example** 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 47Provides predicates for implementing diverse query methods. 48 49### equalTo 50 51equalTo(field: string, value: ValueType): DataAbilityPredicates 52 53Sets a **DataAbilityPredicates** object to match the field with data type **ValueType** and value equal to the specified value. 54 55**System capability**: SystemCapability.DistributedDataManager.DataShare.Core 56 57**Parameters** 58 59| Name| Type| Mandatory| Description| 60| -------- | -------- | -------- | -------- | 61| field | string | Yes| Column name in the table.| 62| value | [ValueType](#valuetype) | Yes| Value to match the **DataAbilityPredicates**.| 63 64**Return value** 65 66| Type| Description| 67| -------- | -------- | 68| [DataAbilityPredicates](#dataabilitypredicates) | **DataAbilityPredicates** object that matches the specified field.| 69 70**Example** 71 72 ```js 73 dataAbilityPredicates.equalTo("NAME", "lisi") 74 ``` 75 76### notEqualTo 77 78notEqualTo(field: string, value: ValueType): DataAbilityPredicates 79 80Sets a **DataAbilityPredicates** object to match the field with data type **ValueType** and value not equal to the specified value. 81 82**System capability**: SystemCapability.DistributedDataManager.DataShare.Core 83 84**Parameters** 85 86| Name| Type| Mandatory| Description| 87| -------- | -------- | -------- | -------- | 88| field | string | Yes| Column name in the table.| 89| value | [ValueType](#valuetype) | Yes| Value to match the **DataAbilityPredicates**.| 90 91**Return value** 92 93| Type| Description| 94| -------- | -------- | 95| [DataAbilityPredicates](#dataabilitypredicates) | **DataAbilityPredicates** object that matches the specified field.| 96 97**Example** 98 99 ```js 100 dataAbilityPredicates.notEqualTo("NAME", "lisi") 101 ``` 102 103### beginWrap 104 105beginWrap(): DataAbilityPredicates 106 107Adds a left parenthesis to this **DataAbilityPredicates**. 108 109**System capability**: SystemCapability.DistributedDataManager.DataShare.Core 110 111**Return value** 112 113| Type| Description| 114| -------- | -------- | 115| [DataAbilityPredicates](#dataabilitypredicates) | **DataAbilityPredicates** object with a left parenthesis.| 116 117**Example** 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 132Adds a right parenthesis to this **DataAbilityPredicates**. 133 134**System capability**: SystemCapability.DistributedDataManager.DataShare.Core 135 136**Return value** 137 138| Type| Description| 139| -------- | -------- | 140| [DataAbilityPredicates](#dataabilitypredicates) | **DataAbilityPredicates** object with a right parenthesis.| 141 142**Example** 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 157Adds the OR condition to this **DataAbilityPredicates**. 158 159**System capability**: SystemCapability.DistributedDataManager.DataShare.Core 160 161**Return value** 162 163| Type| Description| 164| -------- | -------- | 165| [DataAbilityPredicates](#dataabilitypredicates) | **DataAbilityPredicates** object with the OR condition.| 166 167**Example** 168 169 ```js 170 dataAbilityPredicates.equalTo("NAME", "Lisa") 171 .or() 172 .equalTo("NAME", "Rose") 173 ``` 174 175### and 176 177and(): DataAbilityPredicates 178 179Adds the AND condition to this **DataAbilityPredicates**. 180 181**System capability**: SystemCapability.DistributedDataManager.DataShare.Core 182 183**Return value** 184 185| Type| Description| 186| -------- | -------- | 187| [DataAbilityPredicates](#dataabilitypredicates) | **DataAbilityPredicates** object with the AND condition.| 188 189**Example** 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 201Sets a **DataAbilityPredicates** object to match a string containing the specified value. 202 203**System capability**: SystemCapability.DistributedDataManager.DataShare.Core 204 205**Parameters** 206 207| Name| Type| Mandatory| Description| 208| -------- | -------- | -------- | -------- | 209| field | string | Yes| Column name in the table.| 210| value | string | Yes| Value to match the **DataAbilityPredicates**.| 211 212**Return value** 213 214| Type| Description| 215| -------- | -------- | 216| [DataAbilityPredicates](#dataabilitypredicates) | **DataAbilityPredicates** object that matches the specified field.| 217 218**Example** 219 220 ```js 221 dataAbilityPredicates.contains("NAME", "os") 222 ``` 223 224### beginsWith 225 226beginsWith(field: string, value: string): DataAbilityPredicates 227 228Sets a **DataAbilityPredicates** object to match a string that starts with the specified value. 229 230**System capability**: SystemCapability.DistributedDataManager.DataShare.Core 231 232**Parameters** 233 234| Name| Type| Mandatory| Description| 235| -------- | -------- | -------- | -------- | 236| field | string | Yes| Column name in the table.| 237| value | string | Yes| Value to match the **DataAbilityPredicates**.| 238 239**Return value** 240 241| Type| Description| 242| -------- | -------- | 243| [DataAbilityPredicates](#dataabilitypredicates) | **DataAbilityPredicates** object that matches the specified field.| 244 245**Example** 246 247 ```js 248 dataAbilityPredicates.beginsWith("NAME", "os") 249 ``` 250 251### endsWith 252 253endsWith(field: string, value: string): DataAbilityPredicates 254 255Sets a **DataAbilityPredicates** object to match a string that ends with the specified value. 256 257**System capability**: SystemCapability.DistributedDataManager.DataShare.Core 258 259**Parameters** 260 261| Name| Type| Mandatory| Description| 262| -------- | -------- | -------- | -------- | 263| field | string | Yes| Column name in the table.| 264| value | string | Yes| Value to match the **DataAbilityPredicates**.| 265 266**Return value** 267 268| Type| Description| 269| -------- | -------- | 270| [DataAbilityPredicates](#dataabilitypredicates) | **DataAbilityPredicates** object that matches the specified field.| 271 272**Example** 273 274 ``` 275 dataAbilityPredicates.endsWith("NAME", "se") 276 ``` 277 278### isNull 279 280isNull(field: string): DataAbilityPredicates 281 282Sets a **DataAbilityPredicates** object to match the field whose value is null. 283 284**System capability**: SystemCapability.DistributedDataManager.DataShare.Core 285 286**Parameters** 287 288| Name| Type| Mandatory| Description| 289| -------- | -------- | -------- | -------- | 290| field | string | Yes| Column name in the table.| 291 292**Return value** 293 294| Type| Description| 295| -------- | -------- | 296| [DataAbilityPredicates](#dataabilitypredicates) | **DataAbilityPredicates** object that matches the specified field.| 297 298**Example** 299 300 ```js 301 dataAbilityPredicates.isNull("NAME") 302 ``` 303 304### isNotNull 305 306isNotNull(field: string): DataAbilityPredicates 307 308Sets a **DataAbilityPredicates** object to match the field whose value is not null. 309 310**System capability**: SystemCapability.DistributedDataManager.DataShare.Core 311 312**Parameters** 313 314| Name| Type| Mandatory| Description| 315| -------- | -------- | -------- | -------- | 316| field | string | Yes| Column name in the table.| 317 318**Return value** 319 320| Type| Description| 321| -------- | -------- | 322| [DataAbilityPredicates](#dataabilitypredicates) | **DataAbilityPredicates** object that matches the specified field.| 323 324**Example** 325 326 ```js 327 dataAbilityPredicates.isNotNull("NAME") 328 ``` 329 330### like 331 332like(field: string, value: string): DataAbilityPredicates 333 334Sets a **DataAbilityPredicates** object to match a string that is similar to the specified value. 335 336**System capability**: SystemCapability.DistributedDataManager.DataShare.Core 337 338**Parameters** 339 340| Name| Type| Mandatory| Description| 341| -------- | -------- | -------- | -------- | 342| field | string | Yes| Column name in the table.| 343| value | string | Yes| Value to match the **DataAbilityPredicates**.| 344 345**Return value** 346 347| Type| Description| 348| -------- | -------- | 349| [DataAbilityPredicates](#dataabilitypredicates) | **DataAbilityPredicates** object that matches the specified field.| 350 351**Example** 352 353 ```js 354 dataAbilityPredicates.like("NAME", "%os%") 355 ``` 356 357### glob 358 359glob(field: string, value: string): DataAbilityPredicates 360 361Sets a **DataAbilityPredicates** object to match the specified string. 362 363**System capability**: SystemCapability.DistributedDataManager.DataShare.Core 364 365**Parameters** 366 367| Name| Type| Mandatory| Description| 368| -------- | -------- | -------- | -------- | 369| field | string | Yes| Column name in the table.| 370| value | string | Yes| Value to match the **DataAbilityPredicates**.| 371 372**Return value** 373 374| Type| Description| 375| -------- | -------- | 376| [DataAbilityPredicates](#dataabilitypredicates) | **DataAbilityPredicates** object that matches the specified field.| 377 378**Example** 379 380 ```js 381 dataAbilityPredicates.glob("NAME", "?h*g") 382 ``` 383 384### between 385 386between(field: string, low: ValueType, high: ValueType): DataAbilityPredicates 387 388Sets a **DataAbilityPredicates** object to match a field whose data type is **ValueType** and value is within the specified range. 389 390**System capability**: SystemCapability.DistributedDataManager.DataShare.Core 391 392**Parameters** 393 394| Name| Type| Mandatory| Description| 395| -------- | -------- | -------- | -------- | 396| field | string | Yes| Column name in the table.| 397| low | [ValueType](#valuetype) | Yes| Minimum value to match the **DataAbilityPredicates**.| 398| high | [ValueType](#valuetype) | Yes| Maximum value to match the **DataAbilityPredicates**.| 399 400**Return value** 401 402| Type| Description| 403| -------- | -------- | 404| [DataAbilityPredicates](#dataabilitypredicates) | **DataAbilityPredicates** object that matches the specified field.| 405 406**Example** 407 408 ```js 409 dataAbilityPredicates.between("AGE", 10, 50) 410 ``` 411 412### notBetween 413 414notBetween(field: string, low: ValueType, high: ValueType): DataAbilityPredicates 415 416Sets a **DataAbilityPredicates** object to match the field with data type **ValueType** and value out of the specified range. 417 418**System capability**: SystemCapability.DistributedDataManager.DataShare.Core 419 420**Parameters** 421 422| Name| Type| Mandatory| Description| 423| -------- | -------- | -------- | -------- | 424| field | string | Yes| Column name in the table.| 425| low | [ValueType](#valuetype) | Yes| Minimum value to match the **DataAbilityPredicates**.| 426| high | [ValueType](#valuetype) | Yes| Maximum value to match the **DataAbilityPredicates**.| 427 428**Return value** 429 430| Type| Description| 431| -------- | -------- | 432| [DataAbilityPredicates](#dataabilitypredicates) | **DataAbilityPredicates** object that matches the specified field.| 433 434**Example** 435 436 ```js 437 dataAbilityPredicates.notBetween("AGE", 10, 50) 438 ``` 439 440### greaterThan 441 442greaterThan(field: string, value: ValueType): DataAbilityPredicates 443 444Sets a **DataAbilityPredicates** object to match the field with data type **ValueType** and value greater than the specified value. 445 446**System capability**: SystemCapability.DistributedDataManager.DataShare.Core 447 448**Parameters** 449 450| Name| Type| Mandatory| Description| 451| -------- | -------- | -------- | -------- | 452| field | string | Yes| Column name in the table.| 453| value | [ValueType](#valuetype) | Yes| Value to match the **DataAbilityPredicates**.| 454 455**Return value** 456 457| Type| Description| 458| -------- | -------- | 459| [DataAbilityPredicates](#dataabilitypredicates) | **DataAbilityPredicates** object that matches the specified field.| 460 461**Example** 462 463 ```js 464 dataAbilityPredicates.greaterThan("AGE", 18) 465 ``` 466 467### lessThan 468 469lessThan(field: string, value: ValueType): DataAbilityPredicates 470 471Sets a **DataAbilityPredicates** object to match the field with data type **ValueType** and value less than the specified value. 472 473**System capability**: SystemCapability.DistributedDataManager.DataShare.Core 474 475**Parameters** 476 477| Name| Type| Mandatory| Description| 478| -------- | -------- | -------- | -------- | 479| field | string | Yes| Column name in the table.| 480| value | [ValueType](#valuetype) | Yes| Value to match the **DataAbilityPredicates**.| 481 482**Return value** 483 484| Type| Description| 485| -------- | -------- | 486| [DataAbilityPredicates](#dataabilitypredicates) | **DataAbilityPredicates** object that matches the specified field.| 487 488**Example** 489 490 ```js 491 dataAbilityPredicates.lessThan("AGE", 20) 492 ``` 493 494### greaterThanOrEqualTo 495 496greaterThanOrEqualTo(field: string, value: ValueType): DataAbilityPredicates 497 498Sets a **DataAbilityPredicates** object to match the field with data type **ValueType** and value greater than or equal to the specified value. 499 500**System capability**: SystemCapability.DistributedDataManager.DataShare.Core 501 502**Parameters** 503 504| Name| Type| Mandatory| Description| 505| -------- | -------- | -------- | -------- | 506| field | string | Yes| Column name in the table.| 507| value | [ValueType](#valuetype) | Yes| Value to match the **DataAbilityPredicates**.| 508 509**Return value** 510 511| Type| Description| 512| -------- | -------- | 513| [DataAbilityPredicates](#dataabilitypredicates) | **DataAbilityPredicates** object that matches the specified field.| 514 515**Example** 516 517 ```js 518 dataAbilityPredicates.greaterThanOrEqualTo("AGE", 18) 519 ``` 520 521### lessThanOrEqualTo 522 523lessThanOrEqualTo(field: string, value: ValueType): DataAbilityPredicates 524 525Sets a **DataAbilityPredicates** object to match the field with data type **ValueType** and value less than or equal to the specified value. 526 527**System capability**: SystemCapability.DistributedDataManager.DataShare.Core 528 529**Parameters** 530 531| Name| Type| Mandatory| Description| 532| -------- | -------- | -------- | -------- | 533| field | string | Yes| Column name in the table.| 534| value | [ValueType](#valuetype) | Yes| Value to match the **DataAbilityPredicates**.| 535 536**Return value** 537 538| Type| Description| 539| -------- | -------- | 540| [DataAbilityPredicates](#dataabilitypredicates) | **DataAbilityPredicates** object that matches the specified field.| 541 542**Example** 543 544 ```js 545 dataAbilityPredicates.lessThanOrEqualTo("AGE", 20) 546 ``` 547 548### orderByAsc 549 550orderByAsc(field: string): DataAbilityPredicates 551 552Sets a **DataAbilityPredicates** object to match the column with values sorted in ascending order. 553 554**System capability**: SystemCapability.DistributedDataManager.DataShare.Core 555 556**Parameters** 557 558| Name| Type| Mandatory| Description| 559| -------- | -------- | -------- | -------- | 560| field | string | Yes| Column name in the table.| 561 562**Return value** 563 564| Type| Description| 565| -------- | -------- | 566| [DataAbilityPredicates](#dataabilitypredicates) | **DataAbilityPredicates** object that matches the specified field.| 567 568**Example** 569 570 ```js 571 dataAbilityPredicates.orderByAsc("NAME") 572 ``` 573 574### orderByDesc 575 576orderByDesc(field: string): DataAbilityPredicates 577 578Sets a **DataAbilityPredicates** object to match the column with values sorted in descending order. 579 580**System capability**: SystemCapability.DistributedDataManager.DataShare.Core 581 582**Parameters** 583 584| Name| Type| Mandatory| Description| 585| -------- | -------- | -------- | -------- | 586| field | string | Yes| Column name in the table.| 587 588**Return value** 589 590| Type| Description| 591| -------- | -------- | 592| [DataAbilityPredicates](#dataabilitypredicates) | **DataAbilityPredicates** object that matches the specified field.| 593 594**Example** 595 596 ```js 597 dataAbilityPredicates.orderByDesc("AGE") 598 ``` 599 600### distinct 601 602distinct(): DataAbilityPredicates 603 604Sets a **DataAbilityPredicates** object to filter out duplicate records. 605 606**System capability**: SystemCapability.DistributedDataManager.DataShare.Core 607 608**Return value** 609 610| Type| Description| 611| -------- | -------- | 612| [DataAbilityPredicates](#dataabilitypredicates) | **DataAbilityPredicates** object that can filter out duplicate records.| 613 614**Example** 615 616 ```js 617 dataAbilityPredicates.equalTo("NAME", "Rose").distinct() 618 ``` 619 620### limitAs 621 622limitAs(value: number): DataAbilityPredicates 623 624Set a **DataAbilityPredicates** object to specify the maximum number of records. 625 626**System capability**: SystemCapability.DistributedDataManager.DataShare.Core 627 628**Parameters** 629 630| Name| Type| Mandatory| Description| 631| -------- | -------- | -------- | -------- | 632| value | number | Yes| Maximum number of records.| 633 634**Return value** 635 636| Type| Description| 637| -------- | -------- | 638| [DataAbilityPredicates](#dataabilitypredicates) | **DataAbilityPredicates** object that specifies the maximum number of records.| 639 640**Example** 641 642 ```js 643 dataAbilityPredicates.equalTo("NAME", "Rose").limitAs(3) 644 ``` 645 646### offsetAs 647 648offsetAs(rowOffset: number): DataAbilityPredicates 649 650Sets a **DataAbilityPredicates** object to specify the start position of the returned result. 651 652**System capability**: SystemCapability.DistributedDataManager.DataShare.Core 653 654**Parameters** 655 656| Name| Type| Mandatory| Description| 657| -------- | -------- | -------- | -------- | 658| rowOffset | number | Yes| Number of rows to offset from the beginning. The value is a positive integer.| 659 660**Return value** 661 662| Type| Description| 663| -------- | -------- | 664| [DataAbilityPredicates](#dataabilitypredicates) | **DataAbilityPredicates** object that specifies the start position of the returned result.| 665 666**Example** 667 668 ```js 669 dataAbilityPredicates.equalTo("NAME", "Rose").offsetAs(3) 670 ``` 671 672 673### groupBy 674 675groupBy(fields: Array<string>): DataAbilityPredicates 676 677Sets a **DataAbilityPredicates** object to group rows that have the same value into summary rows. 678 679**System capability**: SystemCapability.DistributedDataManager.DataShare.Core 680 681**Parameters** 682 683| Name| Type| Mandatory| Description| 684| -------- | -------- | -------- | -------- | 685| fields | Array<string> | Yes| Names of columns to group.| 686 687**Return value** 688 689| Type| Description| 690| -------- | -------- | 691| [DataAbilityPredicates](#dataabilitypredicates) | **DataAbilityPredicates** object that groups rows with the same value.| 692 693**Example** 694 695 ```js 696 dataAbilityPredicates.groupBy(["AGE", "NAME"]) 697 ``` 698 699### indexedBy 700 701indexedBy(field: string): DataAbilityPredicates 702 703Sets a **DataAbilityPredicates** object to specify the index column. 704 705**System capability**: SystemCapability.DistributedDataManager.DataShare.Core 706 707**Parameters** 708 709| Name| Type| Mandatory| Description| 710| -------- | -------- | -------- | -------- | 711| indexName | string | Yes| Name of the index column.| 712 713**Return value** 714 715| Type| Description| 716| -------- | -------- | 717| [DataAbilityPredicates](#dataabilitypredicates) | **DataAbilityPredicates** object that specifies the index column.| 718 719**Example** 720 721 ```js 722 dataAbilityPredicates.indexedBy("SALARY_INDEX") 723 ``` 724 725### in 726 727in(field: string, value: Array<ValueType>): DataAbilityPredicates 728 729Sets a **DataAbilityPredicates** object to match the field with data type Array\<ValueType> and value within the specified range. 730 731**System capability**: SystemCapability.DistributedDataManager.DataShare.Core 732 733**Parameters** 734 735| Name| Type| Mandatory| Description| 736| -------- | -------- | -------- | -------- | 737| field | string | Yes| Column name in the table.| 738| value | Array<[ValueType](#valuetype)> | Yes| Array of **ValueType**s to match.| 739 740 741**Return value** 742 743| Type| Description| 744| -------- | -------- | 745| [DataAbilityPredicates](#dataabilitypredicates) | **DataAbilityPredicates** object that matches the specified field.| 746 747**Example** 748 749 ```js 750 dataAbilityPredicates.in("AGE", [18, 20]) 751 ``` 752 753### notIn 754 755notIn(field: string, value: Array<ValueType>): DataAbilityPredicates 756 757Sets a **DataAbilityPredicates** object to match the field with data type Array\<ValueType> and value out of the specified range. 758 759**System capability**: SystemCapability.DistributedDataManager.DataShare.Core 760 761**Parameters** 762 763| Name| Type| Mandatory| Description| 764| -------- | -------- | -------- | -------- | 765| field | string | Yes| Column name in the table.| 766| value | Array<[ValueType](#valuetype)> | Yes| Array of **ValueType**s to match.| 767 768**Return value** 769 770| Type| Description| 771| -------- | -------- | 772| [DataAbilityPredicates](#dataabilitypredicates) | **DataAbilityPredicates** object that matches the specified field.| 773 774**Example** 775 776 ```js 777 dataAbilityPredicates.notIn("NAME", ["Lisa", "Rose"]) 778 ``` 779 780## ValueType 781 782Enumerates the value types. 783 784**System capability**: SystemCapability.DistributedDataManager.DataShare.Core 785 786| Type | Description | 787| ------- | -------------------- | 788| number | The value is a number. | 789| string | The value is a string. | 790| boolean | The value is of Boolean type.| 791