目录

cloudDatabase (Cloud DB Module)

This module provides capabilities such as writing, querying, and deleting data using Cloud DB.

Since: 5.0.0(12)

Modules to Import

import { cloudDatabase } from '@kit.CloudFoundationKit';

zone

zone(zone: string): DatabaseZone

Initializes a Cloud DB instance using a zone name.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

System capability: SystemCapability.DeviceCloudGateway.CloudFoundation

Since: 5.0.0(12)

Parameters:

Parameter Type Mandatory Description
zone string Yes Zone name.

Returns:

Type Description
DatabaseZone Cloud DB instance that processes data.

Example:

import { cloudDatabase } from '@kit.CloudFoundationKit';

let databaseZone = cloudDatabase.zone('storageArea');

DatabaseZone

Cloud DB instance that processes data.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

System capability: SystemCapability.DeviceCloudGateway.CloudFoundation

Since: 5.0.0(12)

[h2]query

query<T extends DatabaseObject>(condition: DatabaseQuery<T>): Promise<T[]>

Queries data based on specified conditions. This API uses a promise to return the result.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

Required permission: ohos.permission.INTERNET

System capability: SystemCapability.DeviceCloudGateway.CloudFoundation

Since: 5.0.0(12)

Parameters:

Parameter Type Mandatory Description
condition DatabaseQuery<T> Yes Query conditions.

Returns:

Type Description
Promise<T[]> Promise used to return the query result.

Error codes:

For details about the error codes, please refer to Universal Error Codes and ArkTS API Error Codes.

Error Code Error Message
201 No Internet permission.
401 Parameter error.
1008230001 Network connection error.
1008230002 Schema config error.
1008230003 Natural object error.
1008230009 Client internal error.
1008231001 Server error.

Example:

// Create the BookInfo.ets file in the code project.
import { cloudDatabase } from '@kit.CloudFoundationKit';

// Create a BookInfo class that extends cloudDatabase.DatabaseObject.
class BookInfo extends cloudDatabase.DatabaseObject{
  public naturalbase_ClassName(): string {
    return 'BookInfo';
  }
  public keyString: string | undefined;
  public keyBoolean: boolean | undefined;
  public keyByte: number | undefined;
  public keyShort: number | undefined;
  public keyInteger: number | undefined;
  public keyLong: number | undefined;
  public keyFloat: number | undefined;
  public keyDouble: number | undefined;
  public keyText: string | undefined;
  public keyDate: Date | undefined;
  public keyByteArray: Uint8Array | undefined;
}

export { BookInfo };
import { cloudDatabase } from '@kit.CloudFoundationKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BookInfo } from 'xx/BookInfo'; // Import the BookInfo.ets file to the Cloud DB code project. xx indicates the file path.

async () => {
  // Create a BookInfo class that extends cloudDatabase.DatabaseObject. Its implementation is the same as the sample code of the query API which returns the result through a promise.
  try {
    let databaseZone = cloudDatabase.zone('storageArea');
    let condition = new cloudDatabase.DatabaseQuery(BookInfo);
    condition.equalTo('keyString', 'string_123');
    let bookInfoArray = await databaseZone.query(condition);
    hilog.info(0x0000, 'testTag', `Succeeded in querying data, result: ${JSON.stringify(bookInfoArray)}`);
  } catch (err) {
    hilog.error(0x0000, 'testTag', `Failed to query data, code: ${err.code}, message: ${err.message}`);
  }
}

[h2]query

query<T extends DatabaseObject>(condition: DatabaseQuery<T>, callback: AsyncCallback<T[]>): void

Queries data based on specified conditions. This API uses an asynchronous callback to return the result.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

Required permission: ohos.permission.INTERNET

System capability: SystemCapability.DeviceCloudGateway.CloudFoundation

Since: 5.0.0(12)

Parameters:

Parameter Type Mandatory Description
condition DatabaseQuery<T> Yes Query conditions.
callback AsyncCallback<T[]> Yes Callback. If data is queried successfully, err is undefined and data is the result array obtained; otherwise, err is an error object.

Error codes:

For details about the error codes, please refer to Universal Error Codes and ArkTS API Error Codes.

Error Code Error Message
201 No Internet permission.
401 Parameter error.
1008230001 Network connection error.
1008230002 Schema config error.
1008230003 Natural object error.
1008230009 Client internal error.
1008231001 Server error.

Example:

import { cloudDatabase } from '@kit.CloudFoundationKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BookInfo } from 'xx/BookInfo'; // xx is the path to the BookInfo file.

// Create a BookInfo class that extends cloudDatabase.DatabaseObject. Its implementation is the same as the sample code of the query API which returns the result through a promise.
let databaseZone = cloudDatabase.zone('storageArea');
let condition = new cloudDatabase.DatabaseQuery(BookInfo);
condition.equalTo('keyString', 'string_123');
databaseZone.query(condition, (err: BusinessError, bookInfoArray) => {
  if (err) {
    hilog.error(0x0000, 'testTag', `Failed to query data, code: ${err.code}, message: ${err.message}`);
  } else {
    hilog.info(0x0000, 'testTag', `Succeeded in querying data, result: ${JSON.stringify(bookInfoArray)}`);
  }
});

[h2]calculateQuery

calculateQuery<T extends DatabaseObject>(condition: DatabaseQuery<T>, fieldName: string, calculate: QueryCalculate): Promise<number>

Queries data that meets the query conditions from the database and performs an arithmetic calculation on the specified field. This API uses a promise to return the result.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

Required permission: ohos.permission.INTERNET

System capability: SystemCapability.DeviceCloudGateway.CloudFoundation

Since: 5.0.0(12)

Parameters:

Parameter Type Mandatory Description
condition DatabaseQuery<T> Yes Query conditions.
fieldName string Yes Name of the field on which the arithmetic calculation is performed in the query object.
calculate QueryCalculate Yes Calculation type.

Returns:

Type Description
Promise<number> Promise used to return the calculation result of the specified field.

Error codes:

For details about the error codes, please refer to Universal Error Codes and ArkTS API Error Codes.

Error Code Error Message
201 No Internet permission.
401 Parameter error.
1008230001 Network connection error.
1008230002 Schema config error.
1008230003 Natural object error.
1008230009 Client internal error.
1008231001 Server error.

