# cloudDatabase (云数据库模块)

> phone 5.0.0(12)+ | 2in1 6.1.0(23)+ | tablet 5.0.0(12)+ | tv 5.1.1(19)+ | wearable 5.1.0(18)+

本模块提供使用云数据库进行数据写入、查询、删除等操作的能力。

**起始版本：** 5.0.0(12)

## 导入模块

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

## zone

zone(zone: string): DatabaseZone

通过zone名称初始化云数据库实例。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本5.0.0(12)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.DeviceCloudGateway.CloudFoundation

**起始版本：** 5.0.0(12)

**参数：**

|参数名|类型|必填|说明|
|:---|:-----|:-|:-------|
|zone|string|是|zone的名称。|

**返回值：**

|类型|说明|
|:----------------------------|:-----------|
|[DatabaseZone](#databasezone)|云数据库处理数据的实例。|

**示例：**

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

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

## DatabaseZone

云数据库处理数据的实例。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本5.0.0(12)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.DeviceCloudGateway.CloudFoundation

**起始版本：** 5.0.0(12)

### query

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

通过条件查询数据。使用Promise异步回调。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本5.0.0(12)开始，该接口支持在元服务中使用。

**需要权限：** ohos.permission.INTERNET

**系统能力：** SystemCapability.DeviceCloudGateway.CloudFoundation

**起始版本：** 5.0.0(12)

**参数：**

|参数名|类型|必填|说明|
|:--------|:---------------------------------------------------------|:-|:---------|
|condition|[DatabaseQuery](#databasequeryt-extends-databaseobject)<T>|是|提供丰富的查询条件。|

**返回值：**

|类型|说明|
|:-----------|:----------------|
|Promise<T[]>|Promise对象，返回查询结果。|

**错误码：**

以下错误码的详细介绍请参见[通用错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)和[ArkTS API错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-cloudfoundation)。

|错误码ID|错误信息|
|:---------|:------------------------|
|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.|

**示例：**

```typescript
// 在代码工程中创建BookInfo.ets文件
import { cloudDatabase } from '@kit.CloudFoundationKit';

// 创建一个BookInfo的类继承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 };
```

```typescript
import { cloudDatabase } from '@kit.CloudFoundationKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BookInfo } from 'xx/BookInfo'; // 在云数据库代码工程中引入BookInfo.ets文件，xx是文件的路径

async () => {
  // 创建一个BookInfo的类继承cloudDatabase.DatabaseObject，内容与使用Promise异步回调的query接口示例一致
  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}`);
  }
}
```

### query

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

通过条件查询数据。使用callback异步回调。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本5.0.0(12)开始，该接口支持在元服务中使用。

**需要权限：** ohos.permission.INTERNET

**系统能力：** SystemCapability.DeviceCloudGateway.CloudFoundation

**起始版本：** 5.0.0(12)

**参数：**

|参数名|类型|必填|说明|
|:--------|:---------------------------------------------------------|:-|:------------------------------------------------|
|condition|[DatabaseQuery](#databasequeryt-extends-databaseobject)<T>|是|提供丰富的查询条件。|
|callback|AsyncCallback<T[]>|是|回调函数。当查询数据成功，err为undefined，data为查询到的结果数组；否则为错误对象。|

**错误码：**

以下错误码的详细介绍请参见[通用错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)和[ArkTS API错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-cloudfoundation)。

|错误码ID|错误信息|
|:---------|:------------------------|
|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.|

**示例：**

```typescript
import { cloudDatabase } from '@kit.CloudFoundationKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BookInfo } from 'xx/BookInfo'; // xx是BookInfo文件的路径

// 创建一个BookInfo的类继承cloudDatabase.DatabaseObject，内容与使用Promise异步回调的query接口示例一致
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)}`);
  }
});
```

### calculateQuery

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

从数据库中查询符合条件的数据，并对指定字段进行算术计算。使用Promise异步回调。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本5.0.0(12)开始，该接口支持在元服务中使用。

**需要权限：** ohos.permission.INTERNET

**系统能力：** SystemCapability.DeviceCloudGateway.CloudFoundation

**起始版本：** 5.0.0(12)

**参数：**

