@ohos.data.dataAbility (DataAbility Predicates)

DataAbility provides APIs for creating predicates, which implement different query methods for relational database (RDB) stores.

NOTE

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.

Modules to Import

import dataAbility from '@ohos.data.dataAbility';

dataAbility.createRdbPredicates

createRdbPredicates(name: string, dataAbilityPredicates: DataAbilityPredicates): rdb.RdbPredicates

Creates an RdbPredicates object from a DataAbilityPredicates object.

System capability: SystemCapability.DistributedDataManager.DataShare.Core

Parameters

Name Type Mandatory Description
name string Yes Name of a database table.
dataAbilityPredicates DataAbilityPredicates Yes DataAbilityPredicates object.

Return value

Type Description
rdb.RdbPredicates RdbPredicates object created.

Example

let dataAbilityPredicates = new dataAbility.DataAbilityPredicates()
dataAbilityPredicates.equalTo("NAME", "Rose")
let predicates = dataAbility.createRdbPredicates("EMPLOYEE", dataAbilityPredicates)

DataAbilityPredicates

Provides predicates for implementing diverse query methods.

equalTo

equalTo(field: string, value: ValueType): DataAbilityPredicates

Sets a DataAbilityPredicates object to match the field with data type ValueType and value equal to the specified value.

System capability: SystemCapability.DistributedDataManager.DataShare.Core

Parameters

Name Type Mandatory Description
field string Yes Column name in the table.
value ValueType Yes Value to match the DataAbilityPredicates.

Return value

Type Description
DataAbilityPredicates DataAbilityPredicates object that matches the specified field.

Example

dataAbilityPredicates.equalTo("NAME", "lisi")

notEqualTo

notEqualTo(field: string, value: ValueType): DataAbilityPredicates

Sets a DataAbilityPredicates object to match the field with data type ValueType and value not equal to the specified value.

System capability: SystemCapability.DistributedDataManager.DataShare.Core

Parameters

Name Type Mandatory Description
field string Yes Column name in the table.
value ValueType Yes Value to match the DataAbilityPredicates.

Return value

Type Description
DataAbilityPredicates DataAbilityPredicates object that matches the specified field.

Example

dataAbilityPredicates.notEqualTo("NAME", "lisi")

beginWrap

beginWrap(): DataAbilityPredicates

Adds a left parenthesis to this DataAbilityPredicates.

System capability: SystemCapability.DistributedDataManager.DataShare.Core

Return value

Type Description
DataAbilityPredicates DataAbilityPredicates object with a left parenthesis.

Example

dataAbilityPredicates.equalTo("NAME", "lisi")
    .beginWrap()
    .equalTo("AGE", 18)
    .or()
    .equalTo("SALARY", 200.5)
    .endWrap()

endWrap

endWrap(): DataAbilityPredicates

Adds a right parenthesis to this DataAbilityPredicates.

System capability: SystemCapability.DistributedDataManager.DataShare.Core

Return value

Type Description
DataAbilityPredicates DataAbilityPredicates object with a right parenthesis.

Example

dataAbilityPredicates.equalTo("NAME", "lisi")
    .beginWrap()
    .equalTo("AGE", 18)
    .or()
    .equalTo("SALARY", 200.5)
    .endWrap()

or

or(): DataAbilityPredicates

Adds the OR condition to this DataAbilityPredicates.

System capability: SystemCapability.DistributedDataManager.DataShare.Core

Return value

Type Description
DataAbilityPredicates DataAbilityPredicates object with the OR condition.

Example

dataAbilityPredicates.equalTo("NAME", "Lisa")
    .or()
    .equalTo("NAME", "Rose")

and

and(): DataAbilityPredicates

Adds the AND condition to this DataAbilityPredicates.

System capability: SystemCapability.DistributedDataManager.DataShare.Core

Return value

Type Description
DataAbilityPredicates DataAbilityPredicates object with the AND condition.

Example

