harmony 鸿蒙@ohos.data.relationalStore (关系型数据库)(系统接口)

  • 2025-06-12
  • 浏览 (4)

@ohos.data.relationalStore (关系型数据库)(系统接口)

关系型数据库(Relational Database,RDB)是一种基于关系模型来管理数据的数据库。关系型数据库基于SQLite组件提供了一套完整的对本地数据库进行管理的机制,对外提供了一系列的增、删、改、查等接口,也可以直接运行用户输入的SQL语句来满足复杂的场景需要。不支持Worker线程。 ArkTS侧支持的基本数据类型:number、string、二进制类型数据、boolean。为保证插入并读取数据成功,建议一条数据不要超过2M。超出该大小,插入成功,读取失败。

该模块提供以下关系型数据库相关的常用功能:

  • RdbPredicates:数据库中用来代表数据实体的性质、特征或者数据实体之间关系的词项,主要用来定义数据库的操作条件。
  • RdbStore:提供管理关系数据库(RDB)方法的接口。
  • ResultSet:提供用户调用关系型数据库查询接口之后返回的结果集合。

说明:

  • 本模块首批接口从API version 9开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。

  • 当前页面仅包含本模块的系统接口,其他公开接口参见@ohos.data.relationalStore (关系型数据库)

导入模块

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

StoreConfig

管理数据库配置。

系统能力: SystemCapability.DistributedDataManager.RelationalStore.Core

名称 类型 必填 说明
isSearchable11+ boolean 指定数据库是否支持搜索,true表示支持搜索,false表示不支持搜索,默认不支持搜索。
系统接口: 此接口为系统接口。
从API version 11开始,支持此可选参数。
haMode12+ HAMode 指定关系型数据库存储的高可用性模式,SINGLE表示将数据写入单个关系型数据库存储,MAIN_REPLICA表示将数据写入主关系型数据库存储和副本关系型数据库存储,但不支持加密场景和attach场景。MAIN_REPLICA会导致数据库写入性能的劣化,默认为SINGLE。
系统接口: 此接口为系统接口。
从API version 12开始,支持此可选参数。

HAMode12+

描述关系型数据库存储的高可用性模式的枚举。

系统能力: SystemCapability.DistributedDataManager.RelationalStore.Core

名称 说明
SINGLE 0 表示将数据写入单个关系型数据库存储。
MAIN_REPLICA 1 表示将数据写入主关系型数据库存储和副本关系型数据库存储,不支持加密场景和attach场景。

Reference11+

记录表之间通过表字段指定的关联关系。其中表a关联到表b,称a为b关联的子表,b为a关联的父表。

系统能力: SystemCapability.DistributedDataManager.RelationalStore.Core

系统接口: 此接口为系统接口。

名称 类型 必填 说明
sourceTable string 关联的子表名称。
targetTable string 关联的父表名称。
refFields Record 表示关联表的关联字段。键值数据中键为子表字段,值为父表字段。

DistributedConfig10+

记录表的分布式配置信息。

系统能力: SystemCapability.DistributedDataManager.RelationalStore.Core

名称 类型 必填 说明
references11+ Array<Reference> 设置表之间的关联关系,可以设置多个字段的关联,子表和父表关联字段的值必须相同。默认数据库表之间无关联关系。
系统接口: 此接口为系统接口。
从API version 11开始,支持此可选参数。

RdbStore

提供管理关系型数据库(RDB)的接口。

在使用以下相关接口前,请使用executeSql接口初始化数据库表结构和相关数据。

update

update(table: string, values: ValuesBucket, predicates: dataSharePredicates.DataSharePredicates, callback: AsyncCallback<number>):void

根据DataSharePredicates的指定实例对象更新数据库中的数据,使用callback异步回调。由于共享内存大小限制为2Mb,因此单条数据的大小需小于2Mb,否则会查询失败。

系统能力: SystemCapability.DistributedDataManager.RelationalStore.Core

模型约束: 此接口仅可在Stage模型下可用。

系统接口: 此接口为系统接口。

参数:

参数名 类型 必填 说明
table string 指定的目标表名。
values ValuesBucket values指示数据库中要更新的数据行。键值对与数据库表的列名相关联。
predicates dataSharePredicates.DataSharePredicates DataSharePredicates的实例对象指定的更新条件。
callback AsyncCallback<number> 指定的callback回调方法。返回受影响的行数。

错误码:

以下错误码的详细介绍请参见通用错误码关系型数据库错误码

错误码ID 错误信息
202 Permission verification failed, application which is not a system application uses system API.
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
14800000 Inner error.
14800011 Failed to open the database because it is corrupted.
14800014 The RdbStore or ResultSet is already closed.
14800015 The database does not respond.
14800021 SQLite: Generic error. Possible causes: Insert failed or the updated data does not exist.
14800022 SQLite: Callback routine requested an abort.
14800023 SQLite: Access permission denied.
14800024 SQLite: The database file is locked.
14800025 SQLite: A table in the database is locked.
14800026 SQLite: The database is out of memory.
14800027 SQLite: Attempt to write a readonly database.
14800028 SQLite: Some kind of disk I/O error occurred.
14800029 SQLite: The database is full.
14800030 SQLite: Unable to open the database file.
14800031 SQLite: TEXT or BLOB exceeds size limit.
14800032 SQLite: Abort due to constraint violation.
14800033 SQLite: Data type mismatch.
14800034 SQLite: Library used incorrectly.
14800047 The WAL file size exceeds the default limit.

