From db0a31bf3c6f0bdfd8146fff5d229c73cdcc2d97 Mon Sep 17 00:00:00 2001 From: sun-dou Date: Thu, 17 Feb 2022 18:40:49 +0800 Subject: [PATCH 01/11] RDB Signed-off-by: sun-dou --- .../reference/apis/js-apis-data-rdb.md | 210 +++ .../reference/apis/js-apis-data-rdb.md.bak | 1348 +++++++++++++++++ 2 files changed, 1558 insertions(+) create mode 100644 zh-cn/application-dev/reference/apis/js-apis-data-rdb.md.bak diff --git a/zh-cn/application-dev/reference/apis/js-apis-data-rdb.md b/zh-cn/application-dev/reference/apis/js-apis-data-rdb.md index 225abf90184..8a3c77d4ccc 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-data-rdb.md +++ b/zh-cn/application-dev/reference/apis/js-apis-data-rdb.md @@ -153,6 +153,48 @@ constructor(name: string) let predicates = new data_rdb.RdbPredicates("EMPLOYEE") ``` +### inDevices + +inDevices(devices: Array): RdbPredicates; + + +同步分布式数据库时指定远程设备。 + + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | devices | Array | 是 | 指定的远程设备。 | + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | [RdbPredicates](#rdbpredicates) | 返回与指定字段匹配的谓词。 | + +- 示例： + ``` + let predicates = new data_rdb.RdbPredicates("EMPLOYEE") + predicates.inDevices(['device']) + ``` + +### inAllDevices + +inAllDevices(): RdbPredicates; + + +指定同步分布式数据库时连接到本地设备的所有远程设备。 + + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | [RdbPredicates](#rdbpredicates) | 返回与指定字段匹配的谓词。 | + +- 示例： + ``` + let predicates = new data_rdb.RdbPredicates("EMPLOYEE") + predicates.inAllDevices() + ``` ### equalTo @@ -1184,6 +1226,174 @@ executeSql(sql: string, bindArgs?: Array<ValueType>):Promise<void> promise.then(() => { console.info(TAG + 'delete done.')}) ``` + +### setDistributedTables + +setDistributedTables(tables: Array, callback: AsyncCallback): void; + +设置分布式列表，结果以callbck形式返回。 + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | tables | Array | 是 | 要设置的分布式列表表名 | + | callback | AsyncCallback<void> | 是 | 指定callback回调函数。 | + +- 示例： + ``` + rdbStore.setDistributedTables(['EMPLOYEE'], function () { + console.info(TAG + 'setDistributedTables done.')}) + ``` + + +### setDistributedTables + + setDistributedTables(tables: Array): Promise; + +设置分布式列表，结果以Promise形式返回。 + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | tables | Array | 是 | 要设置的分布式列表表名 | + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | Promise<void> | 指定Promise回调函数。 | + +- 示例： + ``` + let promise = rdbStore.setDistributedTables(['EMPLOYEE']) + promise.then(() => { + console.info(TAG + 'setDistributedTables done.')}) + ``` + +### obtainDistributedTableName + +obtainDistributedTableName(device: string, table: string, callback: AsyncCallback): void; + +根据本地表名获取指定远程设备的分布式表名。在查询远程设备数据库时，需要使用分布式表名, 结果以callbck形式返回。 + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | device | string | 是 | 远程设备 | + | table | string | 是 | 本地表名 | + | callback | AsyncCallback<string> | 是 | 指定callback回调函数。 | + +- 示例： + ``` + rdbStore.obtainDistributedTableName(deviceId, 'EMPLOYEE', function () { + console.info(TAG + 'obtainDistributedTableName done.')}) + ``` + + +### obtainDistributedTableName + + obtainDistributedTableName(device: string, table: string): Promise; + +根据本地表名获取指定远程设备的分布式表名。在查询远程设备数据库时，需要使用分布式表名，结果以Promise形式返回。 + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | device | string | 是 | 远程设备 | + | table | string | 是 | 本地表名 | + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | Promise<string> | 指定Promise回调函数。 | + +- 示例： + ``` + let promise = rdbStore.obtainDistributedTableName(deviceId, 'EMPLOYEE') + promise.then(() => { + console.info(TAG + 'obtainDistributedTableName done.')}) + ``` + +### sync + +sync(mode: SyncMode, predicates: RdbPredicates, callback: AsyncCallback>): void; + +在设备之间同步数据, 结果以callbck形式返回。 + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | mode | SyncMode | 是 | 指示同步模式。该值可以是推、拉。 | + | predicates | RdbPredicates | 是 | 约束同步数据和设备。 | + | callback | AsyncCallback<Array<[string, number]>> | 是 | 指定callback回调函数。 | + +- 示例： + ``` + rdbStore.sync(rdb.SyncMode.SYNC_MODE_PUSH, precdicate, function () { + console.info(TAG + 'sync done.')}) + ``` + + +### sync + + sync(mode: SyncMode, predicates: RdbPredicates): Promise>; + +在设备之间同步数据，结果以Promise形式返回。 + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | mode | SyncMode | 是 | 指示同步模式。该值可以是推、拉。 | + | predicates | RdbPredicates | 是 | 约束同步数据和设备。 | + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | Promise<Array<[string, number]>> | 指定Promise回调函数。 | + +- 示例： + ``` + let promise = rdbStore.sync(rdb.SyncMode.SYNC_MODE_PUSH, precdicate) + promise.then(() => { + console.info(TAG + 'sync done.')}) + ``` + +### on + +on(event: 'dataChange', type: SubscribeType, observer: Callback>): void; + +注册数据库的观察者。当分布式数据库中的数据发生更改时，将调用回调。 + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | type | SubscribeType | 是 | 指在{@code SubscribeType}中定义的订阅类型。 | + | observer | Callback> | 是 | 指分布式数据库中数据更改事件的观察者。 | + +- 示例： + ``` + rdbStore.on(rdb.SyncMode.SYNC_MODE_PUSH, precdicate, function () { + console.info(TAG + 'sync done.')}) + ``` + +### off + +off(event:'dataChange', type: SubscribeType, observer: Callback>): void; + +从数据库中删除指定类型的指定观察者, 结果以callbck形式返回。 + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | type | SubscribeType | 是 | 指在{@code SubscribeType}中定义的订阅类型。 | + | observer | Callback> | 是 | 指已注册的数据更改观察者。| + +- 示例： + ``` + rdbStore.on(rdb.SyncMode.SYNC_MODE_PUSH, precdicate, function () { + console.info(TAG + 'sync done.')}) + ``` + + ## StoreConfig 管理关系数据库配置。 diff --git a/zh-cn/application-dev/reference/apis/js-apis-data-rdb.md.bak b/zh-cn/application-dev/reference/apis/js-apis-data-rdb.md.bak new file mode 100644 index 00000000000..e25f042c7f6 --- /dev/null +++ b/zh-cn/application-dev/reference/apis/js-apis-data-rdb.md.bak @@ -0,0 +1,1348 @@ +# 关系型数据库 + +> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** +> 本模块首批接口从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形式返回。 + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | context | Context | 是 | 应用程序或功能的上下文 | + | config | [StoreConfig](#storeconfig) | 是 | 与此RDB存储相关的数据库配置。 | + | version | number | 是 | 数据库版本。 | + | callback | AsyncCallback<[RdbStore](#rdbstore)> | 是 | 指定callback回调函数。返回一个RdbStore。 | + +- 示例： + ``` + import Ability from '@ohos.application.Ability' + import data_rdb from '@ohos.data.rdb' + export default class MainAbility extends Ability { + const STORE_CONFIG = { name: "RdbTest.db"} + const SQL_CREATE_TABLE = "CREATE TABLE IF NOT EXISTS EMPLOYEE (ID INTEGER PRIMARY KEY AUTOINCREMENT, NAME TEXT NOT NULL, AGE INTEGER, SALARY REAL, CODES BLOB)" + data_rdb.getRdbStore(this.context, STORE_CONFIG, 1, function (err, rdbStore) { + rdbStore.executeSql(SQL_CREATE_TABLE) + console.info(TAG + 'create table done.') + }) + } + ``` + +## data_rdb.getRdbStore + +getRdbStore(context: Context, config: StoreConfig, version: number): Promise<RdbStore> + +获得一个相关的RdbStore，操作关系型数据库，用户可以根据自己的需求配置RdbStore的参数，然后通过RdbStore调用相关接口可以执行相关的数据操作，结果以Promise形式返回。 + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | context | Context | 是 | 应用程序或功能的上下文 | + | config | [StoreConfig](#storeconfig) | 是 | 与此RDB存储相关的数据库配置。 | + | version | number | 是 | 数据库版本。 | + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | Promise<[RdbStore](#rdbstore)> | 指定Promise回调函数。返回一个RdbStore。 | + +- 示例： + ``` + import Ability from '@ohos.application.Ability' + import data_rdb from '@ohos.data.rdb' + export default class MainAbility extends Ability { + const STORE_CONFIG = { name: "RdbTest.db" } + const SQL_CREATE_TABLE = "CREATE TABLE IF NOT EXISTS EMPLOYEE (ID INTEGER PRIMARY KEY AUTOINCREMENT, NAME TEXT NOT NULL, AGE INTEGER, SALARY REAL, CODES BLOB)" + let promise = data_rdb.getRdbStore(this.context, STORE_CONFIG, 1); + promise.then(async (rdbStore) => { + await rdbStore.executeSql(SQL_CREATE_TABLE, null) + }).catch((err) => { + expect(null).assertFail(); + }) + } + ``` + +## data_rdb.deleteRdbStore + +deleteRdbStore(context: Context, name: string, callback: AsyncCallback<void>): void + +删除数据库，结果以callback形式返回。 + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | context | Context | 是 | 应用程序或功能的上下文 | + | name | string | 是 | 数据库名称。 | + | callback | AsyncCallback<void> | 是 | 指定callback回调函数。如果数据库已删除，则为true；否则返回false。 | + +- 示例： + ``` + import Ability from '@ohos.application.Ability' + import data_rdb from '@ohos.data.rdb' + export default class MainAbility extends Ability { + data_rdb.deleteRdbStore(this.context, "RdbTest.db", function (err, rdbStore) { + console.info(TAG + 'delete store done.')}) + } + ``` + +## data_rdb.deleteRdbStore + +deleteRdbStore(context: Context, name: string): Promise<void> + +使用指定的数据库文件配置删除数据库，结果以Promise形式返回。 + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | context | Context | 是 | 应用程序或功能的上下文 | + | name | string | 是 | 数据库名称。 | + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | Promise<void> | 指定Promise回调函数。如果数据库已删除，则为true；否则返回false。 | + +- 示例： + ``` + import Ability from '@ohos.application.Ability' + import data_rdb from '@ohos.data.rdb' + export default class MainAbility extends Ability { + let promise = data_rdb.deleteRdbStore(this.context, "RdbTest.db") + promise.then(()=>{ + console.info(TAG + 'delete store done.') + }) + } + ``` + +## RdbPredicates + +表示关系型数据库（RDB）的谓词。该类确定RDB中条件表达式的值是true还是false。 + + +### constructor + +constructor(name: string) + + +构造函数。 + + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | name | string | 是 | 数据库表名。 | + +- 示例： + ``` + let predicates = new data_rdb.RdbPredicates("EMPLOYEE") + ``` + + +### equalTo + +equalTo(field: string, value: ValueType): RdbPredicates + + +配置谓词以匹配数据字段为ValueType且值等于指定值的字段。 + + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | field | string | 是 | 数据库表中的列名。 | + | value | [ValueType](#valuetype) | 是 | 指示要与谓词匹配的值。 | + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | [RdbPredicates](#rdbpredicates) | 返回与指定字段匹配的谓词。 | + +- 示例： + ``` + let predicates = new data_rdb.RdbPredicates("EMPLOYEE") + predicates.equalTo("NAME", "lisi") + ``` + + +### notEqualTo + +notEqualTo(field: string, value: ValueType): RdbPredicates + + +配置谓词以匹配数据字段为ValueType且值不等于指定值的字段。 + + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | field | string | 是 | 数据库表中的列名。 | + | value | [ValueType](#valuetype) | 是 | 指示要与谓词匹配的值。 | + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | [RdbPredicates](#rdbpredicates) | 返回与指定字段匹配的谓词。 | + +- 示例： + ``` + let predicates = new data_rdb.RdbPredicates("EMPLOYEE") + predicates.notEqualTo("NAME", "lisi") + ``` + + +### beginWrap + +beginWrap(): RdbPredicates + + +向谓词添加左括号。 + + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | [RdbPredicates](#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 + + +向谓词添加右括号。 + + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | [RdbPredicates](#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 + + +将或条件添加到谓词中。 + + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | [RdbPredicates](#rdbpredicates) | 返回带有或条件的Rdb谓词。 | + +- 示例： + ``` + let predicates = new data_rdb.RdbPredicates("EMPLOYEE") + predicates.equalTo("NAME", "Lisa") + .or() + .equalTo("NAME", "Rose") + ``` + + +### and + +and(): RdbPredicates + + +向谓词添加和条件。 + + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | [RdbPredicates](#rdbpredicates) | 返回带有和条件的Rdb谓词。 | + +- 示例： + ``` + let predicates = new data_rdb.RdbPredicates("EMPLOYEE") + predicates.equalTo("NAME", "Lisa") + .and() + .equalTo("SALARY", 200.5) + ``` + + +### contains + +contains(field: string, value: string): RdbPredicat + + +配置谓词以匹配数据字段为String且value包含指定值的字段。 + + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | field | string | 是 | 数据库表中的列名。 | + | value | string | 是 | 指示要与谓词匹配的值。 | + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | [RdbPredicates](#rdbpredicates) | 返回与指定字段匹配的谓词。 | + +- 示例： + ``` + let predicates = new data_rdb.RdbPredicates("EMPLOYEE") + predicates.contains("NAME", "os") + ``` + + +### beginsWith + +beginsWith(field: string, value: string): RdbPredicates + + +配置谓词以匹配数据字段为String且值以指定字符串开头的字段。 + + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | field | string | 是 | 数据库表中的列名。 | + | value | string | 是 | 指示要与谓词匹配的值。 | + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | [RdbPredicates](#rdbpredicates) | 返回与指定字段匹配的谓词。 | + +- 示例： + ``` + let predicates = new data_rdb.RdbPredicates("EMPLOYEE") + predicates.beginsWith("NAME", "os") + ``` + + +### endsWith + +endsWith(field: string, value: string): RdbPredicates + + +配置谓词以匹配数据字段为String且值以指定字符串结尾的字段。 + + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | field | string | 是 | 数据库表中的列名。 | + | value | string | 是 | 指示要与谓词匹配的值。 | + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | [RdbPredicates](#rdbpredicates) | 返回与指定字段匹配的谓词。 | + +- 示例： + ``` + let predicates = new data_rdb.RdbPredicates("EMPLOYEE") + predicates.endsWith("NAME", "se") + ``` + + +### isNull + +isNull(field: string): RdbPredicates + + +配置谓词以匹配值为null的字段。 + + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | field | string | 是 | 数据库表中的列名。 | + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | [RdbPredicates](#rdbpredicates) | 返回与指定字段匹配的谓词。 | + +- 示例 + ``` + let predicates = new data_rdb.RdbPredicates("EMPLOYEE") + predicates.isNull("NAME") + ``` + + +### isNotNull + +isNotNull(field: string): RdbPredicates + + +配置谓词以匹配值不为null的指定字段。 + + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | field | string | 是 | 数据库表中的列名。 | + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | [RdbPredicates](#rdbpredicates) | 返回与指定字段匹配的谓词。 | + +- 示例： + ``` + let predicates = new data_rdb.RdbPredicates("EMPLOYEE") + predicates.isNotNull("NAME") + ``` + + +### like + +like(field: string, value: string): RdbPredicates + + +配置谓词以匹配数据字段为String且值类似于指定字符串的字段。 + + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | field | string | 是 | 数据库表中的列名。 | + | value | string | 是 | 指示要与谓词匹配的值。 | + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | [RdbPredicates](#rdbpredicates) | 返回与指定字段匹配的谓词。 | + +- 示例： + ``` + let predicates = new data_rdb.RdbPredicates("EMPLOYEE") + predicates.like("NAME", "%os%") + ``` + + +### glob + +glob(field: string, value: string): RdbPredicates + + +配置RdbPredicates匹配数据字段为String的指定字段。 + + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | field | string | 是 | 数据库表中的列名。 | + | value | string | 是 | 指示要与谓词匹配的值。
支持通配符，*表示0个、1个或多个数字或字符，?表示1个数字或字符。 | + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | [RdbPredicates](#rdbpredicates) | 返回与指定字段匹配的谓词。 | + +- 示例： + ``` + let predicates = new data_rdb.RdbPredicates("EMPLOYEE") + predicates.glob("NAME", "?h*g") + ``` + + +### between + +between(field: string, low: ValueType, high: ValueType): RdbPredicates + + +将谓词配置为匹配数据字段为ValueType且value在给定范围内的指定字段。 + + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | field | string | 是 | 数据库表中的列名。 | + | low | [ValueType](#valuetype) | 是 | 指示与谓词匹配的最小值。 | + | high | [ValueType](#valuetype) | 是 | 指示要与谓词匹配的最大值。 | + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | [RdbPredicates](#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超出给定范围的指定字段。 + + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | field | string | 是 | 数据库表中的列名。 | + | low | [ValueType](#valuetype) | 是 | 指示与谓词匹配的最小值。 | + | high | [ValueType](#valuetype) | 是 | 指示要与谓词匹配的最大值。 | + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | [RdbPredicates](#rdbpredicates) | 返回与指定字段匹配的谓词。 | + +- 示例： + ``` + let predicates = new data_rdb.RdbPredicates("EMPLOYEE") + predicates.notBetween("AGE", 10, 50) + ``` + + +### greaterThan + +greaterThan(field: string, value: ValueType): RdbPredicatesgr + + +配置谓词以匹配数据字段为ValueType且值大于指定值的字段。 + + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | field | string | 是 | 数据库表中的列名。 | + | value | [ValueType](#valuetype) | 是 | 指示要与谓词匹配的值。 | + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | [RdbPredicates](#rdbpredicates) | 返回与指定字段匹配的谓词。 | + +- 示例： + ``` + let predicates = new data_rdb.RdbPredicates("EMPLOYEE") + predicates.greaterThan("AGE", 18) + ``` + + +### lessThan + +lessThan(field: string, value: ValueType): RdbPredicates + + +配置谓词以匹配数据字段为valueType且value小于指定值的字段。 + + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | field | string | 是 | 数据库表中的列名。 | + | value | [ValueType](#valuetype) | 是 | 指示要与谓词匹配的值。 | + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | [RdbPredicates](#rdbpredicates) | 返回与指定字段匹配的谓词。 | + +- 示例： + ``` + let predicates = new data_rdb.RdbPredicates("EMPLOYEE") + predicates.lessThan("AGE", 20) + ``` + + +### greaterThanOrEqualTo + + +greaterThanOrEqualTo(field: string, value: ValueType): RdbPredicates + + +配置谓词以匹配数据字段为ValueType且value大于或等于指定值的字段。 + + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | field | string | 是 | 数据库表中的列名。 | + | value | [ValueType](#valuetype) | 是 | 指示要与谓词匹配的值。 | + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | [RdbPredicates](#rdbpredicates) | 返回与指定字段匹配的谓词。 | + +- 示例： + ``` + let predicates = new data_rdb.RdbPredicates("EMPLOYEE") + predicates.greaterThanOrEqualTo("AGE", 18) + ``` + + +### lessThanOrEqualTo + + +lessThanOrEqualTo(field: string, value: ValueType): RdbPredicates + + +配置谓词以匹配数据字段为ValueType且value小于或等于指定值的字段。 + + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | field | string | 是 | 数据库表中的列名。 | + | value | [ValueType](#valuetype) | 是 | 指示要与谓词匹配的值。 | + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | [RdbPredicates](#rdbpredicates) | 返回与指定字段匹配的谓词。 | + +- 示例： + ``` + let predicates = new data_rdb.RdbPredicates("EMPLOYEE") + predicates.lessThanOrEqualTo("AGE", 20) + ``` + + +### orderByAsc + + +orderByAsc(field: string): RdbPredicates + + +配置谓词以匹配其值按升序排序的列。 + + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | field | string | 是 | 数据库表中的列名。 | + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | [RdbPredicates](#rdbpredicates) | 返回与指定字段匹配的谓词。 | + +- 示例： + ``` + let predicates = new data_rdb.RdbPredicates("EMPLOYEE") + predicates.orderByAsc("NAME") + ``` + + +### orderByDesc + + +orderByDesc(field: string): RdbPredicates + + +配置谓词以匹配其值按降序排序的列。 + + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | field | string | 是 | 数据库表中的列名。 | + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | [RdbPredicates](#rdbpredicates) | 返回与指定字段匹配的谓词。 | + +- 示例： + ``` + let predicates = new data_rdb.RdbPredicates("EMPLOYEE") + predicates.orderByDesc("AGE") + ``` + + +### distinct + +distinct(): RdbPredicates + + +配置谓词以过滤重复记录并仅保留其中一个。 + + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | [RdbPredicates](#rdbpredicates) | 返回可用于过滤重复记录的谓词。 | + +- 示例： + ``` + let predicates = new data_rdb.RdbPredicates("EMPLOYEE") + predicates.equalTo("NAME", "Rose").distinct("NAME") + let resultSet = await rdbStore.query(predicates, ["NAME"]) + ``` + + +### limitAs + +limitAs(value: number): RdbPredicates + + +设置最大数据记录数的谓词。 + + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 最大数据记录数。 | + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | [RdbPredicates](#rdbpredicates) | 返回可用于设置最大数据记录数的谓词。 | + +- 示例： + ``` + let predicates = new data_rdb.RdbPredicates("EMPLOYEE") + predicates.equalTo("NAME", "Rose").limitAs(3) + ``` + + +### offsetAs + +offsetAs(rowOffset: number): RdbPredicates + + +配置RdbPredicates以指定返回结果的起始位置。 + + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | rowOffset | number | 是 | 返回结果的起始位置，取值为正整数。 | + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | [RdbPredicates](#rdbpredicates) | 返回具有指定返回结果起始位置的谓词。 | + +- 示例： + ``` + let predicates = new data_rdb.RdbPredicates("EMPLOYEE") + predicates.equalTo("NAME", "Rose").offsetAs(3) + ``` + + +### groupBy + +groupBy(fields: Array<string>): RdbPredicates + + +配置RdbPredicates按指定列分组查询结果。 + + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | fields | Array<string> | 是 | 指定分组依赖的列名。 | + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | [RdbPredicates](#rdbpredicates) | 返回分组查询列的谓词。 | + +- 示例： + ``` + let predicates = new data_rdb.RdbPredicates("EMPLOYEE") + predicates.groupBy(["AGE", "NAME"]) + ``` + + +### indexedBy + +indexedBy(indexName: string): RdbPredicates + + +配置RdbPredicates以指定索引列。 + + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | indexName | string | 是 | 索引列的名称。 | + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | [RdbPredicates](#rdbpredicates) | 返回具有指定索引列的RdbPredicates。 | + +- 示例： + ``` + let predicates = new data_rdb.RdbPredicates("EMPLOYEE") + predicates.indexedBy("SALARY_INDEX") + ``` + + +### in + +in(field: string, value: Array<ValueType>): RdbPredicates + + +配置RdbPredicates以匹配数据字段为ValueType数组且值在给定范围内的指定字段。 + + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | field | string | 是 | 数据库表中的列名。 | + | value | Array<[ValueType](#valuetype)> | 是 | 以ValueType型数组形式指定的要匹配的值。 | + + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | [RdbPredicates](#rdbpredicates) | 返回与指定字段匹配的谓词。 | + +- 示例： + ``` + let predicates = new data_rdb.RdbPredicates("EMPLOYEE") + predicates.in("AGE", [18, 20]) + ``` + + +### notIn + +notIn(field: string, value: Array<ValueType>): RdbPredicates + + +将RdbPredicates配置为匹配数据字段为ValueType且值超出给定范围的指定字段。 + + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | field | string | 是 | 数据库表中的列名。 | + | value | Array<[ValueType](#valuetype)> | 是 | 以ValueType数组形式指定的要匹配的值。 | + + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | [RdbPredicates](#rdbpredicates) | 返回与指定字段匹配的谓词。 | + +- 示例： + ``` + let predicates = new data_rdb.RdbPredicates("EMPLOYEE") + predicates.notIn("NAME", ["Lisa", "Rose"]) + ``` + + +## RdbStore + +提供管理关系数据库(RDB)方法的接口。 + + +### insert + +insert(name: string, values: ValuesBucket, callback: AsyncCallback<number>):void + +向目标表中插入一行数据，结果以callback形式返回。 + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | name | string | 是 | 指定的目标表名。 | + | values | [ValuesBucket](#valuesbucket) | 是 | 表示要插入到表中的数据行。 | + | callback | AsyncCallback<number> | 是 | 指定callback回调函数。如果操作成功，返回行ID；否则返回-1。 | + +- 示例： + ``` + const valueBucket = { + "NAME": "Lisa", + "AGE": 18, + "SALARY": 100.5, + "CODES": new Uint8Array([1, 2, 3, 4, 5]), + } + rdbStore.insert("EMPLOYEE", valueBucket, function (err, ret) { + expect(1).assertEqual(ret) + console.log(TAG + "insert first done: " + ret)}) + ``` + + +### insert + +insert(name: string, values: ValuesBucket):Promise<number> + +向目标表中插入一行数据，结果以Promise形式返回。 + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | name | string | 是 | 指定的目标表名。 | + | values | [ValuesBucket](#valuesbucket) | 是 | 表示要插入到表中的数据行。 | + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | Promise<number> | 指定Promise回调函数。如果操作成功，返回行ID；否则返回-1。 | + +- 示例： + ``` + const valueBucket = { + "NAME": "Lisa", + "AGE": 18, + "SALARY": 100.5, + "CODES": new Uint8Array([1, 2, 3, 4, 5]), + } + let promise = rdbStore.insert("EMPLOYEE", valueBucket) + promise.then(async (ret) => { + await console.log(TAG + "insert first done: " + ret) + }).catch((err) => {}) + ``` + + +### update + +update(values: ValuesBucket, rdbPredicates: RdbPredicates, callback: AsyncCallback<number>):void + +根据RdbPredicates的指定实例对象更新数据库中的数据，结果以callback形式返回。 + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | values | [ValuesBucket](#valuesbucket) | 是 | value指示数据库中要更新的数据行。键值对与数据库表的列名相关联 | + | rdbPredicates | [RdbPredicates](#rdbpredicates) | 是 | 表示要插入到表中的数据行。 | + | callback | AsyncCallback<number> | 是 | 指定的callback回调方法。返回受影响的行数。 | + +- 示例： + ``` + const valueBucket = { + "NAME": "Rose", + "AGE": 22, + "SALARY": 200.5, + "CODES": new Uint8Array([1, 2, 3, 4, 5]), + } + let predicates = new data_rdb.RdbPredicates("EMPLOYEE") + predicates.equalTo("NAME", "Lisa") + rdbStore.update(valueBucket, predicates, function (err, ret) { + console.log(TAG + "updated row count: " + changedRows)}) + ``` + + +### update + +update(values: ValuesBucket, rdbPredicates: RdbPredicates):Promise<number> + +根据RdbPredicates的指定实例对象更新数据库中的数据，结果以Promise形式返回。 + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | values | [ValuesBucket](#valuesbucket) | 是 | value指示数据库中要更新的数据行。键值对与数据库表的列名相关联 | + | rdbPredicates | [RdbPredicates](#rdbpredicates) | 是 | 表示要插入到表中的数据行。 | + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | Promise<number> | 指定的Promise回调方法。返回受影响的行数。 | + +- 示例： + ``` + const valueBucket = { + "NAME": "Rose", + "AGE": 22, + "SALARY": 200.5, + "CODES": new Uint8Array([1, 2, 3, 4, 5]), + } + let predicates = new data_rdb.RdbPredicates("EMPLOYEE") + predicates.equalTo("NAME", "Lisa") + let promise = rdbStore.update(valueBucket, predicates) + promise.then(async (ret) => { + await console.log(TAG + "updated row count: " + changedRows) + }).catch((err) => {}) + ``` + + +### delete + +delete(rdbPredicates: RdbPredicates, callback: AsyncCallback<number>):void + + +根据rdbPredicates的指定实例对象从数据库中删除数据，结果以callback形式返回。 + + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | rdbPredicates | [RdbPredicates](#rdbpredicates) | 是 | RdbPredicates的实例对象指定的删除条件。 | + | callback | AsyncCallback<number> | 是 | 指定callback回调函数。返回受影响的行数。 | + +- 示例： + ``` + let predicates = new data_rdb.RdbPredicates("EMPLOYEE") + predicates.equalTo("NAME", "Lisa") + rdbStore.delete(predicates, function (err, rows) { + console.log(TAG + "delete rows: " + rows)}) + ``` + + +### delete + +delete(rdbPredicates: RdbPredicates):Promise<number> + +根据rdbPredicates的指定实例对象从数据库中删除数据，结果以Promise形式返回。 + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | rdbPredicates | [RdbPredicates](#rdbpredicates) | 是 | RdbPredicates的实例对象指定的删除条件。 | + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | Promise<number> | 指定Promise回调函数。返回受影响的行数。 | + +- 示例： + ``` + let predicates = new data_rdb.RdbPredicates("EMPLOYEE") + predicates.equalTo("NAME", "Lisa") + let promise = rdbStore.delete(predicates) + promise.then((rows) => { + console.log(TAG + "delete rows: " + rows) + }).catch((err) => {}) + ``` + + +### query + +query(rdbPredicates: RdbPredicates, columns: Array<string>, callback: AsyncCallback<ResultSet>):void + +根据指定条件查询数据库中的数据，结果以callback形式返回。 + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | rdbPredicates | [RdbPredicates](#rdbpredicates) | 是 | 表示rdbPredicates的实例对象指定的查询条件。 | + | columns | Array<string> | 是 | 表示要查询的列。如果值为空，则查询应用于所有列。 | + | callback | AsyncCallback<[ResultSet](js-apis-data-resultset.md)> | 是 | 指定callback回调函数。如果操作成功，则返回ResultSet对象。 | + +- 示例： + ``` + let predicates = new data_rdb.RdbPredicates("EMPLOYEE") + predicates.equalTo("NAME", "Rose") + rdbStore.query(predicates, ["ID", "NAME", "AGE", "SALARY", "CODES"], function (err, resultSet) { + console.log(TAG + "resultSet column names:" + resultSet.columnNames) + console.log(TAG + "resultSet column count:" + resultSet.columnCount)}) + ``` + + +### query + +query(rdbPredicates: RdbPredicates, columns?: Array<string>):Promise<ResultSet> + +根据指定条件查询数据库中的数据，结果以Promise形式返回。 + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | rdbPredicates | [RdbPredicates](#rdbpredicates) | 是 | 表示rdbPredicates的实例对象指定的查询条件。 | + | columns | Array<string> | 否 | 表示要查询的列。如果值为空，则查询应用于所有列。 | + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | Promise<[ResultSet](../apis/js-apis-data-resultset.md)> | 指定Promise回调函数。如果操作成功，则返回ResultSet对象。 | + +- 示例： + ``` + let predicates = new data_rdb.RdbPredicates("EMPLOYEE") + predicates.equalTo("NAME", "Rose") + let promise = rdbStore.query(predicates, ["ID", "NAME", "AGE", "SALARY", "CODES"]) + promise.then((resultSet) => { + console.log(TAG + "resultSet column names:" + resultSet.columnNames) + console.log(TAG + "resultSet column count:" + resultSet.columnCount)}) + ``` + + +### querySql8+ + +querySql(sql: string, bindArgs: Array<ValueType>, callback: AsyncCallback<ResultSet>):void + +根据指定SQL语句查询数据库中的数据，结果以callback形式返回。 + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | sql | string | 是 | 指定要执行的SQL语句。 | + | bindArgs | Array<[ValueType](#valuetype)> | 是 | SQL语句中参数的值。 | + | callback | AsyncCallback<[ResultSet](js-apis-data-resultset.md)> | 是 | 指定callback回调函数。如果操作成功，则返回ResultSet对象。 | + +- 示例： + ``` + rdbStore.querySql("SELECT * FROM EMPLOYEE CROSS JOIN BOOK WHERE BOOK.NAME = ?", ['sanguo'], function (err, resultSet) { + console.log(TAG + "resultSet column names:" + resultSet.columnNames) + console.log(TAG + "resultSet column count:" + resultSet.columnCount)}) + ``` + + +### querySql8+ + +querySql(sql: string, bindArgs?: Array<ValueType>):Promise<ResultSet> + +根据指定SQL语句查询数据库中的数据，结果以Promise形式返回。 + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | sql | string | 是 | 指定要执行的SQL语句。 | + | bindArgs | Array<[ValueType](#valuetype)> | 否 | SQL语句中参数的值。 | + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | Promise<[ResultSet](../apis/js-apis-data-resultset.md)> | 指定Promise回调函数。如果操作成功，则返回ResultSet对象。 | + +- 示例： + ``` + let promise = rdbStore.querySql("SELECT * FROM EMPLOYEE CROSS JOIN BOOK WHERE BOOK.NAME = ?", ['sanguo']) + promise.then((resultSet) => { + console.log(TAG + "resultSet column names:" + resultSet.columnNames) + console.log(TAG + "resultSet column count:" + resultSet.columnCount)}) + ``` + + +### executeSql + +executeSql(sql: string, bindArgs: Array<ValueType>, callback: AsyncCallback<void>):void + +执行包含指定参数但不返回值的SQL语句，结果以callbck形式返回。 + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | sql | string | 是 | 指定要执行的SQL语句。 | + | bindArgs | Array<[ValueType](#valuetype)> | 是 | SQL语句中参数的值。 | + | callback | AsyncCallback<void> | 是 | 指定callback回调函数。 | + +- 示例： + ``` + rdbStore.executeSql("DELETE FROM EMPLOYEE", null, function () { + console.info(TAG + 'delete done.')}) + ``` + + +### executeSql + +executeSql(sql: string, bindArgs?: Array<ValueType>):Promise<void> + +执行包含指定参数但不返回值的SQL语句，结果以Promise形式返回。 + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | sql | string | 是 | 指定要执行的SQL语句。 | + | bindArgs | Array<[ValueType](#valuetype)> | 否 | SQL语句中参数的值。 | + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | Promise<void> | 指定Promise回调函数。 | + +- 示例： + ``` + let promise = rdbStore.executeSql("DELETE FROM EMPLOYEE") + promise.then(() => { + console.info(TAG + 'delete done.')}) + ``` + +### setDistributedTables + +setDistributedTables(tables: Array, callback: AsyncCallback): void; + +设置分布式列表，结果以callbck形式返回。 + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | tables | Array | 是 | 要设置的分布式列表表名 | + | callback | AsyncCallback<void> | 是 | 指定callback回调函数。 | + +- 示例： + ``` + rdbStore.setDistributedTables(['employee'], function () { + console.info(TAG + 'setDistributedTables done.')}) + ``` + + +### setDistributedTables + + setDistributedTables(tables: Array): Promise; + +设置分布式列表，结果以Promise形式返回。 + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | tables | Array | 是 | 要设置的分布式列表表名 | + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | Promise<void> | 指定Promise回调函数。 | + +- 示例： + ``` + let promise = rdbStore.setDistributedTables(['employee']) + promise.then(() => { + console.info(TAG + 'setDistributedTables done.')}) + ``` + +### obtainDistributedTableName + +obtainDistributedTableName(device: string, table: string, callback: AsyncCallback): void; + +根据本地表名获取指定远程设备的分布式表名。在查询远程设备数据库时，需要使用分布式表名, 结果以callbck形式返回。 + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | device | string | 是 | 远程设备 | + | table | string | 是 | 本地表名 | + | callback | AsyncCallback<string> | 是 | 指定callback回调函数。 | + +- 示例： + ``` + rdbStore.obtainDistributedTableName(deviceId, "employee", function () { + console.info(TAG + 'obtainDistributedTableName done.')}) + ``` + + +### obtainDistributedTableName + + obtainDistributedTableName(device: string, table: string): Promise; + +根据本地表名获取指定远程设备的分布式表名。在查询远程设备数据库时，需要使用分布式表名，结果以Promise形式返回。 + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | device | string | 是 | 远程设备 | + | table | string | 是 | 本地表名 | + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | Promise<string> | 指定Promise回调函数。 | + +- 示例： + ``` + let promise = rdbStore.obtainDistributedTableName(deviceId, "employee") + promise.then(() => { + console.info(TAG + 'obtainDistributedTableName done.')}) + ``` + +### sync + +sync(mode: SyncMode, predicates: RdbPredicates, callback: AsyncCallback>): void; + +在设备之间同步数据, 结果以callbck形式返回。 + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | mode | SyncMode | 是 | 指示同步模式。该值可以是推、拉。 | + | predicates | RdbPredicates | 是 | 约束同步数据和设备。 | + | callback | AsyncCallback<Array<[string, number]>> | 是 | 指定callback回调函数。 | + +- 示例： + ``` + rdbStore.sync(rdb.SyncMode.SYNC_MODE_PUSH, precdicate, function () { + console.info(TAG + 'sync done.')}) + ``` + + +### sync + + sync(mode: SyncMode, predicates: RdbPredicates): Promise>; + +在设备之间同步数据，结果以Promise形式返回。 + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | mode | SyncMode | 是 | 指示同步模式。该值可以是推、拉。 | + | predicates | RdbPredicates | 是 | 约束同步数据和设备。 | + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | Promise<Array<[string, number]>> | 指定Promise回调函数。 | + +- 示例： + ``` + let promise = rdbStore.sync(rdb.SyncMode.SYNC_MODE_PUSH, precdicate) + promise.then(() => { + console.info(TAG + 'sync done.')}) + ``` + + + + +## StoreConfig + +管理关系数据库配置。 + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| name | string | 是 | 数据库文件名。 | + + +## ValueType + +用于表示允许的数据字段类型。 + +| 名称 | 说明 | +| -------- | -------- | +| number | 表示值类型为数字。 | +| string | 表示值类型为字符。 | +| boolean | 表示值类型为布尔值。| + + +## ValuesBucket + +用于存储键值对。 + + +| 名称 | 参数类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| [key: string] | [ValueType](#valuetype)\| Uint8Array \| null | 是 | 用于存储键值对。 | -- Gitee From 2a4048b25554bb6cfa81a6a1c6905bcc461b6d8a Mon Sep 17 00:00:00 2001 From: sun-dou Date: Fri, 18 Feb 2022 15:48:37 +0800 Subject: [PATCH 02/11] update doc Signed-off-by: sun-dou --- .../reference/apis/js-apis-data-rdb.md | 35 +- .../reference/apis/js-apis-data-rdb.md.bak | 1348 ----------------- 2 files changed, 21 insertions(+), 1362 deletions(-) delete mode 100644 zh-cn/application-dev/reference/apis/js-apis-data-rdb.md.bak diff --git a/zh-cn/application-dev/reference/apis/js-apis-data-rdb.md b/zh-cn/application-dev/reference/apis/js-apis-data-rdb.md index 8a3c77d4ccc..d1b8d80223d 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-data-rdb.md +++ b/zh-cn/application-dev/reference/apis/js-apis-data-rdb.md @@ -1280,7 +1280,7 @@ obtainDistributedTableName(device: string, table: string, callback: AsyncCallbac | -------- | -------- | -------- | -------- | | device | string | 是 | 远程设备 | | table | string | 是 | 本地表名 | - | callback | AsyncCallback<string> | 是 | 指定callback回调函数。 | + | callback | AsyncCallback<string> | 是 | 指定的callback回调函数。如果操作成功，返回分布式表名。 | - 示例： ``` @@ -1304,7 +1304,7 @@ obtainDistributedTableName(device: string, table: string, callback: AsyncCallbac - 返回值： | 类型 | 说明 | | -------- | -------- | - | Promise<string> | 指定Promise回调函数。 | + | Promise<string> | 指定Promise回调函数。如果操作成功，返回分布式表名。 | - 示例： ``` @@ -1324,11 +1324,11 @@ sync(mode: SyncMode, predicates: RdbPredicates, callback: AsyncCallback> | 是 | 指定callback回调函数。 | + | callback | AsyncCallback<Array<[string, number]>> | 是 | 指定的callback回调函数，用于向调用者发送同步结果。string：设备ID；number：每个设备同步状态，0表示成功，1表示失败。| - 示例： ``` - rdbStore.sync(rdb.SyncMode.SYNC_MODE_PUSH, precdicate, function () { + rdbStore.sync(rdb.SyncMode.SYNC_MODE_PUSH, precdicate, function (err, [[devices[0], 0]]) { console.info(TAG + 'sync done.')}) ``` @@ -1348,7 +1348,7 @@ sync(mode: SyncMode, predicates: RdbPredicates, callback: AsyncCallback> | 指定Promise回调函数。 | + | Promise<Array<[string, number]>> | 指定Promise回调函数。用于向调用者发送同步结果。string：设备ID；number：每个设备同步状态，0表示成功，1表示失败。 | - 示例： ``` @@ -1371,8 +1371,8 @@ on(event: 'dataChange', type: SubscribeType, observer: Callback>): - 示例： ``` - rdbStore.on(rdb.SyncMode.SYNC_MODE_PUSH, precdicate, function () { - console.info(TAG + 'sync done.')}) + rdbStore.on(“dataChange”, rdb.SubscribeType.SUBSCRIBE_TYPE_REMOTE, function (err, devices) { + console.info(TAG + 'on done.')}) ``` ### off @@ -1389,8 +1389,8 @@ off(event:'dataChange', type: SubscribeType, observer: Callback>): - 示例： ``` - rdbStore.on(rdb.SyncMode.SYNC_MODE_PUSH, precdicate, function () { - console.info(TAG + 'sync done.')}) + rdbStore.on(dataChange”, rdb.SubscribeType.SUBSCRIBE_TYPE_REMOTE, function (err, devices) { + console.info(TAG + 'off done.')}) ``` @@ -1413,12 +1413,19 @@ off(event:'dataChange', type: SubscribeType, observer: Callback>): | string | 表示值类型为字符。 | | boolean | 表示值类型为布尔值。| +## SyncMode -## ValuesBucket +指数据库同步模式。 + +| 名称 | 说明 | +| -------- | -------- | +| SYNC_MODE_PUSH | 表示数据已从本地设备推送到远程设备。 | +| SYNC_MODE_PULL | 表示数据从远程设备拉至本地设备。 | -用于存储键值对。 +## SubscribeType +描述订阅类型。 -| 名称 | 参数类型 | 必填 | 说明 | -| -------- | -------- | -------- | -------- | -| [key: string] | [ValueType](#valuetype)\| Uint8Array \| null | 是 | 用于存储键值对。 | +| 名称 | 说明 | +| -------- | -------- | +| SUBSCRIBE_TYPE_REMOTE | 订阅远程数据更改。 | diff --git a/zh-cn/application-dev/reference/apis/js-apis-data-rdb.md.bak b/zh-cn/application-dev/reference/apis/js-apis-data-rdb.md.bak deleted file mode 100644 index e25f042c7f6..00000000000 --- a/zh-cn/application-dev/reference/apis/js-apis-data-rdb.md.bak +++ /dev/null @@ -1,1348 +0,0 @@ -# 关系型数据库 - -> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** -> 本模块首批接口从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形式返回。 - -- 参数： - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | context | Context | 是 | 应用程序或功能的上下文 | - | config | [StoreConfig](#storeconfig) | 是 | 与此RDB存储相关的数据库配置。 | - | version | number | 是 | 数据库版本。 | - | callback | AsyncCallback<[RdbStore](#rdbstore)> | 是 | 指定callback回调函数。返回一个RdbStore。 | - -- 示例： - ``` - import Ability from '@ohos.application.Ability' - import data_rdb from '@ohos.data.rdb' - export default class MainAbility extends Ability { - const STORE_CONFIG = { name: "RdbTest.db"} - const SQL_CREATE_TABLE = "CREATE TABLE IF NOT EXISTS EMPLOYEE (ID INTEGER PRIMARY KEY AUTOINCREMENT, NAME TEXT NOT NULL, AGE INTEGER, SALARY REAL, CODES BLOB)" - data_rdb.getRdbStore(this.context, STORE_CONFIG, 1, function (err, rdbStore) { - rdbStore.executeSql(SQL_CREATE_TABLE) - console.info(TAG + 'create table done.') - }) - } - ``` - -## data_rdb.getRdbStore - -getRdbStore(context: Context, config: StoreConfig, version: number): Promise<RdbStore> - -获得一个相关的RdbStore，操作关系型数据库，用户可以根据自己的需求配置RdbStore的参数，然后通过RdbStore调用相关接口可以执行相关的数据操作，结果以Promise形式返回。 - -- 参数： - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | context | Context | 是 | 应用程序或功能的上下文 | - | config | [StoreConfig](#storeconfig) | 是 | 与此RDB存储相关的数据库配置。 | - | version | number | 是 | 数据库版本。 | - -- 返回值： - | 类型 | 说明 | - | -------- | -------- | - | Promise<[RdbStore](#rdbstore)> | 指定Promise回调函数。返回一个RdbStore。 | - -- 示例： - ``` - import Ability from '@ohos.application.Ability' - import data_rdb from '@ohos.data.rdb' - export default class MainAbility extends Ability { - const STORE_CONFIG = { name: "RdbTest.db" } - const SQL_CREATE_TABLE = "CREATE TABLE IF NOT EXISTS EMPLOYEE (ID INTEGER PRIMARY KEY AUTOINCREMENT, NAME TEXT NOT NULL, AGE INTEGER, SALARY REAL, CODES BLOB)" - let promise = data_rdb.getRdbStore(this.context, STORE_CONFIG, 1); - promise.then(async (rdbStore) => { - await rdbStore.executeSql(SQL_CREATE_TABLE, null) - }).catch((err) => { - expect(null).assertFail(); - }) - } - ``` - -## data_rdb.deleteRdbStore - -deleteRdbStore(context: Context, name: string, callback: AsyncCallback<void>): void - -删除数据库，结果以callback形式返回。 - -- 参数： - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | context | Context | 是 | 应用程序或功能的上下文 | - | name | string | 是 | 数据库名称。 | - | callback | AsyncCallback<void> | 是 | 指定callback回调函数。如果数据库已删除，则为true；否则返回false。 | - -- 示例： - ``` - import Ability from '@ohos.application.Ability' - import data_rdb from '@ohos.data.rdb' - export default class MainAbility extends Ability { - data_rdb.deleteRdbStore(this.context, "RdbTest.db", function (err, rdbStore) { - console.info(TAG + 'delete store done.')}) - } - ``` - -## data_rdb.deleteRdbStore - -deleteRdbStore(context: Context, name: string): Promise<void> - -使用指定的数据库文件配置删除数据库，结果以Promise形式返回。 - -- 参数： - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | context | Context | 是 | 应用程序或功能的上下文 | - | name | string | 是 | 数据库名称。 | - -- 返回值： - | 类型 | 说明 | - | -------- | -------- | - | Promise<void> | 指定Promise回调函数。如果数据库已删除，则为true；否则返回false。 | - -- 示例： - ``` - import Ability from '@ohos.application.Ability' - import data_rdb from '@ohos.data.rdb' - export default class MainAbility extends Ability { - let promise = data_rdb.deleteRdbStore(this.context, "RdbTest.db") - promise.then(()=>{ - console.info(TAG + 'delete store done.') - }) - } - ``` - -## RdbPredicates - -表示关系型数据库（RDB）的谓词。该类确定RDB中条件表达式的值是true还是false。 - - -### constructor - -constructor(name: string) - - -构造函数。 - - -- 参数： - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | name | string | 是 | 数据库表名。 | - -- 示例： - ``` - let predicates = new data_rdb.RdbPredicates("EMPLOYEE") - ``` - - -### equalTo - -equalTo(field: string, value: ValueType): RdbPredicates - - -配置谓词以匹配数据字段为ValueType且值等于指定值的字段。 - - -- 参数： - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | field | string | 是 | 数据库表中的列名。 | - | value | [ValueType](#valuetype) | 是 | 指示要与谓词匹配的值。 | - -- 返回值： - | 类型 | 说明 | - | -------- | -------- | - | [RdbPredicates](#rdbpredicates) | 返回与指定字段匹配的谓词。 | - -- 示例： - ``` - let predicates = new data_rdb.RdbPredicates("EMPLOYEE") - predicates.equalTo("NAME", "lisi") - ``` - - -### notEqualTo - -notEqualTo(field: string, value: ValueType): RdbPredicates - - -配置谓词以匹配数据字段为ValueType且值不等于指定值的字段。 - - -- 参数： - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | field | string | 是 | 数据库表中的列名。 | - | value | [ValueType](#valuetype) | 是 | 指示要与谓词匹配的值。 | - -- 返回值： - | 类型 | 说明 | - | -------- | -------- | - | [RdbPredicates](#rdbpredicates) | 返回与指定字段匹配的谓词。 | - -- 示例： - ``` - let predicates = new data_rdb.RdbPredicates("EMPLOYEE") - predicates.notEqualTo("NAME", "lisi") - ``` - - -### beginWrap - -beginWrap(): RdbPredicates - - -向谓词添加左括号。 - - -- 返回值： - | 类型 | 说明 | - | -------- | -------- | - | [RdbPredicates](#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 - - -向谓词添加右括号。 - - -- 返回值： - | 类型 | 说明 | - | -------- | -------- | - | [RdbPredicates](#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 - - -将或条件添加到谓词中。 - - -- 返回值： - | 类型 | 说明 | - | -------- | -------- | - | [RdbPredicates](#rdbpredicates) | 返回带有或条件的Rdb谓词。 | - -- 示例： - ``` - let predicates = new data_rdb.RdbPredicates("EMPLOYEE") - predicates.equalTo("NAME", "Lisa") - .or() - .equalTo("NAME", "Rose") - ``` - - -### and - -and(): RdbPredicates - - -向谓词添加和条件。 - - -- 返回值： - | 类型 | 说明 | - | -------- | -------- | - | [RdbPredicates](#rdbpredicates) | 返回带有和条件的Rdb谓词。 | - -- 示例： - ``` - let predicates = new data_rdb.RdbPredicates("EMPLOYEE") - predicates.equalTo("NAME", "Lisa") - .and() - .equalTo("SALARY", 200.5) - ``` - - -### contains - -contains(field: string, value: string): RdbPredicat - - -配置谓词以匹配数据字段为String且value包含指定值的字段。 - - -- 参数： - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | field | string | 是 | 数据库表中的列名。 | - | value | string | 是 | 指示要与谓词匹配的值。 | - -- 返回值： - | 类型 | 说明 | - | -------- | -------- | - | [RdbPredicates](#rdbpredicates) | 返回与指定字段匹配的谓词。 | - -- 示例： - ``` - let predicates = new data_rdb.RdbPredicates("EMPLOYEE") - predicates.contains("NAME", "os") - ``` - - -### beginsWith - -beginsWith(field: string, value: string): RdbPredicates - - -配置谓词以匹配数据字段为String且值以指定字符串开头的字段。 - - -- 参数： - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | field | string | 是 | 数据库表中的列名。 | - | value | string | 是 | 指示要与谓词匹配的值。 | - -- 返回值： - | 类型 | 说明 | - | -------- | -------- | - | [RdbPredicates](#rdbpredicates) | 返回与指定字段匹配的谓词。 | - -- 示例： - ``` - let predicates = new data_rdb.RdbPredicates("EMPLOYEE") - predicates.beginsWith("NAME", "os") - ``` - - -### endsWith - -endsWith(field: string, value: string): RdbPredicates - - -配置谓词以匹配数据字段为String且值以指定字符串结尾的字段。 - - -- 参数： - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | field | string | 是 | 数据库表中的列名。 | - | value | string | 是 | 指示要与谓词匹配的值。 | - -- 返回值： - | 类型 | 说明 | - | -------- | -------- | - | [RdbPredicates](#rdbpredicates) | 返回与指定字段匹配的谓词。 | - -- 示例： - ``` - let predicates = new data_rdb.RdbPredicates("EMPLOYEE") - predicates.endsWith("NAME", "se") - ``` - - -### isNull - -isNull(field: string): RdbPredicates - - -配置谓词以匹配值为null的字段。 - - -- 参数： - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | field | string | 是 | 数据库表中的列名。 | - -- 返回值： - | 类型 | 说明 | - | -------- | -------- | - | [RdbPredicates](#rdbpredicates) | 返回与指定字段匹配的谓词。 | - -- 示例 - ``` - let predicates = new data_rdb.RdbPredicates("EMPLOYEE") - predicates.isNull("NAME") - ``` - - -### isNotNull - -isNotNull(field: string): RdbPredicates - - -配置谓词以匹配值不为null的指定字段。 - - -- 参数： - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | field | string | 是 | 数据库表中的列名。 | - -- 返回值： - | 类型 | 说明 | - | -------- | -------- | - | [RdbPredicates](#rdbpredicates) | 返回与指定字段匹配的谓词。 | - -- 示例： - ``` - let predicates = new data_rdb.RdbPredicates("EMPLOYEE") - predicates.isNotNull("NAME") - ``` - - -### like - -like(field: string, value: string): RdbPredicates - - -配置谓词以匹配数据字段为String且值类似于指定字符串的字段。 - - -- 参数： - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | field | string | 是 | 数据库表中的列名。 | - | value | string | 是 | 指示要与谓词匹配的值。 | - -- 返回值： - | 类型 | 说明 | - | -------- | -------- | - | [RdbPredicates](#rdbpredicates) | 返回与指定字段匹配的谓词。 | - -- 示例： - ``` - let predicates = new data_rdb.RdbPredicates("EMPLOYEE") - predicates.like("NAME", "%os%") - ``` - - -### glob - -glob(field: string, value: string): RdbPredicates - - -配置RdbPredicates匹配数据字段为String的指定字段。 - - -- 参数： - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | field | string | 是 | 数据库表中的列名。 | - | value | string | 是 | 指示要与谓词匹配的值。
支持通配符，*表示0个、1个或多个数字或字符，?表示1个数字或字符。 | - -- 返回值： - | 类型 | 说明 | - | -------- | -------- | - | [RdbPredicates](#rdbpredicates) | 返回与指定字段匹配的谓词。 | - -- 示例： - ``` - let predicates = new data_rdb.RdbPredicates("EMPLOYEE") - predicates.glob("NAME", "?h*g") - ``` - - -### between - -between(field: string, low: ValueType, high: ValueType): RdbPredicates - - -将谓词配置为匹配数据字段为ValueType且value在给定范围内的指定字段。 - - -- 参数： - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | field | string | 是 | 数据库表中的列名。 | - | low | [ValueType](#valuetype) | 是 | 指示与谓词匹配的最小值。 | - | high | [ValueType](#valuetype) | 是 | 指示要与谓词匹配的最大值。 | - -- 返回值： - | 类型 | 说明 | - | -------- | -------- | - | [RdbPredicates](#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超出给定范围的指定字段。 - - -- 参数： - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | field | string | 是 | 数据库表中的列名。 | - | low | [ValueType](#valuetype) | 是 | 指示与谓词匹配的最小值。 | - | high | [ValueType](#valuetype) | 是 | 指示要与谓词匹配的最大值。 | - -- 返回值： - | 类型 | 说明 | - | -------- | -------- | - | [RdbPredicates](#rdbpredicates) | 返回与指定字段匹配的谓词。 | - -- 示例： - ``` - let predicates = new data_rdb.RdbPredicates("EMPLOYEE") - predicates.notBetween("AGE", 10, 50) - ``` - - -### greaterThan - -greaterThan(field: string, value: ValueType): RdbPredicatesgr - - -配置谓词以匹配数据字段为ValueType且值大于指定值的字段。 - - -- 参数： - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | field | string | 是 | 数据库表中的列名。 | - | value | [ValueType](#valuetype) | 是 | 指示要与谓词匹配的值。 | - -- 返回值： - | 类型 | 说明 | - | -------- | -------- | - | [RdbPredicates](#rdbpredicates) | 返回与指定字段匹配的谓词。 | - -- 示例： - ``` - let predicates = new data_rdb.RdbPredicates("EMPLOYEE") - predicates.greaterThan("AGE", 18) - ``` - - -### lessThan - -lessThan(field: string, value: ValueType): RdbPredicates - - -配置谓词以匹配数据字段为valueType且value小于指定值的字段。 - - -- 参数： - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | field | string | 是 | 数据库表中的列名。 | - | value | [ValueType](#valuetype) | 是 | 指示要与谓词匹配的值。 | - -- 返回值： - | 类型 | 说明 | - | -------- | -------- | - | [RdbPredicates](#rdbpredicates) | 返回与指定字段匹配的谓词。 | - -- 示例： - ``` - let predicates = new data_rdb.RdbPredicates("EMPLOYEE") - predicates.lessThan("AGE", 20) - ``` - - -### greaterThanOrEqualTo - - -greaterThanOrEqualTo(field: string, value: ValueType): RdbPredicates - - -配置谓词以匹配数据字段为ValueType且value大于或等于指定值的字段。 - - -- 参数： - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | field | string | 是 | 数据库表中的列名。 | - | value | [ValueType](#valuetype) | 是 | 指示要与谓词匹配的值。 | - -- 返回值： - | 类型 | 说明 | - | -------- | -------- | - | [RdbPredicates](#rdbpredicates) | 返回与指定字段匹配的谓词。 | - -- 示例： - ``` - let predicates = new data_rdb.RdbPredicates("EMPLOYEE") - predicates.greaterThanOrEqualTo("AGE", 18) - ``` - - -### lessThanOrEqualTo - - -lessThanOrEqualTo(field: string, value: ValueType): RdbPredicates - - -配置谓词以匹配数据字段为ValueType且value小于或等于指定值的字段。 - - -- 参数： - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | field | string | 是 | 数据库表中的列名。 | - | value | [ValueType](#valuetype) | 是 | 指示要与谓词匹配的值。 | - -- 返回值： - | 类型 | 说明 | - | -------- | -------- | - | [RdbPredicates](#rdbpredicates) | 返回与指定字段匹配的谓词。 | - -- 示例： - ``` - let predicates = new data_rdb.RdbPredicates("EMPLOYEE") - predicates.lessThanOrEqualTo("AGE", 20) - ``` - - -### orderByAsc - - -orderByAsc(field: string): RdbPredicates - - -配置谓词以匹配其值按升序排序的列。 - - -- 参数： - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | field | string | 是 | 数据库表中的列名。 | - -- 返回值： - | 类型 | 说明 | - | -------- | -------- | - | [RdbPredicates](#rdbpredicates) | 返回与指定字段匹配的谓词。 | - -- 示例： - ``` - let predicates = new data_rdb.RdbPredicates("EMPLOYEE") - predicates.orderByAsc("NAME") - ``` - - -### orderByDesc - - -orderByDesc(field: string): RdbPredicates - - -配置谓词以匹配其值按降序排序的列。 - - -- 参数： - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | field | string | 是 | 数据库表中的列名。 | - -- 返回值： - | 类型 | 说明 | - | -------- | -------- | - | [RdbPredicates](#rdbpredicates) | 返回与指定字段匹配的谓词。 | - -- 示例： - ``` - let predicates = new data_rdb.RdbPredicates("EMPLOYEE") - predicates.orderByDesc("AGE") - ``` - - -### distinct - -distinct(): RdbPredicates - - -配置谓词以过滤重复记录并仅保留其中一个。 - - -- 返回值： - | 类型 | 说明 | - | -------- | -------- | - | [RdbPredicates](#rdbpredicates) | 返回可用于过滤重复记录的谓词。 | - -- 示例： - ``` - let predicates = new data_rdb.RdbPredicates("EMPLOYEE") - predicates.equalTo("NAME", "Rose").distinct("NAME") - let resultSet = await rdbStore.query(predicates, ["NAME"]) - ``` - - -### limitAs - -limitAs(value: number): RdbPredicates - - -设置最大数据记录数的谓词。 - - -- 参数： - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | value | number | 是 | 最大数据记录数。 | - -- 返回值： - | 类型 | 说明 | - | -------- | -------- | - | [RdbPredicates](#rdbpredicates) | 返回可用于设置最大数据记录数的谓词。 | - -- 示例： - ``` - let predicates = new data_rdb.RdbPredicates("EMPLOYEE") - predicates.equalTo("NAME", "Rose").limitAs(3) - ``` - - -### offsetAs - -offsetAs(rowOffset: number): RdbPredicates - - -配置RdbPredicates以指定返回结果的起始位置。 - - -- 参数： - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | rowOffset | number | 是 | 返回结果的起始位置，取值为正整数。 | - -- 返回值： - | 类型 | 说明 | - | -------- | -------- | - | [RdbPredicates](#rdbpredicates) | 返回具有指定返回结果起始位置的谓词。 | - -- 示例： - ``` - let predicates = new data_rdb.RdbPredicates("EMPLOYEE") - predicates.equalTo("NAME", "Rose").offsetAs(3) - ``` - - -### groupBy - -groupBy(fields: Array<string>): RdbPredicates - - -配置RdbPredicates按指定列分组查询结果。 - - -- 参数： - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | fields | Array<string> | 是 | 指定分组依赖的列名。 | - -- 返回值： - | 类型 | 说明 | - | -------- | -------- | - | [RdbPredicates](#rdbpredicates) | 返回分组查询列的谓词。 | - -- 示例： - ``` - let predicates = new data_rdb.RdbPredicates("EMPLOYEE") - predicates.groupBy(["AGE", "NAME"]) - ``` - - -### indexedBy - -indexedBy(indexName: string): RdbPredicates - - -配置RdbPredicates以指定索引列。 - - -- 参数： - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | indexName | string | 是 | 索引列的名称。 | - -- 返回值： - | 类型 | 说明 | - | -------- | -------- | - | [RdbPredicates](#rdbpredicates) | 返回具有指定索引列的RdbPredicates。 | - -- 示例： - ``` - let predicates = new data_rdb.RdbPredicates("EMPLOYEE") - predicates.indexedBy("SALARY_INDEX") - ``` - - -### in - -in(field: string, value: Array<ValueType>): RdbPredicates - - -配置RdbPredicates以匹配数据字段为ValueType数组且值在给定范围内的指定字段。 - - -- 参数： - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | field | string | 是 | 数据库表中的列名。 | - | value | Array<[ValueType](#valuetype)> | 是 | 以ValueType型数组形式指定的要匹配的值。 | - - -- 返回值： - | 类型 | 说明 | - | -------- | -------- | - | [RdbPredicates](#rdbpredicates) | 返回与指定字段匹配的谓词。 | - -- 示例： - ``` - let predicates = new data_rdb.RdbPredicates("EMPLOYEE") - predicates.in("AGE", [18, 20]) - ``` - - -### notIn - -notIn(field: string, value: Array<ValueType>): RdbPredicates - - -将RdbPredicates配置为匹配数据字段为ValueType且值超出给定范围的指定字段。 - - -- 参数： - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | field | string | 是 | 数据库表中的列名。 | - | value | Array<[ValueType](#valuetype)> | 是 | 以ValueType数组形式指定的要匹配的值。 | - - -- 返回值： - | 类型 | 说明 | - | -------- | -------- | - | [RdbPredicates](#rdbpredicates) | 返回与指定字段匹配的谓词。 | - -- 示例： - ``` - let predicates = new data_rdb.RdbPredicates("EMPLOYEE") - predicates.notIn("NAME", ["Lisa", "Rose"]) - ``` - - -## RdbStore - -提供管理关系数据库(RDB)方法的接口。 - - -### insert - -insert(name: string, values: ValuesBucket, callback: AsyncCallback<number>):void - -向目标表中插入一行数据，结果以callback形式返回。 - -- 参数： - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | name | string | 是 | 指定的目标表名。 | - | values | [ValuesBucket](#valuesbucket) | 是 | 表示要插入到表中的数据行。 | - | callback | AsyncCallback<number> | 是 | 指定callback回调函数。如果操作成功，返回行ID；否则返回-1。 | - -- 示例： - ``` - const valueBucket = { - "NAME": "Lisa", - "AGE": 18, - "SALARY": 100.5, - "CODES": new Uint8Array([1, 2, 3, 4, 5]), - } - rdbStore.insert("EMPLOYEE", valueBucket, function (err, ret) { - expect(1).assertEqual(ret) - console.log(TAG + "insert first done: " + ret)}) - ``` - - -### insert - -insert(name: string, values: ValuesBucket):Promise<number> - -向目标表中插入一行数据，结果以Promise形式返回。 - -- 参数： - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | name | string | 是 | 指定的目标表名。 | - | values | [ValuesBucket](#valuesbucket) | 是 | 表示要插入到表中的数据行。 | - -- 返回值： - | 类型 | 说明 | - | -------- | -------- | - | Promise<number> | 指定Promise回调函数。如果操作成功，返回行ID；否则返回-1。 | - -- 示例： - ``` - const valueBucket = { - "NAME": "Lisa", - "AGE": 18, - "SALARY": 100.5, - "CODES": new Uint8Array([1, 2, 3, 4, 5]), - } - let promise = rdbStore.insert("EMPLOYEE", valueBucket) - promise.then(async (ret) => { - await console.log(TAG + "insert first done: " + ret) - }).catch((err) => {}) - ``` - - -### update - -update(values: ValuesBucket, rdbPredicates: RdbPredicates, callback: AsyncCallback<number>):void - -根据RdbPredicates的指定实例对象更新数据库中的数据，结果以callback形式返回。 - -- 参数： - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | values | [ValuesBucket](#valuesbucket) | 是 | value指示数据库中要更新的数据行。键值对与数据库表的列名相关联 | - | rdbPredicates | [RdbPredicates](#rdbpredicates) | 是 | 表示要插入到表中的数据行。 | - | callback | AsyncCallback<number> | 是 | 指定的callback回调方法。返回受影响的行数。 | - -- 示例： - ``` - const valueBucket = { - "NAME": "Rose", - "AGE": 22, - "SALARY": 200.5, - "CODES": new Uint8Array([1, 2, 3, 4, 5]), - } - let predicates = new data_rdb.RdbPredicates("EMPLOYEE") - predicates.equalTo("NAME", "Lisa") - rdbStore.update(valueBucket, predicates, function (err, ret) { - console.log(TAG + "updated row count: " + changedRows)}) - ``` - - -### update - -update(values: ValuesBucket, rdbPredicates: RdbPredicates):Promise<number> - -根据RdbPredicates的指定实例对象更新数据库中的数据，结果以Promise形式返回。 - -- 参数： - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | values | [ValuesBucket](#valuesbucket) | 是 | value指示数据库中要更新的数据行。键值对与数据库表的列名相关联 | - | rdbPredicates | [RdbPredicates](#rdbpredicates) | 是 | 表示要插入到表中的数据行。 | - -- 返回值： - | 类型 | 说明 | - | -------- | -------- | - | Promise<number> | 指定的Promise回调方法。返回受影响的行数。 | - -- 示例： - ``` - const valueBucket = { - "NAME": "Rose", - "AGE": 22, - "SALARY": 200.5, - "CODES": new Uint8Array([1, 2, 3, 4, 5]), - } - let predicates = new data_rdb.RdbPredicates("EMPLOYEE") - predicates.equalTo("NAME", "Lisa") - let promise = rdbStore.update(valueBucket, predicates) - promise.then(async (ret) => { - await console.log(TAG + "updated row count: " + changedRows) - }).catch((err) => {}) - ``` - - -### delete - -delete(rdbPredicates: RdbPredicates, callback: AsyncCallback<number>):void - - -根据rdbPredicates的指定实例对象从数据库中删除数据，结果以callback形式返回。 - - -- 参数： - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | rdbPredicates | [RdbPredicates](#rdbpredicates) | 是 | RdbPredicates的实例对象指定的删除条件。 | - | callback | AsyncCallback<number> | 是 | 指定callback回调函数。返回受影响的行数。 | - -- 示例： - ``` - let predicates = new data_rdb.RdbPredicates("EMPLOYEE") - predicates.equalTo("NAME", "Lisa") - rdbStore.delete(predicates, function (err, rows) { - console.log(TAG + "delete rows: " + rows)}) - ``` - - -### delete - -delete(rdbPredicates: RdbPredicates):Promise<number> - -根据rdbPredicates的指定实例对象从数据库中删除数据，结果以Promise形式返回。 - -- 参数： - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | rdbPredicates | [RdbPredicates](#rdbpredicates) | 是 | RdbPredicates的实例对象指定的删除条件。 | - -- 返回值： - | 类型 | 说明 | - | -------- | -------- | - | Promise<number> | 指定Promise回调函数。返回受影响的行数。 | - -- 示例： - ``` - let predicates = new data_rdb.RdbPredicates("EMPLOYEE") - predicates.equalTo("NAME", "Lisa") - let promise = rdbStore.delete(predicates) - promise.then((rows) => { - console.log(TAG + "delete rows: " + rows) - }).catch((err) => {}) - ``` - - -### query - -query(rdbPredicates: RdbPredicates, columns: Array<string>, callback: AsyncCallback<ResultSet>):void - -根据指定条件查询数据库中的数据，结果以callback形式返回。 - -- 参数： - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | rdbPredicates | [RdbPredicates](#rdbpredicates) | 是 | 表示rdbPredicates的实例对象指定的查询条件。 | - | columns | Array<string> | 是 | 表示要查询的列。如果值为空，则查询应用于所有列。 | - | callback | AsyncCallback<[ResultSet](js-apis-data-resultset.md)> | 是 | 指定callback回调函数。如果操作成功，则返回ResultSet对象。 | - -- 示例： - ``` - let predicates = new data_rdb.RdbPredicates("EMPLOYEE") - predicates.equalTo("NAME", "Rose") - rdbStore.query(predicates, ["ID", "NAME", "AGE", "SALARY", "CODES"], function (err, resultSet) { - console.log(TAG + "resultSet column names:" + resultSet.columnNames) - console.log(TAG + "resultSet column count:" + resultSet.columnCount)}) - ``` - - -### query - -query(rdbPredicates: RdbPredicates, columns?: Array<string>):Promise<ResultSet> - -根据指定条件查询数据库中的数据，结果以Promise形式返回。 - -- 参数： - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | rdbPredicates | [RdbPredicates](#rdbpredicates) | 是 | 表示rdbPredicates的实例对象指定的查询条件。 | - | columns | Array<string> | 否 | 表示要查询的列。如果值为空，则查询应用于所有列。 | - -- 返回值： - | 类型 | 说明 | - | -------- | -------- | - | Promise<[ResultSet](../apis/js-apis-data-resultset.md)> | 指定Promise回调函数。如果操作成功，则返回ResultSet对象。 | - -- 示例： - ``` - let predicates = new data_rdb.RdbPredicates("EMPLOYEE") - predicates.equalTo("NAME", "Rose") - let promise = rdbStore.query(predicates, ["ID", "NAME", "AGE", "SALARY", "CODES"]) - promise.then((resultSet) => { - console.log(TAG + "resultSet column names:" + resultSet.columnNames) - console.log(TAG + "resultSet column count:" + resultSet.columnCount)}) - ``` - - -### querySql8+ - -querySql(sql: string, bindArgs: Array<ValueType>, callback: AsyncCallback<ResultSet>):void - -根据指定SQL语句查询数据库中的数据，结果以callback形式返回。 - -- 参数： - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | sql | string | 是 | 指定要执行的SQL语句。 | - | bindArgs | Array<[ValueType](#valuetype)> | 是 | SQL语句中参数的值。 | - | callback | AsyncCallback<[ResultSet](js-apis-data-resultset.md)> | 是 | 指定callback回调函数。如果操作成功，则返回ResultSet对象。 | - -- 示例： - ``` - rdbStore.querySql("SELECT * FROM EMPLOYEE CROSS JOIN BOOK WHERE BOOK.NAME = ?", ['sanguo'], function (err, resultSet) { - console.log(TAG + "resultSet column names:" + resultSet.columnNames) - console.log(TAG + "resultSet column count:" + resultSet.columnCount)}) - ``` - - -### querySql8+ - -querySql(sql: string, bindArgs?: Array<ValueType>):Promise<ResultSet> - -根据指定SQL语句查询数据库中的数据，结果以Promise形式返回。 - -- 参数： - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | sql | string | 是 | 指定要执行的SQL语句。 | - | bindArgs | Array<[ValueType](#valuetype)> | 否 | SQL语句中参数的值。 | - -- 返回值： - | 类型 | 说明 | - | -------- | -------- | - | Promise<[ResultSet](../apis/js-apis-data-resultset.md)> | 指定Promise回调函数。如果操作成功，则返回ResultSet对象。 | - -- 示例： - ``` - let promise = rdbStore.querySql("SELECT * FROM EMPLOYEE CROSS JOIN BOOK WHERE BOOK.NAME = ?", ['sanguo']) - promise.then((resultSet) => { - console.log(TAG + "resultSet column names:" + resultSet.columnNames) - console.log(TAG + "resultSet column count:" + resultSet.columnCount)}) - ``` - - -### executeSql - -executeSql(sql: string, bindArgs: Array<ValueType>, callback: AsyncCallback<void>):void - -执行包含指定参数但不返回值的SQL语句，结果以callbck形式返回。 - -- 参数： - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | sql | string | 是 | 指定要执行的SQL语句。 | - | bindArgs | Array<[ValueType](#valuetype)> | 是 | SQL语句中参数的值。 | - | callback | AsyncCallback<void> | 是 | 指定callback回调函数。 | - -- 示例： - ``` - rdbStore.executeSql("DELETE FROM EMPLOYEE", null, function () { - console.info(TAG + 'delete done.')}) - ``` - - -### executeSql - -executeSql(sql: string, bindArgs?: Array<ValueType>):Promise<void> - -执行包含指定参数但不返回值的SQL语句，结果以Promise形式返回。 - -- 参数： - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | sql | string | 是 | 指定要执行的SQL语句。 | - | bindArgs | Array<[ValueType](#valuetype)> | 否 | SQL语句中参数的值。 | - -- 返回值： - | 类型 | 说明 | - | -------- | -------- | - | Promise<void> | 指定Promise回调函数。 | - -- 示例： - ``` - let promise = rdbStore.executeSql("DELETE FROM EMPLOYEE") - promise.then(() => { - console.info(TAG + 'delete done.')}) - ``` - -### setDistributedTables - -setDistributedTables(tables: Array, callback: AsyncCallback): void; - -设置分布式列表，结果以callbck形式返回。 - -- 参数： - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | tables | Array | 是 | 要设置的分布式列表表名 | - | callback | AsyncCallback<void> | 是 | 指定callback回调函数。 | - -- 示例： - ``` - rdbStore.setDistributedTables(['employee'], function () { - console.info(TAG + 'setDistributedTables done.')}) - ``` - - -### setDistributedTables - - setDistributedTables(tables: Array): Promise; - -设置分布式列表，结果以Promise形式返回。 - -- 参数： - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | tables | Array | 是 | 要设置的分布式列表表名 | - -- 返回值： - | 类型 | 说明 | - | -------- | -------- | - | Promise<void> | 指定Promise回调函数。 | - -- 示例： - ``` - let promise = rdbStore.setDistributedTables(['employee']) - promise.then(() => { - console.info(TAG + 'setDistributedTables done.')}) - ``` - -### obtainDistributedTableName - -obtainDistributedTableName(device: string, table: string, callback: AsyncCallback): void; - -根据本地表名获取指定远程设备的分布式表名。在查询远程设备数据库时，需要使用分布式表名, 结果以callbck形式返回。 - -- 参数： - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | device | string | 是 | 远程设备 | - | table | string | 是 | 本地表名 | - | callback | AsyncCallback<string> | 是 | 指定callback回调函数。 | - -- 示例： - ``` - rdbStore.obtainDistributedTableName(deviceId, "employee", function () { - console.info(TAG + 'obtainDistributedTableName done.')}) - ``` - - -### obtainDistributedTableName - - obtainDistributedTableName(device: string, table: string): Promise; - -根据本地表名获取指定远程设备的分布式表名。在查询远程设备数据库时，需要使用分布式表名，结果以Promise形式返回。 - -- 参数： - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | device | string | 是 | 远程设备 | - | table | string | 是 | 本地表名 | - -- 返回值： - | 类型 | 说明 | - | -------- | -------- | - | Promise<string> | 指定Promise回调函数。 | - -- 示例： - ``` - let promise = rdbStore.obtainDistributedTableName(deviceId, "employee") - promise.then(() => { - console.info(TAG + 'obtainDistributedTableName done.')}) - ``` - -### sync - -sync(mode: SyncMode, predicates: RdbPredicates, callback: AsyncCallback>): void; - -在设备之间同步数据, 结果以callbck形式返回。 - -- 参数： - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | mode | SyncMode | 是 | 指示同步模式。该值可以是推、拉。 | - | predicates | RdbPredicates | 是 | 约束同步数据和设备。 | - | callback | AsyncCallback<Array<[string, number]>> | 是 | 指定callback回调函数。 | - -- 示例： - ``` - rdbStore.sync(rdb.SyncMode.SYNC_MODE_PUSH, precdicate, function () { - console.info(TAG + 'sync done.')}) - ``` - - -### sync - - sync(mode: SyncMode, predicates: RdbPredicates): Promise>; - -在设备之间同步数据，结果以Promise形式返回。 - -- 参数： - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | mode | SyncMode | 是 | 指示同步模式。该值可以是推、拉。 | - | predicates | RdbPredicates | 是 | 约束同步数据和设备。 | - -- 返回值： - | 类型 | 说明 | - | -------- | -------- | - | Promise<Array<[string, number]>> | 指定Promise回调函数。 | - -- 示例： - ``` - let promise = rdbStore.sync(rdb.SyncMode.SYNC_MODE_PUSH, precdicate) - promise.then(() => { - console.info(TAG + 'sync done.')}) - ``` - - - - -## StoreConfig - -管理关系数据库配置。 - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | -------- | -------- | -------- | -| name | string | 是 | 数据库文件名。 | - - -## ValueType - -用于表示允许的数据字段类型。 - -| 名称 | 说明 | -| -------- | -------- | -| number | 表示值类型为数字。 | -| string | 表示值类型为字符。 | -| boolean | 表示值类型为布尔值。| - - -## ValuesBucket - -用于存储键值对。 - - -| 名称 | 参数类型 | 必填 | 说明 | -| -------- | -------- | -------- | -------- | -| [key: string] | [ValueType](#valuetype)\| Uint8Array \| null | 是 | 用于存储键值对。 | -- Gitee From 709661ab03538794cc6659e0aac2a25b77b71929 Mon Sep 17 00:00:00 2001 From: sun-dou Date: Fri, 18 Feb 2022 16:14:52 +0800 Subject: [PATCH 03/11] update doc Signed-off-by: sun-dou --- .../reference/apis/js-apis-data-rdb.md | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/zh-cn/application-dev/reference/apis/js-apis-data-rdb.md b/zh-cn/application-dev/reference/apis/js-apis-data-rdb.md index d1b8d80223d..201eaf04fa2 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-data-rdb.md +++ b/zh-cn/application-dev/reference/apis/js-apis-data-rdb.md @@ -1241,7 +1241,7 @@ setDistributedTables(tables: Array, callback: AsyncCallback): void - 示例： ``` - rdbStore.setDistributedTables(['EMPLOYEE'], function () { + rdbStore.setDistributedTables(["EMPLOYEE"], function () { console.info(TAG + 'setDistributedTables done.')}) ``` @@ -1255,7 +1255,7 @@ setDistributedTables(tables: Array, callback: AsyncCallback): void - 参数： | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | - | tables | Array | 是 | 要设置的分布式列表表名 | + | tables | Array | 是 | 要设置的分布式列表表名。 | - 返回值： | 类型 | 说明 | @@ -1264,7 +1264,7 @@ setDistributedTables(tables: Array, callback: AsyncCallback): void - 示例： ``` - let promise = rdbStore.setDistributedTables(['EMPLOYEE']) + let promise = rdbStore.setDistributedTables(["EMPLOYEE"]) promise.then(() => { console.info(TAG + 'setDistributedTables done.')}) ``` @@ -1278,13 +1278,13 @@ obtainDistributedTableName(device: string, table: string, callback: AsyncCallbac - 参数： | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | - | device | string | 是 | 远程设备 | - | table | string | 是 | 本地表名 | - | callback | AsyncCallback<string> | 是 | 指定的callback回调函数。如果操作成功，返回分布式表名。 | + | device | string | 是 | 远程设备 。| + | table | string | 是 | 本地表名。 | + | callback | AsyncCallback<string> | 是 | 指定的callback回调函数。如果操作成功，返回远程设备的分布式表名。 | - 示例： ``` - rdbStore.obtainDistributedTableName(deviceId, 'EMPLOYEE', function () { + rdbStore.obtainDistributedTableName(deviceId, "EMPLOYEE", function (err, tabeName) { console.info(TAG + 'obtainDistributedTableName done.')}) ``` @@ -1304,11 +1304,11 @@ obtainDistributedTableName(device: string, table: string, callback: AsyncCallbac - 返回值： | 类型 | 说明 | | -------- | -------- | - | Promise<string> | 指定Promise回调函数。如果操作成功，返回分布式表名。 | + | Promise<string> | 指定Promise回调函数。如果操作成功，返回远程设备的分布式表名。 | - 示例： ``` - let promise = rdbStore.obtainDistributedTableName(deviceId, 'EMPLOYEE') + let promise = rdbStore.obtainDistributedTableName(deviceId, "EMPLOYEE") promise.then(() => { console.info(TAG + 'obtainDistributedTableName done.')}) ``` @@ -1328,7 +1328,7 @@ sync(mode: SyncMode, predicates: RdbPredicates, callback: AsyncCallback Date: Fri, 18 Feb 2022 17:48:38 +0800 Subject: [PATCH 04/11] update doc Signed-off-by: sun-dou --- .../reference/apis/js-apis-data-rdb.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/zh-cn/application-dev/reference/apis/js-apis-data-rdb.md b/zh-cn/application-dev/reference/apis/js-apis-data-rdb.md index 201eaf04fa2..165d9727869 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-data-rdb.md +++ b/zh-cn/application-dev/reference/apis/js-apis-data-rdb.md @@ -158,13 +158,13 @@ constructor(name: string) inDevices(devices: Array): RdbPredicates; -同步分布式数据库时指定远程设备。 +同步分布式数据库时指定组网内的远程设备。 - 参数： | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | - | devices | Array | 是 | 指定的远程设备。 | + | devices | Array | 是 | 指定的组网内的远程设备ID。 | - 返回值： | 类型 | 说明 | @@ -174,7 +174,7 @@ inDevices(devices: Array): RdbPredicates; - 示例： ``` let predicates = new data_rdb.RdbPredicates("EMPLOYEE") - predicates.inDevices(['device']) + predicates.inDevices(device) ``` ### inAllDevices @@ -182,7 +182,7 @@ inDevices(devices: Array): RdbPredicates; inAllDevices(): RdbPredicates; -指定同步分布式数据库时连接到本地设备的所有远程设备。 +同步分布式数据库时连接到组网内的所有远程设备。 - 返回值： @@ -1322,7 +1322,7 @@ sync(mode: SyncMode, predicates: RdbPredicates, callback: AsyncCallback> | 是 | 指定的callback回调函数，用于向调用者发送同步结果。string：设备ID；number：每个设备同步状态，0表示成功，1表示失败。| @@ -1342,13 +1342,13 @@ sync(mode: SyncMode, predicates: RdbPredicates, callback: AsyncCallback> | 指定Promise回调函数。用于向调用者发送同步结果。string：设备ID；number：每个设备同步状态，0表示成功，1表示失败。 | + | Promise<Array<[string, number]>> | 指定Promise回调函数，用于向调用者发送同步结果。string：设备ID；number：每个设备同步状态，0表示成功，1表示失败。 | - 示例： ``` -- Gitee From e0924913992d9013a14b29f94e4b20a52e17612a Mon Sep 17 00:00:00 2001 From: sun-dou Date: Sat, 19 Feb 2022 19:16:38 +0800 Subject: [PATCH 05/11] update docs Signed-off-by: sun-dou --- .../reference/apis/js-apis-data-rdb.md | 98 +++++++++++++++---- 1 file changed, 79 insertions(+), 19 deletions(-) diff --git a/zh-cn/application-dev/reference/apis/js-apis-data-rdb.md b/zh-cn/application-dev/reference/apis/js-apis-data-rdb.md index 165d9727869..9883dd540a8 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-data-rdb.md +++ b/zh-cn/application-dev/reference/apis/js-apis-data-rdb.md @@ -1241,8 +1241,13 @@ setDistributedTables(tables: Array, callback: AsyncCallback): void - 示例： ``` - rdbStore.setDistributedTables(["EMPLOYEE"], function () { - console.info(TAG + 'setDistributedTables done.')}) + rdbStore.setDistributedTables(["EMPLOYEE"], function (err) { + if (err) { + console.info('setDistributedTables failed.') + return + } + console.info('setDistributedTables success.') + }) ``` @@ -1266,7 +1271,10 @@ setDistributedTables(tables: Array, callback: AsyncCallback): void ``` let promise = rdbStore.setDistributedTables(["EMPLOYEE"]) promise.then(() => { - console.info(TAG + 'setDistributedTables done.')}) + console.info("setDistributedTables success.") + }).catch((err) => { + console.info("setDistributedTables failed."") + }) ``` ### obtainDistributedTableName @@ -1284,8 +1292,13 @@ obtainDistributedTableName(device: string, table: string, callback: AsyncCallbac - 示例： ``` - rdbStore.obtainDistributedTableName(deviceId, "EMPLOYEE", function (err, tabeName) { - console.info(TAG + 'obtainDistributedTableName done.')}) + rdbStore.obtainDistributedTableName(deviceId, "EMPLOYEE", function (err, tableName) { + if (err) { + console.info('obtainDistributedTableName failed.') + return + } + console.info('obtainDistributedTableName success, tableName=.' + tableName) + }) ``` @@ -1309,8 +1322,11 @@ obtainDistributedTableName(device: string, table: string, callback: AsyncCallbac - 示例： ``` let promise = rdbStore.obtainDistributedTableName(deviceId, "EMPLOYEE") - promise.then(() => { - console.info(TAG + 'obtainDistributedTableName done.')}) + promise.then((tableName) => { + console.info('obtainDistributedTableName success, tableName=' + tableName) + }).catch((err) => { + console.info('obtainDistributedTableName failed.') + }) ``` ### sync @@ -1324,12 +1340,22 @@ sync(mode: SyncMode, predicates: RdbPredicates, callback: AsyncCallback> | 是 | 指定的callback回调函数，用于向调用者发送同步结果。string：设备ID；number：每个设备同步状态，0表示成功，1表示失败。| + | callback | AsyncCallback<Array<[string, number]>> | 是 | 指定的callback回调函数，用于向调用者发送同步结果。string：设备ID；number：每个设备同步状态，0表示成功，其他值表示失败。| - 示例： ``` - rdbStore.sync(rdb.SyncMode.SYNC_MODE_PUSH, precdicate, function (err, [[devices[i], number]]) { - console.info(TAG + 'sync done.')}) + let predicate = new rdb.RdbPredicates('EMPLOYEE') + predicate.inDevices(['12345678abcde']) + rdbStore.sync(rdb.SyncMode.SYNC_MODE_PUSH, predicate, function (err, result) { + if (err) { + console.log('sync failed') + return + } + console.log('sync done.') + for (let i = 0; i < result.length; i++) { + console.log('device=' + result[i][0] + ' status=' + result[i][1]) + } + }) ``` @@ -1348,13 +1374,21 @@ sync(mode: SyncMode, predicates: RdbPredicates, callback: AsyncCallback> | 指定Promise回调函数，用于向调用者发送同步结果。string：设备ID；number：每个设备同步状态，0表示成功，1表示失败。 | + | Promise<Array<[string, number]>> | 指定Promise回调函数，用于向调用者发送同步结果。string：设备ID；number：每个设备同步状态，0表示成功，其他值表示失败。 | - 示例： ``` - let promise = rdbStore.sync(rdb.SyncMode.SYNC_MODE_PUSH, precdicate) - promise.then(() => { - console.info(TAG + 'sync done.')}) + let predicate = new rdb.RdbPredicates('EMPLOYEE') + predicate.inDevices(['12345678abcde']) + let promise = rdbStore.sync(rdb.SyncMode.SYNC_MODE_PUSH, predicate) + promise.then(result) { + console.log('sync done.') + for (let i = 0; i < result.length; i++) { + console.log('device=' + result[i][0] + ' status=' + result[i][1]) + } + }).catch((err) => { + console.log('sync failed') + }) ``` ### on @@ -1371,8 +1405,16 @@ on(event: 'dataChange', type: SubscribeType, observer: Callback>): - 示例： ``` - rdbStore.on(“dataChange”, rdb.SubscribeType.SUBSCRIBE_TYPE_REMOTE, function (err, devices) { - console.info(TAG + 'on done.')}) + function storeObserver(devices) { + for (let i = 0; i < devices.length; i++) { + console.log('device=' + device[i] + ' data changed') + } + } + try { + rdbStore.on('dataChange', rdb.SubscribeType.SUBSCRIBE_TYPE_REMOTE, storeObserver) + } catch (err) { + console.log('register observer failed') + } ``` ### off @@ -1389,8 +1431,16 @@ off(event:'dataChange', type: SubscribeType, observer: Callback>): - 示例： ``` - rdbStore.on(dataChange”, rdb.SubscribeType.SUBSCRIBE_TYPE_REMOTE, function (err, devices) { - console.info(TAG + 'off done.')}) + function storeObserver(devices) { + for (let i = 0; i < devices.length; i++) { + console.log('device=' + device[i] + ' data changed') + } + } + try { + rdbStore.off('dataChange', rdb.SubscribeType.SUBSCRIBE_TYPE_REMOTE, storeObserver) + } catch (err) { + console.log('unregister observer failed') + } ``` @@ -1413,13 +1463,23 @@ off(event:'dataChange', type: SubscribeType, observer: Callback>): | string | 表示值类型为字符。 | | boolean | 表示值类型为布尔值。| +## ValuesBucket + +用于存储键值对。 + + +| 名称 | 参数类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| [key: string] | [ValueType](#valuetype)\| Uint8Array \| null | 是 | 用于存储键值对。 | + + ## SyncMode 指数据库同步模式。 | 名称 | 说明 | | -------- | -------- | -| SYNC_MODE_PUSH | 表示数据已从本地设备推送到远程设备。 | +| SYNC_MODE_PUSH | 表示数据从本地设备推送到远程设备。 | | SYNC_MODE_PULL | 表示数据从远程设备拉至本地设备。 | ## SubscribeType -- Gitee From 90da6111e819dc7e4257f30884c7fe6f821aeebb Mon Sep 17 00:00:00 2001 From: sun-dou Date: Sat, 19 Feb 2022 19:27:33 +0800 Subject: [PATCH 06/11] update docs Signed-off-by: sun-dou --- zh-cn/application-dev/reference/apis/js-apis-data-rdb.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/zh-cn/application-dev/reference/apis/js-apis-data-rdb.md b/zh-cn/application-dev/reference/apis/js-apis-data-rdb.md index 9883dd540a8..4a57f3d47c0 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-data-rdb.md +++ b/zh-cn/application-dev/reference/apis/js-apis-data-rdb.md @@ -174,7 +174,7 @@ inDevices(devices: Array): RdbPredicates; - 示例： ``` let predicates = new data_rdb.RdbPredicates("EMPLOYEE") - predicates.inDevices(device) + predicate.inDevices(['12345678abcde']) ``` ### inAllDevices -- Gitee From 2a8b4ecc7f6ce48296e9fef3308678d4c5f8651a Mon Sep 17 00:00:00 2001 From: sun-dou Date: Sat, 19 Feb 2022 19:52:57 +0800 Subject: [PATCH 07/11] update docs Signed-off-by: sun-dou --- zh-cn/application-dev/reference/apis/js-apis-data-rdb.md | 1 + 1 file changed, 1 insertion(+) diff --git a/zh-cn/application-dev/reference/apis/js-apis-data-rdb.md b/zh-cn/application-dev/reference/apis/js-apis-data-rdb.md index 4a57f3d47c0..b17b701722f 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-data-rdb.md +++ b/zh-cn/application-dev/reference/apis/js-apis-data-rdb.md @@ -1489,3 +1489,4 @@ off(event:'dataChange', type: SubscribeType, observer: Callback>): | 名称 | 说明 | | -------- | -------- | | SUBSCRIBE_TYPE_REMOTE | 订阅远程数据更改。 | + -- Gitee From fbc043478b1ed0e1a33c5d518ef467c1350adbd9 Mon Sep 17 00:00:00 2001 From: sun-dou Date: Sat, 19 Feb 2022 20:03:56 +0800 Subject: [PATCH 08/11] update docs Signed-off-by: sun-dou --- zh-cn/application-dev/reference/apis/js-apis-data-rdb.md | 1 - 1 file changed, 1 deletion(-) diff --git a/zh-cn/application-dev/reference/apis/js-apis-data-rdb.md b/zh-cn/application-dev/reference/apis/js-apis-data-rdb.md index b17b701722f..4a57f3d47c0 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-data-rdb.md +++ b/zh-cn/application-dev/reference/apis/js-apis-data-rdb.md @@ -1489,4 +1489,3 @@ off(event:'dataChange', type: SubscribeType, observer: Callback>): | 名称 | 说明 | | -------- | -------- | | SUBSCRIBE_TYPE_REMOTE | 订阅远程数据更改。 | - -- Gitee From dccfedf5213880eb49bcfb6a410c1559475cf914 Mon Sep 17 00:00:00 2001 From: sun-dou Date: Mon, 21 Feb 2022 19:20:21 +0800 Subject: [PATCH 09/11] update docs Signed-off-by: sun-dou --- .../database-relational-guidelines.md | 50 +++++++++++ .../reference/apis/js-apis-data-rdb.md | 5 +- .../subsys-data-relational-database-guide.md | 82 ++++++++++++++----- 3 files changed, 115 insertions(+), 22 deletions(-) diff --git a/zh-cn/application-dev/database/database-relational-guidelines.md b/zh-cn/application-dev/database/database-relational-guidelines.md index 127fa0bae8e..ff9e6b6c1e8 100644 --- a/zh-cn/application-dev/database/database-relational-guidelines.md +++ b/zh-cn/application-dev/database/database-relational-guidelines.md @@ -76,6 +76,8 @@ | 类名 | 接口名 | 描述 | | -------- | -------- | -------- | +| RdbPredicates |inDevices(devices: Array): RdbPredicates | 配置谓词以匹配数据字段为string数组的指定字段。
- devices：组网内指定的远程设备ID。
- RdbPredicates：返回与指定字段匹配的谓词。 | +| RdbPredicates |inAllDevices(): RdbPredicates | 向谓词添加组网内所有远程设备。
- RdbPredicates：返回与指定字段匹配的谓词。 | | RdbPredicates | equalTo(field: string, value: ValueType): RdbPredicates | 配置谓词以匹配数据字段为ValueType且值等于指定值的字段。
- field：数据库表中的列名。
- value：指示要与谓词匹配的值。
- RdbPredicates：返回与指定字段匹配的谓词。 | | RdbPredicates | notEqualTo(field: string, value: ValueType): RdbPredicates | 配置谓词以匹配数据字段为ValueType且值不等于指定值的字段。
- field：数据库表中的列名。
- value：指示要与谓词匹配的值。
- RdbPredicates：返回与指定字段匹配的谓词。 | | RdbPredicates | beginWrap(): RdbPredicates | 向谓词添加左括号。
- RdbPredicates：返回带有左括号的谓词。 | @@ -145,6 +147,54 @@ | RdbStore | changeEncryptKey(newEncryptKey:Uint8Array, callback: AsyncCallback<number>):void; | 数据库更改秘钥接口，通过callback 可以异步处理返回结果。返回结果0成功，非0失败。 | | RdbStore | changeEncryptKey(newEncryptKey:Uint8Array): Promise<number>; | 数据库更改秘钥接口，通过await 可以同步处理返回结果。返回结果0成功，非0失败。 | +**设置分布式列表。** + +用户可以对当前数据库中的列表设置为分布式列表。 + +**表9** 设置分布式列表 + +| 类名 | 接口名 | 描述 | +| -------- | -------- | -------- | +| RdbStore | setDistributedTables(tables: Array, callback: AsyncCallback): void;| 设置分布式列表，结果以callback形式返回。
- tables：要设置的分布式列表表名。
- callback：指定callback回调函数。 | +| RdbStore | setDistributedTables(tables: Array): Promise; | 设置分布式列表，结果以Promise形式返回。
- tables：要设置的分布式列表表名。 | + +**根据本地表名获取指定远程设备的分布式表名。** + +用户根据本地表名获取指定远程设备的分布式表名。在查询远程设备数据库时，需要使用分布式表名。 + +**表10** 根据本地表名获取指定远程设备的分布式表名 + +| 类名 | 接口名 | 描述 | +| -------- | -------- | -------- | +| RdbStore | obtainDistributedTableName(device: string, table: string, callback: AsyncCallback): void; | 根据本地表名获取指定远程设备的分布式表名。在查询远程设备数据库时，需要使用分布式表名, 结果以callbck形式返回。
- device：远程设备。
- table：本地表名。
- callback：指定的callback回调函数，如果操作成功，返回远程设备的分布式表名。 | +| RdbStore | obtainDistributedTableName(device: string, table: string): Promise; | 根据本地表名获取指定远程设备的分布式表名。在查询远程设备数据库时，需要使用分布式表名，结果以Promise形式返回。
- device：远程设备。
- table：本地表名。 | + +**在设备之间同步数据。** + +**表11** 在设备之间同步数据 + +| 类名 | 接口名 | 描述 | +| -------- | -------- | -------- | +| RdbStore | sync(mode: SyncMode, predicates: RdbPredicates, callback: AsyncCallback>): void;| 在设备之间同步数据，结果以callback形式返回。
- mode：指同步模式。SYNC_MODE_PUSH 表示数据从本地设备推送到远程设备；SYNC_MODE_PULL 表示数据从远程设备拉至本地设备。
- predicates：约束同步数据和设备。
- callback：指定的callback回调函数，string：设备ID；number：每个设备同步状态，0表示成功，其他值表示失败。 | +| RdbStore | sync(mode: SyncMode, predicates: RdbPredicates): Promise>;| 在设备之间同步数据，结果以Promise形式返回。
- mode：指同步模式。SYNC_MODE_PUSH 表示数据从本地设备推送到远程设备；SYNC_MODE_PULL 表示数据从远程设备拉至本地设备。
- predicates：约束同步数据和设备。 | + + +**注册数据库的观察者。** + +**表12** 注册数据库的观察者 + +| 类名 | 接口名 | 描述 | +| -------- | -------- | -------- | +| RdbStore |on(event: 'dataChange', type: SubscribeType, observer: Callback>): void;| 注册数据库的观察者。当分布式数据库中的数据发生更改时，将调用回调。
- type：指在{@code SubscribeType}中定义的订阅类型；SUBSCRIBE_TYPE_REMOTE 订阅远程数据更改。
- observer：指分布式数据库中数据更改事件的观察者。 | + +**从数据库中删除指定类型的指定观察者。** + +**表13** 从数据库中删除指定类型的指定观察者 + +| 类名 | 接口名 | 描述 | +| -------- | -------- | -------- | +| RdbStore |off(event:'dataChange', type: SubscribeType, observer: Callback>): void;| 从数据库中删除指定类型的指定观察者，结果以callbck形式返回。。
- type：指在{@code SubscribeType}中定义的订阅类型；SUBSCRIBE_TYPE_REMOTE 订阅远程数据更改。
- observer：指已注册的数据更改观察者。 | + ## 开发步骤 diff --git a/zh-cn/application-dev/reference/apis/js-apis-data-rdb.md b/zh-cn/application-dev/reference/apis/js-apis-data-rdb.md index 4a57f3d47c0..1a486855cfc 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-data-rdb.md +++ b/zh-cn/application-dev/reference/apis/js-apis-data-rdb.md @@ -1311,8 +1311,8 @@ obtainDistributedTableName(device: string, table: string, callback: AsyncCallbac - 参数： | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | - | device | string | 是 | 远程设备 | - | table | string | 是 | 本地表名 | + | device | string | 是 | 远程设备。 | + | table | string | 是 | 本地表名。 | - 返回值： | 类型 | 说明 | @@ -1463,6 +1463,7 @@ off(event:'dataChange', type: SubscribeType, observer: Callback>): | string | 表示值类型为字符。 | | boolean | 表示值类型为布尔值。| + ## ValuesBucket 用于存储键值对。 diff --git a/zh-cn/device-dev/subsystems/subsys-data-relational-database-guide.md b/zh-cn/device-dev/subsystems/subsys-data-relational-database-guide.md index 15df71090d0..1fa9effc79f 100644 --- a/zh-cn/device-dev/subsystems/subsys-data-relational-database-guide.md +++ b/zh-cn/device-dev/subsystems/subsys-data-relational-database-guide.md @@ -36,7 +36,7 @@ - RdbPredicates：开发者无需编写复杂的SQL语句，仅通过调用该类中条件相关的方法，如equalTo、notEqualTo、groupBy、orderByAsc、beginsWith等，就可自动完成SQL语句拼接，方便用户聚焦业务操作。 - RawRdbPredicates：可满足复杂SQL语句的场景，支持开发者自己设置where条件子句和whereArgs参数。不支持equalTo等条件接口的使用。 - 表7 数据库谓词API + 表3 数据库谓词API | 类名 | 接口名 | 描述 | | ---- | ---- | ---- | | RdbPredicates | AbsPredicates *EqualTo(std::string field, std::string value) | 设置谓词条件，满足field字段与value值相等。 | @@ -46,6 +46,9 @@ | RdbPredicates | AbsPredicates *OrderByAsc(std::string field) | 设置谓词条件，根据field字段升序排列。 | | RdbPredicates | void SetWhereClause(std::string whereClause) | 设置where条件子句。 | | RdbPredicates | void SetWhereArgs(std::vector\ whereArgs) | 设置whereArgs参数，该值表示where子句中占位符的值。 | + | RdbPredicates | AbsRdbPredicates *InDevices(std::vector& devices) | 设置谓词条件，同步分布式数据库时指定组网内的远程设备。 | + | RdbPredicates | AbsRdbPredicates *InAllDevices() | 设置谓词条件，同步分布式数据库时连接到组网内的所有远程设备。| + ### 数据表的增删改查 @@ -55,7 +58,7 @@ 关系型数据库提供了插入数据的接口，通过ValuesBucket输入要存储的数据，通过返回值判断是否插入成功，插入成功时返回最新插入数据所在的行号，失败时则返回-1。 - 表3 数据表插入API + 表4 数据表插入API | 类名 | 接口名 | 描述 | | ---- | ---- | ---- | @@ -74,7 +77,7 @@ 调用更新接口，传入要更新的数据，并通过AbsRdbPredicates指定更新条件。该接口的返回值表示更新操作影响的行数。如果更新失败，则返回0。 - 表4 数据表更新API + 表6 数据表更新API | 类名 | 接口名 | 描述 | | ---- | ---- | ---- | | RdbStore | int Update(int &changedRows, const ValuesBucket &values, const AbsRdbPredicates &predicates) | 更新数据库表中符合谓词指定条件的数据。
  • changedRows：更新的记录条数。
  • values：以ValuesBucket存储的要更新的数据。
  • predicates：指定了更新操作的表名和条件。AbsRdbPredicates的实现类有两个：RdbPredicates和RawRdbPredicates。
    • RdbPredicates：支持调用谓词提供的equalTo等接口，设置更新条件。
    • RawRdbPredicates：仅支持设置表名、where条件子句、whereArgs三个参数，不支持equalTo等接口调用。
| @@ -86,7 +89,7 @@ - 直接调用查询接口。使用该接口，会将包含查询条件的谓词自动拼接成完整的SQL语句进行查询操作，无需用户传入原生的SQL语句。 - 执行原生的SQL语句进行查询操作。 - 表6 数据表查询API + 表7 数据表查询API | 类名 | 接口名 | 描述 | | ---- | ---- | ---- | | RdbStore | std::unique_ptr Query(const AbsRdbPredicates &predicates, const std::vector\ columns) | 查询数据。
  • predicates：谓词，可以设置查询条件。AbsRdbPredicates的实现类有两个：RdbPredicates和RawRdbPredicates。
    • RdbPredicates：支持调用谓词提供的equalTo等接口，设置更新条件。
    • RawRdbPredicates：仅支持设置表名、where条件子句、whereArgs三个参数，不支持equalTo等接口调用。
  • columns：规定查询返回的列。
| @@ -96,22 +99,61 @@ 关系型数据库提供了查询返回的结果集ResultSet，其指向查询结果中的一行数据，供用户对查询结果进行遍历和访问。ResultSet对外API如下所示。 - 表8 结果集API - | 类名 | 接口名 | 描述 | - | ---- | ---- | ---- | - | ResultSet | int GoTo(int offset) | 从结果集当前位置移动指定偏移量。 | - | ResultSet | int GoToRow(int position) | 将结果集移动到指定位置。 | - | ResultSet | int GoToNextRow() | 将结果集向后移动一行。 | - | ResultSet | int GoToPreviousRow() | 将结果集向前移动一行。 | - | ResultSet | int IsStarted(bool &result) | 判断结果集是否被移动过。 | - | ResultSet | int IsEnded(bool &result) | 判断结果集是否被移动到最后一行之后。 | - | ResultSet | int IsAtFirstRow(bool &result) | 判断结果集当前位置是否在第一行。 | - | ResultSet | int IsAtLastRow(bool &result) | 判断结果集当前位置是否在最后一行。 | - | ResultSet | int GetRowCount(int &count) | 获取当前结果集中的记录条数。 | - | ResultSet | int GetColumnCount(int &count) | 获取结果集中的列数。 | - | ResultSet | int GetString(int columnIndex, std::string &value) | 获取当前行指定列的值，以String类型返回。 | - | ResultSet | int GetBlob(int columnIndex, std::vector\ &blob) | 获取当前行指定列的值，以字节数组形式返回。 | - | ResultSet | int GetDouble(int columnIndex, double &value) | 获取当前行指定列的值，以double型返回。 | +表8 结果集API +| 类名 | 接口名 | 描述 | +| ---- | ---- | ---- | +| ResultSet | int GoTo(int offset) | 从结果集当前位置移动指定偏移量。 | +| ResultSet | int GoToRow(int position) | 将结果集移动到指定位置。 | +| ResultSet | int GoToNextRow() | 将结果集向后移动一行。 | +| ResultSet | int GoToPreviousRow() | 将结果集向前移动一行。 | +| ResultSet | int IsStarted(bool &result) | 判断结果集是否被移动过。 | +| ResultSet | int IsEnded(bool &result) | 判断结果集是否被移动到最后一行之后。 | +| ResultSet | int IsAtFirstRow(bool &result) | 判断结果集当前位置是否在第一行。 | +| ResultSet | int IsAtLastRow(bool &result) | 判断结果集当前位置是否在最后一行。 | +| ResultSet | int GetRowCount(int &count) | 获取当前结果集中的记录条数。 | +| ResultSet | int GetColumnCount(int &count) | 获取结果集中的列数。 | +| ResultSet | int GetString(int columnIndex, std::string &value) | 获取当前行指定列的值，以String类型返回。 | +| ResultSet | int GetBlob(int columnIndex, std::vector\ &blob) | 获取当前行指定列的值，以字节数组形式返回。 | +| ResultSet | int GetDouble(int columnIndex, double &value) | 获取当前行指定列的值，以double型返回。 | + +### 设置分布式列表 + +用户可以对当前数据库中的列表设置为分布式列表。 + +表9 设置分布式列表 +| 类名 | 接口名 | 描述 | +| ---- | ---- | ---- | +| RdbStore | bool SetDistributedTables(const std::vector& tables) | 设置分布式列表。
  • tables：要设置的分布式列表表名
+ +### 根据本地表名获取指定远程设备的分布式表名 + +用户根据本地表名获取指定远程设备的分布式表名。在查询远程设备数据库时，需要使用分布式表名。 + +表9 根据本地表名获取指定远程设备的分布式表名 +| 类名 | 接口名 | 描述 | +| ---- | ---- | ---- | +| RdbStore | std::string ObtainDistributedTableName(const std::string& device, const std::string& table) | 根据本地表名获取指定远程设备的分布式表名。在查询远程设备数据库时，需要使用分布式表名。
  • device：远程设备ID
  • table：本地表名
+ +### 在设备之间同步数据 + +表10 在设备之间同步数据 +| 类名 | 接口名 | 描述 | +| ---- | ---- | ---- | +| RdbStore | bool Sync(const SyncOption& option, const AbsRdbPredicates& predicate, const SyncCallback& callback) | 在设备之间同步数据。
  • option：同步选项；mode：同步模式(PUSH表示数据从本地设备推送到远程设备/PULL表示数据从远程设备拉至本地设备)；isBlock：是否阻塞
  • callback：指定的callback回调函数
+ +### 注册数据库的观察者 + +表10 注册数据库的观察者 +| 类名 | 接口名 | 描述 | +| ---- | ---- | ---- | +| RdbStore | bool Subscribe(const SubscribeOption& option, RdbStoreObserver *observer) | 注册数据库的观察者。当分布式数据库中的数据发生更改时，将调用回调。
  • option：订阅类型；
  • observer：指分布式数据库中数据更改事件的观察者
+ +### 从数据库中删除指定类型的指定观察者 + +表10 从数据库中删除指定类型的指定观察者 +| 类名 | 接口名 | 描述 | +| ---- | ---- | ---- | +| RdbStore | bool UnSubscribe(const SubscribeOption& option, RdbStoreObserver *observer) | 从数据库中删除指定类型的指定观察者。
  • option：订阅类型；
  • observer：指已注册的数据更改观察者
## 约束与限制 -- Gitee From b56c870b1c38af76b2d4c6835975b75937c2d188 Mon Sep 17 00:00:00 2001 From: sun-dou Date: Tue, 22 Feb 2022 11:36:22 +0800 Subject: [PATCH 10/11] update docs Signed-off-by: sun-dou --- .../database-relational-guidelines.md | 70 +++++++++++++++++- .../subsys-data-relational-database-guide.md | 72 +++++++++++++++++++ 2 files changed, 140 insertions(+), 2 deletions(-) diff --git a/zh-cn/application-dev/database/database-relational-guidelines.md b/zh-cn/application-dev/database/database-relational-guidelines.md index ff9e6b6c1e8..bd24f69f501 100644 --- a/zh-cn/application-dev/database/database-relational-guidelines.md +++ b/zh-cn/application-dev/database/database-relational-guidelines.md @@ -76,8 +76,8 @@ | 类名 | 接口名 | 描述 | | -------- | -------- | -------- | -| RdbPredicates |inDevices(devices: Array): RdbPredicates | 配置谓词以匹配数据字段为string数组的指定字段。
- devices：组网内指定的远程设备ID。
- RdbPredicates：返回与指定字段匹配的谓词。 | -| RdbPredicates |inAllDevices(): RdbPredicates | 向谓词添加组网内所有远程设备。
- RdbPredicates：返回与指定字段匹配的谓词。 | +| RdbPredicates |inDevices(devices: Array): RdbPredicates | 同步分布式数据库时指定组网内的远程设备。
- devices：组网内指定的远程设备ID。
- RdbPredicates：返回与指定字段匹配的谓词。 | +| RdbPredicates |inAllDevices(): RdbPredicates | 同步分布式数据库时连接到组网内的所有远程设备。
- RdbPredicates：返回与指定字段匹配的谓词。 | | RdbPredicates | equalTo(field: string, value: ValueType): RdbPredicates | 配置谓词以匹配数据字段为ValueType且值等于指定值的字段。
- field：数据库表中的列名。
- value：指示要与谓词匹配的值。
- RdbPredicates：返回与指定字段匹配的谓词。 | | RdbPredicates | notEqualTo(field: string, value: ValueType): RdbPredicates | 配置谓词以匹配数据字段为ValueType且值不等于指定值的字段。
- field：数据库表中的列名。
- value：指示要与谓词匹配的值。
- RdbPredicates：返回与指定字段匹配的谓词。 | | RdbPredicates | beginWrap(): RdbPredicates | 向谓词添加左括号。
- RdbPredicates：返回带有左括号的谓词。 | @@ -248,3 +248,69 @@ resultSet.close() ``` + +4. 设置分布式同步表。 + 1. 数据库调用接口设置分布式同步列表。 + 2. 判断是否设置成功。 + + 示例代码如下： + + ``` + let promise = rdbStore.setDistributedTables(["test"]) + promise.then(() => { + console.info("setDistributedTables success.") + }).catch((err) => { + console.info("setDistributedTables failed."") + }) + ``` + + 5. 分布式数据同步。 + 1. 构造用于同步分布式表的谓词对象，指定组网内的远程设备。 + 2. 调用同步数据的接口 。 + 3. 判断是否数据同步成功。 + + 示例代码如下： + + ``` + let predicate = new dataRdb.RdbPredicates('test') + predicate.inDevices(['12345678abcde']) + let promise = rdbStore.sync(rdb.SyncMode.SYNC_MODE_PUSH, predicate) + promise.then(result) { + console.log('sync done.') + for (let i = 0; i < result.length; i++) { + console.log('device=' + result[i][0] + ' status=' + result[i][1]) + } + }).catch((err) => { + console.log('sync failed') + }) + ``` + +6. 分布式数据订阅。 + 1. 调用分布式数据订阅接口，注册数据库的观察者。 + 2. 当分布式数据库中的数据发生更改时，将调用回调。 + + 示例代码如下： + + ``` + function storeObserver(devices) { + for (let i = 0; i < devices.length; i++) { + console.log('device=' + device[i] + ' data changed') + } + } + try { + rdbStore.on('dataChange', rdb.SubscribeType.SUBSCRIBE_TYPE_REMOTE, storeObserver) + } catch (err) { + console.log('register observer failed') + } + ``` + +7. 跨设备查询。 + 1. 根据本地表名获取指定远程设备的分布式表名。 + 2. 调用结果集接口，返回查询结果。 + + 示例代码如下： + + ``` + let tableName = rdbStore.obtainDistributedTableName(deviceId, "test"); + let resultSet = rdbStore.querySql("SELECT * FROM " + tableName) + ``` \ No newline at end of file diff --git a/zh-cn/device-dev/subsystems/subsys-data-relational-database-guide.md b/zh-cn/device-dev/subsystems/subsys-data-relational-database-guide.md index 1fa9effc79f..7f9673a0939 100644 --- a/zh-cn/device-dev/subsystems/subsys-data-relational-database-guide.md +++ b/zh-cn/device-dev/subsystems/subsys-data-relational-database-guide.md @@ -231,3 +231,75 @@ resultSet.goToNextRow(); ``` +4. 设置分布式同步表 + + a. 调用接口设置分布式同步表。 + + 示例代码如下： + + ``` + store->SetDistributedTables("test"); + ``` + +5. 分布式数据同步 + + a. 定义同步模式和阻塞状态。 + + b. 构造用于同步分布式表的谓词对象，指定组网内的远程设备。 + + c. 调用接口同步数据。 + + 示例代码如下： + + ``` + SyncOption option; + option.mode = PUSH; + option.isBlock = true; + AbsRdbPredicates predicate("test"); + predicate.InAllDevices(); + store->Sync(option, predicate, []（const SyncResult& result) { + for (const auto& [device, status] : result) { + LogI("device=%s status=%d", device.c_str(), status); + } + }); + ``` + +6. 分布式数据订阅 + + a. 重写数据更改观察者OnChange()函数。 + + b. 定义分布式数据订阅类型。 + + c. 调用接口实现分布式数据订阅，或取消订阅。 + + 示例代码如下： + + ``` + class MyObserver : public RdbStoreObserver { + public: + void OnChange(const std::vector& devices) override { + for (const auto& device ： devices) { + LOGI("device=%s data change", device.c_str()); + } + } + }; + + SubscribeOption option; + option.mode = SubscribeMode::REMOTE; + MyObserver observer; + Subscribe(option, &observer); // 分布式数据订阅 + + UnSubscribe(option, &observer); // 取消订阅 + ``` + +7. 跨设备查询 + + a. 根据本地表名获取指定远程设备的分布式表名。 + + b. 根据指定SQL语句查询数据库中的数据。 + + 示例代码如下： + ``` + std::string tableName = store->ObtainDistributedTableName("123456789abcd", "test"); + auto resultSet = store->QuerySql("SELECT * from ?;", tableName); + ``` -- Gitee From 1f011efafa6504b07c399cf64dd26d5228a192c9 Mon Sep 17 00:00:00 2001 From: sun-dou Date: Tue, 22 Feb 2022 14:58:10 +0800 Subject: [PATCH 11/11] update docs Signed-off-by: sun-dou --- .../subsystems/subsys-data-relational-database-guide.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/zh-cn/device-dev/subsystems/subsys-data-relational-database-guide.md b/zh-cn/device-dev/subsystems/subsys-data-relational-database-guide.md index 7f9673a0939..ef830096d1e 100644 --- a/zh-cn/device-dev/subsystems/subsys-data-relational-database-guide.md +++ b/zh-cn/device-dev/subsystems/subsys-data-relational-database-guide.md @@ -262,7 +262,7 @@ LogI("device=%s status=%d", device.c_str(), status); } }); - ``` + ``` 6. 分布式数据订阅 @@ -278,7 +278,7 @@ class MyObserver : public RdbStoreObserver { public: void OnChange(const std::vector& devices) override { - for (const auto& device ： devices) { + for (const auto& device : devices) { LOGI("device=%s data change", device.c_str()); } } @@ -287,9 +287,9 @@ SubscribeOption option; option.mode = SubscribeMode::REMOTE; MyObserver observer; - Subscribe(option, &observer); // 分布式数据订阅 + store->Subscribe(option, &observer); // 分布式数据订阅 - UnSubscribe(option, &observer); // 取消订阅 + store->UnSubscribe(option, &observer); // 取消订阅 ``` 7. 跨设备查询 -- Gitee