|参数名|类型|必填|说明|
|:--------|:---------------------------------------------------------|:-|:---------------|
|condition|[DatabaseQuery](#databasequeryt-extends-databaseobject)<T>|是|提供丰富的查询条件。|
|fieldName|string|是|指定查询对象中要计算的字段名称。|
|calculate|[QueryCalculate](#querycalculate)|是|云数据库查询算术计算的类型。|

**返回值：**

|类型|说明|
|:--------------|:------------------------|
|Promise<number>|Promise对象。返回查询字段名称算术运算结果。|

**错误码：**

以下错误码的详细介绍请参见[通用错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)和[ArkTS API错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-cloudfoundation)。

|错误码ID|错误信息|
|:---------|:------------------------|
|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.|

**示例：**

```typescript
import { cloudDatabase } from '@kit.CloudFoundationKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BookInfo } from 'xx/BookInfo'; // xx是BookInfo文件的路径

async () => {
  // 创建一个BookInfo的类继承cloudDatabase.DatabaseObject，内容与使用Promise异步回调的query接口示例一致
  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}`);
  }
}
```

### calculateQuery

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

从数据库中查询符合条件的数据，并对指定字段进行算术计算。使用callback异步回调。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本5.0.0(12)开始，该接口支持在元服务中使用。

**需要权限：** ohos.permission.INTERNET

**系统能力：** SystemCapability.DeviceCloudGateway.CloudFoundation

**起始版本：** 5.0.0(12)

**参数：**

|参数名|类型|必填|说明|
|:--------|:---------------------------------------------------------|:-|:----------------------------------------------|
|condition|[DatabaseQuery](#databasequeryt-extends-databaseobject)<T>|是|提供丰富的查询条件。|
|fieldName|string|是|指定查询对象中要计算的字段名称。|
|calculate|[QueryCalculate](#querycalculate)|是|云数据库查询算术计算的类型。|
|callback|AsyncCallback<number>|是|回调函数。当算术计算成功，err为undefined，data为算术运算结果；否则为错误对象。|

**错误码：**

以下错误码的详细介绍请参见[通用错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)和[ArkTS API错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-cloudfoundation)。

|错误码ID|错误信息|
|:---------|:------------------------|
|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.|

**示例：**

```typescript
import { cloudDatabase } from '@kit.CloudFoundationKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BookInfo } from 'xx/BookInfo'; // xx是BookInfo文件的路径

// 创建一个BookInfo的类继承cloudDatabase.DatabaseObject，内容与使用Promise异步回调的query接口示例一致
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}`);
    }
  });
```

### upsert

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

向数据库更新数据。使用Promise异步回调。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本5.0.0(12)开始，该接口支持在元服务中使用。

**需要权限：** ohos.permission.INTERNET

**系统能力：** SystemCapability.DeviceCloudGateway.CloudFoundation

**起始版本：** 5.0.0(12)

**参数：**

|参数名|类型|必填|说明|
|:---------|:------|:-|:-------|
|objectList|T[] | T|是|一个或多个对象。|

**返回值：**

|类型|说明|
|:--------------|:---------------------|
|Promise<number>|Promise对象。返回更新成功的数据数量。|

**错误码：**

以下错误码的详细介绍请参见[通用错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)和[ArkTS API错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-cloudfoundation)。

|错误码ID|错误信息|
|:---------|:------------------------|
|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.|

**示例：**

```typescript
import { cloudDatabase } from '@kit.CloudFoundationKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BookInfo } from 'xx/BookInfo'; // xx是BookInfo文件的路径

async () => {
  // 创建一个BookInfo的类继承cloudDatabase.DatabaseObject，内容与使用Promise异步回调的query接口示例一致
  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}`);
  }
}
```

### upsert

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

向数据库更新数据。使用callback异步回调。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本5.0.0(12)开始，该接口支持在元服务中使用。

**需要权限：** ohos.permission.INTERNET

**系统能力：** SystemCapability.DeviceCloudGateway.CloudFoundation

**起始版本：** 5.0.0(12)

**参数：**

|参数名|类型|必填|说明|
|:---------|:--------------------|:-|:-------------------------------------------------|
|objectList|T[] | T|是|一个或多个对象。|
|callback|AsyncCallback<number>|是|回调函数。当更新数据成功，err为undefined，data为更新成功的数据数量；否则为错误对象。|

**错误码：**

以下错误码的详细介绍请参见[通用错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)和[ArkTS API错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-cloudfoundation)。

|错误码ID|错误信息|
|:---------|:------------------------|
|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.|

**示例：**

```typescript
import { cloudDatabase } from '@kit.CloudFoundationKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BookInfo } from 'xx/BookInfo'; // xx是BookInfo文件的路径

// 创建一个BookInfo的类继承cloudDatabase.DatabaseObject，内容与使用Promise异步回调的query接口示例一致
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}`);
  }
});
```

### delete

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

在数据库中删除一条或者多条数据。使用Promise异步回调。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本5.0.0(12)开始，该接口支持在元服务中使用。

**需要权限：** ohos.permission.INTERNET

**系统能力：** SystemCapability.DeviceCloudGateway.CloudFoundation

**起始版本：** 5.0.0(12)

**参数：**

|参数名|类型|必填|说明|
|:---------|:------|:-|:-------|
|objectList|T[] | T|是|一个或多个对象。|