示例:

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

let value1 = "Rose";
let value2 = 22;
let value3 = 200.5;
let value4 = new Uint8Array([1, 2, 3, 4, 5]);

// 以下三种方式可用
const valueBucket1: ValuesBucket = {
  'NAME': value1,
  'AGE': value2,
  'SALARY': value3,
  'CODES': value4,
};
const valueBucket2: ValuesBucket = {
  NAME: value1,
  AGE: value2,
  SALARY: value3,
  CODES: value4,
};
const valueBucket3: ValuesBucket = {
  "NAME": value1,
  "AGE": value2,
  "SALARY": value3,
  "CODES": value4,
};

let predicates = new dataSharePredicates.DataSharePredicates();
predicates.equalTo("NAME", "Lisa");
if (store != undefined) {
  (store as relationalStore.RdbStore).update("EMPLOYEE", valueBucket1, predicates, (err, rows) => {
    if (err) {
      console.error(`Updated failed, code is ${err.code},message is ${err.message}`);
      return;
    }
    console.info(`Updated row count: ${rows}`);
  });
}

update

update(table: string, values: ValuesBucket, predicates: dataSharePredicates.DataSharePredicates):Promise<number>

根据DataSharePredicates的指定实例对象更新数据库中的数据,使用Promise异步回调。由于共享内存大小限制为2Mb,因此单条数据的大小需小于2Mb,否则会查询失败。

系统能力: SystemCapability.DistributedDataManager.RelationalStore.Core

模型约束: 此接口仅可在Stage模型下可用。

系统接口: 此接口为系统接口。

参数:

参数名 类型 必填 说明
table string 指定的目标表名。
values ValuesBucket values指示数据库中要更新的数据行。键值对与数据库表的列名相关联。
predicates dataSharePredicates.DataSharePredicates DataSharePredicates的实例对象指定的更新条件。

返回值

类型 说明
Promise<number> 指定的Promise回调方法。返回受影响的行数。

错误码:

以下错误码的详细介绍请参见通用错误码关系型数据库错误码

错误码ID 错误信息
202 Permission verification failed, application which is not a system application uses system API.
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
14800000 Inner error.
14800011 Failed to open the database because it is corrupted.
14800014 The RdbStore or ResultSet is already closed.
14800015 The database does not respond.
14800021 SQLite: Generic error. Possible causes: Insert failed or the updated data does not exist.
14800022 SQLite: Callback routine requested an abort.
14800023 SQLite: Access permission denied.
14800024 SQLite: The database file is locked.
14800025 SQLite: A table in the database is locked.
14800026 SQLite: The database is out of memory.
14800027 SQLite: Attempt to write a readonly database.
14800028 SQLite: Some kind of disk I/O error occurred.
14800029 SQLite: The database is full.
14800030 SQLite: Unable to open the database file.
14800031 SQLite: TEXT or BLOB exceeds size limit.
14800032 SQLite: Abort due to constraint violation.
14800033 SQLite: Data type mismatch.
14800034 SQLite: Library used incorrectly.
14800047 The WAL file size exceeds the default limit.

示例:

import { dataSharePredicates } from '@kit.ArkData';
import { ValuesBucket } from '@kit.ArkData';
import { BusinessError } from '@kit.BasicServicesKit';

let value1 = "Rose";
let value2 = 22;
let value3 = 200.5;
let value4 = new Uint8Array([1, 2, 3, 4, 5]);

// 以下三种方式可用
const valueBucket1: ValuesBucket = {
  'NAME': value1,
  'AGE': value2,
  'SALARY': value3,
  'CODES': value4,
};
const valueBucket2: ValuesBucket = {
  NAME: value1,
  AGE: value2,
  SALARY: value3,
  CODES: value4,
};
const valueBucket3: ValuesBucket = {
  "NAME": value1,
  "AGE": value2,
  "SALARY": value3,
  "CODES": value4,
};

let predicates = new dataSharePredicates.DataSharePredicates();
predicates.equalTo("NAME", "Lisa");
if (store != undefined) {
  (store as relationalStore.RdbStore).update("EMPLOYEE", valueBucket1, predicates).then(async (rows: Number) => {
    console.info(`Updated row count: ${rows}`);
  }).catch((err: BusinessError) => {
    console.error(`Updated failed, code is ${err.code},message is ${err.message}`);
  });
}

delete

delete(table: string, predicates: dataSharePredicates.DataSharePredicates, callback: AsyncCallback<number>):void

根据DataSharePredicates的指定实例对象从数据库中删除数据,使用callback异步回调。

系统能力: SystemCapability.DistributedDataManager.RelationalStore.Core

模型约束: 此接口仅可在Stage模型下可用。

系统接口: 此接口为系统接口。

参数:

参数名 类型 必填 说明
table string 指定的目标表名,不能为空字符串。
predicates dataSharePredicates.DataSharePredicates DataSharePredicates的实例对象指定的删除条件。
callback AsyncCallback<number> 指定callback回调函数。返回受影响的行数量。

错误码:

以下错误码的详细介绍请参见通用错误码关系型数据库错误码

