查询数据
====

云数据库通过[query()](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/cloudfoundation-clouddatabase#query)方法查询对象，并提供了丰富的谓词查询，比如[equalTo()](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/cloudfoundation-clouddatabase#equalto)、[notEqualTo()](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/cloudfoundation-clouddatabase#notequalto)、[in()](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/cloudfoundation-clouddatabase#in)等。通过单个或者多个链式过滤条件，开发者可以从存储区查询到满足特定条件的对象，也可以通过排序谓词对查询结果排序，或者通过限定查询返回数量谓词限定查询结果返回的数量。详细的查询条件请参见[DatabaseQuery](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/cloudfoundation-clouddatabase#databasequeryt-extends-databaseobject)。

应用会直接从云侧存储区服务器查询数据，本地不会缓存数据。

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/7e/v3/vKpHVkN_R8Wfo58YsA8ftg/note_3.0-zh-cn.png?HW-CC-KV=V1&HW-CC-Date=20260612T073603Z&HW-CC-Expire=86400&HW-CC-Sign=5D9B50D1657B38EB7AA9B9328683229697EE98211B486FA29882E85E80D13539)

*   每次的查询操作仅支持查询一个对象类型下的数据。
    
*   调用查询数据方法，有两种返回方式，返回一个Promise对象或者在参数中传入一个callback对象返回，下面以Promise为例详细说明。
    

#### 约束与限制

支持Phone、Tablet设备。并且从5.1.0(18)版本开始，新增支持Wearable设备；从5.1.1(19)版本开始，新增支持TV设备；从6.1.0(23)版本开始，新增支持PC/2in1设备。

#### 前提条件

已[初始化数据库访问](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/cloudfoundation-database-initialize)。

#### 简单查询

开发者可以在无查询条件时，获取一个对象类型中所有的对象；也可以指定单个查询条件，来获取满足该条件的对象。