Example:

import { cloudDatabase } from '@kit.CloudFoundationKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BookInfo } from 'xx/BookInfo'; // xx is the path to the BookInfo file.

async () => {
  // Create a BookInfo class that extends cloudDatabase.DatabaseObject. Its implementation is the same as the sample code of the query API which returns the result through a promise.
  try {
    let databaseZone = cloudDatabase.zone('storageArea');
    let condition = new cloudDatabase.DatabaseQuery(BookInfo);
    condition.lessThan('keyInteger', 100);
    let count = await databaseZone.calculateQuery(condition, 'keyInteger', cloudDatabase.QueryCalculate.AVERAGE);
    hilog.info(0x0000, 'testTag', `Succeeded in calculating queried data, result: ${count}`);
  } catch (err) {
    hilog.error(0x0000, 'testTag', `Failed to calculate queried data, code: ${err.code}, message: ${err.message}`);
  }
}

[h2]calculateQuery

calculateQuery<T extends DatabaseObject>(condition: DatabaseQuery<T>, fieldName: string, calculate: QueryCalculate, callback: AsyncCallback<number>): void

Queries data that meets the query conditions from the database and performs an arithmetic calculation on the specified field. This API uses an asynchronous callback to return the result.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

Required permission: ohos.permission.INTERNET

System capability: SystemCapability.DeviceCloudGateway.CloudFoundation

Since: 5.0.0(12)

Parameters:

Parameter Type Mandatory Description
condition DatabaseQuery<T> Yes Query conditions.
fieldName string Yes Name of the field on which the arithmetic calculation is performed in the query object.
calculate QueryCalculate Yes Calculation type.
callback AsyncCallback<number> Yes Callback. If the arithmetic calculation is successful, err is undefined and data is the calculation result; otherwise, err is an error object.

Error codes:

For details about the error codes, please refer to Universal Error Codes and ArkTS API Error Codes.

Error Code Error Message
201 No Internet permission.
401 Parameter error.
1008230001 Network connection error.
1008230002 Schema config error.
1008230003 Natural object error.
1008230009 Client internal error.
1008231001 Server error.

Example:

import { cloudDatabase } from '@kit.CloudFoundationKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BookInfo } from 'xx/BookInfo'; // xx is the path to the BookInfo file.

// Create a BookInfo class that extends cloudDatabase.DatabaseObject. Its implementation is the same as the sample code of the query API which returns the result through a promise.
let databaseZone = cloudDatabase.zone('storageArea');
let condition = new cloudDatabase.DatabaseQuery(BookInfo);
condition.lessThan('keyInteger', 100);
databaseZone.calculateQuery(condition, 'keyInteger', cloudDatabase.QueryCalculate.AVERAGE,
  (err: BusinessError, num) => {
    if (err) {
      hilog.error(0x0000, 'testTag', `Failed to calculate queried data, code: ${err.code}, message: ${err.message}`);
    } else {
      hilog.info(0x0000, 'testTag', `Succeeded in calculating queried data, result: ${num}`);
    }
  });

[h2]upsert

upsert<T extends DatabaseObject>(objectList: T[] | T): Promise<number>

Updates data in the database. This API uses a promise to return the result.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

Required permission: ohos.permission.INTERNET

System capability: SystemCapability.DeviceCloudGateway.CloudFoundation

Since: 5.0.0(12)

Parameters:

Parameter Type Mandatory Description
objectList T[] | T Yes One or more objects.

Returns:

Type Description
Promise<number> Promise used to return the number of data records that are successfully updated.

Error codes:

For details about the error codes, please refer to Universal Error Codes and ArkTS API Error Codes.

Error Code Error Message
201 No Internet permission.
401 Parameter error.
1008230001 Network connection error.
1008230002 Schema config error.
1008230003 Natural object error.
1008230009 Client internal error.
1008231001 Server error.

Example:

import { cloudDatabase } from '@kit.CloudFoundationKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BookInfo } from 'xx/BookInfo'; // xx is the path to the BookInfo file.

async () => {
  // Create a BookInfo class that extends cloudDatabase.DatabaseObject. Its implementation is the same as the sample code of the query API which returns the result through a promise.
  try {
    let databaseZone = cloudDatabase.zone('storageArea');
    let book = new BookInfo();
    book.keyString = 'string_12';
    book.keyInteger = 90;
    let book1 = new BookInfo();
    book1.keyString = 'string_1234';
    book1.keyInteger = 101;
    let num = await databaseZone.upsert([book, book1]);
    hilog.info(0x0000, 'testTag', `Succeeded in upserting data, result: ${num}`);
  } catch (err) {
    hilog.error(0x0000, 'testTag', `Failed to upsert data, code: ${err.code}, message: ${err.message}`);
  }
}

[h2]upsert

upsert<T extends DatabaseObject>(objectList: T[] | T, callback: AsyncCallback<number>): void

Updates data in the database. This API uses an asynchronous callback to return the result.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

Required permission: ohos.permission.INTERNET

System capability: SystemCapability.DeviceCloudGateway.CloudFoundation

Since: 5.0.0(12)

Parameters:

Parameter Type Mandatory Description
objectList T[] | T Yes One or more objects.
callback AsyncCallback<number> Yes Callback. If the data is updated successfully, err is undefined and data is the number of records that are successfully updated; otherwise, err is an error object.

Error codes:

For details about the error codes, please refer to Universal Error Codes and ArkTS API Error Codes.

Error Code Error Message
201 No Internet permission.
401 Parameter error.
1008230001 Network connection error.
1008230002 Schema config error.
1008230003 Natural object error.
1008230009 Client internal error.
1008231001 Server error.

Example:

import { cloudDatabase } from '@kit.CloudFoundationKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BookInfo } from 'xx/BookInfo'; // xx is the path to the BookInfo file.

// Create a BookInfo class that extends cloudDatabase.DatabaseObject. Its implementation is the same as the sample code of the query API which returns the result through a promise.
let databaseZone = cloudDatabase.zone('storageArea');
let book = new BookInfo();
book.keyString = 'string_12';
book.keyInteger = 90;
let book1 = new BookInfo();
book1.keyString = 'string_1234';
book1.keyInteger = 101;
databaseZone.upsert([book, book1], (err: BusinessError, num) => {
  if (err) {
    hilog.error(0x0000, 'testTag', `Failed to upsert data, code: ${err.code}, message: ${err.message}`);
  } else {
    hilog.info(0x0000, 'testTag', `Succeeded in upserting data, result: ${num}`);
  }
});