错误码ID 错误信息
202 Permission verification failed, application which is not a system application uses system API.
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
14800000 Inner error.
14800011 Failed to open the database because it is corrupted.
14800014 The RdbStore or ResultSet is already closed.
14800015 The database does not respond.
14800021 SQLite: Generic error. Possible causes: Insert failed or the updated data does not exist.
14800022 SQLite: Callback routine requested an abort.
14800023 SQLite: Access permission denied.
14800024 SQLite: The database file is locked.
14800025 SQLite: A table in the database is locked.
14800026 SQLite: The database is out of memory.
14800027 SQLite: Attempt to write a readonly database.
14800028 SQLite: Some kind of disk I/O error occurred.
14800029 SQLite: The database is full.
14800030 SQLite: Unable to open the database file.
14800031 SQLite: TEXT or BLOB exceeds size limit.
14800032 SQLite: Abort due to constraint violation.
14800033 SQLite: Data type mismatch.
14800034 SQLite: Library used incorrectly.
14800047 The WAL file size exceeds the default limit.

示例:

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

let predicates = new dataSharePredicates.DataSharePredicates();
predicates.equalTo("NAME", "Lisa");
if (store != undefined) {
  (store as relationalStore.RdbStore).delete("EMPLOYEE", predicates, (err, rows) => {
    if (err) {
      console.error(`Delete failed, code is ${err.code},message is ${err.message}`);
      return;
    }
    console.info(`Delete rows: ${rows}`);
  });
}

delete

delete(table: string, predicates: dataSharePredicates.DataSharePredicates):Promise<number>

根据DataSharePredicates的指定实例对象从数据库中删除数据,使用Promise异步回调。

系统能力: SystemCapability.DistributedDataManager.RelationalStore.Core

模型约束: 此接口仅可在Stage模型下可用。

系统接口: 此接口为系统接口。

参数:

参数名 类型 必填 说明
table string 指定的目标表名。
predicates dataSharePredicates.DataSharePredicates DataSharePredicates的实例对象指定的删除条件。

返回值

类型 说明
Promise<number> Promise对象。返回受影响的行数。

错误码:

以下错误码的详细介绍请参见通用错误码关系型数据库错误码

错误码ID 错误信息
202 Permission verification failed, application which is not a system application uses system API.
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
14800000 Inner error.
14800011 Failed to open the database because it is corrupted.
14800014 The RdbStore or ResultSet is already closed.
14800015 The database does not respond.
14800021 SQLite: Generic error. Possible causes: Insert failed or the updated data does not exist.
14800022 SQLite: Callback routine requested an abort.
14800023 SQLite: Access permission denied.
14800024 SQLite: The database file is locked.
14800025 SQLite: A table in the database is locked.
14800026 SQLite: The database is out of memory.
14800027 SQLite: Attempt to write a readonly database.
14800028 SQLite: Some kind of disk I/O error occurred.
14800029 SQLite: The database is full.
14800030 SQLite: Unable to open the database file.
14800031 SQLite: TEXT or BLOB exceeds size limit.
14800032 SQLite: Abort due to constraint violation.
14800033 SQLite: Data type mismatch.
14800034 SQLite: Library used incorrectly.
14800047 The WAL file size exceeds the default limit.

示例:

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

let predicates = new dataSharePredicates.DataSharePredicates();
predicates.equalTo("NAME", "Lisa");
if (store != undefined) {
  (store as relationalStore.RdbStore).delete("EMPLOYEE", predicates).then((rows: Number) => {
    console.info(`Delete rows: ${rows}`);
  }).catch((err: BusinessError) => {
    console.error(`Delete failed, code is ${err.code},message is ${err.message}`);
  });
}

query10+

query(table: string, predicates: dataSharePredicates.DataSharePredicates, callback: AsyncCallback<ResultSet>):void

根据指定条件查询数据库中的数据,使用callback异步回调。由于共享内存大小限制为2Mb,因此单条数据的大小需小于2Mb,否则会查询失败。

系统能力: SystemCapability.DistributedDataManager.RelationalStore.Core

模型约束: 此接口仅可在Stage模型下可用。

系统接口: 此接口为系统接口。

参数:

参数名 类型 必填 说明
table string 指定的目标表名。
predicates dataSharePredicates.DataSharePredicates DataSharePredicates的实例对象指定的查询条件。
callback AsyncCallback<ResultSet> 指定callback回调函数。如果操作成功,则返回ResultSet对象。

错误码:

以下错误码的详细介绍请参见通用错误码关系型数据库错误码

错误码ID 错误信息
202 Permission verification failed, application which is not a system application uses system API.
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
14800000 Inner error.
14800014 The RdbStore or ResultSet is already closed.
14800015 The database does not respond.

示例:

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

