Ddd---Signed-off-by: dd--- <humengdi2@huawei.com>

@ohos.data.dataSharePredicates (DataShare Predicates)

DataSharePredicates provides a filter object to query data in a database by using DataShare APIs. It is often used to update, delete, and query data.

The APIs provided by DataSharePredicates correspond to the filter criteria of the database. Before using the APIs, you need to have basic database knowledge.

DataSharePredicates applies to the following scenario:

It is used as a search criterion in the media file management service. For details, see FetchOptions in the fetch options of the album management. In this scenario, you do not need to pay attention to the database type.

It is used as a search criterion when APIs of the RDB store and KV store are called. In this scenario, use the corresponding predicate based on the database type.

NOTE

The initial APIs of this module are supported since API version 10. Newly added APIs will be marked with a superscript to indicate their earliest API version.

The APIs of this module can be used only in the stage model.

Modules to Import

import { dataSharePredicates } from '@kit.ArkData';

DataSharePredicates

Provides APIs for setting different DataSharePredicates objects. This type is not multi-thread safe. If a DataSharePredicates instance is operated by multiple threads at the same time in an application, use a lock for it.

equalTo¹⁰⁺

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

Creates a DataSharePredicates object to search for the records in the specified column that are equal to the given value.

Currently, both the RDB store and KV store support this predicate.

System capability: SystemCapability.DistributedDataManager.DataShare.Core

Atomic service API: This API can be used in atomic services since API version 20.

Parameters

Name	Type	Mandatory	Description
field	string	Yes	Column name in the database table. If this parameter is set to undefined or null, the predicate used is invalid.
value	ValueType	Yes	Value to match. If this parameter is set to undefined or null, the predicate used is invalid.

Return value

Type	Description
DataSharePredicates	DataSharePredicates object created.

Example

let predicates = new dataSharePredicates.DataSharePredicates();
predicates.equalTo("NAME", "Rose");

and¹⁰⁺

and(): DataSharePredicates

Creates a DataSharePredicates object to add the AND condition.

Currently, both the RDB store and KV store support this predicate.

System capability: SystemCapability.DistributedDataManager.DataShare.Core

Atomic service API: This API can be used in atomic services since API version 20.

Return value

Type	Description
DataSharePredicates	DataSharePredicates object with the AND operator.

Example

let predicates = new dataSharePredicates.DataSharePredicates();
predicates.equalTo("NAME", "lisi")
    .and()
    .equalTo("SALARY", 200.5);

orderByAsc¹⁰⁺

orderByAsc(field: string): DataSharePredicates

Creates a DataSharePredicates object that sorts records in ascending order.

Currently, both the RDB store and KV store support this predicate.

System capability: SystemCapability.DistributedDataManager.DataShare.Core

Atomic service API: This API can be used in atomic services since API version 20.

Parameters

Name	Type	Mandatory	Description
field	string	Yes	Column name in the database table. If this parameter is set to undefined or null, the predicate used is invalid.

Return value

Type	Description
DataSharePredicates	DataSharePredicates object created.

Example

let predicates = new dataSharePredicates.DataSharePredicates();
predicates.orderByAsc("AGE");

orderByDesc¹⁰⁺

orderByDesc(field: string): DataSharePredicates

Creates a DataSharePredicates object that sorts data in descending order.

Currently, both the RDB store and KV store support this predicate.

System capability: SystemCapability.DistributedDataManager.DataShare.Core

Atomic service API: This API can be used in atomic services since API version 20.

Parameters

Name	Type	Mandatory	Description
field	string	Yes	Column name in the database table. If this parameter is set to undefined or null, the predicate used is invalid.

Return value

Type	Description
DataSharePredicates	DataSharePredicates object created.

Example

let predicates = new dataSharePredicates.DataSharePredicates();
predicates.orderByDesc("AGE");

limit¹⁰⁺

limit(total: number, offset: number): DataSharePredicates

Creates a DataSharePredicates object to specify the number of records in the result and the start position.

Currently, both the RDB store and KV store support this predicate.

System capability: SystemCapability.DistributedDataManager.DataShare.Core

Atomic service API: This API can be used in atomic services since API version 20.

Parameters