**返回值：**

|类型|说明|
|:--------------|:---------------------|
|Promise<number>|Promise对象。返回删除成功的数据数量。|

**错误码：**

以下错误码的详细介绍请参见[通用错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)和[ArkTS API错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-cloudfoundation)。

|错误码ID|错误信息|
|:---------|:------------------------|
|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.|

**示例：**

```typescript
import { cloudDatabase } from '@kit.CloudFoundationKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BookInfo } from 'xx/BookInfo'; // xx是BookInfo文件的路径

async () => {
  // 创建一个BookInfo的类继承cloudDatabase.DatabaseObject，内容与使用Promise异步回调的query接口示例一致
  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}`);
  }
}
```

### delete

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

在数据库中删除一条或者多条数据。使用callback异步回调。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本5.0.0(12)开始，该接口支持在元服务中使用。

**需要权限：** ohos.permission.INTERNET

**系统能力：** SystemCapability.DeviceCloudGateway.CloudFoundation

**起始版本：** 5.0.0(12)

**参数：**

|参数名|类型|必填|说明|
|:---------|:--------------------|:-|:-------------------------------------------------|
|objectList|T[] | T|是|一个或多个对象。|
|callback|AsyncCallback<number>|是|回调函数。当删除数据成功，err为undefined，data为删除成功的数据数量；否则为错误对象。|

**错误码：**

以下错误码的详细介绍请参见[通用错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)和[ArkTS API错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-cloudfoundation)。

|错误码ID|错误信息|
|:---------|:------------------------|
|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.|

**示例：**

```typescript
import { cloudDatabase } from '@kit.CloudFoundationKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BookInfo } from 'xx/BookInfo'; // xx是BookInfo文件的路径

