From 6796f057bf0fd8b7afa66fcb98fcd46e3497eb5f Mon Sep 17 00:00:00 2001 From: cuirenjie Date: Thu, 25 Apr 2024 20:56:12 +0800 Subject: [PATCH] fixed 0bc0f9b from https://gitee.com/renjiecui/docs/pulls/43087 Add sync interfaces Signed-off-by: cuirenjie --- .../js-apis-data-relationalStore.md | 553 ++++++++++++++++++ 1 file changed, 553 insertions(+) diff --git a/zh-cn/application-dev/reference/apis-arkdata/js-apis-data-relationalStore.md b/zh-cn/application-dev/reference/apis-arkdata/js-apis-data-relationalStore.md index 438db43d2a..687d2d73c4 100644 --- a/zh-cn/application-dev/reference/apis-arkdata/js-apis-data-relationalStore.md +++ b/zh-cn/application-dev/reference/apis-arkdata/js-apis-data-relationalStore.md @@ -2391,6 +2391,96 @@ if(store != undefined) { } ``` +### insertSync12+ + +insertSync(table: string, values: ValuesBucket, conflict?: ConflictResolution):number + +向目标表中插入一行数据。由于共享内存大小限制为2Mb，因此单条数据的大小需小于2Mb，否则会查询失败。 + +**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------------------------- | ---- | ------------------------------------------------------------ | +| table | string | 是 | 指定的目标表名。 | +| values | [ValuesBucket](#valuesbucket) | 是 | 表示要插入到表中的数据行。 | +| conflict | [ConflictResolution](#conflictresolution10) | 否 | 指定冲突解决方式。默认值是relationalStore.ConflictResolution.ON_CONFLICT_NONE。 | + +**返回值**： + +| 类型 | 说明 | +| ------ | ------------------------------------ | +| number | 如果操作成功，返回行ID；否则返回-1。 | + +**错误码：** + +以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。 + +| **错误码ID** | **错误信息** | +| ------------ | ------------------------------------------------------------ | +| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | +| 14800000 | Inner error. | +| 14800011 | Database corrupted. | +| 14800014 | Already closed. | +| 14800015 | The database is busy. | +| 14800021 | SQLite: Generic error. | +| 14800022 | SQLite: Callback routine requested an abort. | +| 14800023 | SQLite: Access permission denied. | +| 14800024 | SQLite: The database file is locked. | +| 14800025 | SQLite: A table in the database is locked. | +| 14800026 | SQLite: The database is out of memory. | +| 14800027 | SQLite: Attempt to write a readonly database. | +| 14800028 | SQLite: Some kind of disk I/O error occurred. | +| 14800029 | SQLite: The database is full. | +| 14800030 | SQLite: Unable to open the database file. | +| 14800031 | SQLite: TEXT or BLOB exceeds size limit. | +| 14800032 | SQLite: Abort due to constraint violation. | +| 14800033 | SQLite: Data type mismatch. | +| 14800034 | SQLite: Library used incorrectly. | +| 14800047 | The WAL file size exceeds the default limit. | + +**示例：** + +```ts +import { ValuesBucket } from '@ohos.data.ValuesBucket'; +import { BusinessError } from "@ohos.base"; + +let value1 = "Lisa"; +let value2 = 18; +let value3 = 100.5; +let value4 = new Uint8Array([1, 2, 3, 4, 5]); + +// 以下三种方式可用 +const valueBucket1: ValuesBucket = { + 'NAME': value1, + 'AGE': value2, + 'SALARY': value3, + 'CODES': value4, +}; +const valueBucket2: ValuesBucket = { + NAME: value1, + AGE: value2, + SALARY: value3, + CODES: value4, +}; +const valueBucket3: ValuesBucket = { + "NAME": value1, + "AGE": value2, + "SALARY": value3, + "CODES": value4, +}; + +if(store != undefined) { + try { + let rowId : number = (store as relationalStore.RdbStore).insertSync("EMPLOYEE", valueBucket1, relationalStore.ConflictResolution.ON_CONFLICT_REPLACE); + console.info(`Insert is successful, rowId = ${rowId}`); + } catch (error) { + console.error(`Insert is failed, code is ${error.code},message is ${error.message}`); + } +} +``` + ### batchInsert batchInsert(table: string, values: Array<ValuesBucket>, callback: AsyncCallback<number>):void @@ -2579,6 +2669,103 @@ if(store != undefined) { } ``` +### batchInsertSync12+ + +batchInsertSync(table: string, values: Array<ValuesBucket>):number + +向目标表中插入一组数据。 + +**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------------------------------------------ | ---- | ---------------------------- | +| table | string | 是 | 指定的目标表名。 | +| values | Array<[ValuesBucket](#valuesbucket)> | 是 | 表示要插入到表中的一组数据。 | + +**返回值**： + +| 类型 | 说明 | +| ------ | ---------------------------------------------- | +| number | 如果操作成功，返回插入的数据个数，否则返回-1。 | + +**错误码：** + +以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。 + +| **错误码ID** | **错误信息** | +| ------------ | ------------------------------------------------------------ | +| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | +| 14800000 | Inner error. | +| 14800011 | Database corrupted. | +| 14800014 | Already closed. | +| 14800015 | The database is busy. | +| 14800021 | SQLite: Generic error. | +| 14800022 | SQLite: Callback routine requested an abort. | +| 14800023 | SQLite: Access permission denied. | +| 14800024 | SQLite: The database file is locked. | +| 14800025 | SQLite: A table in the database is locked. | +| 14800026 | SQLite: The database is out of memory. | +| 14800027 | SQLite: Attempt to write a readonly database. | +| 14800028 | SQLite: Some kind of disk I/O error occurred. | +| 14800029 | SQLite: The database is full. | +| 14800030 | SQLite: Unable to open the database file. | +| 14800031 | SQLite: TEXT or BLOB exceeds size limit. | +| 14800032 | SQLite: Abort due to constraint violation. | +| 14800033 | SQLite: Data type mismatch. | +| 14800034 | SQLite: Library used incorrectly. | +| 14800047 | The WAL file size exceeds the default limit. | + +**示例：** + +```ts +import { ValuesBucket } from '@ohos.data.ValuesBucket'; +import { BusinessError } from "@ohos.base"; + +let value1 = "Lisa"; +let value2 = 18; +let value3 = 100.5; +let value4 = new Uint8Array([1, 2, 3, 4, 5]); +let value5 = "Jack"; +let value6 = 19; +let value7 = 101.5; +let value8 = new Uint8Array([6, 7, 8, 9, 10]); +let value9 = "Tom"; +let value10 = 20; +let value11 = 102.5; +let value12 = new Uint8Array([11, 12, 13, 14, 15]); + +const valueBucket1: ValuesBucket = { + 'NAME': value1, + 'AGE': value2, + 'SALARY': value3, + 'CODES': value4, +}; +const valueBucket2: ValuesBucket = { + 'NAME': value5, + 'AGE': value6, + 'SALARY': value7, + 'CODES': value8, +}; +const valueBucket3: ValuesBucket = { + 'NAME': value9, + 'AGE': value10, + 'SALARY': value11, + 'CODES': value12, +}; + +let valueBuckets = new Array(valueBucket1, valueBucket2, valueBucket3); +if(store != undefined) { + try { + let insertNum: number = (store as relationalStore.RdbStore).batchInsertSync("EMPLOYEE", valueBuckets); + console.info(`batchInsert is successful, the number of values that were inserted = ${insertNum}`); + } catch (err) { + console.error(`batchInsert is failed, code is ${err.code},message is ${err.message}`); + } +} +``` + ### update update(values: ValuesBucket, predicates: RdbPredicates, callback: AsyncCallback<number>):void @@ -2933,6 +3120,98 @@ if(store != undefined) { } ``` +### updateSync12+ + +updateSync(values: ValuesBucket, predicates: RdbPredicates, conflict?: ConflictResolution):number + +根据RdbPredicates的指定实例对象更新数据库中的数据。由于共享内存大小限制为2Mb，因此单条数据的大小需小于2Mb，否则会查询失败。 + +**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ---------- | ------------------------------------------- | ---- | ------------------------------------------------------------ | +| values | [ValuesBucket](#valuesbucket) | 是 | values指示数据库中要更新的数据行。键值对与数据库表的列名相关联。 | +| predicates | [RdbPredicates](#rdbpredicates) | 是 | RdbPredicates的实例对象指定的更新条件。 | +| conflict | [ConflictResolution](#conflictresolution10) | 否 | 指定冲突解决方式。默认值是relationalStore.ConflictResolution.ON_CONFLICT_NONE。 | + +**返回值**： + +| 类型 | 说明 | +| ------ | ------------------ | +| number | 返回受影响的行数。 | + +**错误码：** + +以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。 + +| **错误码ID** | **错误信息** | +| ------------ | ------------------------------------------------------------ | +| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | +| 14800000 | Inner error. | +| 14800011 | Database corrupted. | +| 14800014 | Already closed. | +| 14800015 | The database is busy. | +| 14800021 | SQLite: Generic error. | +| 14800022 | SQLite: Callback routine requested an abort. | +| 14800023 | SQLite: Access permission denied. | +| 14800024 | SQLite: The database file is locked. | +| 14800025 | SQLite: A table in the database is locked. | +| 14800026 | SQLite: The database is out of memory. | +| 14800027 | SQLite: Attempt to write a readonly database. | +| 14800028 | SQLite: Some kind of disk I/O error occurred. | +| 14800029 | SQLite: The database is full. | +| 14800030 | SQLite: Unable to open the database file. | +| 14800031 | SQLite: TEXT or BLOB exceeds size limit. | +| 14800032 | SQLite: Abort due to constraint violation. | +| 14800033 | SQLite: Data type mismatch. | +| 14800034 | SQLite: Library used incorrectly. | +| 14800047 | The WAL file size exceeds the default limit. | + +**示例：** + +```ts +import { ValuesBucket } from '@ohos.data.ValuesBucket'; +import { BusinessError } from "@ohos.base"; + +let value1 = "Rose"; +let value2 = 22; +let value3 = 200.5; +let value4 = new Uint8Array([1, 2, 3, 4, 5]); + +// 以下三种方式可用 +const valueBucket1: ValuesBucket = { + 'NAME': value1, + 'AGE': value2, + 'SALARY': value3, + 'CODES': value4, +}; +const valueBucket2: ValuesBucket = { + NAME: value1, + AGE: value2, + SALARY: value3, + CODES: value4, +}; +const valueBucket3: ValuesBucket = { + "NAME": value1, + "AGE": value2, + "SALARY": value3, + "CODES": value4, +}; + +let predicates = new relationalStore.RdbPredicates("EMPLOYEE"); +predicates.equalTo("NAME", "Lisa"); +if(store != undefined) { + try { + let rows: Number = (store as relationalStore.RdbStore).updateSync(valueBucket1, predicates, relationalStore.ConflictResolution.ON_CONFLICT_REPLACE); + console.info(`Updated row count: ${rows}`); + } catch (error) { + console.error(`Updated failed, code is ${error.code},message is ${error.message}`); + } +} +``` + ### delete delete(predicates: RdbPredicates, callback: AsyncCallback<number>):void @@ -3054,6 +3333,70 @@ if(store != undefined) { } ``` +### deleteSync12+ + +deleteSync(predicates: RdbPredicates):number + +根据RdbPredicates的指定实例对象从数据库中删除数据。 + +**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ---------- | ------------------------------- | ---- | --------------------------------------- | +| predicates | [RdbPredicates](#rdbpredicates) | 是 | RdbPredicates的实例对象指定的删除条件。 | + +**返回值**： + +| 类型 | 说明 | +| ------ | ------------------ | +| number | 返回受影响的行数。 | + +**错误码：** + +以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。 + +| **错误码ID** | **错误信息** | +| ------------ | ------------------------------------------------------------ | +| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | +| 14800000 | Inner error. | +| 14800011 | Database corrupted. | +| 14800014 | Already closed. | +| 14800015 | The database is busy. | +| 14800021 | SQLite: Generic error. | +| 14800022 | SQLite: Callback routine requested an abort. | +| 14800023 | SQLite: Access permission denied. | +| 14800024 | SQLite: The database file is locked. | +| 14800025 | SQLite: A table in the database is locked. | +| 14800026 | SQLite: The database is out of memory. | +| 14800027 | SQLite: Attempt to write a readonly database. | +| 14800028 | SQLite: Some kind of disk I/O error occurred. | +| 14800029 | SQLite: The database is full. | +| 14800030 | SQLite: Unable to open the database file. | +| 14800031 | SQLite: TEXT or BLOB exceeds size limit. | +| 14800032 | SQLite: Abort due to constraint violation. | +| 14800033 | SQLite: Data type mismatch. | +| 14800034 | SQLite: Library used incorrectly. | +| 14800047 | The WAL file size exceeds the default limit. | + +**示例：** + +```ts +import { BusinessError } from "@ohos.base"; + +let predicates = new relationalStore.RdbPredicates("EMPLOYEE"); +predicates.equalTo("NAME", "Lisa"); +if(store != undefined) { + try { + let rows: Number = (store as relationalStore.RdbStore).deleteSync(predicates) + console.info(`Delete rows: ${rows}`); + } catch (err) { + console.error(`Delete failed, code is ${err.code},message is ${err.message}`); + } +} +``` + ### query10+ query(predicates: RdbPredicates, callback: AsyncCallback<ResultSet>):void @@ -3217,6 +3560,65 @@ if(store != undefined) { } ``` +### querySync12+ + +querySync(predicates: RdbPredicates, columns?: Array<string>):ResultSet + +根据指定条件查询数据库中的数据。由于共享内存大小限制为2Mb，因此单条数据的大小需小于2Mb，否则会查询失败。 + +**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ---------- | ------------------------------- | ---- | ------------------------------------------------------------ | +| predicates | [RdbPredicates](#rdbpredicates) | 是 | RdbPredicates的实例对象指定的查询条件。 | +| columns | Array<string> | 否 | 表示要查询的列。如果值为空，则查询应用于所有列。默认值为空。 | + +**错误码：** + +以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。 + +| **错误码ID** | **错误信息** | +| ------------ | ------------------------------------------------------------ | +| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | +| 14800000 | Inner error. | +| 14800014 | Already closed. | +| 14800015 | The database is busy. | + +**返回值**： + +| 类型 | 说明 | +| ----------------------- | ----------------------------------- | +| [ResultSet](#resultset) | 如果操作成功，则返回ResultSet对象。 | + +**示例：** + +```ts +import { BusinessError } from "@ohos.base"; + +let predicates = new relationalStore.RdbPredicates("EMPLOYEE"); +predicates.equalTo("NAME", "Rose"); +if(store != undefined) { + try { + let resultSet: relationalStore.ResultSet = (store as relationalStore.RdbStore).querySync(predicates, ["ID", "NAME", "AGE", "SALARY", "CODES"]); + console.info(`ResultSet column names: ${resultSet.columnNames}, column count: ${resultSet.columnCount}`); + // resultSet是一个数据集合的游标，默认指向第-1个记录，有效的数据从0开始。 + while (resultSet.goToNextRow()) { + const id = resultSet.getLong(resultSet.getColumnIndex("ID")); + const name = resultSet.getString(resultSet.getColumnIndex("NAME")); + const age = resultSet.getLong(resultSet.getColumnIndex("AGE")); + const salary = resultSet.getDouble(resultSet.getColumnIndex("SALARY")); + console.info(`id=${id}, name=${name}, age=${age}, salary=${salary}`); + } + // 释放数据集的内存 + resultSet.close(); + } catch (err) { + console.error(`Query failed, code is ${err.code},message is ${err.message}`); + } +} +``` + ### remoteQuery remoteQuery(device: string, table: string, predicates: RdbPredicates, columns: Array<string> , callback: AsyncCallback<ResultSet>): void @@ -3529,6 +3931,65 @@ if(store != undefined) { } ``` +### querySqlSync12+ + +querySqlSync(sql: string, bindArgs?: Array<ValueType>):ResultSet + +根据指定SQL语句查询数据库中的数据。 + +**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------------------ | ---- | ------------------------------------------------------------ | +| sql | string | 是 | 指定要执行的SQL语句。 | +| bindArgs | Array<[ValueType](#valuetype)> | 否 | SQL语句中参数的值。该值与sql参数语句中的占位符相对应。当sql参数语句完整时，该参数不填。默认值为空。 | + +**返回值**： + +| 类型 | 说明 | +| ----------------------- | ----------------------------------- | +| [ResultSet](#resultset) | 如果操作成功，则返回ResultSet对象。 | + +**错误码：** + +以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。 + +| **错误码ID** | **错误信息** | +| ------------ | ------------------------------------------------------------ | +| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | +| 14800000 | Inner error. | +| 14800014 | Already closed. | +| 14800015 | The database is busy. | + +**示例：** + +```ts +import { BusinessError } from "@ohos.base"; + +let predicates = new relationalStore.RdbPredicates("EMPLOYEE"); +predicates.equalTo("NAME", "Rose"); +if(store != undefined) { + try { + let resultSet: relationalStore.ResultSet = (store as relationalStore.RdbStore).querySqlSync("SELECT * FROM EMPLOYEE CROSS JOIN BOOK WHERE BOOK.NAME = 'sanguo'"); + console.info(`ResultSet column names: ${resultSet.columnNames}, column count: ${resultSet.columnCount}`); + // resultSet是一个数据集合的游标，默认指向第-1个记录，有效的数据从0开始。 + while (resultSet.goToNextRow()) { + const id = resultSet.getLong(resultSet.getColumnIndex("ID")); + const name = resultSet.getString(resultSet.getColumnIndex("NAME")); + const age = resultSet.getLong(resultSet.getColumnIndex("AGE")); + const salary = resultSet.getDouble(resultSet.getColumnIndex("SALARY")); + console.info(`id=${id}, name=${name}, age=${age}, salary=${salary}`); + } + // 释放数据集的内存 + resultSet.close(); + } catch (err) { + console.error(`Query failed, code is ${err.code},message is ${err.message}`); + } +} +``` + ### executeSql10+ executeSql(sql: string, callback: AsyncCallback<void>):void @@ -3878,6 +4339,98 @@ if(store != null) { } ``` +### executeSync12+ + +executeSync(sql: string, args?: Array<ValueType>): ValueType + +执行包含指定参数的SQL语句，返回值类型为ValueType。 + +该接口支持执行增删改操作，支持执行PRAGMA语法的sql，支持对表的操作（建表、删表、修改表）,返回结果类型由执行具体sql的结果决定。 + +此接口不支持执行查询、附加数据库和事务操作，可以使用[querySql](#querysql10)、[query](#query10)、[attach](#attach12)、[beginTransaction](#begintransaction)、[commit](#commit)等接口代替。 + +**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------------------------------------ | ---- | ------------------------------------------------------------ | +| sql | string | 是 | 指定要执行的SQL语句。 | +| args | Array<[ValueType](#valuetype)> | 否 | SQL语句中参数的值。该值与sql参数语句中的占位符相对应。该参数不填，或者填null或undefined，都认为是sql参数语句完整。默认值为空。 | + +**返回值**： + +| 类型 | 说明 | +| ----------------------- | ------------------- | +| [ValueType](#valuetype) | 返回sql执行后的结果 | + +**错误码：** + +以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。 + +| **错误码ID** | **错误信息** | +| ------------ | ------------------------------------------------------------ | +| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | +| 801 | Capability not supported the sql(attach,begin,commit,rollback etc.). | +| 14800000 | Inner error. | +| 14800011 | Database corrupted. | +| 14800014 | Already closed. | +| 14800015 | The database is busy. | +| 14800021 | SQLite: Generic error. | +| 14800022 | SQLite: Callback routine requested an abort. | +| 14800023 | SQLite: Access permission denied. | +| 14800024 | SQLite: The database file is locked. | +| 14800025 | SQLite: A table in the database is locked. | +| 14800026 | SQLite: The database is out of memory. | +| 14800027 | SQLite: Attempt to write a readonly database. | +| 14800028 | SQLite: Some kind of disk I/O error occurred. | +| 14800029 | SQLite: The database is full. | +| 14800030 | SQLite: Unable to open the database file. | +| 14800031 | SQLite: TEXT or BLOB exceeds size limit. | +| 14800032 | SQLite: Abort due to constraint violation. | +| 14800033 | SQLite: Data type mismatch. | +| 14800034 | SQLite: Library used incorrectly. | +| 14800047 | The WAL file size exceeds the default limit. | + +**示例：** + +```ts +import { BusinessError } from "@ohos.base"; + +// 校验数据库完整性 +if(store != undefined) { + const SQL_CHECK_INTEGRITY = 'PRAGMA integrity_check'; + try { + let data = (store as relationalStore.RdbStore).executeSync(SQL_CHECK_INTEGRITY) + console.info(`check result: ${data}`); + } catch (err: BusinessError) { + console.error(`check failed, code is ${err.code}, message is ${err.message}`); + } +} + +// 删除表中所有数据 +if(store != undefined) { + const SQL_DELETE_TABLE = 'DELETE FROM test'; + try { + let data = (store as relationalStore.RdbStore).executeSync(SQL_DELETE_TABLE) + console.info(`delete result: ${data}`); + } catch (err: BusinessError) { + console.error(`delete failed, code is ${err.code}, message is ${err.message}`); + } +} + +// 删表 +if(store != undefined) { + const SQL_DROP_TABLE = 'DROP TABLE test'; + try { + let data = (store as relationalStore.RdbStore).executeSync(SQL_DROP_TABLE) + console.info(`drop result: ${data}`); + } catch (err) { + console.error(`drop failed, code is ${err.code}, message is ${err.message}`); + } +} +``` + ### getModifyTime10+ getModifyTime(table: string, columnName: string, primaryKeys: PRIKeyType[], callback: AsyncCallback<ModifyTime>): void -- Gitee