*   查询对象类型BookInfo的所有数据。
    
    import { hilog } from '@kit.PerformanceAnalysisKit';
    
    async queryAll() {
      try {
        let resultArray = await databaseZone.query(condition);
        hilog.info(0x0000, 'testTag', \`Succeeded in querying data, result: ${JSON.stringify(resultArray)}\`);
      } catch (err) {
        hilog.error(0x0000, 'testTag', \`Failed to query data, code: ${err.code}, message: ${err.message}\`);
      }
    }
    
    ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/db/v3/FK5u3GtgT_6H5y8AxjUZsA/note_3.0-zh-cn.png?HW-CC-KV=V1&HW-CC-Date=20260612T073603Z&HW-CC-Expire=86400&HW-CC-Sign=054E07A407EDEEC8F525BB5D4AB658D3E6EA4EE7C71F8823BDC019BD01FE85B3)
    
    后续hilog都需要从@kit.PerformanceAnalysisKit中引入，将不在示例代码中呈现。
    
*   通过异步侦听的方式查询“bookName”参数对应的书籍。
    
    async queryBook(bookName: string): Promise<BookInfo> {
      try {
        condition.equalTo('bookName', bookName);
        let resultArray = await databaseZone.query(condition);
        let bookInfo = resultArray\[0\];
        hilog.info(0x0000, 'testTag', \`Succeeded in querying data, result: ${JSON.stringify(resultArray)}\`);
        return Promise.resolve(bookInfo);
      } catch (err) {
        hilog.error(0x0000, 'testTag', \`Failed to query data, code: ${err.code}, message: ${err.message}\`);
        return Promise.reject(err);
      }
    }
    

#### 复合查询

开发者可以通过多个链式过滤条件，来获取满足条件的对象。多个链式条件之间默认用“与”运算。

*   构造查询条件，并调用[query()](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/cloudfoundation-clouddatabase#query)方法，查询“bookName”包含“数据库”，“price”大于20.0并且小于50.0的书籍。
    
    condition.contains('bookName', '数据库')
      .greaterThan('price', 20.0)
      .and()
      .lessThan('price', 50.0);
    let resultArray = await databaseZone.query(condition);
    
*   构造查询条件，并调用[query()](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/cloudfoundation-clouddatabase#query)方法，查询“bookName”包含“数据库”，“price”在小于20.0或者大于50.0区间的书籍。
    
    condition.contains('bookName', '数据库')
      .lessThan('price', 20.0)
      .or()
      .greaterThan('price', 50.0);
    let resultArray = await databaseZone.query(condition);
    
*   构造查询条件，并调用[query()](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/cloudfoundation-clouddatabase#query)方法，查询“bookName”包含“史记”，“author”是“司马迁”，“price”大于60.0的书籍。
    
    condition.contains('bookName', '史记')
      .equalTo('author', '司马迁')
      .greaterThan('price', 60.0);
    let resultArray = await databaseZone.query(condition);
    
*   构造查询条件，并调用[query()](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/cloudfoundation-clouddatabase#query)方法，查询“bookName”包含“自传”，并且“author”是“齐白石”，或者“author”是“司马迁”，并且“price”大于60.0的书籍。
    
    condition.contains('bookName', '自传')
      .beginGroup()
      .equalTo('author', '齐白石')
      .or()
      .equalTo('author', '司马迁')
      .endGroup()
      .greaterThan('price', 60.0);
    let resultArray = await databaseZone.query(condition);
    
*   构造查询条件，并调用[query()](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/cloudfoundation-clouddatabase#query)方法，查询“bookName”包含“数据库”，并且“borrowerTime”在特定时间段内的书籍。其中，针对Date类型构造greaterThan()、greaterThanOrEqualTo()、lessThan()、lessThanOrEqualTo()、equalTo()、notEqualTo()查询条件时，需要调用getTime()方法将Date类型转换成number类型。
    
    let begin = (new Date("2025-12-29T08:00:00.000+08:00")).getTime();
    let end = (new Date("2025-12-31T08:00:00.000+08:00")).getTime();
    condition.contains('bookName', '数据库')
      .greaterThan('borrowerTime', begin)
      .and()
      .lessThan('borrowerTime', end);
    let resultArray = await databaseZone.query(condition);
    

#### 数据排序

开发者可以通过[orderByAsc()](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/cloudfoundation-clouddatabase#orderbyasc)或者[orderByDesc()](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/cloudfoundation-clouddatabase#orderbydesc)实现对查询结果集中的对象按某个字段进行升序或者降序排列，排序谓词需要在其它查询谓词之后且在限定数据查询数量谓词之前。

condition.lessThan('price', 50.0)
  .orderByDesc('price');
let resultArray = await databaseZone.query(condition);

#### 随机查询

从6.0.1(21)版本开始，新增支持随机查询功能。

开发者可以通过[orderByRandom()](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/cloudfoundation-clouddatabase#orderbyrandom)按随机顺序展示查询结果集中的对象。

该方法适用于推荐随机内容、播放随机音视频等场景。

condition.orderByRandom()
  .limit(10);
let resultArray = await databaseZone.query(condition);

#### 限定数据查询返回数量

在查询数据时，开发者可以通过[limit()](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/cloudfoundation-clouddatabase#limit)限定查询返回数据的起始位置和数量，实现数据的分页。例如与排序查询谓词组合使用，可以实现获取top-N条数据。

对查询结果中的对象限定查询返回数量时，限定数据查询返回数量谓词在所有其他谓词查询之后。

*   构造查询条件，并调用[query()](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/cloudfoundation-clouddatabase#query)方法，查询所有价格小于50.0的书籍，并且只显示最开始10条记录。
    
    condition.lessThan('price', 50.0)
      .limit(10);
    let resultArray = await databaseZone.query(condition);
    
*   构造查询条件，并调用[query()](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/cloudfoundation-clouddatabase#query)方法，查询所有价格小于50.0的书籍，并将查询结果按照降序排序，只显示价格排序从第6条开始的10条记录。
    
    condition.lessThan('price', 50.0)
      .orderByDesc('price')
      .limit(10, 6);
    let resultArray = await databaseZone.query(condition);
    

#### 对查询结果进行算术计算

在查询数据时，可以通过[calculateQuery()](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/cloudfoundation-clouddatabase#calculatequery)对查询结果对象中的某个字段进行算术计算并返回计算的结果。

构造查询条件，并调用[calculateQuery()](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/cloudfoundation-clouddatabase#calculatequery)方法，查询所有价格小于50.0的书籍，并且计算所有书籍价格的平均值。

async calculateQuery() {
  try {
    condition.lessThan('price', 50.0);
    let resultNum = await databaseZone.calculateQuery(condition, 'price', cloudDatabase.QueryCalculate.AVERAGE);
    hilog.info(0x0000, 'testTag', \`Succeeded in calculating queried data, result: ${JSON.stringify(resultNum)}\`);
  } catch (err) {
    hilog.error(0x0000, 'testTag', \`Failed to calculate queried data, code: ${err.code}, message: ${err.message}\`);
  }
}