async () => {
  // 创建一个BookInfo的类继承cloudDatabase.DatabaseObject，内容与使用Promise异步回调的query接口示例一致
  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

数据库数据类型基类，在云端生成表结构时继承。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本5.0.0(12)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.DeviceCloudGateway.CloudFoundation

**起始版本：** 5.0.0(12)

### naturalbase_ClassName

naturalbase_ClassName(): string

数据类型基类名称。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本5.0.0(12)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.DeviceCloudGateway.CloudFoundation

**起始版本：** 5.0.0(12)

**返回值：**

|类型|说明|
|:-----|:-------------------------|
|string|返回数据类型基类名称，需要与创建的对象类型名称一致。|

**示例：**

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

// 创建一个BookInfo的类继承cloudDatabase.DatabaseObject，内容与使用Promise异步回调的query接口示例一致
class BookInfo extends cloudDatabase.DatabaseObject{
  public naturalbase_ClassName(): string {
    return 'BookInfo';
  }
}

export { BookInfo };
```

## FieldType

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

云数据库支持的数据类型。取值类型为下表类型中的并集/交集。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本5.0.0(12)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.DeviceCloudGateway.CloudFoundation

**起始版本：** 5.0.0(12)

|类型|说明|
|:---------|:---------------------------|
|string|表示值类型为字符，可取任意值。|
|number|表示值类型为数字，可取任意值。|
|boolean|表示值类型为布尔类型，可取true或者false。|
|Uint8Array|表示值类型为8位无符号整型数组，可取任意值。|
|Date|表示值类型为日期，值固定格式为"YYYY-MM-DD"。|

## QueryCalculate

枚举， 查询算术计算类型。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本5.0.0(12)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.DeviceCloudGateway.CloudFoundation

**起始版本：** 5.0.0(12)

|名称|值|说明|
|:------|:-|:------|
|AVERAGE|0|计算平均数。|
|SUM|1|计算总和。|
|MAXIMUM|2|计算最大值。|
|MINIMUM|3|计算最小值。|
|COUNT|4|计算记录总数。|

## DatabaseQuery<T extends DatabaseObject>

提供丰富的谓词查询来构建查询条件。根据谓词查询方法构造自己的DatabaseQuery对象。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本5.0.0(12)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.DeviceCloudGateway.CloudFoundation

**起始版本：** 5.0.0(12)

### constructor

constructor(entityClass: new () => T)

构造查询实体类信息。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本5.0.0(12)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.DeviceCloudGateway.CloudFoundation

**起始版本：** 5.0.0(12)

**参数：**

|参数名|类型|必填|说明|
|:----------|:----------|:-|:--------|
|entityClass|new () => T|是|数据对象的实体类。|

**示例：**

```typescript
import { cloudDatabase } from '@kit.CloudFoundationKit';
import { BookInfo } from 'xx/BookInfo'; // xx是BookInfo文件的路径

let condition = new cloudDatabase.DatabaseQuery(BookInfo);
```

### equalTo

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

添加实体类中某个字段的值等于指定值的查询条件。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本5.0.0(12)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.DeviceCloudGateway.CloudFoundation

**起始版本：** 5.0.0(12)

**参数：**

|参数名|类型|必填|说明|
|:--------|:----------------------|:-|:--------------|
|fieldName|string|是|实体类中的字段名。|
|value|[FieldType](#fieldtype)|是|云数据库中支持的数据类型的值。|

**返回值：**

|类型|说明|
|:---------------------------------------------------------|:---------------|
|[DatabaseQuery](#databasequeryt-extends-databaseobject)<T>|DatabaseQuery对象。|

**示例：**

```typescript
import { cloudDatabase } from '@kit.CloudFoundationKit';
import { BookInfo } from 'xx/BookInfo'; // xx是BookInfo文件的路径
import { hilog } from '@kit.PerformanceAnalysisKit';

async () => {
  // 创建一个BookInfo的类继承cloudDatabase.DatabaseObject，内容与使用Promise异步回调的query接口示例一致
  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}`);
  }
}
```

### notEqualTo

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

添加实体类中某个字段的值不等于指定值的查询条件。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本5.0.0(12)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.DeviceCloudGateway.CloudFoundation

**起始版本：** 5.0.0(12)

**参数：**

|参数名|类型|必填|说明|
|:--------|:----------------------|:-|:--------------|
|fieldName|string|是|实体类中的字段名。|
|value|[FieldType](#fieldtype)|是|云数据库中支持的数据类型的值。|

**返回值：**

|类型|说明|
|:---------------------------------------------------------|:---------------|
|[DatabaseQuery](#databasequeryt-extends-databaseobject)<T>|DatabaseQuery对象。|

**示例：**

```typescript
import { cloudDatabase } from '@kit.CloudFoundationKit';
import { BookInfo } from 'xx/BookInfo'; // xx是BookInfo文件的路径
import { hilog } from '@kit.PerformanceAnalysisKit';


async () => {
  // 创建一个BookInfo的类继承cloudDatabase.DatabaseObject，内容与使用Promise异步回调的query接口示例一致
  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}`);
  }
}
```

### beginsWith

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

添加实体类中string类型字段值以指定子串开头的查询条件。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本5.0.0(12)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.DeviceCloudGateway.CloudFoundation

**起始版本：** 5.0.0(12)

**参数：**

|参数名|类型|必填|说明|
|:--------|:----------------------|:-|:--------------|
|fieldName|string|是|实体类中的字段名。|
|value|[FieldType](#fieldtype)|是|云数据库中支持的数据类型的值。|

**返回值：**

|类型|说明|
|:---------------------------------------------------------|:---------------|
|[DatabaseQuery](#databasequeryt-extends-databaseobject)<T>|DatabaseQuery对象。|

**示例：**

```typescript
import { cloudDatabase } from '@kit.CloudFoundationKit';
import { BookInfo } from 'xx/BookInfo'; // xx是BookInfo文件的路径
import { hilog } from '@kit.PerformanceAnalysisKit';

async () => {
  // 创建一个BookInfo的类继承cloudDatabase.DatabaseObject，内容与使用Promise异步回调的query接口示例一致
  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}`);
  }
}
```

### endsWith

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

添加实体类中string类型字段值以指定子串结尾的查询条件。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本5.0.0(12)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.DeviceCloudGateway.CloudFoundation

**起始版本：** 5.0.0(12)

**参数：**

|参数名|类型|必填|说明|
|:--------|:----------------------|:-|:--------------|
|fieldName|string|是|实体类中的字段名。|
|value|[FieldType](#fieldtype)|是|云数据库中支持的数据类型的值。|

**返回值：**

|类型|说明|
|:---------------------------------------------------------|:---------------|
|[DatabaseQuery](#databasequeryt-extends-databaseobject)<T>|DatabaseQuery对象。|

**示例：**

```typescript
import { cloudDatabase } from '@kit.CloudFoundationKit';
import { BookInfo } from 'xx/BookInfo'; // xx是BookInfo文件的路径
import { hilog } from '@kit.PerformanceAnalysisKit';

async () => {
  // 创建一个BookInfo的类继承cloudDatabase.DatabaseObject，内容与使用Promise异步回调的query接口示例一致
  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}`);
  }
}
```

### contains

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

添加实体类中字符串类型字段值包含指定子字符串的查询条件。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本5.0.0(12)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.DeviceCloudGateway.CloudFoundation

**起始版本：** 5.0.0(12)

**参数：**

|参数名|类型|必填|说明|
|:--------|:----------------------|:-|:--------------|
|fieldName|string|是|实体类中的字段名。|
|value|[FieldType](#fieldtype)|是|云数据库中支持的数据类型的值。|

**返回值：**

|类型|说明|
|:---------------------------------------------------------|:---------------|
|[DatabaseQuery](#databasequeryt-extends-databaseobject)<T>|DatabaseQuery对象。|

**示例：**

```typescript
import { cloudDatabase } from '@kit.CloudFoundationKit';
import { BookInfo } from 'xx/BookInfo'; // xx是BookInfo文件的路径
import { hilog } from '@kit.PerformanceAnalysisKit';