let predicates = new dataSharePredicates.DataSharePredicates();
predicates.equalTo("NAME", "Rose");
if (store != undefined) {
  (store as relationalStore.RdbStore).query("EMPLOYEE", predicates, (err, resultSet) => {
    if (err) {
      console.error(`Query failed, code is ${err.code},message is ${err.message}`);
      return;
    }
    console.info(`ResultSet column names: ${resultSet.columnNames}, column count: ${resultSet.columnCount}`);
    // resultSet是一个数据集合的游标,默认指向第-1个记录,有效的数据从0开始。
    while (resultSet.goToNextRow()) {
      const id = resultSet.getLong(resultSet.getColumnIndex("ID"));
      const name = resultSet.getString(resultSet.getColumnIndex("NAME"));
      const age = resultSet.getLong(resultSet.getColumnIndex("AGE"));
      const salary = resultSet.getDouble(resultSet.getColumnIndex("SALARY"));
      console.info(`id=${id}, name=${name}, age=${age}, salary=${salary}`);
    }
    // 释放数据集的内存
    resultSet.close();
  });
}

query

query(table: string, predicates: dataSharePredicates.DataSharePredicates, columns: Array<string>, callback: AsyncCallback<ResultSet>):void

根据指定条件查询数据库中的数据,使用callback异步回调。由于共享内存大小限制为2Mb,因此单条数据的大小需小于2Mb,否则会查询失败。

系统能力: SystemCapability.DistributedDataManager.RelationalStore.Core

模型约束: 此接口仅可在Stage模型下可用。

系统接口: 此接口为系统接口。

参数:

参数名 类型 必填 说明
table string 指定的目标表名。
predicates dataSharePredicates.DataSharePredicates DataSharePredicates的实例对象指定的查询条件。
columns Array<string> 表示要查询的列。如果值为空,则查询应用于所有列。
callback AsyncCallback<ResultSet> 指定callback回调函数。如果操作成功,则返回ResultSet对象。

错误码:

以下错误码的详细介绍请参见通用错误码关系型数据库错误码

错误码ID 错误信息
202 Permission verification failed, application which is not a system application uses system API.
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
14800000 Inner error.
14800014 The RdbStore or ResultSet is already closed.
14800015 The database does not respond.

示例:

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

let predicates = new dataSharePredicates.DataSharePredicates();
predicates.equalTo("NAME", "Rose");
if (store != undefined) {
  (store as relationalStore.RdbStore).query("EMPLOYEE", predicates, ["ID", "NAME", "AGE", "SALARY", "CODES"], (err, resultSet) => {
    if (err) {
      console.error(`Query failed, code is ${err.code},message is ${err.message}`);
      return;
    }
    console.info(`ResultSet column names: ${resultSet.columnNames}, column count: ${resultSet.columnCount}`);
    // resultSet是一个数据集合的游标,默认指向第-1个记录,有效的数据从0开始。
    while (resultSet.goToNextRow()) {
      const id = resultSet.getLong(resultSet.getColumnIndex("ID"));
      const name = resultSet.getString(resultSet.getColumnIndex("NAME"));
      const age = resultSet.getLong(resultSet.getColumnIndex("AGE"));
      const salary = resultSet.getDouble(resultSet.getColumnIndex("SALARY"));
      console.info(`id=${id}, name=${name}, age=${age}, salary=${salary}`);
    }
    // 释放数据集的内存
    resultSet.close();
  });
}

query

query(table: string, predicates: dataSharePredicates.DataSharePredicates, columns?: Array<string>):Promise<ResultSet>

根据指定条件查询数据库中的数据,使用Promise异步回调。由于共享内存大小限制为2Mb,因此单条数据的大小需小于2Mb,否则会查询失败。

系统能力: SystemCapability.DistributedDataManager.RelationalStore.Core

模型约束: 此接口仅可在Stage模型下可用。

系统接口: 此接口为系统接口。

参数:

参数名 类型 必填 说明
table string 指定的目标表名。
predicates dataSharePredicates.DataSharePredicates DataSharePredicates的实例对象指定的查询条件。
columns Array<string> 表示要查询的列。如果值为空,则查询应用于所有列。

返回值

类型 说明
Promise<ResultSet> Promise对象。如果操作成功,则返回ResultSet对象。

错误码:

以下错误码的详细介绍请参见通用错误码关系型数据库错误码

错误码ID 错误信息
202 Permission verification failed, application which is not a system application uses system API.
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
14800000 Inner error.
14800014 The RdbStore or ResultSet is already closed.
14800015 The database does not respond.

示例:

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

let predicates = new dataSharePredicates.DataSharePredicates();
predicates.equalTo("NAME", "Rose");
if (store != undefined) {
  (store as relationalStore.RdbStore).query("EMPLOYEE", predicates, ["ID", "NAME", "AGE", "SALARY", "CODES"]).then((resultSet: relationalStore.ResultSet) => {
    console.info(`ResultSet column names: ${resultSet.columnNames}, column count: ${resultSet.columnCount}`);
    // resultSet是一个数据集合的游标,默认指向第-1个记录,有效的数据从0开始。
    while (resultSet.goToNextRow()) {
      const id = resultSet.getLong(resultSet.getColumnIndex("ID"));
      const name = resultSet.getString(resultSet.getColumnIndex("NAME"));
      const age = resultSet.getLong(resultSet.getColumnIndex("AGE"));
      const salary = resultSet.getDouble(resultSet.getColumnIndex("SALARY"));
      console.info(`id=${id}, name=${name}, age=${age}, salary=${salary}`);
    }
    // 释放数据集的内存
    resultSet.close();
  }).catch((err: BusinessError) => {
    console.error(`Query failed, code is ${err.code},message is ${err.message}`);
  });
}

