HarmonyOS API:@ohos.data.rdb (关系型数据库)

joytrian
发布于 2023-4-6 16:57
浏览
0收藏

版本:v3.1 Beta

@ohos.data.rdb (关系型数据库)

更新时间: 2023-02-17 09:19


关系型数据库(Relational Database,RDB)是一种基于关系模型来管理数据的数据库。


关系型数据库基于SQLite组件提供了一套完整的对本地数据库进行管理的机制,对外提供了一系列的增、删、改、查等接口,也可以直接运行用户输入的SQL语句来满足复杂的场景需要。当应用卸载后,其相关数据库会被自动清除。


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

  • ​RdbPredicates​​: 数据库中用来代表数据实体的性质、特征或者数据实体之间关系的词项,主要用来定义数据库的操作条件。
  • ​RdbStore​​:提供管理关系数据库(RDB)方法的接口。


说明

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

导入模块

import data_rdb from '@ohos.data.rdb';

data_rdb.getRdbStore

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

获得一个相关的RdbStore,操作关系型数据库,用户可以根据自己的需求配置RdbStore的参数,然后通过RdbStore调用相关接口可以执行相关的数据操作,使用callback异步回调。

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

参数:

参数名

类型

必填

说明

context

Context

应用的上下文。

FA模型的应用Context定义见​​Context​​。

Stage模型的应用Context定义见​​Context​​。

config

​StoreConfig​

与此RDB存储相关的数据库配置。

version

number

数据库版本。

目前暂不支持通过version自动识别数据库升级降级操作,只能由开发者自行维护。

callback

AsyncCallback<​​RdbStore​​>

指定callback回调函数,返回RdbStore对象。

示例:

FA模型示例:

// 获取context
import featureAbility from '@ohos.ability.featureAbility'
let context = featureAbility.getContext()

// 获取context后调用getRdbStore
const STORE_CONFIG = { name: "RdbTest.db"}
data_rdb.getRdbStore(context, STORE_CONFIG, 1, function (err, rdbStore) {
    if (err) {
        console.info("Get RdbStore failed, err: " + err)
        return
    }
    console.log("Get RdbStore successfully.")
})

Stage模型示例:

// 获取context
import UIAbility from '@ohos.app.ability.UIAbility'
let context
class EntryAbility extends UIAbility {
    onWindowStageCreate(windowStage){
        context = this.context
    }
}

// 获取context后调用getRdbStore
const STORE_CONFIG = { name: "RdbTest.db"}
data_rdb.getRdbStore(context, STORE_CONFIG, 1, function (err, rdbStore) {
    if (err) {
        console.info("Get RdbStore failed, err: " + err)
        return
    }
    console.log("Get RdbStore successfully.")
})

data_rdb.getRdbStore

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

获得一个相关的RdbStore,操作关系型数据库,用户可以根据自己的需求配置RdbStore的参数,然后通过RdbStore调用相关接口可以执行相关的数据操作,使用Promise异步回调。

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

参数:

参数名

类型

必填

说明

context

Context

应用的上下文。

FA模型的应用Context定义见​​Context​​。

Stage模型的应用Context定义见​​Context​​。

config

​StoreConfig​

与此RDB存储相关的数据库配置。

version

number

数据库版本。

目前暂不支持通过version自动识别数据库升级降级操作,只能由开发者自行维护。

返回值

类型

说明

Promise<​​RdbStore​​>

Promise对象。返回RdbStore对象。

示例:

FA模型示例:

// 获取context
import featureAbility from '@ohos.ability.featureAbility'
let context = featureAbility.getContext()

// 获取context后调用getRdbStore
const STORE_CONFIG = { name: "RdbTest.db" }
let promise = data_rdb.getRdbStore(context, STORE_CONFIG, 1);
promise.then(async (rdbStore) => {
    console.log("Get RdbStore successfully.")
}).catch((err) => {
    console.log("Get RdbStore failed, err: " + err)
})

Stage模型示例:

// 获取context
import UIAbility from '@ohos.app.ability.UIAbility'
let context
class EntryAbility extends UIAbility {
    onWindowStageCreate(windowStage){
        context = this.context
    }
}