[h2]delete

delete<T extends DatabaseObject>(objectList: T[] | T): Promise<number>

Deletes one or more data records from the database. This API uses a promise to return the result.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

Required permission: ohos.permission.INTERNET

System capability: SystemCapability.DeviceCloudGateway.CloudFoundation

Since: 5.0.0(12)

Parameters:

Parameter Type Mandatory Description
objectList T[] | T Yes One or more objects.

Returns:

Type Description
Promise<number> Promise used to return the number of data records that are successfully deleted.

Error codes:

For details about the error codes, please refer to Universal Error Codes and ArkTS API Error Codes.

Error Code Error Message
201 No Internet permission.
401 Parameter error.
1008230001 Network connection error.
1008230002 Schema config error.
1008230003 Natural object error.
1008230009 Client internal error.
1008231001 Server error.

Example:

import { cloudDatabase } from '@kit.CloudFoundationKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BookInfo } from 'xx/BookInfo'; // xx is the path to the BookInfo file.

async () => {
  // Create a BookInfo class that extends cloudDatabase.DatabaseObject. Its implementation is the same as the sample code of the query API which returns the result through a promise.
  try {
    let databaseZone = cloudDatabase.zone('storageArea');
    let condition = new cloudDatabase.DatabaseQuery(BookInfo);
    condition.lessThan('keyInteger', 100);
    let bookArray = await databaseZone.query(condition);
    let deleteNum = await databaseZone.delete(bookArray);
    hilog.info(0x0000, 'testTag', `Succeeded in deleting a book, result: ${deleteNum}`);
  } catch (err) {
  hilog.error(0x0000, 'testTag', `Failed to delete a book, code: ${err.code}, message: ${err.message}`);
  }
}

[h2]delete

delete<T extends DatabaseObject>(objectList: T[] | T, callback: AsyncCallback<number>): void

Deletes one or more data records from the database. This API uses an asynchronous callback to return the result.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

Required permission: ohos.permission.INTERNET

System capability: SystemCapability.DeviceCloudGateway.CloudFoundation

Since: 5.0.0(12)

Parameters:

Parameter Type Mandatory Description
objectList T[] | T Yes One or more objects.
callback AsyncCallback<number> Yes Callback. If the data is deleted successfully, err is undefined and data is the number of records that are successfully deleted; otherwise, err is an error object.

Error codes:

For details about the error codes, please refer to Universal Error Codes and ArkTS API Error Codes.

Error Code Error Message
201 No Internet permission.
401 Parameter error.
1008230001 Network connection error.
1008230002 Schema config error.
1008230003 Natural object error.
1008230009 Client internal error.
1008231001 Server error.

Example:

import { cloudDatabase } from '@kit.CloudFoundationKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BookInfo } from 'xx/BookInfo'; // xx is the path to the BookInfo file.

async () => {
  // Create a BookInfo class that extends cloudDatabase.DatabaseObject. Its implementation is the same as the sample code of the query API which returns the result through a promise.
  let databaseZone = cloudDatabase.zone('storageArea');
  let condition = new cloudDatabase.DatabaseQuery(BookInfo);
  condition.lessThan('keyInteger', 100);
  try {
    let bookArray = await databaseZone.query(condition);
    databaseZone.delete(bookArray, (err: BusinessError, num) => {
      if (err) {
        hilog.error(0x0000, 'testTag', `Failed to delete a book, code: ${err.code}, message: ${err.message}`);
      } else {
        hilog.info(0x0000, 'testTag', `Succeeded in deleting a book, result: ${num}`);
      }
    });
  } catch (err) {
    hilog.error(0x0000, 'testTag', `Failed to query books, code: ${err.code}, message: ${err.message}`);
  }
}

DatabaseObject

Base class for a database data type, which is extended during table structure generation on the cloud.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

System capability: SystemCapability.DeviceCloudGateway.CloudFoundation

Since: 5.0.0(12)

[h2]naturalbase_ClassName

naturalbase_ClassName(): string

Base class name for a data type.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

System capability: SystemCapability.DeviceCloudGateway.CloudFoundation

Since: 5.0.0(12)

Returns:

Type Description
string Base class name for a data type, which must be the same as the name of the created object type.

Example:

import { cloudDatabase } from '@kit.CloudFoundationKit';

// Create a BookInfo class that extends cloudDatabase.DatabaseObject. Its implementation is the same as the sample code of the query API which returns the result through a promise.
class BookInfo extends cloudDatabase.DatabaseObject{
  public naturalbase_ClassName(): string {
    return 'BookInfo';
  }
}

export { BookInfo };

FieldType

type FieldType = string | number | boolean | Uint8Array | Date

Data types supported by Cloud DB. The value types are the union or intersection of the types listed in the table below.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

System capability: SystemCapability.DeviceCloudGateway.CloudFoundation

Since: 5.0.0(12)

Type Description
string The value can be any string.
number The value can be any number.
boolean The value is of the Boolean type and can be set to true or false.
Uint8Array The value is an array of 8-bit unsigned integers and can be set to any value.
Date The value is a date, in UTC format. It must be in the fixed format of YYYY-MM-DD HH:MM:SS SSS.

QueryCalculate

Enumerated arithmetic calculation types.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

System capability: SystemCapability.DeviceCloudGateway.CloudFoundation

Since: 5.0.0(12)

Name Value Description
AVERAGE 0 Calculate the average value.
SUM 1 Calculate the sum.
MAXIMUM 2 Calculate the maximum value.
MINIMUM 3 Calculate the minimum value.
COUNT 4 Calculate the total number of records.

DatabaseQuery<T extends DatabaseObject>

Provides various predicate query methods to construct query conditions. You can create your own DatabaseQuery object using these predicate query methods.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

System capability: SystemCapability.DeviceCloudGateway.CloudFoundation

Since: 5.0.0(12)

[h2]constructor

constructor(entityClass: new () => T)

Constructs the query information for the specified entity class.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

System capability: SystemCapability.DeviceCloudGateway.CloudFoundation

