目录

@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:

  • 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.

System capability: SystemCapability.DistributedDataManager.DataShare.Core

[h2]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 field is undefined or null, the predicate configured by this interface call is invalid.
value ValueType Yes

Value to match with the predicate.

If value is undefined or null, the predicate configured by this interface call is invalid.

Return value

Type Description
DataSharePredicates DataSharePredicates object created.

Example

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

[h2]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);

[h2]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 field is undefined or null, the predicate configured by this interface call is invalid.

Return value

Type Description
DataSharePredicates DataSharePredicates object created.

Example

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

[h2]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 field is undefined or null, the predicate configured by this interface call is invalid.

Return value

Type Description
DataSharePredicates DataSharePredicates object created.

Example

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

[h2]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 key-value database is used and total is undefined or null, the maximum number of records is limited to 0.

If the relational database is used and total is undefined or null, the maximum number of records is not limited.

When using a key-value database, for details about the value range, see the description of the total parameter in limit.

When using a relational database, for details about the value range, see the description of the value parameter in limitAs.
offset number Yes

Start position of the query result.

If offset is undefined or null, the start position is the beginning of the result set.

When using a key-value database, for details about the value range, see the description of the offset parameter in limit.

When using a relational database, for details about the value range, 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);

[h2]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 field is undefined or null, the predicate configured by this API call is invalid.

When field is the string 'null' or 'undefined', the key-value database and relational database APIs may return unexpected matching results or throw an exception when using this predicate.
value Array<ValueType> Yes

Value to match, specified as an array of the ValueType type.

If value is undefined or null, the predicate configured by this API call is invalid.

Return value

Type Description
DataSharePredicates DataSharePredicates object created.

Example

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

[h2]notEqualTo23+

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 key-value database and relational database APIs.
value ValueType Yes

Value to match with the predicate.

If value is undefined or null, the predicate configured by this interface call is invalid.

Return value

Type Description
DataSharePredicates DataSharePredicates object created.

Example

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

[h2]beginWrap23+

beginWrap(): DataSharePredicates

Adds a left parenthesis to the predicate, which is equivalent to "(" in an SQL statement and must be used together 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();

[h2]endWrap23+

endWrap(): DataSharePredicates

Adds a right parenthesis to the predicate, which is equivalent to ")" in an SQL statement and must be used together 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();

[h2]or23+

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");

[h2]like23+

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 field is undefined or null, the predicate configured by this API call is invalid.

When field is the string 'null' or 'undefined', the key-value database and relational database APIs may return unexpected matching results or throw an exception when using this predicate.
value string Yes

Wildcard expression to match with the predicate.

In the expression, '%' represents zero, one, or more digits or characters, and '_' represents a single digit or character. It is case insensitive.

If value is undefined or null, the predicate configured by this API call is invalid.

Return value

Type Description
DataSharePredicates DataSharePredicates object created.

Example

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

[h2]between23+

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 field is undefined or null, the predicate configured by this API call is invalid.

When field is the string 'null' or 'undefined', the key-value database and relational database APIs may return unexpected matching results or throw an exception when using this predicate.
low ValueType Yes

Indicate matching with the predicate as the minimum value.

When low is a number, sort by numeric value to specify the matching range.

When low is a string, sort in lexicographical order to specify the matching range.

When low is a boolean, sort by numeric value to specify the matching range.
high ValueType Yes

Indicate matching with the predicate as the maximum value.

When high is a number, sort by numeric value to specify the matching range.

When high is a string, sort in lexicographical order to specify the matching range.

When high is a boolean, sort by numeric value to specify the matching range.

Return value

Type Description
DataSharePredicates DataSharePredicates object created.

Example

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

[h2]notBetween23+

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 field is undefined or null, the predicate configured by this API call is invalid.

When field is the string 'null' or 'undefined', the key-value database and relational database APIs may return unexpected matching results or throw an exception when using this predicate.
low ValueType Yes

Indicate matching with the predicate as the minimum value.

When low is a number, sort by numeric value to specify the matching range.

When low is a string, sort in lexicographical order to specify the matching range.

When low is a boolean, sort by numeric value to specify the matching range.
high ValueType Yes

Indicate matching with the predicate as the maximum value.

When high is a number, sort by numeric value to specify the matching range.

When high is a string, sort in lexicographical order to specify the matching range.

When high is a boolean, sort by numeric value to specify the matching range.

Return value

Type Description
DataSharePredicates DataSharePredicates object created.

Example

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

[h2]greaterThan23+

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 field is undefined or null, the predicate configured by this API call is invalid.

When field is the string 'null' or 'undefined', the key-value database and relational database APIs may return unexpected matching results or throw an exception when using this predicate.
value ValueType Yes

Value to match with the predicate.

If value is undefined or null, the predicate configured by this interface call is invalid.

Return value

Type Description
DataSharePredicates DataSharePredicates object created.

Example

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

[h2]lessThan23+

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 with the predicate.

If value is undefined or null, the predicate configured by this interface call is invalid.

Return value

Type Description
DataSharePredicates DataSharePredicates object created.

Example

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

[h2]greaterThanOrEqualTo23+

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 field is undefined or null, the predicate configured by this API call is invalid.

When field is the string 'null' or 'undefined', the key-value database and relational database APIs may return unexpected matching results or throw an exception when using this predicate.
value ValueType Yes

Value to match with the predicate.

If value is undefined or null, the predicate configured by this interface call is invalid.

Return value

Type Description
DataSharePredicates DataSharePredicates object created.

Example

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

[h2]lessThanOrEqualTo23+

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 field is undefined or null, the predicate configured by this API call is invalid.

When field is the string 'null' or 'undefined', the key-value database and relational database APIs may return unexpected matching results or throw an exception when using this predicate.
value ValueType Yes

Value to match with the predicate.

If value is undefined or null, the predicate configured by this interface call is invalid.

Return value

Type Description
DataSharePredicates DataSharePredicates object created.

Example

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

[h2]notIn23+

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 field is undefined or null, the predicate configured by this API call is invalid.

When field is the string 'null' or 'undefined', the key-value database and relational database APIs may return unexpected matching results or throw an exception when using this predicate.
value Array<ValueType> Yes

Value to match, specified as an array of the ValueType type.

If value is undefined or null, the predicate configured by this API call is invalid.

Return value

Type Description
DataSharePredicates DataSharePredicates object created.

Example

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