harmony 鸿蒙Functions

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

Functions

说明:

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

relationalStore.getRdbStore

getRdbStore(context: Context, config: StoreConfig, callback: AsyncCallback<RdbStore>): void

创建或打开已有的关系型数据库,开发者可以根据自己的需求配置config参数,然后通过RdbStore调用相关接口执行数据操作。使用callback异步回调。

对应沙箱路径下无数据库文件时,将创建数据库文件,文件创建位置详见StoreConfig。对应路径下已有数据库文件时,将打开已有数据库文件。

开发者在创建数据库时,应谨慎配置是否进行数据库加密的参数encrypt,数据库创建后,禁止对该参数进行修改。

当前开库的加密类型 本设备上创建该数据库时的加密类型 结果
非加密 加密 将数据库以加密方式打开。
加密 非加密 将数据库以非加密方式打开。

getRdbStore目前不支持多线程并发操作。

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

参数:

参数名 类型 必填 说明
context Context 应用的上下文。
FA模型的应用Context定义见Context
Stage模型的应用Context定义见Context
config StoreConfig 与此RDB存储相关的数据库配置。
callback AsyncCallback<RdbStore> 指定callback回调函数,返回RdbStore对象。

错误码:

以下错误码的详细介绍请参见通用错误码关系型数据库错误码。其中,14800011错误码处理可参考数据库备份与恢复

错误码ID 错误信息
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
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.
14801001 The operation is supported in the stage model only.
14801002 Invalid data group ID.
14800017 StoreConfig is changed.
14800020 The secret key is corrupted or lost.
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.
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.

示例:

FA模型示例:

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

let store: relationalStore.RdbStore|undefined = undefined;
let context = featureAbility.getContext();

const STORE_CONFIG: relationalStore.StoreConfig = {
  name: "RdbTest.db",
  securityLevel: relationalStore.SecurityLevel.S3
};

relationalStore.getRdbStore(context, STORE_CONFIG, async (err: BusinessError, rdbStore: relationalStore.RdbStore) => {
  if (err) {
    console.error(`Get RdbStore failed, code is ${err.code},message is ${err.message}`);
    return;
  }
  console.info('Get RdbStore successfully.');
  store = rdbStore;
  // 成功获取到 rdbStore 后执行后续操作
});

Stage模型示例:

import { UIAbility } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';

let store: relationalStore.RdbStore|undefined = undefined;

class EntryAbility extends UIAbility {
  onWindowStageCreate(windowStage: window.WindowStage) {
    const STORE_CONFIG: relationalStore.StoreConfig = {
      name: "RdbTest.db",
      securityLevel: relationalStore.SecurityLevel.S3
    };

    relationalStore.getRdbStore(this.context, STORE_CONFIG, async (err: BusinessError, rdbStore: relationalStore.RdbStore) => {
      if (err) {
        console.error(`Get RdbStore failed, code is ${err.code},message is ${err.message}`);
        return;
      }
      console.info('Get RdbStore successfully.');
      store = rdbStore;
      // 成功获取到 rdbStore 后执行后续操作
    });
  }
}

relationalStore.getRdbStore

getRdbStore(context: Context, config: StoreConfig): Promise<RdbStore>

创建或打开已有的关系型数据库,开发者可以根据自己的需求配置config参数,然后通过RdbStore调用相关接口执行数据操作。使用Promise异步回调。

对应沙箱路径下无数据库文件时,将创建数据库文件,文件创建位置详见StoreConfig。对应路径下已有数据库文件时,将打开已有数据库文件。

开发者在创建数据库时,应谨慎配置是否进行数据库加密的参数encrypt,数据库创建后,禁止对该参数进行修改。

当前开库的加密类型 本设备上创建该数据库时的加密类型 结果
非加密 加密 将数据库以加密方式打开。
加密 非加密 将数据库以非加密方式打开。

getRdbStore目前不支持多线程并发操作。

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

参数:

参数名 类型 必填 说明
context Context 应用的上下文。
FA模型的应用Context定义见Context
Stage模型的应用Context定义见Context
config StoreConfig 与此RDB存储相关的数据库配置。

返回值

类型 说明
Promise<RdbStore> Promise对象。返回RdbStore对象。