Name	Type	Mandatory	Description
total	number	Yes	Maximum number of records. If the KV store is used and total is undefined or null, the maximum number of records is 0. For details about the value range, see the description of this parameter in limit. If the RDB store is used and total is undefined or null, the maximum number of records is not limited. For details about the value range, see the description of this parameter in limitAs.
offset	number	Yes	Start position of the query result. If this parameter is set to undefined or null, the start position is the beginning of the result set. For details about the value range in a KV store, see the description of this parameter in limit. For details about the value range in an RDB store, see the description of the rowOffset parameter in offsetAs.

Return value

Type	Description
DataSharePredicates	DataSharePredicates object created.

Example

let predicates = new dataSharePredicates.DataSharePredicates();
predicates.equalTo("NAME", "Rose").limit(10, 3);

in¹⁰⁺

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

Creates a DataSharePredicates object to match the data that is within the specified range.

Currently, both the RDB store and KV store support this predicate.

System capability: SystemCapability.DistributedDataManager.DataShare.Core

Atomic service API: This API can be used in atomic services since API version 20.

Parameters

Name	Type	Mandatory	Description
field	string	Yes	Column name in the database table. If this parameter is set to undefined or null, the predicate used is invalid.
value	Array<ValueType>	Yes	Array of the values to match.

Return value

Type	Description
DataSharePredicates	DataSharePredicates object created.

Example

let predicates = new dataSharePredicates.DataSharePredicates();
predicates.in("AGE", [18, 20]);

notEqualTo²³⁺

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

Creates a DataSharePredicates object to match the data that is not equal to the specified value.

Currently, both the RDB store and KV store support this predicate.

System capability: SystemCapability.DistributedDataManager.DataShare.Core

Parameters

Name	Type	Mandatory	Description
field	string	Yes	Column name in the database table. If this parameter is set to undefined or null, the predicate used is invalid. If this parameter is set to 'null' or 'undefined' in string, the matching result may not be as expected or an exception may be thrown when the predicate is used by the KV store and RDB store APIs.
value	ValueType	Yes	Value to match. If this parameter is set to undefined or null, the predicate used is invalid.

Return value

Type	Description
DataSharePredicates	DataSharePredicates object created.

Example

let predicates = new dataSharePredicates.DataSharePredicates();
predicates.notEqualTo("NAME", "Rose");

beginWrap²³⁺

beginWrap(): DataSharePredicates

Adds a left parenthesis to this DataSharePredicates. This API is similar to "(" in an SQL statement and must be used with the right parenthesis.

Currently, only RDB store supports this predicate.

System capability: SystemCapability.DistributedDataManager.DataShare.Core

Return value

Type	Description
DataSharePredicates	DataSharePredicates object with a left parenthesis.

Example

let predicates = new dataSharePredicates.DataSharePredicates();
predicates.equalTo("NAME", "lisi")
    .beginWrap()
    .equalTo("AGE", 18)
    .or()
    .equalTo("SALARY", 200.5)
    .endWrap();

endWrap²³⁺

endWrap(): DataSharePredicates

Adds a right parenthesis to this DataSharePredicates. This API is similar to ")" in an SQL statement and must be used with the left parenthesis.

Currently, only RDB store supports this predicate.

System capability: SystemCapability.DistributedDataManager.DataShare.Core

Return value

Type	Description
DataSharePredicates	DataSharePredicates object with a right parenthesis.

Example

let predicates = new dataSharePredicates.DataSharePredicates();
predicates.equalTo("NAME", "lisi")
    .beginWrap()
    .equalTo("AGE", 18)
    .or()
    .equalTo("SALARY", 200.5)
    .endWrap();

or²³⁺

or(): DataSharePredicates

Creates a DataSharePredicates object to add the OR condition.

Currently, both the RDB store and KV store support this predicate.

System capability: SystemCapability.DistributedDataManager.DataShare.Core

Return value

Type	Description
DataSharePredicates	DataSharePredicates object with the OR operator.

Example

let predicates = new dataSharePredicates.DataSharePredicates()
predicates.equalTo("NAME", "lisi")
    .or()
    .equalTo("NAME", "Rose");

like²³⁺

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

Creates a DataSharePredicates object to match the data that matches the specified wildcard expression.

Currently, both the RDB store and KV store support this predicate.