async () => {
  // 创建一个BookInfo的类继承cloudDatabase.DatabaseObject，内容与使用Promise异步回调的query接口示例一致
  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}`);
  }
}
```

### greaterThan

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

添加实体类字段值大于指定值的查询条件。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本5.0.0(12)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.DeviceCloudGateway.CloudFoundation

**起始版本：** 5.0.0(12)

**参数：**

|参数名|类型|必填|说明|
|:--------|:----------------------|:-|:--------------|
|fieldName|string|是|实体类中的字段名。|
|value|[FieldType](#fieldtype)|是|云数据库中支持的数据类型的值。|

**返回值：**

|类型|说明|
|:---------------------------------------------------------|:---------------|
|[DatabaseQuery](#databasequeryt-extends-databaseobject)<T>|DatabaseQuery对象。|

**示例：**

```typescript
import { cloudDatabase } from '@kit.CloudFoundationKit';
import { BookInfo } from 'xx/BookInfo'; // xx是BookInfo文件的路径
import { hilog } from '@kit.PerformanceAnalysisKit';

async () => {
  // 创建一个BookInfo的类继承cloudDatabase.DatabaseObject，内容与使用Promise异步回调的query接口示例一致
  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}`);
  }
}
```

### greaterThanOrEqualTo

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

添加实体类字段值大于或等于指定值的查询条件。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本5.0.0(12)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.DeviceCloudGateway.CloudFoundation

**起始版本：** 5.0.0(12)

**参数：**

|参数名|类型|必填|说明|
|:--------|:----------------------|:-|:--------------|
|fieldName|string|是|实体类中的字段名。|
|value|[FieldType](#fieldtype)|是|云数据库中支持的数据类型的值。|

**返回值：**

|类型|说明|
|:---------------------------------------------------------|:---------------|
|[DatabaseQuery](#databasequeryt-extends-databaseobject)<T>|DatabaseQuery对象。|

**示例：**

```typescript
import { cloudDatabase } from '@kit.CloudFoundationKit';
import { BookInfo } from 'xx/BookInfo'; // xx是BookInfo文件的路径
import { hilog } from '@kit.PerformanceAnalysisKit';

async () => {
  // 创建一个BookInfo的类继承cloudDatabase.DatabaseObject，内容与使用Promise异步回调的query接口示例一致
  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}`);
  }
}
```

### lessThan

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

添加实体类字段值小于指定值的查询条件。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本5.0.0(12)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.DeviceCloudGateway.CloudFoundation

**起始版本：** 5.0.0(12)

**参数：**

|参数名|类型|必填|说明|
|:--------|:----------------------|:-|:--------------|
|fieldName|string|是|实体类中的字段名。|
|value|[FieldType](#fieldtype)|是|云数据库中支持的数据类型的值。|

**返回值：**

|类型|说明|
|:---------------------------------------------------------|:---------------|
|[DatabaseQuery](#databasequeryt-extends-databaseobject)<T>|DatabaseQuery对象。|

**示例：**

```typescript
import { cloudDatabase } from '@kit.CloudFoundationKit';
import { BookInfo } from 'xx/BookInfo'; // xx是BookInfo文件的路径
import { hilog } from '@kit.PerformanceAnalysisKit';

async () => {
  // 创建一个BookInfo的类继承cloudDatabase.DatabaseObject，内容与使用Promise异步回调的query接口示例一致
  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}`);
  }
}
```

### lessThanOrEqualTo

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

添加实体类字段值小于或等于指定值的查询条件。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本5.0.0(12)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.DeviceCloudGateway.CloudFoundation

**起始版本：** 5.0.0(12)

**参数：**

|参数名|类型|必填|说明|
|:--------|:----------------------|:-|:--------------|
|fieldName|string|是|实体类中的字段名。|
|value|[FieldType](#fieldtype)|是|云数据库中支持的数据类型的值。|

**返回值：**

|类型|说明|
|:---------------------------------------------------------|:---------------|
|[DatabaseQuery](#databasequeryt-extends-databaseobject)<T>|DatabaseQuery对象。|

**示例：**

```typescript
import { cloudDatabase } from '@kit.CloudFoundationKit';
import { BookInfo } from 'xx/BookInfo'; // xx是BookInfo文件的路径
import { hilog } from '@kit.PerformanceAnalysisKit';