错误码:

以下错误码的详细介绍请参见通用错误码关系型数据库错误码。其中,14800011错误码处理可参考数据库备份与恢复

错误码ID 错误信息
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
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.
14801001 The operation is supported in the stage model only.
14801002 Invalid data group ID.
14800017 StoreConfig is changed.
14800020 The secret key is corrupted or lost.
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.
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.

示例:

FA模型示例:

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

let store: relationalStore.RdbStore|undefined = undefined;
let context = featureAbility.getContext();

const STORE_CONFIG: relationalStore.StoreConfig = {
  name: "RdbTest.db",
  securityLevel: relationalStore.SecurityLevel.S3
};

relationalStore.getRdbStore(context, STORE_CONFIG).then(async (rdbStore: relationalStore.RdbStore) => {
  store = rdbStore;
  console.info('Get RdbStore successfully.');
}).catch((err: BusinessError) => {
  console.error(`Get RdbStore failed, code is ${err.code},message is ${err.message}`);
});

Stage模型示例:

import { UIAbility } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';

let store: relationalStore.RdbStore|undefined = undefined;

class EntryAbility extends UIAbility {
  onWindowStageCreate(windowStage: window.WindowStage) {
    const STORE_CONFIG: relationalStore.StoreConfig = {
      name: "RdbTest.db",
      securityLevel: relationalStore.SecurityLevel.S3
    };

    relationalStore.getRdbStore(this.context, STORE_CONFIG).then(async (rdbStore: relationalStore.RdbStore) => {
      store = rdbStore;
      console.info('Get RdbStore successfully.');
    }).catch((err: BusinessError) => {
      console.error(`Get RdbStore failed, code is ${err.code},message is ${err.message}`);
    });
  }
}

relationalStore.deleteRdbStore

deleteRdbStore(context: Context, name: string, callback: AsyncCallback<void>): void

删除数据库文件,使用callback异步回调。

删除成功后,建议将数据库对象置为null。建立数据库时,若在StoreConfig中配置了自定义路径,则调用此接口进行删库无效,必须使用 deleteRdbStore 接口进行删库。

当使用向量数据库时,在调用deleteRdbStore接口前,应当确保向量数据库已打开的RdbStore和ResultSet均已成功关闭。

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

参数:

参数名 类型 必填 说明
context Context 应用的上下文。
FA模型的应用Context定义见Context
Stage模型的应用Context定义见Context
name string 数据库名称。
callback AsyncCallback<void> 指定callback回调函数。

错误码:

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

错误码ID 错误信息
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
14800000 Inner error.
14800010 Failed to open or delete the database by an invalid database path.

示例:

FA模型示例:

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

let store: relationalStore.RdbStore|undefined = undefined;
let context = featureAbility.getContext();

relationalStore.deleteRdbStore(context, "RdbTest.db", (err: BusinessError) => {
  if (err) {
    console.error(`Delete RdbStore failed, code is ${err.code},message is ${err.message}`);
    return;
  }
  store = undefined;
  console.info('Delete RdbStore successfully.');
});

Stage模型示例:

import { UIAbility } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';

let store: relationalStore.RdbStore|undefined = undefined;

class EntryAbility extends UIAbility {
  onWindowStageCreate(windowStage: window.WindowStage) {
    relationalStore.deleteRdbStore(this.context, "RdbTest.db", (err: BusinessError) => {
      if (err) {
        console.error(`Delete RdbStore failed, code is ${err.code},message is ${err.message}`);
        return;
      }
      store = undefined;
      console.info('Delete RdbStore successfully.');
    });
  }
}

relationalStore.deleteRdbStore

deleteRdbStore(context: Context, name: string): Promise<void>

使用指定的数据库文件配置删除数据库,使用Promise异步回调。

删除成功后,建议将数据库对象置为null。建立数据库时,若在StoreConfig中配置了自定义路径,则调用此接口进行删库无效,必须使用 deleteRdbStore 接口进行删库。

当使用向量数据库时,在调用deleteRdbStore接口前,应当确保向量数据库已打开的RdbStore和ResultSet均已成功关闭。

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

参数