cloudSync11+

cloudSync(mode: SyncMode, predicates: RdbPredicates, progress: Callback<ProgressDetails>, callback: AsyncCallback<void>): void

手动执行按条件进行端云同步,使用callback异步回调。使用该接口需要实现云同步功能。

说明:

从API version 18开始,手动执行端云同步时,设置谓词条件时新增支持指定资产下载能力。此时,同步模式需要设置为relationalStore.SyncMode.SYNC_MODE_CLOUD_FIRST

谓词中支持使用主键(必填)和资产(可选)作为同步条件:选择资产作为同步条件时,谓词仅支持equalTo;指定资产的数量较多时(最多支持指定50个资产),建议谓词中仅使用主键作为同步条件。

系统能力: SystemCapability.DistributedDataManager.CloudSync.Client

系统接口: 此接口为系统接口。

参数:

参数名 类型 必填 说明
mode SyncMode 表示数据库的同步模式。
predicates RdbPredicates 表示同步数据的谓词条件。
progress Callback<ProgressDetails> 用来处理数据库同步详细信息的回调函数。
callback AsyncCallback<void> 指定的callback回调函数,用于向调用者发送同步结果。

错误码:

以下错误码的详细介绍请参见通用错误码关系型数据库错误码

错误码ID 错误信息
202 if permission verification failed, application which is not a system application uses system API.
401 Parameter error. Possible causes: 1. Need 2 - 4 parameter(s). 2. The RdbStore must be not nullptr. 3. The mode must be a SyncMode of cloud. 4. The tablesNames must be not empty. 5. The progress must be a callback type. 6.The callback must be a function.
801 Capability not supported.
14800014 The RdbStore or ResultSet is already closed.

示例1:手动同步,同步模式为云端同步到本地设备

let predicates = new relationalStore.RdbPredicates("EMPLOYEE");
predicates.in("id", ["id1", "id2"]);

if (store != undefined) {
  (store as relationalStore.RdbStore).cloudSync(relationalStore.SyncMode.SYNC_MODE_CLOUD_FIRST, predicates, (progressDetail: relationalStore.ProgressDetails) => {
    console.info(`progress: ${progressDetail}`);
  }, (err) => {
    if (err) {
      console.error(`cloudSync failed, code is ${err.code},message is ${err.message}}`);
      return;
    }
    console.info('Cloud sync succeeded');
  });
};

示例2:指定资产下载

import { BusinessError } from '@kit.BasicServicesKit';

let predicates = new relationalStore.RdbPredicates("EMPLOYEE");
let asset: relationalStore.Asset = {
  name: "name",
  uri: "uri",
  path: "path",
  createTime: new Date().getTime().toString(),
  modifyTime: new Date().getTime().toString(),
  size: "1024"
};
// 谓词条件中指定主键和资产,asset为数据库的资产列
predicates.beginWrap().equalTo("id", "id1").and().equalTo("asset", asset).endWrap();

if (store != undefined) {
  (store as relationalStore.RdbStore).cloudSync(relationalStore.SyncMode.SYNC_MODE_CLOUD_FIRST, predicates, (progressDetail: relationalStore.ProgressDetails) => {
    console.info(`progress: ${progressDetail}`);
  }, (err) => {
    if (err) {
      console.error(`cloud sync failed, code is ${err.code},message is ${err.message}}`);
      return;
    }
    console.info('cloud sync succeeded');
  });
};

cloudSync11+

cloudSync(mode: SyncMode, predicates: RdbPredicates, progress: Callback<ProgressDetails>): Promise<void>

手动执行按条件进行端云同步,使用Promise异步处理。使用该接口需要实现云同步功能。

说明:

从API version 18开始,手动执行端云同步时,设置谓词条件时新增支持指定资产下载能力。此时,同步模式需要设置为relationalStore.SyncMode.SYNC_MODE_CLOUD_FIRST

谓词中支持使用主键(必填)和资产(可选)作为同步条件:选择资产作为同步条件时,谓词仅支持equalTo;指定资产的数量较多时(最多支持指定50个资产),建议谓词中仅使用主键作为同步条件。

系统能力: SystemCapability.DistributedDataManager.CloudSync.Client

系统接口: 此接口为系统接口。

参数:

参数名 类型 必填 说明
mode SyncMode 表示数据库的同步模式。
predicates RdbPredicates 表示同步数据的谓词条件。
progress Callback<ProgressDetails> 用来处理数据库同步详细信息的回调函数。

返回值

类型 说明
Promise<void> Promise对象,用于向调用者发送同步结果。

错误码:

以下错误码的详细介绍请参见通用错误码关系型数据库错误码

错误码ID 错误信息
202 if permission verification failed, application which is not a system application uses system API.
401 Parameter error. Possible causes: 1. Need 2 - 4 parameter(s). 2. The RdbStore must be not nullptr. 3. The mode must be a SyncMode of cloud. 4. The tablesNames must be not empty. 5. The progress must be a callback type.
801 Capability not supported.
14800014 The RdbStore or ResultSet is already closed.

示例1:手动同步,同步模式为云端同步到本地设备

import { BusinessError } from '@kit.BasicServicesKit';

let predicates = new relationalStore.RdbPredicates("EMPLOYEE");
predicates.in("id", ["id1", "id2"]);