Since: 5.0.0(12)

Parameters:

Parameter Type Mandatory Description
entityClass new () => T Yes Entity class of a data object.

Example:

import { cloudDatabase } from '@kit.CloudFoundationKit';
import { BookInfo } from 'xx/BookInfo'; // xx is the path to the BookInfo file.

let condition = new cloudDatabase.DatabaseQuery(BookInfo);

[h2]equalTo

equalTo(fieldName: string, value: FieldType): DatabaseQuery<T>

Adds a query condition where the value of a field in an entity class is equal to a specified value.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

System capability: SystemCapability.DeviceCloudGateway.CloudFoundation

Since: 5.0.0(12)

Parameters:

Parameter Type Mandatory Description
fieldName string Yes Name of a field in an entity class.
value FieldType Yes Value of a data type supported by Cloud DB.

Returns:

Type Description
DatabaseQuery<T> DatabaseQuery object.

Example:

import { cloudDatabase } from '@kit.CloudFoundationKit';
import { BookInfo } from 'xx/BookInfo'; // xx is the path to the BookInfo file.
import { hilog } from '@kit.PerformanceAnalysisKit';

async () => {
  // Create a BookInfo class that extends cloudDatabase.DatabaseObject. Its implementation is the same as the sample code of the query API which returns the result through a promise.
  let databaseZone = cloudDatabase.zone('storageArea');
  let condition = new cloudDatabase.DatabaseQuery(BookInfo);
  condition.equalTo('keyString', 'string_123');
  try {
    let bookInfoArray = await databaseZone.query(condition);
    hilog.info(0x0000, 'testTag', `Succeeded in querying data, result: ${JSON.stringify(bookInfoArray)}`);
  } catch (err) {
    hilog.error(0x0000, 'testTag', `Failed to query books, code: ${err.code}, message: ${err.message}`);
  }
}

[h2]notEqualTo

notEqualTo(fieldName: string, value: FieldType): DatabaseQuery<T>

Adds a query condition where the value of a field in an entity class is not equal to a specified value.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

System capability: SystemCapability.DeviceCloudGateway.CloudFoundation

Since: 5.0.0(12)

Parameters:

Parameter Type Mandatory Description
fieldName string Yes Name of a field in an entity class.
value FieldType Yes Value of a data type supported by Cloud DB.

Returns:

Type Description
DatabaseQuery<T> DatabaseQuery object.

Example:

import { cloudDatabase } from '@kit.CloudFoundationKit';
import { BookInfo } from 'xx/BookInfo'; // xx is the path to the BookInfo file.
import { hilog } from '@kit.PerformanceAnalysisKit';


async () => {
  // Create a BookInfo class that extends cloudDatabase.DatabaseObject. Its implementation is the same as the sample code of the query API which returns the result through a promise.
  let databaseZone = cloudDatabase.zone('storageArea');
  let condition = new cloudDatabase.DatabaseQuery(BookInfo);
  condition.notEqualTo('keyString', 'string_123');
  try {
    let bookInfoArray = await databaseZone.query(condition);
    hilog.info(0x0000, 'testTag', `Succeeded in querying data, result: ${JSON.stringify(bookInfoArray)}`);
  } catch (err) {
    hilog.error(0x0000, 'testTag', `Failed to query books, code: ${err.code}, message: ${err.message}`);
  }
}

[h2]beginsWith

beginsWith(fieldName: string, value: FieldType): DatabaseQuery<T>

Adds a query condition where the value of a string-type field in an entity class starts with a specified substring.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

System capability: SystemCapability.DeviceCloudGateway.CloudFoundation

Since: 5.0.0(12)

Parameters:

Parameter Type Mandatory Description
fieldName string Yes Name of a field in an entity class.
value FieldType Yes Value of a data type supported by Cloud DB.

Returns:

Type Description
DatabaseQuery<T> DatabaseQuery object.

Example:

import { cloudDatabase } from '@kit.CloudFoundationKit';
import { BookInfo } from 'xx/BookInfo'; // xx is the path to the BookInfo file.
import { hilog } from '@kit.PerformanceAnalysisKit';

async () => {
  // Create a BookInfo class that extends cloudDatabase.DatabaseObject. Its implementation is the same as the sample code of the query API which returns the result through a promise.
  let databaseZone = cloudDatabase.zone('storageArea');
  let condition = new cloudDatabase.DatabaseQuery(BookInfo);
  condition.beginsWith('keyString', 'key');
  try {
    let bookInfoArray = await databaseZone.query(condition);
    hilog.info(0x0000, 'testTag', `Succeeded in querying data, result: ${JSON.stringify(bookInfoArray)}`);
  } catch (err) {
    hilog.error(0x0000, 'testTag', `Failed to query books, code: ${err.code}, message: ${err.message}`);
  }
}

[h2]endsWith

endsWith(fieldName: string, value: FieldType): DatabaseQuery<T>

Adds a query condition where the value of a string-type field in an entity class ends with a specified substring.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

System capability: SystemCapability.DeviceCloudGateway.CloudFoundation

Since: 5.0.0(12)

Parameters:

Parameter Type Mandatory Description
fieldName string Yes Name of a field in an entity class.
value FieldType Yes Value of a data type supported by Cloud DB.

Returns:

Type Description
DatabaseQuery<T> DatabaseQuery object.

Example:

import { cloudDatabase } from '@kit.CloudFoundationKit';
import { BookInfo } from 'xx/BookInfo'; // xx is the path to the BookInfo file.
import { hilog } from '@kit.PerformanceAnalysisKit';

async () => {
  // Create a BookInfo class that extends cloudDatabase.DatabaseObject. Its implementation is the same as the sample code of the query API which returns the result through a promise.
  let databaseZone = cloudDatabase.zone('storageArea');
  let condition = new cloudDatabase.DatabaseQuery(BookInfo);
  condition.endsWith('keyString', 'string');
  try {
    let bookInfoArray = await databaseZone.query(condition);
    hilog.info(0x0000, 'testTag', `Succeeded in querying data, result: ${JSON.stringify(bookInfoArray)}`);
  } catch (err) {
    hilog.error(0x0000, 'testTag', `Failed to query books, code: ${err.code}, message: ${err.message}`);
  }
}

[h2]contains