// 获取context后调用getRdbStore
const STORE_CONFIG = { name: "RdbTest.db" }
let promise = data_rdb.getRdbStore(context, STORE_CONFIG, 1);
promise.then(async (rdbStore) => {
    console.log("Get RdbStore successfully.")
}).catch((err) => {
    console.log("Get RdbStore failed, err: " + err)
})

data_rdb.deleteRdbStore

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

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

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

参数:

参数名

类型

必填

说明

context

Context

应用的上下文。

FA模型的应用Context定义见​​Context​​。

Stage模型的应用Context定义见​​Context​​。

name

string

数据库名称。

callback

AsyncCallback<void>

指定callback回调函数。

示例:

FA模型示例:

// 获取context
import featureAbility from '@ohos.ability.featureAbility'
let context = featureAbility.getContext()

// 获取context后调用deleteRdbStore
data_rdb.deleteRdbStore(context, "RdbTest.db", function (err) {
    if (err) {
        console.info("Delete RdbStore failed, err: " + err)
        return
    }
    console.log("Delete RdbStore successfully.")
})

Stage模型示例:

// 获取context
import UIAbility from '@ohos.app.ability.UIAbility'
let context
class EntryAbility extends UIAbility {
    onWindowStageCreate(windowStage){
        context = this.context
    }
}

// 获取context后调用deleteRdbStore
data_rdb.deleteRdbStore(context, "RdbTest.db", function (err) {
    if (err) {
        console.info("Delete RdbStore failed, err: " + err)
        return
    }
    console.log("Delete RdbStore successfully.")
})

data_rdb.deleteRdbStore

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

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

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

参数

参数名

类型

必填

说明

context

Context

应用的上下文。

FA模型的应用Context定义见​​Context​​。

Stage模型的应用Context定义见​​Context​​。

name

string

数据库名称。

返回值

类型

说明

Promise<void>

无返回结果的Promise对象。

示例:

FA模型示例:

// 获取context
import featureAbility from '@ohos.ability.featureAbility'
let context = featureAbility.getContext()

// 获取context后调用deleteRdbStore
let promise = data_rdb.deleteRdbStore(context, "RdbTest.db")
promise.then(() => {
    console.log("Delete RdbStore successfully.")
}).catch((err) => {
    console.info("Delete RdbStore failed, err: " + err)
})

Stage模型示例:

// 获取context
import UIAbility from '@ohos.app.ability.UIAbility'
let context
class EntryAbility extends UIAbility {
    onWindowStageCreate(windowStage){
        context = this.context
    }
}

// 获取context后调用deleteRdbStore
let promise = data_rdb.deleteRdbStore(context, "RdbTest.db")
promise.then(()=>{
    console.log("Delete RdbStore successfully.")
}).catch((err) => {
    console.info("Delete RdbStore failed, err: " + err)
})

ValueType

用于表示允许的数据字段类型。

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

类型

说明

number

表示值类型为数字。

string

表示值类型为字符。

boolean

表示值类型为布尔值。

ValuesBucket

用于存储键值对的类型。

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

键类型

值类型

string

​ValueType​​| Uint8Array | null

SyncMode8+

指数据库同步模式。

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

名称

说明

SYNC_MODE_PUSH

0

表示数据从本地设备推送到远程设备。

SYNC_MODE_PULL

1

表示数据从远程设备拉至本地设备。

SubscribeType8+

描述订阅类型。

需要权限: ohos.permission.DISTRIBUTED_DATASYNC

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

名称

说明

SUBSCRIBE_TYPE_REMOTE

0

订阅远程数据更改。

RdbPredicates

表示关系型数据库(RDB)的谓词。该类确定RDB中条件表达式的值是true还是false。

constructor

constructor(name: string)

构造函数。

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

参数:

参数名

类型

必填

说明

name

string

数据库表名。

示例:

let predicates = new data_rdb.RdbPredicates("EMPLOYEE")

inDevices8+

inDevices(devices: Array<string>): RdbPredicates