async () => {
  // 创建一个BookInfo的类继承cloudDatabase.DatabaseObject，内容与使用Promise异步回调的query接口示例一致
  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}`);
  }
}
```

### in

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

添加实体类字段值包含在指定数组中的查询条件。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本5.0.0(12)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.DeviceCloudGateway.CloudFoundation

**起始版本：** 5.0.0(12)

**参数：**

|参数名|类型|必填|说明|
|:--------|:------------------------|:-|:-----------------|
|fieldName|string|是|实体类中的字段名。|
|values|[FieldType](#fieldtype)[]|是|云数据库中支持的数据类型的值的数组。|

**返回值：**

|类型|说明|
|:---------------------------------------------------------|:---------------|
|[DatabaseQuery](#databasequeryt-extends-databaseobject)<T>|DatabaseQuery对象。|

**示例：**

```typescript
import { cloudDatabase } from '@kit.CloudFoundationKit';
import { BookInfo } from 'xx/BookInfo'; // xx是BookInfo文件的路径
import { hilog } from '@kit.PerformanceAnalysisKit';

async () => {
  // 创建一个BookInfo的类继承cloudDatabase.DatabaseObject，内容与使用Promise异步回调的query接口示例一致
  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}`);
  }
}
```

### isNull

isNull(fieldName: string): DatabaseQuery<T>

添加实体类某字段值为空的查询条件。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本5.0.0(12)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.DeviceCloudGateway.CloudFoundation

**起始版本：** 5.0.0(12)

**参数：**

|参数名|类型|必填|说明|
|:--------|:-----|:-|:--------|
|fieldName|string|是|实体类中的字段名。|

**返回值：**

|类型|说明|
|:---------------------------------------------------------|:---------------|
|[DatabaseQuery](#databasequeryt-extends-databaseobject)<T>|DatabaseQuery对象。|

**示例：**

```typescript
import { cloudDatabase } from '@kit.CloudFoundationKit';
import { BookInfo } from 'xx/BookInfo'; // xx是BookInfo文件的路径
import { hilog } from '@kit.PerformanceAnalysisKit';

async () => {
  // 创建一个BookInfo的类继承cloudDatabase.DatabaseObject，内容与使用Promise异步回调的query接口示例一致
  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}`);
  }
}
```

### isNotNull

isNotNull(fieldName: string): DatabaseQuery<T>

添加实体类某字段值不为空的查询条件。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本5.0.0(12)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.DeviceCloudGateway.CloudFoundation

**起始版本：** 5.0.0(12)

**参数：**

|参数名|类型|必填|说明|
|:--------|:-----|:-|:--------|
|fieldName|string|是|实体类中的字段名。|

**返回值：**

|类型|说明|
|:---------------------------------------------------------|:---------------|
|[DatabaseQuery](#databasequeryt-extends-databaseobject)<T>|DatabaseQuery对象。|

**示例：**

```typescript
import { cloudDatabase } from '@kit.CloudFoundationKit';
import { BookInfo } from 'xx/BookInfo'; // xx是BookInfo文件的路径
import { hilog } from '@kit.PerformanceAnalysisKit';

async () => {
  // 创建一个BookInfo的类继承cloudDatabase.DatabaseObject，内容与使用Promise异步回调的query接口示例一致
  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}`);
  }
}
```

### orderByAsc

orderByAsc(fieldName: string): DatabaseQuery<T>

按指定字段升序对查询结果进行排序。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本5.0.0(12)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.DeviceCloudGateway.CloudFoundation

**起始版本：** 5.0.0(12)

**参数：**

|参数名|类型|必填|说明|
|:--------|:-----|:-|:--------|
|fieldName|string|是|实体类中的字段名。|

**返回值：**

|类型|说明|
|:---------------------------------------------------------|:---------------|
|[DatabaseQuery](#databasequeryt-extends-databaseobject)<T>|DatabaseQuery对象。|

**示例：**

```typescript
import { cloudDatabase } from '@kit.CloudFoundationKit';
import { BookInfo } from 'xx/BookInfo'; // xx是BookInfo文件的路径
import { hilog } from '@kit.PerformanceAnalysisKit';

async () => {
  // 创建一个BookInfo的类继承cloudDatabase.DatabaseObject，内容与使用Promise异步回调的query接口示例一致
  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}`);
  }
}
```

### orderByDesc

orderByDesc(fieldName: string): DatabaseQuery<T>

按指定字段降序对查询结果进行排序。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本5.0.0(12)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.DeviceCloudGateway.CloudFoundation

**起始版本：** 5.0.0(12)

**参数：**