System capability: SystemCapability.DistributedDataManager.DataShare.Core

Parameters

Name	Type	Mandatory	Description
field	string	Yes	Column name in the database table. If this parameter is set to undefined or null, the predicate used is invalid. If this parameter is set to 'null' or 'undefined' in string, the matching result may not be as expected or an exception may be thrown when the predicate is used by the KV store and RDB store APIs.
value	string	Yes	Wildcard expression to match. In the expression, '%' represents zero, one, or more digits or characters, and '_' represents a single digit or character. It is case insensitive. If this parameter is set to undefined or null, the predicate used is invalid.

Return value

Type	Description
DataSharePredicates	DataSharePredicates object created.

Example

let predicates = new dataSharePredicates.DataSharePredicates();
predicates.like("NAME", "%os%");

between²³⁺

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

Creates a DataSharePredicates object to match the data that is within the specified range, including the start and end values.

Currently, only RDB store supports this predicate.

System capability: SystemCapability.DistributedDataManager.DataShare.Core

Parameters

Name	Type	Mandatory	Description
field	string	Yes	Column name in the database table. If this parameter is set to undefined or null, the predicate used is invalid. If this parameter is set to 'null' or 'undefined' in string, the matching result may not be as expected or an exception may be thrown when the predicate is used by the KV store and RDB store APIs.
low	ValueType	Yes	Minimum value of the range to set. If low is set to a number, the matching range is specified based on the numeric order. If low is set to a string, the matching range is specified based on the lexicographical order. If low is set to boolean, the matching range is specified based on the numeric order.
high	ValueType	Yes	Maximum value to match the DataAbilityPredicates. If high is set to a number, the matching range is specified based on the numeric order. If high is set to a string, the matching range is specified based on the lexicographical order. If high is set to boolean, the matching range is specified based on the numeric order.

Return value

Type	Description
DataSharePredicates	DataSharePredicates object created.

Example

let predicates = new dataSharePredicates.DataSharePredicates();
predicates.between("AGE", 10, 50);

notBetween²³⁺

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

Creates a DataSharePredicates object to match the data that is out of the specified range, excluding the start and end values.

Currently, only RDB store supports this predicate.

System capability: SystemCapability.DistributedDataManager.DataShare.Core

Parameters

Name	Type	Mandatory	Description
field	string	Yes	Column name in the database table. If this parameter is set to undefined or null, the predicate used is invalid. If this parameter is set to 'null' or 'undefined' in string, the matching result may not be as expected or an exception may be thrown when the predicate is used by the KV store and RDB store APIs.
low	ValueType	Yes	Minimum value of the range to set. If low is set to a number, the matching range is specified based on the numeric order. If low is set to a string, the matching range is specified based on the lexicographical order. If low is set to boolean, the matching range is specified based on the numeric order.
high	ValueType	Yes	Maximum value to match the DataAbilityPredicates. If high is set to a number, the matching range is specified based on the numeric order. If high is set to a string, the matching range is specified based on the lexicographical order. If high is set to boolean, the matching range is specified based on the numeric order.

Return value

Type	Description
DataSharePredicates	DataSharePredicates object created.

Example

let predicates = new dataSharePredicates.DataSharePredicates();
predicates.notBetween("AGE", 10, 50);

greaterThan²³⁺

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

Creates a DataSharePredicates object to match the data that is greater than the specified value.

Currently, both the RDB store and KV store support this predicate.

System capability: SystemCapability.DistributedDataManager.DataShare.Core

Parameters

Name	Type	Mandatory	Description
field	string	Yes	Column name in the database table. If this parameter is set to undefined or null, the predicate used is invalid. If this parameter is set to 'null' or 'undefined' in string, the matching result may not be as expected or an exception may be thrown when the predicate is used by the KV store and RDB store APIs.
value	ValueType	Yes	Value to match. If this parameter is set to undefined or null, the predicate used is invalid.

Return value

Type	Description
DataSharePredicates	DataSharePredicates object created.

Example

let predicates = new dataSharePredicates.DataSharePredicates();
predicates.greaterThan("AGE", 10);

lessThan²³⁺

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

Creates a DataSharePredicates object to match the data that is less than the specified value.