同步分布式数据库时连接到组网内指定的远程设备。

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

参数:

参数名

类型

必填

说明

devices

Array<string>

指定的组网内的远程设备ID。

返回值

类型

说明

​RdbPredicates​

返回与指定字段匹配的谓词。

示例:

let predicates = new data_rdb.RdbPredicates("EMPLOYEE")
predicates.inDevices(['12345678abcde'])

inAllDevices8+

inAllDevices(): RdbPredicates

同步分布式数据库时连接到组网内所有的远程设备。

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

返回值

类型

说明

​RdbPredicates​

返回与指定字段匹配的谓词。

示例:

let predicates = new data_rdb.RdbPredicates("EMPLOYEE")
predicates.inAllDevices()

equalTo

equalTo(field: string, value: ValueType): RdbPredicates

配置谓词以匹配数据字段为ValueType且值等于指定值的字段。

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

参数:

参数名

类型

必填

说明

field

string

数据库表中的列名。

value

​ValueType​

指示要与谓词匹配的值。

返回值

类型

说明

​RdbPredicates​

返回与指定字段匹配的谓词。

示例:

let predicates = new data_rdb.RdbPredicates("EMPLOYEE")
predicates.equalTo("NAME", "lisi")

notEqualTo

notEqualTo(field: string, value: ValueType): RdbPredicates

配置谓词以匹配数据字段为ValueType且值不等于指定值的字段。

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

参数:

参数名

类型

必填

说明

field

string

数据库表中的列名。

value

​ValueType​

指示要与谓词匹配的值。

返回值

类型

说明

​RdbPredicates​

返回与指定字段匹配的谓词。

示例:

let predicates = new data_rdb.RdbPredicates("EMPLOYEE")
predicates.notEqualTo("NAME", "lisi")

beginWrap

beginWrap(): RdbPredicates

向谓词添加左括号。

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

返回值

类型

说明

​RdbPredicates​

返回带有左括号的Rdb谓词。

示例:

let predicates = new data_rdb.RdbPredicates("EMPLOYEE")
predicates.equalTo("NAME", "lisi")
    .beginWrap()
    .equalTo("AGE", 18)
    .or()
    .equalTo("SALARY", 200.5)
    .endWrap()

endWrap

endWrap(): RdbPredicates

向谓词添加右括号。

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

返回值

类型

说明

​RdbPredicates​

返回带有右括号的Rdb谓词。

示例:

let predicates = new data_rdb.RdbPredicates("EMPLOYEE")
predicates.equalTo("NAME", "lisi")
    .beginWrap()
    .equalTo("AGE", 18)
    .or()
    .equalTo("SALARY", 200.5)
    .endWrap()

or

or(): RdbPredicates

将或条件添加到谓词中。

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

返回值

类型

说明

​RdbPredicates​

返回带有或条件的Rdb谓词。

示例:

let predicates = new data_rdb.RdbPredicates("EMPLOYEE")
predicates.equalTo("NAME", "Lisa")
    .or()
    .equalTo("NAME", "Rose")

and

and(): RdbPredicates

向谓词添加和条件。

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

返回值

类型

说明

​RdbPredicates​

返回带有和条件的Rdb谓词。

示例:

let predicates = new data_rdb.RdbPredicates("EMPLOYEE")
predicates.equalTo("NAME", "Lisa")
    .and()
    .equalTo("SALARY", 200.5)

contains

contains(field: string, value: string): RdbPredicates

配置谓词以匹配数据字段为string且value包含指定值的字段。

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

参数:

参数名

类型

必填

说明

field

string

数据库表中的列名。

value

string

指示要与谓词匹配的值。

返回值

类型

说明

​RdbPredicates​

返回与指定字段匹配的谓词。

示例:

let predicates = new data_rdb.RdbPredicates("EMPLOYEE")
predicates.contains("NAME", "os")

beginsWith

beginsWith(field: string, value: string): RdbPredicates

配置谓词以匹配数据字段为string且值以指定字符串开头的字段。

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

参数:

参数名

类型

必填

说明

field

string