参数名 类型 必填 说明
context Context 应用的上下文。
FA模型的应用Context定义见Context
Stage模型的应用Context定义见Context
name string 数据库名称。

返回值

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

错误码:

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

错误码ID 错误信息
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
14800000 Inner error.
14800010 Failed to open or delete the database by an invalid database path.

示例:

FA模型示例:

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

let store: relationalStore.RdbStore|undefined = undefined;
let context = featureAbility.getContext();

relationalStore.deleteRdbStore(context, "RdbTest.db").then(() => {
  store = undefined;
  console.info('Delete RdbStore successfully.');
}).catch((err: BusinessError) => {
  console.error(`Delete RdbStore failed, code is ${err.code},message is ${err.message}`);
});

Stage模型示例:

import { UIAbility } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';

let store: relationalStore.RdbStore|undefined = undefined;

class EntryAbility extends UIAbility {
  onWindowStageCreate(windowStage: window.WindowStage) {
    relationalStore.deleteRdbStore(this.context, "RdbTest.db").then(() => {
      store = undefined;
      console.info('Delete RdbStore successfully.');
    }).catch((err: BusinessError) => {
      console.error(`Delete RdbStore failed, code is ${err.code},message is ${err.message}`);
    });
  }
}

relationalStore.deleteRdbStore10+

deleteRdbStore(context: Context, config: StoreConfig, callback: AsyncCallback<void>): void

使用指定的数据库文件配置删除数据库,使用callback异步回调。

删除成功后,建议将数据库对象置为null。若数据库文件处于公共沙箱目录下,则删除数据库时必须使用该接口,当存在多个进程操作同一个数据库的情况,建议向其他进程发送数据库删除通知使其感知并处理。建立数据库时,若在StoreConfig中配置了自定义路径,则必须调用此接口进行删库。

当使用向量数据库时,在调用deleteRdbStore接口前,应当确保向量数据库已打开的RdbStore和ResultSet均已成功关闭。

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

参数:

参数名 类型 必填 说明
context Context 应用的上下文。
FA模型的应用Context定义见Context
Stage模型的应用Context定义见Context
config StoreConfig 与此RDB存储相关的数据库配置。
callback AsyncCallback&lt;void&gt; 指定callback回调函数。

错误码:

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

错误码ID 错误信息
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
14800000 Inner error.
14800010 Failed to open or delete the database by an invalid database path.
14801001 The operation is supported in the stage model only.
14801002 Invalid data group ID.

示例:

FA模型示例:

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

let store: relationalStore.RdbStore|undefined = undefined;
let context = featureAbility.getContext();

const STORE_CONFIG: relationalStore.StoreConfig = {
  name: "RdbTest.db",
  securityLevel: relationalStore.SecurityLevel.S3
};

relationalStore.deleteRdbStore(context, STORE_CONFIG, (err: BusinessError) => {
  if (err) {
    console.error(`Delete RdbStore failed, code is ${err.code},message is ${err.message}`);
    return;
  }
  store = undefined;
  console.info('Delete RdbStore successfully.');
});

Stage模型示例:

import { UIAbility } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';

let store: relationalStore.RdbStore|undefined = undefined;

class EntryAbility extends UIAbility {
  onWindowStageCreate(windowStage: window.WindowStage) {
    const STORE_CONFIG: relationalStore.StoreConfig = {
      name: "RdbTest.db",
      securityLevel: relationalStore.SecurityLevel.S3
    };
    relationalStore.deleteRdbStore(this.context, STORE_CONFIG, (err: BusinessError) => {
      if (err) {
        console.error(`Delete RdbStore failed, code is ${err.code},message is ${err.message}`);
        return;
      }
      store = undefined;
      console.info('Delete RdbStore successfully.');
    });
  }
}

relationalStore.deleteRdbStore10+

deleteRdbStore(context: Context, config: StoreConfig): Promise<void>

使用指定的数据库文件配置删除数据库,使用Promise异步回调。

删除成功后,建议将数据库对象置为null。若数据库文件处于公共沙箱目录下,则删除数据库时必须使用该接口,当存在多个进程操作同一个数据库的情况,建议向其他进程发送数据库删除通知使其感知并处理。建立数据库时,若在StoreConfig中配置了自定义路径,则必须调用此接口进行删库。