dataAbilityPredicates.equalTo("NAME", "Lisa")
    .and()
    .equalTo("SALARY", 200.5)

contains

contains(field: string, value: string): DataAbilityPredicates

Sets a DataAbilityPredicates object to match a string containing the specified value.

System capability: SystemCapability.DistributedDataManager.DataShare.Core

Parameters

Name Type Mandatory Description
field string Yes Column name in the table.
value string Yes Value to match the DataAbilityPredicates.

Return value

Type Description
DataAbilityPredicates DataAbilityPredicates object that matches the specified field.

Example

dataAbilityPredicates.contains("NAME", "os")

beginsWith

beginsWith(field: string, value: string): DataAbilityPredicates

Sets a DataAbilityPredicates object to match a string that starts with the specified value.

System capability: SystemCapability.DistributedDataManager.DataShare.Core

Parameters

Name Type Mandatory Description
field string Yes Column name in the table.
value string Yes Value to match the DataAbilityPredicates.

Return value

Type Description
DataAbilityPredicates DataAbilityPredicates object that matches the specified field.

Example

dataAbilityPredicates.beginsWith("NAME", "os")

endsWith

endsWith(field: string, value: string): DataAbilityPredicates

Sets a DataAbilityPredicates object to match a string that ends with the specified value.

System capability: SystemCapability.DistributedDataManager.DataShare.Core

Parameters

Name Type Mandatory Description
field string Yes Column name in the table.
value string Yes Value to match the DataAbilityPredicates.

Return value

Type Description
DataAbilityPredicates DataAbilityPredicates object that matches the specified field.

Example

dataAbilityPredicates.endsWith("NAME", "se")

isNull

isNull(field: string): DataAbilityPredicates

Sets a DataAbilityPredicates object to match the field whose value is null.

System capability: SystemCapability.DistributedDataManager.DataShare.Core

Parameters

Name Type Mandatory Description
field string Yes Column name in the table.

Return value

Type Description
DataAbilityPredicates DataAbilityPredicates object that matches the specified field.

Example

dataAbilityPredicates.isNull("NAME")

isNotNull

isNotNull(field: string): DataAbilityPredicates

Sets a DataAbilityPredicates object to match the field whose value is not null.

System capability: SystemCapability.DistributedDataManager.DataShare.Core

Parameters

Name Type Mandatory Description
field string Yes Column name in the table.

Return value

Type Description
DataAbilityPredicates DataAbilityPredicates object that matches the specified field.

Example

dataAbilityPredicates.isNotNull("NAME")

like

like(field: string, value: string): DataAbilityPredicates

Sets a DataAbilityPredicates object to match a string that is similar to the specified value.

System capability: SystemCapability.DistributedDataManager.DataShare.Core

Parameters

Name Type Mandatory Description
field string Yes Column name in the table.
value string Yes Value to match the DataAbilityPredicates.

Return value

Type Description
DataAbilityPredicates DataAbilityPredicates object that matches the specified field.

Example

dataAbilityPredicates.like("NAME", "%os%")

glob

glob(field: string, value: string): DataAbilityPredicates

Sets a DataAbilityPredicates object to match the specified string.

System capability: SystemCapability.DistributedDataManager.DataShare.Core

Parameters

Name Type Mandatory Description
field string Yes Column name in the table.
value string Yes Value to match the DataAbilityPredicates.

Return value

Type Description
DataAbilityPredicates DataAbilityPredicates object that matches the specified field.

Example

dataAbilityPredicates.glob("NAME", "?h*g")

between

between(field: string, low: ValueType, high: ValueType): DataAbilityPredicates

Sets a DataAbilityPredicates object to match a field whose data type is ValueType and value is within the specified range.

System capability: SystemCapability.DistributedDataManager.DataShare.Core

Parameters

Name Type Mandatory Description
field string Yes Column name in the table.
low ValueType Yes Minimum value to match the DataAbilityPredicates.
high ValueType Yes Maximum value to match the DataAbilityPredicates.