contains(fieldName: string, value: FieldType): DatabaseQuery<T>

Adds a query condition where the value of a string-type field in an entity class contains the specified substring.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

System capability: SystemCapability.DeviceCloudGateway.CloudFoundation

Since: 5.0.0(12)

Parameters:

Parameter Type Mandatory Description
fieldName string Yes Name of a field in an entity class.
value FieldType Yes Value of a data type supported by Cloud DB.

Returns:

Type Description
DatabaseQuery<T> DatabaseQuery object.

Example:

import { cloudDatabase } from '@kit.CloudFoundationKit';
import { BookInfo } from 'xx/BookInfo'; // xx is the path to the BookInfo file.
import { hilog } from '@kit.PerformanceAnalysisKit';

async () => {
  // Create a BookInfo class that extends cloudDatabase.DatabaseObject. Its implementation is the same as the sample code of the query API which returns the result through a promise.
  let databaseZone = cloudDatabase.zone('storageArea');
  let condition = new cloudDatabase.DatabaseQuery(BookInfo);
  condition.contains('keyString', 'string');
  try {
    let bookInfoArray = await databaseZone.query(condition);
    hilog.info(0x0000, 'testTag', `Succeeded in querying data, result: ${JSON.stringify(bookInfoArray)}`);
  } catch (err) {
    hilog.error(0x0000, 'testTag', `Failed to query books, code: ${err.code}, message: ${err.message}`);
  }
}

[h2]greaterThan

greaterThan(fieldName: string, value: FieldType): DatabaseQuery<T>

Adds a query condition where the value of a field in an entity class is greater than a specified value.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

System capability: SystemCapability.DeviceCloudGateway.CloudFoundation

Since: 5.0.0(12)

Parameters:

Parameter Type Mandatory Description
fieldName string Yes Name of a field in an entity class.
value FieldType Yes Value of a data type supported by Cloud DB.

Returns:

Type Description
DatabaseQuery<T> DatabaseQuery object.

Example:

import { cloudDatabase } from '@kit.CloudFoundationKit';
import { BookInfo } from 'xx/BookInfo'; // xx is the path to the BookInfo file.
import { hilog } from '@kit.PerformanceAnalysisKit';

async () => {
  // Create a BookInfo class that extends cloudDatabase.DatabaseObject. Its implementation is the same as the sample code of the query API which returns the result through a promise.
  let databaseZone = cloudDatabase.zone('storageArea');
  let condition = new cloudDatabase.DatabaseQuery(BookInfo);
  condition.greaterThan('keyInteger', 100);
  try {
    let bookInfoArray = await databaseZone.query(condition);
    hilog.info(0x0000, 'testTag', `Succeeded in querying data, result: ${JSON.stringify(bookInfoArray)}`);
  } catch (err) {
    hilog.error(0x0000, 'testTag', `Failed to query books, code: ${err.code}, message: ${err.message}`);
  }
}

[h2]greaterThanOrEqualTo

greaterThanOrEqualTo(fieldName: string, value: FieldType): DatabaseQuery<T>

Adds a query condition where the value of a field in an entity class is greater than or equal to a specified value.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

System capability: SystemCapability.DeviceCloudGateway.CloudFoundation

Since: 5.0.0(12)

Parameters:

Parameter Type Mandatory Description
fieldName string Yes Name of a field in an entity class.
value FieldType Yes Value of a data type supported by Cloud DB.

Returns:

Type Description
DatabaseQuery<T> DatabaseQuery object.

Example:

import { cloudDatabase } from '@kit.CloudFoundationKit';
import { BookInfo } from 'xx/BookInfo'; // xx is the path to the BookInfo file.
import { hilog } from '@kit.PerformanceAnalysisKit';

async () => {
  // Create a BookInfo class that extends cloudDatabase.DatabaseObject. Its implementation is the same as the sample code of the query API which returns the result through a promise.
  let databaseZone = cloudDatabase.zone('storageArea');
  let condition = new cloudDatabase.DatabaseQuery(BookInfo);
  condition.greaterThanOrEqualTo('keyInteger', 100);
  try {
    let bookInfoArray = await databaseZone.query(condition);
    hilog.info(0x0000, 'testTag', `Succeeded in querying data, result: ${JSON.stringify(bookInfoArray)}`);
  } catch (err) {
    hilog.error(0x0000, 'testTag', `Failed to query books, code: ${err.code}, message: ${err.message}`);
  }
}

[h2]lessThan

lessThan(fieldName: string, value: FieldType): DatabaseQuery<T>

Adds a query condition where the value of a field in an entity class is less than a specified value.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

System capability: SystemCapability.DeviceCloudGateway.CloudFoundation

Since: 5.0.0(12)

Parameters:

Parameter Type Mandatory Description
fieldName string Yes Name of a field in an entity class.
value FieldType Yes Value of a data type supported by Cloud DB.

Returns:

Type Description
DatabaseQuery<T> DatabaseQuery object.

Example:

import { cloudDatabase } from '@kit.CloudFoundationKit';
import { BookInfo } from 'xx/BookInfo'; // xx is the path to the BookInfo file.
import { hilog } from '@kit.PerformanceAnalysisKit';

async () => {
  // Create a BookInfo class that extends cloudDatabase.DatabaseObject. Its implementation is the same as the sample code of the query API which returns the result through a promise.
  let databaseZone = cloudDatabase.zone('storageArea');
  let condition = new cloudDatabase.DatabaseQuery(BookInfo);
  condition.lessThan('keyInteger', 100);
  try {
    let bookInfoArray = await databaseZone.query(condition);
    hilog.info(0x0000, 'testTag', `Succeeded in querying data, result: ${JSON.stringify(bookInfoArray)}`);
  } catch (err) {
    hilog.error(0x0000, 'testTag', `Failed to query books, code: ${err.code}, message: ${err.message}`);
  }
}

[h2]lessThanOrEqualTo

lessThanOrEqualTo(fieldName: string, value: FieldType): DatabaseQuery<T>

Adds a query condition where the value of a field in an entity class is less than or equal to a specified value.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

System capability: SystemCapability.DeviceCloudGateway.CloudFoundation

Since: 5.0.0(12)

Parameters:

Parameter Type Mandatory Description
fieldName string Yes Name of a field in an entity class.
value FieldType Yes Value of a data type supported by Cloud DB.

Returns:

Type Description
DatabaseQuery<T> DatabaseQuery object.

Example:

import { cloudDatabase } from '@kit.CloudFoundationKit';
import { BookInfo } from 'xx/BookInfo'; // xx is the path to the BookInfo file.
import { hilog } from '@kit.PerformanceAnalysisKit';

async () => {
  // Create a BookInfo class that extends cloudDatabase.DatabaseObject. Its implementation is the same as the sample code of the query API which returns the result through a promise.
  let databaseZone = cloudDatabase.zone('storageArea');
  let condition = new cloudDatabase.DatabaseQuery(BookInfo);
  condition.lessThanOrEqualTo('keyInteger', 100);
  try {
    let bookInfoArray = await databaseZone.query(condition);
    hilog.info(0x0000, 'testTag', `Succeeded in querying data, result: ${JSON.stringify(bookInfoArray)}`);
  } catch (err) {
    hilog.error(0x0000, 'testTag', `Failed to query books, code: ${err.code}, message: ${err.message}`);
  }
}

[h2]in

in(fieldName: string, values: FieldType[]): DatabaseQuery<T>

Adds a query condition where the value of a field in an entity class is contained in a specified array.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

System capability: SystemCapability.DeviceCloudGateway.CloudFoundation

Since: 5.0.0(12)

Parameters:

Parameter Type Mandatory Description
fieldName string Yes Name of a field in an entity class.
values FieldType[] Yes Array of values whose types are supported by Cloud DB.

Returns:

Type Description
DatabaseQuery<T> DatabaseQuery object.

Example:

import { cloudDatabase } from '@kit.CloudFoundationKit';
import { BookInfo } from 'xx/BookInfo'; // xx is the path to the BookInfo file.
import { hilog } from '@kit.PerformanceAnalysisKit';

async () => {
  // Create a BookInfo class that extends cloudDatabase.DatabaseObject. Its implementation is the same as the sample code of the query API which returns the result through a promise.
  let databaseZone = cloudDatabase.zone('storageArea');
  let condition = new cloudDatabase.DatabaseQuery(BookInfo);
  condition.in('keyInteger', [100, 200]);
  try {
    let bookInfoArray = await databaseZone.query(condition);
    hilog.info(0x0000, 'testTag', `Succeeded in querying data, result: ${JSON.stringify(bookInfoArray)}`);
  } catch (err) {
    hilog.error(0x0000, 'testTag', `Failed to query books, code: ${err.code}, message: ${err.message}`);
  }
}

[h2]isNull

isNull(fieldName: string): DatabaseQuery<T>

Adds a query condition where a field in an entity class is null.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

System capability: SystemCapability.DeviceCloudGateway.CloudFoundation

Since: 5.0.0(12)

Parameters:

Parameter Type Mandatory Description
fieldName string Yes Name of a field in an entity class.

Returns:

Type Description
DatabaseQuery<T> DatabaseQuery object.

Example:

import { cloudDatabase } from '@kit.CloudFoundationKit';
import { BookInfo } from 'xx/BookInfo'; // xx is the path to the BookInfo file.
import { hilog } from '@kit.PerformanceAnalysisKit';

async () => {
  // Create a BookInfo class that extends cloudDatabase.DatabaseObject. Its implementation is the same as the sample code of the query API which returns the result through a promise.
  let databaseZone = cloudDatabase.zone('storageArea');
  let condition = new cloudDatabase.DatabaseQuery(BookInfo);
  condition.isNull('keyDate');
  try {
    let bookInfoArray = await databaseZone.query(condition);
    hilog.info(0x0000, 'testTag', `Succeeded in querying data, result: ${JSON.stringify(bookInfoArray)}`);
  } catch (err) {
    hilog.error(0x0000, 'testTag', `Failed to query books, code: ${err.code}, message: ${err.message}`);
  }
}

[h2]isNotNull

isNotNull(fieldName: string): DatabaseQuery<T>

Adds a query condition where a field in an entity class is not null.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

System capability: SystemCapability.DeviceCloudGateway.CloudFoundation

Since: 5.0.0(12)

Parameters:

Parameter Type Mandatory Description
fieldName string Yes Name of a field in an entity class.

Returns:

Type Description
DatabaseQuery<T> DatabaseQuery object.

Example:

import { cloudDatabase } from '@kit.CloudFoundationKit';
import { BookInfo } from 'xx/BookInfo'; // xx is the path to the BookInfo file.
import { hilog } from '@kit.PerformanceAnalysisKit';

async () => {
  // Create a BookInfo class that extends cloudDatabase.DatabaseObject. Its implementation is the same as the sample code of the query API which returns the result through a promise.
  let databaseZone = cloudDatabase.zone('storageArea');
  let condition = new cloudDatabase.DatabaseQuery(BookInfo);
  condition.isNotNull('keyDate');
  try {
    let bookInfoArray = await databaseZone.query(condition);
    hilog.info(0x0000, 'testTag', `Succeeded in querying data, result: ${JSON.stringify(bookInfoArray)}`);
  } catch (err) {
    hilog.error(0x0000, 'testTag', `Failed to query books, code: ${err.code}, message: ${err.message}`);
  }
}

[h2]orderByAsc

orderByAsc(fieldName: string): DatabaseQuery<T>

Sorts query results by the specified field in ascending order.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

System capability: SystemCapability.DeviceCloudGateway.CloudFoundation

Since: 5.0.0(12)

Parameters:

Parameter Type Mandatory Description
fieldName string Yes Name of a field in an entity class.

Returns:

Type Description
DatabaseQuery<T> DatabaseQuery object.

Example:

import { cloudDatabase } from '@kit.CloudFoundationKit';
import { BookInfo } from 'xx/BookInfo'; // xx is the path to the BookInfo file.
import { hilog } from '@kit.PerformanceAnalysisKit';

async () => {
  // Create a BookInfo class that extends cloudDatabase.DatabaseObject. Its implementation is the same as the sample code of the query API which returns the result through a promise.
  let databaseZone = cloudDatabase.zone('storageArea');
  let condition = new cloudDatabase.DatabaseQuery(BookInfo);
  condition.orderByAsc('keyInteger');
  try {
    let bookInfoArray = await databaseZone.query(condition);
    hilog.info(0x0000, 'testTag', `Succeeded in querying data, result: ${JSON.stringify(bookInfoArray)}`);
  } catch (err) {
    hilog.error(0x0000, 'testTag', `Failed to query books, code: ${err.code}, message: ${err.message}`);
  }
}