if (store != undefined) {
  (store as relationalStore.RdbStore).cloudSync(relationalStore.SyncMode.SYNC_MODE_CLOUD_FIRST, predicates, (progressDetail: relationalStore.ProgressDetails) => {
    console.info(`progress: ${progressDetail}`);
  }).then(() => {
    console.info('cloud sync succeeded');
  }).catch((err: BusinessError) => {
    console.error(`cloud sync failed, code is ${err.code},message is ${err.message}}`);
  });
};

示例2:指定资产下载

import { BusinessError } from '@kit.BasicServicesKit';

let predicates = new relationalStore.RdbPredicates("EMPLOYEE");
let asset: relationalStore.Asset = {
  name: "name",
  uri: "uri",
  path: "path",
  createTime: new Date().getTime().toString(),
  modifyTime: new Date().getTime().toString(),
  size: "1024"
};
// 谓词条件中指定主键和资产,asset为数据库的资产列
predicates.beginWrap().equalTo("id", "id1").and().equalTo("asset", asset).endWrap();

if (store != undefined) {
  (store as relationalStore.RdbStore).cloudSync(relationalStore.SyncMode.SYNC_MODE_CLOUD_FIRST, predicates, (progressDetail: relationalStore.ProgressDetails) => {
    console.info(`progress: ${progressDetail}`);
  }).then(() => {
    console.info('Cloud sync succeeded');
  }).catch((err: BusinessError) => {
    console.error(`cloudSync failed, code is ${err.code},message is ${err.message}}`);
  });
};

querySharingResource11+

querySharingResource(predicates: RdbPredicates, columns?: Array<string>): Promise<ResultSet>

根据谓词条件匹配的数据记录查找对应记录的共享资源标识,返回查找的结果集。如果指定了列字段,则返回结果集中同时包含对应列的字段值,使用Promise异步回调。

系统能力: SystemCapability.DistributedDataManager.CloudSync.Client

系统接口: 此接口为系统接口。

参数:

参数名 类型 必填 说明
predicates RdbPredicates 表示查询的谓词条件。
columns Array<string> 表示要查找的列字段名。此参数不填时,返回的结果集中只包含共享资源标识字段。

返回值:

参数名 说明
Promise<ResultSet> Promise对象,返回查询的结果集。

错误码:

以下错误码的详细介绍请参见通用错误码关系型数据库错误码

错误码ID 错误信息
401 Parameter error. Possible causes: 1. Need 1 - 3 parameter(s)! 2. The RdbStore must be not nullptr. 3. The predicates must be an RdbPredicates. 4. The columns must be a string array.
801 Capability not supported.
14800000 Inner error.
14800011 Failed to open the database because it is corrupted.
14800014 The RdbStore or ResultSet is already closed.
14800015 The database does not respond.
14800021 SQLite: Generic error. Possible causes: Insert failed or the updated data does not exist.
14800022 SQLite: Callback routine requested an abort.
14800023 SQLite: Access permission denied.
14800024 SQLite: The database file is locked.
14800025 SQLite: A table in the database is locked.
14800026 SQLite: The database is out of memory.
14800027 SQLite: Attempt to write a readonly database.
14800028 SQLite: Some kind of disk I/O error occurred.
14800029 SQLite: The database is full.
14800030 SQLite: Unable to open the database file.
14800031 SQLite: TEXT or BLOB exceeds size limit.
14800032 SQLite: Abort due to constraint violation.
14800033 SQLite: Data type mismatch.
14800034 SQLite: Library used incorrectly.

示例:

import { BusinessError } from '@kit.BasicServicesKit';

let sharingResource: string;
let predicates = new relationalStore.RdbPredicates('test_table');
predicates.equalTo('data', 'data_test');
if (store != undefined) {
  (store as relationalStore.RdbStore).querySharingResource(predicates, ['uuid', 'data']).then((resultSet) => {
    if (!resultSet.goToFirstRow()) {
      console.error(`resultSet error`);
      return;
    }
    const res = resultSet.getString(resultSet.getColumnIndex(relationalStore.Field.SHARING_RESOURCE_FIELD));
    console.info(`sharing resource: ${res}`);
    sharingResource = res;
  }).catch((err: BusinessError) => {
    console.error(`query sharing resource failed, code is ${err.code},message is ${err.message}`);
  });
}

querySharingResource11+

querySharingResource(predicates: RdbPredicates, callback: AsyncCallback<ResultSet>): void

根据谓词条件匹配的数据记录查找对应记录的共享资源,返回查找的结果集,使用callback异步回调。

系统能力: SystemCapability.DistributedDataManager.CloudSync.Client

系统接口: 此接口为系统接口。

参数:

参数名 类型 必填 说明
predicates RdbPredicates 表示查询的谓词条件。
callback AsyncCallback<ResultSet> 回调函数。返回查询的结果集。

错误码:

以下错误码的详细介绍请参见通用错误码关系型数据库错误码