Return value

Type Description
DataAbilityPredicates DataAbilityPredicates object that matches the specified field.

Example

dataAbilityPredicates.between("AGE", 10, 50)

notBetween

notBetween(field: string, low: ValueType, high: ValueType): DataAbilityPredicates

Sets a DataAbilityPredicates object to match the field with data type ValueType and value out of the specified range.

System capability: SystemCapability.DistributedDataManager.DataShare.Core

Parameters

Name Type Mandatory Description
field string Yes Column name in the table.
low ValueType Yes Minimum value to match the DataAbilityPredicates.
high ValueType Yes Maximum value to match the DataAbilityPredicates.

Return value

Type Description
DataAbilityPredicates DataAbilityPredicates object that matches the specified field.

Example

dataAbilityPredicates.notBetween("AGE", 10, 50)

greaterThan

greaterThan(field: string, value: ValueType): DataAbilityPredicates

Sets a DataAbilityPredicates object to match the field with data type ValueType and value greater than the specified value.

System capability: SystemCapability.DistributedDataManager.DataShare.Core

Parameters

Name Type Mandatory Description
field string Yes Column name in the table.
value ValueType Yes Value to match the DataAbilityPredicates.

Return value

Type Description
DataAbilityPredicates DataAbilityPredicates object that matches the specified field.

Example

dataAbilityPredicates.greaterThan("AGE", 18)

lessThan

lessThan(field: string, value: ValueType): DataAbilityPredicates

Sets a DataAbilityPredicates object to match the field with data type ValueType and value less than the specified value.

System capability: SystemCapability.DistributedDataManager.DataShare.Core

Parameters

Name Type Mandatory Description
field string Yes Column name in the table.
value ValueType Yes Value to match the DataAbilityPredicates.

Return value

Type Description
DataAbilityPredicates DataAbilityPredicates object that matches the specified field.

Example

dataAbilityPredicates.lessThan("AGE", 20)

greaterThanOrEqualTo

greaterThanOrEqualTo(field: string, value: ValueType): DataAbilityPredicates

Sets a DataAbilityPredicates object to match the field with data type ValueType and value greater than or equal to the specified value.

System capability: SystemCapability.DistributedDataManager.DataShare.Core

Parameters

Name Type Mandatory Description
field string Yes Column name in the table.
value ValueType Yes Value to match the DataAbilityPredicates.

Return value

Type Description
DataAbilityPredicates DataAbilityPredicates object that matches the specified field.

Example

dataAbilityPredicates.greaterThanOrEqualTo("AGE", 18)

lessThanOrEqualTo

lessThanOrEqualTo(field: string, value: ValueType): DataAbilityPredicates

Sets a DataAbilityPredicates object to match the field with data type ValueType and value less than or equal to the specified value.

System capability: SystemCapability.DistributedDataManager.DataShare.Core

Parameters

Name Type Mandatory Description
field string Yes Column name in the table.
value ValueType Yes Value to match the DataAbilityPredicates.

Return value

Type Description
DataAbilityPredicates DataAbilityPredicates object that matches the specified field.

Example

dataAbilityPredicates.lessThanOrEqualTo("AGE", 20)

orderByAsc

orderByAsc(field: string): DataAbilityPredicates

Sets a DataAbilityPredicates object to match the column with values sorted in ascending order.

System capability: SystemCapability.DistributedDataManager.DataShare.Core

Parameters

Name Type Mandatory Description
field string Yes Column name in the table.

Return value

Type Description
DataAbilityPredicates DataAbilityPredicates object that matches the specified field.

Example

dataAbilityPredicates.orderByAsc("NAME")

orderByDesc

orderByDesc(field: string): DataAbilityPredicates

Sets a DataAbilityPredicates object to match the column with values sorted in descending order.

System capability: SystemCapability.DistributedDataManager.DataShare.Core

Parameters