数据库表中的列名。

value

string

指示要与谓词匹配的值。

返回值

类型

说明

​RdbPredicates​

返回与指定字段匹配的谓词。

示例:

let predicates = new data_rdb.RdbPredicates("EMPLOYEE")
predicates.beginsWith("NAME", "os")

endsWith

endsWith(field: string, value: string): RdbPredicates

配置谓词以匹配数据字段为string且值以指定字符串结尾的字段。

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

参数:

参数名

类型

必填

说明

field

string

数据库表中的列名。

value

string

指示要与谓词匹配的值。

返回值

类型

说明

​RdbPredicates​

返回与指定字段匹配的谓词。

示例:

let predicates = new data_rdb.RdbPredicates("EMPLOYEE")
predicates.endsWith("NAME", "se")

isNull

isNull(field: string): RdbPredicates

配置谓词以匹配值为null的字段。

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

参数:

参数名

类型

必填

说明

field

string

数据库表中的列名。

返回值

类型

说明

​RdbPredicates​

返回与指定字段匹配的谓词。

示例

let predicates = new data_rdb.RdbPredicates("EMPLOYEE")
predicates.isNull("NAME")

isNotNull

isNotNull(field: string): RdbPredicates

配置谓词以匹配值不为null的指定字段。

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

参数:

参数名

类型

必填

说明

field

string

数据库表中的列名。

返回值

类型

说明

​RdbPredicates​

返回与指定字段匹配的谓词。

示例:

let predicates = new data_rdb.RdbPredicates("EMPLOYEE")
predicates.isNotNull("NAME")

like

like(field: string, value: string): RdbPredicates

配置谓词以匹配数据字段为string且值类似于指定字符串的字段。

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

参数:

参数名

类型

必填

说明

field

string

数据库表中的列名。

value

string

指示要与谓词匹配的值。

返回值

类型

说明

​RdbPredicates​

返回与指定字段匹配的谓词。

示例:

let predicates = new data_rdb.RdbPredicates("EMPLOYEE")
predicates.like("NAME", "%os%")

glob

glob(field: string, value: string): RdbPredicates

配置RdbPredicates匹配数据字段为string的指定字段。

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

参数:

参数名

类型

必填

说明

field

string

数据库表中的列名。

value

string

指示要与谓词匹配的值。

支持通配符,*表示0个、1个或多个数字或字符,?表示1个数字或字符。

返回值

类型

说明

​RdbPredicates​

返回与指定字段匹配的谓词。

示例:

let predicates = new data_rdb.RdbPredicates("EMPLOYEE")
predicates.glob("NAME", "?h*g")

between

between(field: string, low: ValueType, high: ValueType): RdbPredicates

将谓词配置为匹配数据字段为ValueType且value在给定范围内的指定字段。

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

参数:

参数名

类型

必填

说明

field

string

数据库表中的列名。

low

​ValueType​

指示与谓词匹配的最小值。

high

​ValueType​

指示要与谓词匹配的最大值。

返回值

类型

说明

​RdbPredicates​

返回与指定字段匹配的谓词。

示例:

let predicates = new data_rdb.RdbPredicates("EMPLOYEE")
predicates.between("AGE", 10, 50)

notBetween

notBetween(field: string, low: ValueType, high: ValueType): RdbPredicates

配置RdbPredicates以匹配数据字段为ValueType且value超出给定范围的指定字段。

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

参数:

参数名

类型

必填

说明

field

string

数据库表中的列名。

low

​ValueType​

指示与谓词匹配的最小值。

high

​ValueType​

指示要与谓词匹配的最大值。

返回值

类型

说明

​RdbPredicates​

返回与指定字段匹配的谓词。

示例:

let predicates = new data_rdb.RdbPredicates("EMPLOYEE")
predicates.notBetween("AGE", 10, 50)


文章转载自:​​https://developer.harmonyos.com/cn/docs/documentation/doc-references-V3/js-apis-data-rdb-0000001478181637-V3?catalogVersion=V3​

已于2023-4-6 16:57:37修改
收藏
回复
举报
回复
    相关推荐