|参数名|类型|必填|说明|
|:--------|:-----|:-|:--------|
|fieldName|string|是|实体类中的字段名。|

**返回值：**

|类型|说明|
|:---------------------------------------------------------|:---------------|
|[DatabaseQuery](#databasequeryt-extends-databaseobject)<T>|DatabaseQuery对象。|

**示例：**

```typescript
import { cloudDatabase } from '@kit.CloudFoundationKit';
import { BookInfo } from 'xx/BookInfo'; // xx是BookInfo文件的路径
import { hilog } from '@kit.PerformanceAnalysisKit';

async () => {
  // 创建一个BookInfo的类继承cloudDatabase.DatabaseObject，内容与使用Promise异步回调的query接口示例一致
  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}`);
  }
}
```

### orderByRandom

orderByRandom(): DatabaseQuery<T>

调用此方法可以将查询结果按随机顺序展示。
> 说明
>
> 使用orderByRandom()对数据进行排序时，建议与[limit()](#limit)配合使用。否则，当该对象类型的数据记录数量过多时，可能会影响查询效率，导致查询超时或失败。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本6.0.1(21)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.DeviceCloudGateway.CloudFoundation

**起始版本：** 6.0.1(21)

**返回值：**

|类型|说明|
|:---------------------------------------------------------|:---------------|
|[DatabaseQuery](#databasequeryt-extends-databaseobject)<T>|DatabaseQuery对象。|

**示例：**

```typescript
import { cloudDatabase } from '@kit.CloudFoundationKit';
import { BookInfo } from 'xx/BookInfo'; // xx是BookInfo文件的路径
import { hilog } from '@kit.PerformanceAnalysisKit';

async () => {
  // 创建一个BookInfo的类继承cloudDatabase.DatabaseObject，内容与使用Promise异步回调的query接口示例一致
  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}`);
  }
}
```

### limit

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

指定返回的查询结果集中的数据记录条数。如果不设置offset，则默认从首个对象开始获取前count个对象。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本5.0.0(12)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.DeviceCloudGateway.CloudFoundation

**起始版本：** 5.0.0(12)

**参数：**

|参数名|类型|必填|说明|
|:-----|:-----|:-|:-------------|
|count|number|是|限制可以获得的数据记录数量。|
|offset|number|否|指定数据记录的起始位置。|

**返回值：**

|类型|说明|
|:---------------------------------------------------------|:---------------|
|[DatabaseQuery](#databasequeryt-extends-databaseobject)<T>|DatabaseQuery对象。|

**示例：**

```typescript
import { cloudDatabase } from '@kit.CloudFoundationKit';
import { BookInfo } from 'xx/BookInfo'; // xx是BookInfo文件的路径
import { hilog } from '@kit.PerformanceAnalysisKit';

async () => {
  // 创建一个BookInfo的类继承cloudDatabase.DatabaseObject，内容与使用Promise异步回调的query接口示例一致
  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}`);
  }
}
```

### beginGroup

beginGroup(): DatabaseQuery<T>

调用此方法是为了放置左括号"("附加到任何查询条件并将右括号")"与相同的查询连接起来组合使用。
> 说明
>
> * beginGroup()和endGroup()必须成对出现，并且必须与其他查询条件一起使用。
>
> * 在beginGroup()和endGroup()之间，必须存在以下查询条件中的一个或多个：
>
>   equalTo()、notEqualTo()、greaterThan()、greaterThanOrEqualTo()、lessThan()、lessThanOrEqualTo()、in()、beginsWith()、endsWith()、isNull()、isNotNull()和contains()。
> * beginGroup()不能直接用在and()和or()之前。即不支持beginGroup().and()、beginGroup().and().endGroup()、beginGroup().or()和beginGroup().or().endGroup()。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本5.0.0(12)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.DeviceCloudGateway.CloudFoundation

**起始版本：** 5.0.0(12)

**返回值：**

|类型|说明|
|:---------------------------------------------------------|:---------------|
|[DatabaseQuery](#databasequeryt-extends-databaseobject)<T>|DatabaseQuery对象。|

**示例：**

```typescript
import { cloudDatabase } from '@kit.CloudFoundationKit';
import { BookInfo } from 'xx/BookInfo'; // xx是BookInfo文件的路径
import { hilog } from '@kit.PerformanceAnalysisKit';

async () => {
  // 创建一个BookInfo的类继承cloudDatabase.DatabaseObject，内容与使用Promise异步回调的query接口示例一致
  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}`);
  }
}
```

### endGroup

endGroup(): DatabaseQuery<T>