Name Type Mandatory Description
field string Yes Column name in the table.

Return value

Type Description
DataAbilityPredicates DataAbilityPredicates object that matches the specified field.

Example

dataAbilityPredicates.orderByDesc("AGE")

distinct

distinct(): DataAbilityPredicates

Sets a DataAbilityPredicates object to filter out duplicate records.

System capability: SystemCapability.DistributedDataManager.DataShare.Core

Return value

Type Description
DataAbilityPredicates DataAbilityPredicates object that can filter out duplicate records.

Example

dataAbilityPredicates.equalTo("NAME", "Rose").distinct()

limitAs

limitAs(value: number): DataAbilityPredicates

Set a DataAbilityPredicates object to specify the maximum number of records.

System capability: SystemCapability.DistributedDataManager.DataShare.Core

Parameters

Name Type Mandatory Description
value number Yes Maximum number of records.

Return value

Type Description
DataAbilityPredicates DataAbilityPredicates object that specifies the maximum number of records.

Example

dataAbilityPredicates.equalTo("NAME", "Rose").limitAs(3)

offsetAs

offsetAs(rowOffset: number): DataAbilityPredicates

Sets a DataAbilityPredicates object to specify the start position of the returned result.

System capability: SystemCapability.DistributedDataManager.DataShare.Core

Parameters

Name Type Mandatory Description
rowOffset number Yes Number of rows to offset from the beginning. The value is a positive integer.

Return value

Type Description
DataAbilityPredicates DataAbilityPredicates object that specifies the start position of the returned result.

Example

dataAbilityPredicates.equalTo("NAME", "Rose").offsetAs(3)

groupBy

groupBy(fields: Array<string>): DataAbilityPredicates

Sets a DataAbilityPredicates object to group rows that have the same value into summary rows.

System capability: SystemCapability.DistributedDataManager.DataShare.Core

Parameters

Name Type Mandatory Description
fields Array<string> Yes Names of columns to group.

Return value

Type Description
DataAbilityPredicates DataAbilityPredicates object that groups rows with the same value.

Example

dataAbilityPredicates.groupBy(["AGE", "NAME"])

indexedBy

indexedBy(field: string): DataAbilityPredicates

Sets a DataAbilityPredicates object to specify the index column.

System capability: SystemCapability.DistributedDataManager.DataShare.Core

Parameters

Name Type Mandatory Description
indexName string Yes Name of the index column.

Return value

Type Description
DataAbilityPredicates DataAbilityPredicates object that specifies the index column.

Example

dataAbilityPredicates.indexedBy("SALARY_INDEX")

in

in(field: string, value: Array<ValueType>): DataAbilityPredicates

Sets a DataAbilityPredicates object to match the field with data type Array<ValueType> and value within the specified range.

System capability: SystemCapability.DistributedDataManager.DataShare.Core

Parameters

Name Type Mandatory Description
field string Yes Column name in the table.
value Array<ValueType> Yes Array of ValueTypes to match.

Return value

Type Description
DataAbilityPredicates DataAbilityPredicates object that matches the specified field.

Example

dataAbilityPredicates.in("AGE", [18, 20])

notIn

notIn(field: string, value: Array<ValueType>): DataAbilityPredicates

Sets a DataAbilityPredicates object to match the field with data type Array<ValueType> and value out of the specified range.

System capability: SystemCapability.DistributedDataManager.DataShare.Core

Parameters

Name Type Mandatory Description
field string Yes Column name in the table.
value Array<ValueType> Yes Array of ValueTypes to match.

Return value

Type Description
DataAbilityPredicates DataAbilityPredicates object that matches the specified field.

Example

dataAbilityPredicates.notIn("NAME", ["Lisa", "Rose"])

ValueType

Enumerates the value types.

System capability: SystemCapability.DistributedDataManager.DataShare.Core

Type Description
number The value is a number.
string The value is a string.
boolean The value is of Boolean type.