错误码ID 错误信息
401 Parameter error. Possible causes: 1. Need 1 - 3 parameter(s)! 2. The RdbStore must be not nullptr. 3. The predicates must be an RdbPredicates. 4. The columns must be a string array.
801 Capability not supported.
14800000 Inner error.
14800011 Failed to open the database because it is corrupted.
14800014 The RdbStore or ResultSet is already closed.
14800015 The database does not respond.
14800021 SQLite: Generic error. Possible causes: Insert failed or the updated data does not exist.
14800022 SQLite: Callback routine requested an abort.
14800023 SQLite: Access permission denied.
14800024 SQLite: The database file is locked.
14800025 SQLite: A table in the database is locked.
14800026 SQLite: The database is out of memory.
14800027 SQLite: Attempt to write a readonly database.
14800028 SQLite: Some kind of disk I/O error occurred.
14800029 SQLite: The database is full.
14800030 SQLite: Unable to open the database file.
14800031 SQLite: TEXT or BLOB exceeds size limit.
14800032 SQLite: Abort due to constraint violation.
14800033 SQLite: Data type mismatch.
14800034 SQLite: Library used incorrectly.

示例:

let sharingResource: string;
let predicates = new relationalStore.RdbPredicates('test_table');
predicates.equalTo('data', 'data_test');
if (store != undefined) {
  (store as relationalStore.RdbStore).querySharingResource(predicates, (err, resultSet) => {
    if (err) {
      console.error(`sharing resource failed, code is ${err.code},message is ${err.message}`);
      return;
    }
    if (!resultSet.goToFirstRow()) {
      console.error(`resultSet error`);
      return;
    }
    const res = resultSet.getString(resultSet.getColumnIndex(relationalStore.Field.SHARING_RESOURCE_FIELD));
    console.info(`sharing resource: ${res}`);
    sharingResource = res;
  });
}

querySharingResource11+

querySharingResource(predicates: RdbPredicates, columns: Array<string>, callback: AsyncCallback<ResultSet>): void

根据谓词条件匹配的数据记录查找对应记录的共享资源,返回查找到的共享资源的结果集,同时在结果集中返回谓词条件匹配的指定列名的字段值,使用callback异步回调。

系统能力: SystemCapability.DistributedDataManager.CloudSync.Client

系统接口: 此接口为系统接口。

参数:

参数名 类型 必填 说明
predicates RdbPredicates 表示查询的谓词条件。
columns Array<string> 表示要查找的列字段名。
callback AsyncCallback<ResultSet> 回调函数。返回查询的结果集。

错误码:

以下错误码的详细介绍请参见通用错误码关系型数据库错误码

错误码ID 错误信息
401 Parameter error. Possible causes: 1. Need 1 - 3 parameter(s)! 2. The RdbStore must be not nullptr. 3. The predicates must be an RdbPredicates. 4. The columns must be a string array.
801 Capability not supported.
14800000 Inner error.
14800011 Failed to open the database because it is corrupted.
14800014 The RdbStore or ResultSet is already closed.
14800015 The database does not respond.
14800021 SQLite: Generic error. Possible causes: Insert failed or the updated data does not exist.
14800022 SQLite: Callback routine requested an abort.
14800023 SQLite: Access permission denied.
14800024 SQLite: The database file is locked.
14800025 SQLite: A table in the database is locked.
14800026 SQLite: The database is out of memory.
14800027 SQLite: Attempt to write a readonly database.
14800028 SQLite: Some kind of disk I/O error occurred.
14800029 SQLite: The database is full.
14800030 SQLite: Unable to open the database file.
14800031 SQLite: TEXT or BLOB exceeds size limit.
14800032 SQLite: Abort due to constraint violation.
14800033 SQLite: Data type mismatch.
14800034 SQLite: Library used incorrectly.

示例:

let sharingResource: string;
let predicates = new relationalStore.RdbPredicates('test_table');
predicates.equalTo('data', 'data_test');
if (store != undefined) {
  (store as relationalStore.RdbStore).querySharingResource(predicates, ['uuid', 'data'], (err, resultSet) => {
    if (err) {
      console.error(`sharing resource failed, code is ${err.code},message is ${err.message}`);
      return;
    }
    if (!resultSet.goToFirstRow()) {
      console.error(`resultSet error`);
      return;
    }
    const res = resultSet.getString(resultSet.getColumnIndex(relationalStore.Field.SHARING_RESOURCE_FIELD));
    console.info(`sharing resource: ${res}`);
    sharingResource = res;
  });
}

lockCloudContainer12+

lockCloudContainer(): Promise<number>

手动对应用云端数据库加锁,使用Promise异步处理。

说明:

若手动加锁成功,则其他同账户设备的同应用禁止同步到云端。使用该接口需要实现云同步功能。

系统能力: SystemCapability.DistributedDataManager.RelationalStore.Core

系统接口: 此接口为系统接口。

返回值

类型 说明
Promise<number> Promise对象,如果加锁成功,返回锁的有效时长;如果加锁失败,返回0,单位:ms。

错误码:

以下错误码的详细介绍请参见通用错误码

错误码ID 错误信息
202 Permission verification failed, application which is not a system application uses system API.

示例:

import { BusinessError } from '@kit.BasicServicesKit';

if (store != undefined) {
  (store as relationalStore.RdbStore).lockCloudContainer().then((time: Number) => {
    console.info('lockCloudContainer succeeded time:' + time);
  }).catch((err: BusinessError) => {
    console.error(`lockCloudContainer failed, code is ${err.code},message is ${err.message}`);
  });
}

unlockCloudContainer12+