当使用向量数据库时,在调用deleteRdbStore接口前,应当确保向量数据库已打开的RdbStore和ResultSet均已成功关闭。

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

参数

参数名 类型 必填 说明
context Context 应用的上下文。
FA模型的应用Context定义见Context
Stage模型的应用Context定义见Context
config StoreConfig 与此RDB存储相关的数据库配置。

返回值

类型 说明
Promise&lt;void&gt; 无返回结果的Promise对象。

错误码:

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

错误码ID 错误信息
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
801 Capability not supported.
14800000 Inner error.
14800010 Failed to open or delete the database by an invalid database path.
14801001 The operation is supported in the stage model only.
14801002 Invalid data group ID.

示例:

FA模型示例:

import { featureAbility } from "@kit.AbilityKit";
import { BusinessError } from '@kit.BasicServicesKit';

let store: relationalStore.RdbStore|undefined = undefined;
let context = featureAbility.getContext();

const STORE_CONFIG: relationalStore.StoreConfig = {
  name: "RdbTest.db",
  securityLevel: relationalStore.SecurityLevel.S3
};

relationalStore.deleteRdbStore(context, STORE_CONFIG).then(() => {
  store = undefined;
  console.info('Delete RdbStore successfully.');
}).catch((err: BusinessError) => {
  console.error(`Delete RdbStore failed, code is ${err.code},message is ${err.message}`);
});

Stage模型示例:

import { UIAbility } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';

let store: relationalStore.RdbStore|undefined = undefined;

class EntryAbility extends UIAbility {
  onWindowStageCreate(windowStage: window.WindowStage) {
    const STORE_CONFIG: relationalStore.StoreConfig = {
      name: "RdbTest.db",
      securityLevel: relationalStore.SecurityLevel.S3
    };
    relationalStore.deleteRdbStore(this.context, STORE_CONFIG).then(() => {
      store = undefined;
      console.info('Delete RdbStore successfully.');
    }).catch((err: BusinessError) => {
      console.error(`Delete RdbStore failed, code is ${err.code},message is ${err.message}`);
    });
  }
}

relationalStore.isVectorSupported18+

isVectorSupported(): boolean

判断系统是否提供向量数据库能力。

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

返回值

类型 说明
boolean 系统具备向量数据库能力时返回true,否则返回false。

示例:

let result = relationalStore.isVectorSupported();

relationalStore.isTokenizerSupported18+

isTokenizerSupported(tokenizer: Tokenizer): boolean

判断当前平台是否支持传入的分词器,此为同步接口。

如果当前平台支持传入的分词器时,此接口返回值为true;反之,返回值为false。

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

参数:

参数名 类型 必填 说明
tokenizer Tokenizer 需要被判断是否支持的分词器。

返回值:

类型 说明
boolean true表示当前平台支持当前传入的分词器,false表示当前平台不支持当前传入的分词器。

错误码:

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

错误码ID 错误信息
401 Parameter error. Possible causes: Incorrect parameter types.

示例:

import { relationalStore } from '@kit.ArkData'; // 导入模块

let customType = relationalStore.Tokenizer.CUSTOM_TOKENIZER;
let customTypeSupported = relationalStore.isTokenizerSupported(customType);
console.info("custom tokenizer supported on current platform: " + customTypeSupported);

relationalStore.getInsertSqlInfo20+

getInsertSqlInfo(table: string, values: ValuesBucket, conflict?: ConflictResolution): SqlInfo

获取用于插入数据的SQL语句,此为同步接口。

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

参数:

参数名 类型 必填 说明
table string 要写入数据的数据库表名。
values ValuesBucket 要写入数据库中数据的字段信息以及对应的值信息。
conflict ConflictResolution 指定冲突解决模式。默认值是relationalStore.ConflictResolution.ON_CONFLICT_NONE。

返回值:

类型 说明
SqlInfo SqlInfo对象,其中sql为返回的sql语句,args为执行SQL中的参数信息。

错误码:

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

错误码ID 错误信息
14800001 Invalid args. Possible causes: 1. Empty conditions; 2. Missing GROUP BY clause.