[h2]orderByDesc

orderByDesc(fieldName: string): DatabaseQuery<T>

Sorts query results by the specified field in descending order.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

System capability: SystemCapability.DeviceCloudGateway.CloudFoundation

Since: 5.0.0(12)

Parameters:

Parameter Type Mandatory Description
fieldName string Yes Name of a field in an entity class.

Returns:

Type Description
DatabaseQuery<T> DatabaseQuery object.

Example:

import { cloudDatabase } from '@kit.CloudFoundationKit';
import { BookInfo } from 'xx/BookInfo'; // xx is the path to the BookInfo file.
import { hilog } from '@kit.PerformanceAnalysisKit';

async () => {
  // Create a BookInfo class that extends cloudDatabase.DatabaseObject. Its implementation is the same as the sample code of the query API which returns the result through a promise.
  let databaseZone = cloudDatabase.zone('storageArea');
  let condition = new cloudDatabase.DatabaseQuery(BookInfo);
  condition.orderByDesc('keyInteger');
  try {
    let bookInfoArray = await databaseZone.query(condition);
    hilog.info(0x0000, 'testTag', `Succeeded in querying data, result: ${JSON.stringify(bookInfoArray)}`);
  } catch (err) {
    hilog.error(0x0000, 'testTag', `Failed to query books, code: ${err.code}, message: ${err.message}`);
  }
}

[h2]orderByRandom

orderByRandom(): DatabaseQuery<T>

Sorts query results in random order.

You are advised to use orderByRandom() together with limit() to sort data. Otherwise, if the number of data records of the object type is too large, the query efficiency may be affected, causing query timeout or failure.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 6.0.1(21).

System capability: SystemCapability.DeviceCloudGateway.CloudFoundation

Since: 6.0.1(21)

Returns:

Type Description
DatabaseQuery<T> DatabaseQuery object.

Example:

import { cloudDatabase } from '@kit.CloudFoundationKit';
import { BookInfo } from 'xx/BookInfo'; // xx is the path to the BookInfo file.
import { hilog } from '@kit.PerformanceAnalysisKit';

async () => {
  // Create a BookInfo class that extends cloudDatabase.DatabaseObject. Its implementation is the same as the sample code of the query API which returns the result through a promise.
  let databaseZone = cloudDatabase.zone('storageArea');
  let condition = new cloudDatabase.DatabaseQuery(BookInfo);
  condition.orderByRandom().limit(10);
  try {
    let bookInfoArray = await databaseZone.query(condition);
    hilog.info(0x0000, 'testTag', `Succeeded in querying data, result: ${JSON.stringify(bookInfoArray)}`);
  } catch (err) {
    hilog.error(0x0000, 'testTag', `Failed to query books, code: ${err.code}, message: ${err.message}`);
  }
}

[h2]limit

limit(count: number, offset?: number): DatabaseQuery<T>

Specifies the number of data records in the returned query result set. If you do not set offset, the first count objects will be obtained by default.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

System capability: SystemCapability.DeviceCloudGateway.CloudFoundation

Since: 5.0.0(12)

Parameters:

Parameter Type Mandatory Description
count number Yes Number of data records that can be obtained.
offset number No Start position of data records.

Returns:

Type Description
DatabaseQuery<T> DatabaseQuery object.

Example:

import { cloudDatabase } from '@kit.CloudFoundationKit';
import { BookInfo } from 'xx/BookInfo'; // xx is the path to the BookInfo file.
import { hilog } from '@kit.PerformanceAnalysisKit';

async () => {
  // Create a BookInfo class that extends cloudDatabase.DatabaseObject. Its implementation is the same as the sample code of the query API which returns the result through a promise.
  let databaseZone = cloudDatabase.zone('storageArea');
  let condition = new cloudDatabase.DatabaseQuery(BookInfo);
  condition.lessThan('keyInteger', 100);
  condition.limit(4, 1);
  try {
    let bookInfoArray = await databaseZone.query(condition);
    hilog.info(0x0000, 'testTag', `Succeeded in querying data, result: ${JSON.stringify(bookInfoArray)}`);
  } catch (err) {
    hilog.error(0x0000, 'testTag', `Failed to query books, code: ${err.code}, message: ${err.message}`);
  }
}

[h2]beginGroup

beginGroup(): DatabaseQuery<T>

Adds a left parenthesis "(" to any query condition and pairs it with a right parenthesis ")" to group the conditions together within the same query.

  • beginGroup() and endGroup() must be used together and combined with other query conditions.

  • One or more of the following query conditions must exist between beginGroup() and endGroup():

    equalTo(), notEqualTo(), greaterThan(), greaterThanOrEqualTo(), lessThan(), lessThanOrEqualTo(), in(), beginsWith(), endsWith(), isNull(), isNotNull(), and contains()

  • beginGroup() cannot be directly used before and() or or(). That is, beginGroup().and(), beginGroup().and().endGroup(), beginGroup().or(), and beginGroup().or().endGroup() are not supported.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

System capability: SystemCapability.DeviceCloudGateway.CloudFoundation

Since: 5.0.0(12)

Returns:

Type Description
DatabaseQuery<T> DatabaseQuery object.

Example:

import { cloudDatabase } from '@kit.CloudFoundationKit';
import { BookInfo } from 'xx/BookInfo'; // xx is the path to the BookInfo file.
import { hilog } from '@kit.PerformanceAnalysisKit';

async () => {
  // Create a BookInfo class that extends cloudDatabase.DatabaseObject. Its implementation is the same as the sample code of the query API which returns the result through a promise.
  let databaseZone = cloudDatabase.zone('storageArea');
  let condition = new cloudDatabase.DatabaseQuery(BookInfo);
  condition.beginGroup().equalTo('keyString', 'string_123').endGroup();
  try {
    let bookInfoArray = await databaseZone.query(condition);
    hilog.info(0x0000, 'testTag', `Succeeded in querying data, result: ${JSON.stringify(bookInfoArray)}`);
  } catch (err) {
    hilog.error(0x0000, 'testTag', `Failed to query books, code: ${err.code}, message: ${err.message}`);
  }
}