unlockCloudContainer(): Promise<void>

手动对应用云端数据库解锁,使用Promise异步处理。使用该接口需要实现云同步功能。

系统能力: SystemCapability.DistributedDataManager.RelationalStore.Core

系统接口: 此接口为系统接口。

返回值

类型 说明
Promise<void> 无返回结果的Promise对象。

错误码:

以下错误码的详细介绍请参见通用错误码

错误码ID 错误信息
202 Permission verification failed, application which is not a system application uses system API.

示例:

import { BusinessError } from '@kit.BasicServicesKit';

if (store != undefined) {
  (store as relationalStore.RdbStore).unlockCloudContainer().then(() => {
    console.info('unlockCloudContainer succeeded');
  }).catch((err: BusinessError) => {
    console.error(`unlockCloudContainer failed, code is ${err.code},message is ${err.message}`);
  });
}

restore12+

restore(): Promise<void>

从副本关系型数据库文件恢复数据库,使用Promise异步回调。此接口仅供HAMode为MAIN_REPLICA时使用,且不支持在事务中使用。

系统能力: SystemCapability.DistributedDataManager.RelationalStore.Core

系统接口: 此接口为系统接口。

返回值

类型 说明
Promise<void> 无返回结果的Promise对象。

错误码:

以下错误码的详细介绍请参见通用错误码关系型数据库错误码

错误码ID 错误信息
202 Permission verification failed, application which is not a system application uses system API.
14800000 Inner error.
14800010 Failed to open or delete the database by an invalid database path.
14800011 Failed to open the database because it is corrupted.
14800014 The RdbStore or ResultSet is already closed.
14800015 The database does not respond.
14800021 SQLite: Generic error. Possible causes: Insert failed or the updated data does not exist.
14800022 SQLite: Callback routine requested an abort.
14800023 SQLite: Access permission denied.
14800024 SQLite: The database file is locked.
14800025 SQLite: A table in the database is locked.
14800026 SQLite: The database is out of memory.
14800027 SQLite: Attempt to write a readonly database.
14800028 SQLite: Some kind of disk I/O error occurred.
14800029 SQLite: The database is full.
14800030 SQLite: Unable to open the database file.
14800031 SQLite: TEXT or BLOB exceeds size limit.
14800032 SQLite: Abort due to constraint violation.
14800033 SQLite: Data type mismatch.
14800034 SQLite: Library used incorrectly.

示例:

import { BusinessError } from '@kit.BasicServicesKit';

let store: relationalStore.RdbStore|undefined = undefined;
if (store != undefined) {
  let promiseRestore = (store as relationalStore.RdbStore).restore();
  promiseRestore.then(() => {
    console.info('Succeeded in restoring.');
  }).catch((err: BusinessError) => {
    console.error(`Failed to restore, code is ${err.code},message is ${err.message}`);
  });
}

ResultSet

提供通过查询数据库生成的数据库结果集的访问方法。结果集是指用户调用关系型数据库查询接口之后返回的结果集合,提供了多种灵活的数据访问方式,以便用户获取各项数据。

getFloat32Array12+

getFloat32Array(columnIndex: number): Float32Array

以浮点数组的形式获取当前行中指定列的值,仅可在向量数据库下可用。

系统能力: SystemCapability.DistributedDataManager.RelationalStore.Core

参数:

参数名 类型 必填 说明
columnIndex number 指定的列索引,从0开始。

返回值:

类型 说明
Float32Array 以浮点数组的形式返回指定列的值。

错误码:

以下错误码的详细介绍请参见通用错误码关系型数据库错误码

错误码ID 错误信息
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
801 The capability is not supported because the database is not a vector DB.
14800011 Failed to open the database because it is corrupted.
14800013 Resultset is empty or column index is out of bounds.
14800014 The RdbStore or ResultSet is already closed.
14800021 SQLite: Generic error. Possible causes: Insert failed or the updated data does not exist.
14800022 SQLite: Callback routine requested an abort.
14800023 SQLite: Access permission denied.
14800024 SQLite: The database file is locked.
14800025 SQLite: A table in the database is locked.
14800026 SQLite: The database is out of memory.
14800027 SQLite: Attempt to write a readonly database.
14800028 SQLite: Some kind of disk I/O error occurred.
14800029 SQLite: The database is full.
14800030 SQLite: Unable to open the database file.
14800031 SQLite: TEXT or BLOB exceeds size limit.
14800032 SQLite: Abort due to constraint violation.
14800033 SQLite: Data type mismatch.
14800034 SQLite: Library used incorrectly.

示例:

let resultSet: relationalStore.ResultSet|undefined;
if (resultSet != undefined) {
  const id = (resultSet as relationalStore.ResultSet).getFloat32Array(0);
}

你可能感兴趣的鸿蒙文章

harmony 鸿蒙ArkData(方舟数据管理)

harmony 鸿蒙Class (RdbPredicates)

harmony 鸿蒙arkts-apis-data-relationalStore-RdbStore

harmony 鸿蒙Interface (ResultSet)

harmony 鸿蒙Interface (Transaction)

harmony 鸿蒙Enums

harmony 鸿蒙Functions

harmony 鸿蒙Interfaces (其他)

harmony 鸿蒙Types

harmony 鸿蒙模块描述

0  赞