示例:

import { relationalStore } from '@kit.ArkData'; // 导入模块
const bucket: relationalStore.ValuesBucket = {
  name: "Logitech",
  age: 18,
  sex: "man",
  desc: "asserter"
};
const sqlInfo: relationalStore.SqlInfo = relationalStore.getInsertSqlInfo(
  "USER",
  bucket,
  relationalStore.ConflictResolution.ON_CONFLICT_NONE
);

relationalStore.getUpdateSqlInfo20+

getUpdateSqlInfo(predicates: RdbPredicates, values: ValuesBucket, conflict?: ConflictResolution): SqlInfo

获取用于更新数据的SQL语句,此为同步接口。

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

参数:

参数名 类型 必填 说明
predicates RdbPredicates 与指定字段匹配的谓词。
values ValuesBucket 要写入数据库中数据的字段信息以及对应的值信息。
conflict ConflictResolution 指定冲突解决模式。 默认值是relationalStore.ConflictResolution.ON_CONFLICT_NONE。

返回值:

类型 说明
SqlInfo SqlInfo对象,其中sql为返回的sql语句,args为执行SQL中的参数信息。

错误码:

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

错误码ID 错误信息
14800001 Invalid arguments. Possible causes: 1. Empty conditions; 2. Missing GROUP BY clause.

示例:

import { relationalStore } from '@kit.ArkData'; // 导入模块

const bucket: relationalStore.ValuesBucket = {
  name: "Logitech",
  age: 18,
  sex: "man",
  desc: "asserter"
};
const predicates = new relationalStore.RdbPredicates("users");
const sqlInfo: relationalStore.SqlInfo = relationalStore.getUpdateSqlInfo(
  predicates,
  bucket,
  relationalStore.ConflictResolution.ON_CONFLICT_NONE
);

relationalStore.getDeleteSqlInfo20+

getDeleteSqlInfo(predicates: RdbPredicates): SqlInfo

获取用于删除数据的SQL语句,此为同步接口。

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

参数:

参数名 类型 必填 说明
predicates RdbPredicates 与指定字段匹配的谓词。

返回值:

类型 说明
SqlInfo SqlInfo对象,其中sql为返回的sql语句,args为执行SQL中的参数信息。

错误码:

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

错误码ID 错误信息
14800001 Invalid args. Possible causes: 1. Empty conditions; 2. Missing GROUP BY clause.

示例:

import { relationalStore } from '@kit.ArkData'; // 导入模块

const predicates = new relationalStore.RdbPredicates("users");
predicates.equalTo("tableName", "a");
predicates.notEqualTo("age", 18);
const sqlInfo: relationalStore.SqlInfo = relationalStore.getDeleteSqlInfo(predicates);

relationalStore.getQuerySqlInfo20+

getQuerySqlInfo(predicates: RdbPredicates, columns: Array<string>): SqlInfo

获取用于查询数据的SQL语句,此为同步接口。

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

参数:

参数名 类型 必填 说明
predicates RdbPredicates 与指定字段匹配的谓词。
columns Array<string> 要查询的列;如果不指定此参数,则查询所有列。

返回值:

类型 说明
SqlInfo SqlInfo对象,其中sql为返回的sql语句,args为执行SQL中的参数信息。

错误码:

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

错误码ID 错误信息
14800001 Invalid arguments. Possible causes: 1. Empty conditions; 2. Missing GROUP BY clause.

示例:

import { relationalStore } from '@kit.ArkData'; // 导入模块

const predicates = new relationalStore.RdbPredicates("users");
predicates.notEqualTo("age", 18);
predicates.equalTo("name", "zhangsan");
const sqlInfo: relationalStore.SqlInfo = relationalStore.getQuerySqlInfo(predicates);

你可能感兴趣的鸿蒙文章

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

harmony 鸿蒙Class (RdbPredicates)

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

harmony 鸿蒙Interface (ResultSet)

harmony 鸿蒙Interface (Transaction)

harmony 鸿蒙Enums

harmony 鸿蒙Interfaces (其他)

harmony 鸿蒙Types

harmony 鸿蒙模块描述

harmony 鸿蒙data_asset.h

0  赞