[h2]endGroup

endGroup(): DatabaseQuery<T>

Adds a right parenthesis ")" to any query condition and pairs it with a left parenthesis "(" to group the conditions together within the same query.

  • beginGroup() and endGroup() must be used together and combined with other query conditions.

  • One or more of the following query conditions must exist between beginGroup() and endGroup():

    equalTo(), notEqualTo(), greaterThan(), greaterThanOrEqualTo(), lessThan(), lessThanOrEqualTo(), in(), beginsWith(), endsWith(), isNull(), isNotNull(), and contains()

  • endGroup() cannot be directly used before and() or or(). That is, and().endGroup(), beginGroup().and().endGroup(), or().endGroup(), and beginGroup().or().endGroup() are not supported.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

System capability: SystemCapability.DeviceCloudGateway.CloudFoundation

Since: 5.0.0(12)

Returns:

Type Description
DatabaseQuery<T> DatabaseQuery object.

Example:

import { cloudDatabase } from '@kit.CloudFoundationKit';
import { BookInfo } from 'xx/BookInfo'; // xx is the path to the BookInfo file.
import { hilog } from '@kit.PerformanceAnalysisKit';

async () => {
  // Create a BookInfo class that extends cloudDatabase.DatabaseObject. Its implementation is the same as the sample code of the query API which returns the result through a promise.
  let databaseZone = cloudDatabase.zone('storageArea');
  let condition = new cloudDatabase.DatabaseQuery(BookInfo);
  condition.beginGroup().equalTo('keyString', 'string_123').endGroup();
  try {
    let bookInfoArray = await databaseZone.query(condition);
    hilog.info(0x0000, 'testTag', `Succeeded in querying data, result: ${JSON.stringify(bookInfoArray)}`);
  } catch (err) {
    hilog.error(0x0000, 'testTag', `Failed to query books, code: ${err.code}, message: ${err.message}`);
  }
}

[h2]or

or(): DatabaseQuery<T>

Combines two conditions using the OR operator and returns the union of the two query results.

  • or() can be used only with other query conditions.

  • When it is used together with equalTo(), notEqualTo(), greaterThan(), greaterThanOrEqualTo(), lessThan(), lessThanOrEqualTo(), in(), beginsWith(), endsWith(), isNull(), isNotNull(), or contains(), the intersection of the two query results is returned.

  • When or() is used together with and(), or() cannot directly follow and(). That is, and().or() is not supported.

  • When it is used together with beginGroup() and endGroup():

    • Multi-layer nesting is supported, and beginGroup() and endGroup() must appear in pairs.
    • beginGroup() cannot be used before or(), and endGroup() cannot be used after or().
    • That is, beginGroup().or(), beginGroup().or().endGroup(), and or().endGroup() are not supported.
    • It cannot be used with orderByAsc(), orderByDesc(), or limit().

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

System capability: SystemCapability.DeviceCloudGateway.CloudFoundation

Since: 5.0.0(12)

Returns:

Type Description
DatabaseQuery<T> DatabaseQuery object.

Example:

import { cloudDatabase } from '@kit.CloudFoundationKit';
import { BookInfo } from 'xx/BookInfo'; // xx is the path to the BookInfo file.
import { hilog } from '@kit.PerformanceAnalysisKit';

async () => {
  // Create a BookInfo class that extends cloudDatabase.DatabaseObject. Its implementation is the same as the sample code of the query API which returns the result through a promise.
  let databaseZone = cloudDatabase.zone('storageArea');
  let condition = new cloudDatabase.DatabaseQuery(BookInfo);
  condition.equalTo('keyString', 'string_123').or().lessThan('keyInteger', 50);
  try {
    let bookInfoArray = await databaseZone.query(condition);
    hilog.info(0x0000, 'testTag', `Succeeded in querying data, result: ${JSON.stringify(bookInfoArray)}`);
  } catch (err) {
    hilog.error(0x0000, 'testTag', `Failed to query books, code: ${err.code}, message: ${err.message}`);
  }
}

[h2]and

and(): DatabaseQuery<T>

Combines two conditions using the AND operator and returns the intersection of the two query results.

  • and() can be used only with other query conditions.

  • When it is used together with equalTo(), notEqualTo(), greaterThan(), greaterThanOrEqualTo(), lessThan(), lessThanOrEqualTo(), in(), beginsWith(), endsWith(), isNull(), isNotNull(), or contains(), the intersection of the two query results is returned.

  • When and() is used together with or(), and() cannot be directly followed by or(). That is, and().or() is not supported.

  • When it is used together with beginGroup() and endGroup():

    • Multi-layer nesting is supported, and beginGroup() and endGroup() must appear in pairs.
    • beginGroup() cannot be used before and(), and endGroup() cannot be used after and().
    • That is, beginGroup().and(), beginGroup().and().endGroup(), and and().endGroup() are not supported.
    • It cannot be used with orderByAsc(), orderByDesc(), or limit().

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

System capability: SystemCapability.DeviceCloudGateway.CloudFoundation

Since: 5.0.0(12)

Returns:

Type Description
DatabaseQuery<T> DatabaseQuery object.

Example:

import { cloudDatabase } from '@kit.CloudFoundationKit';
import { BookInfo } from 'xx/BookInfo'; // xx is the path to the BookInfo file.
import { hilog } from '@kit.PerformanceAnalysisKit';

async () => {
  // Create a BookInfo class that extends cloudDatabase.DatabaseObject. Its implementation is the same as the sample code of the query API which returns the result through a promise.
  let databaseZone = cloudDatabase.zone('storageArea');
  let condition = new cloudDatabase.DatabaseQuery(BookInfo);
  condition.equalTo('keyString', 'string_123').and().lessThan('keyInteger', 50);
  try {
    let bookInfoArray = await databaseZone.query(condition);
    hilog.info(0x0000, 'testTag', `Succeeded in querying data, result: ${JSON.stringify(bookInfoArray)}`);
  } catch (err) {
    hilog.error(0x0000, 'testTag', `Failed to query books, code: ${err.code}, message: ${err.message}`);
  }
}