Currently, both the RDB store and KV store support this predicate.

System capability: SystemCapability.DistributedDataManager.DataShare.Core

Parameters

Name	Type	Mandatory	Description
field	string	Yes	Column name in the database table. If field is null or undefined, the predicate configured by calling this API is invalid. If this parameter is set to 'null' or 'undefined' in string, the matching result may not be as expected or an exception may be thrown when the predicate is used by the KV store and RDB store APIs.
value	ValueType	Yes	Value to match. If this parameter is set to undefined or null, the predicate used is invalid.

Return value

Type	Description
DataSharePredicates	DataSharePredicates object created.

Example

let predicates = new dataSharePredicates.DataSharePredicates();
predicates.lessThan("AGE", 50);

greaterThanOrEqualTo²³⁺

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

Creates a DataSharePredicates object to match the data that is greater than or equal to the specified value.

Currently, both the RDB store and KV store support this predicate.

System capability: SystemCapability.DistributedDataManager.DataShare.Core

Parameters

Name	Type	Mandatory	Description
field	string	Yes	Column name in the database table. If this parameter is set to undefined or null, the predicate used is invalid. If this parameter is set to 'null' or 'undefined' in string, the matching result may not be as expected or an exception may be thrown.
value	ValueType	Yes	Value to match. If this parameter is set to undefined or null, the predicate used is invalid.

Return value

Type	Description
DataSharePredicates	DataSharePredicates object created.

Example

let predicates = new dataSharePredicates.DataSharePredicates();
predicates.greaterThanOrEqualTo("AGE", 10);

lessThanOrEqualTo²³⁺

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

Creates a DataSharePredicates object to match the data that is less than or equal to the specified value.

Currently, both the RDB store and KV store support this predicate.

System capability: SystemCapability.DistributedDataManager.DataShare.Core

Parameters

Name	Type	Mandatory	Description
field	string	Yes	Column name in the database table. If this parameter is set to undefined or null, the predicate used is invalid. If this parameter is set to 'null' or 'undefined' in string, the matching result may not be as expected or an exception may be thrown when the predicate is used by the KV store and RDB store APIs.
value	ValueType	Yes	Value to match. If this parameter is set to undefined or null, the predicate used is invalid.

Return value

Type	Description
DataSharePredicates	DataSharePredicates object created.

Example

let predicates = new dataSharePredicates.DataSharePredicates();
predicates.lessThanOrEqualTo("AGE", 50);

notIn²³⁺

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

Creates a DataSharePredicates object to match the data that is not in the specified value.

Currently, both the RDB store and KV store support this predicate.

System capability: SystemCapability.DistributedDataManager.DataShare.Core

Parameters

Name	Type	Mandatory	Description
field	string	Yes	Column name in the database table. If this parameter is set to undefined or null, the predicate used is invalid. If this parameter is set to 'null' or 'undefined' in string, the matching result may not be as expected or an exception may be thrown when the predicate is used by the KV store and RDB store APIs.
value	Array<ValueType>	Yes	Array of the values to match. If this parameter is set to undefined or null, the predicate used is invalid.

Return value

Type	Description
DataSharePredicates	DataSharePredicates object created.

Example

let predicates = new dataSharePredicates.DataSharePredicates();
predicates.notIn("NAME", ["Lisa", "Rose"]);

@ohos.data.dataSharePredicates (DataShare Predicates)

Modules to Import

DataSharePredicates

equalTo10+

and10+

orderByAsc10+

orderByDesc10+

limit10+

in10+

notEqualTo23+

beginWrap23+

endWrap23+

or23+

like23+

between23+

notBetween23+

greaterThan23+

lessThan23+

greaterThanOrEqualTo23+

lessThanOrEqualTo23+

notIn23+

equalTo¹⁰⁺

and¹⁰⁺

orderByAsc¹⁰⁺

orderByDesc¹⁰⁺

limit¹⁰⁺

in¹⁰⁺

notEqualTo²³⁺

beginWrap²³⁺

endWrap²³⁺

or²³⁺

like²³⁺

between²³⁺

notBetween²³⁺

greaterThan²³⁺

lessThan²³⁺

greaterThanOrEqualTo²³⁺

lessThanOrEqualTo²³⁺

notIn²³⁺