调用此方法是为了放置右括号")"附加到任何查询条件并将左括号"("与相同的查询连接起来组合使用。
> 说明
>
> * beginGroup()和endGroup()必须成对出现，并且必须与其他查询条件一起使用。
>
> * 在beginGroup()和endGroup()之间，必须存在以下查询条件中的一个或多个：
>
>   equalTo()、notEqualTo()、greaterThan()、greaterThanOrEqualTo()、lessThan()、lessThanOrEqualTo()、in()、beginsWith()、endsWith()、isNull()、isNotNull()和contains()。
> * endGroup()不能直接用在and()和or()之前。即不支持and().endGroup()、beginGroup().and().endGroup()、or().endGroup()和beginGroup().or().endGroup()。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本5.0.0(12)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.DeviceCloudGateway.CloudFoundation

**起始版本：** 5.0.0(12)

**返回值：**

|类型|说明|
|:---------------------------------------------------------|:---------------|
|[DatabaseQuery](#databasequeryt-extends-databaseobject)<T>|DatabaseQuery对象。|

**示例：**

```typescript
import { cloudDatabase } from '@kit.CloudFoundationKit';
import { BookInfo } from 'xx/BookInfo'; // xx是BookInfo文件的路径
import { hilog } from '@kit.PerformanceAnalysisKit';

async () => {
  // 创建一个BookInfo的类继承cloudDatabase.DatabaseObject，内容与使用Promise异步回调的query接口示例一致
  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}`);
  }
}
```

### or

or(): DatabaseQuery<T>

使用or运算组合两个条件并返回两个查询结果的并集。
> 说明
>
> * or()只能与其他查询条件一起使用。
>
> * 当和equalTo()、notEqualTo()、greaterThan()、greaterThanOrEqualTo()、lessThan()、lessThanOrEqualTo()、in()、beginsWith()、endsWith()、isNull()、isNotNull()和contains()一起使用时，返回两个查询结果的交集。
>
> * 当or()与and()一起使用时，or()前面不能直接跟and()，即不支持and().or()。
>
> * 与beginGroup()和endGroup()结合使用时：
>
>   * 支持多层嵌套，beginGroup()和endGroup()必须成对出现。
>   * beginGroup()不能在or()之前使用，endGroup()不能在or()之后使用。
>   * 即不支持beginGroup().or()、beginGroup().or().endGroup()和or().endGroup()。
>   * 不能与orderByAsc()、orderByDesc()或limit()一起使用。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本5.0.0(12)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.DeviceCloudGateway.CloudFoundation

**起始版本：** 5.0.0(12)

**返回值：**

|类型|说明|
|:---------------------------------------------------------|:---------------|
|[DatabaseQuery](#databasequeryt-extends-databaseobject)<T>|DatabaseQuery对象。|

**示例：**

```typescript
import { cloudDatabase } from '@kit.CloudFoundationKit';
import { BookInfo } from 'xx/BookInfo'; // xx是BookInfo文件的路径
import { hilog } from '@kit.PerformanceAnalysisKit';

async () => {
  // 创建一个BookInfo的类继承cloudDatabase.DatabaseObject，内容与使用Promise异步回调的query接口示例一致
  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}`);
  }
}
```

### and

and(): DatabaseQuery<T>

使用and运算组合两个条件并返回两个查询结果的交集。
> 说明
>
> * and()只能与其他查询条件一起使用。
>
> * 当和equalTo()、notEqualTo()、greaterThan()、greaterThanOrEqualTo()、lessThan()、lessThanOrEqualTo()、in()、beginsWith()、endsWith()、isNull()、isNotNull()和contains()一起使用时，返回两个查询结果的交集。
>
> * 当and()与or()一起使用时，and()后面不能直接跟or()，即不支持and().or()。
>
> * 与beginGroup()和endGroup()结合使用时：
>
>   * 支持多层嵌套，beginGroup()和endGroup()必须成对出现。
>   * beginGroup()不能在and()之前使用，endGroup()不能在and()之后使用。
>   * 即不支持beginGroup().and()、beginGroup().and().endGroup()和and().endGroup()。
>   * 不能与orderByAsc()、orderByDesc()或limit()一起使用。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本5.0.0(12)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.DeviceCloudGateway.CloudFoundation

**起始版本：** 5.0.0(12)

**返回值：**

|类型|说明|
|:---------------------------------------------------------|:---------------|
|[DatabaseQuery](#databasequeryt-extends-databaseobject)<T>|DatabaseQuery对象。|

**示例：**

```typescript
import { cloudDatabase } from '@kit.CloudFoundationKit';
import { BookInfo } from 'xx/BookInfo'; // xx是BookInfo文件的路径
import { hilog } from '@kit.PerformanceAnalysisKit';

async () => {
  // 创建一个BookInfo的类继承cloudDatabase.DatabaseObject，内容与使用Promise异步回调的query接口示例一致
  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}`);
  }
}
```