1# Interface (RdbStore) 2<!--Kit: ArkData--> 3<!--Subsystem: DistributedDataManager--> 4<!--Owner: @baijidong--> 5<!--Designer: @widecode; @htt1997--> 6<!--Tester: @yippo; @logic42--> 7<!--Adviser: @ge-yafang--> 8 9> **说明：** 10> 11> 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 12 13提供管理关系数据库（RDB）方法的接口。 14 15在使用以下API前，请先通过[getRdbStore](arkts-apis-data-relationalStore-f.md#relationalstoregetrdbstore-1)方法获取RdbStore实例，并使用该实例调用对应接口方法。 16 17在此基础上，建议优先使用[execute](arkts-apis-data-relationalStore-RdbStore.md#execute12)方法完成数据库表结构和初始数据的初始化，以确保相关接口调用的前置条件已满足。 18 19## 导入模块 20 21```ts 22import { relationalStore } from '@kit.ArkData'; 23``` 24 25## 属性 26 27**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 28 29| 名称 | 类型 | 只读 | 可选 | 说明 | 30| ------------ | ----------- | ---- | -------------------------------- | -------------------------------- | 31| version<sup>10+</sup> | number | 否 | 否 | 设置和获取数据库版本，值为大于0的正整数。<br>读取和设置version属性会占用数据库连接，避免对该属性进行频繁操作。<br>使用临时变量保存读取到的version值，在数据库变更完成后将其赋值给RdbStore实例的version属性。数据库升级时变更version属性的场景，请参考[开发指南示例代码](../../database/data-persistence-by-rdb-store.md#开发步骤)。 | 32| rebuilt<sup>12+</sup> | [RebuildType](arkts-apis-data-relationalStore-e.md#rebuildtype12) | 是 | 否 | 用于获取数据库是否进行过重建或修复。 | 33 34**错误码：** 35 36以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。 37 38| **错误码ID** | **错误信息** | 39|-----------| ------------------------------------------------------------ | 40| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 41| 801 | Capability not supported. | 42| 14800000 | Inner error. | 43| 14800014 | The RdbStore or ResultSet is already closed. | 44| 14800015 | The database does not respond. | 45| 14800021 | SQLite: Generic error. Possible causes: Insert failed or the updated data does not exist. | 46| 14800023 | SQLite: Access permission denied. | 47| 14800024 | SQLite: The database file is locked. | 48| 14800025 | SQLite: A table in the database is locked. | 49| 14800026 | SQLite: The database is out of memory. | 50| 14800027 | SQLite: Attempt to write a readonly database. | 51| 14800028 | SQLite: Some kind of disk I/O error occurred. | 52| 14800029 | SQLite: The database is full. | 53| 14800030 | SQLite: Unable to open the database file. | 54 55**示例：** 56 57```ts 58// 设置数据库版本 59import { UIAbility } from '@kit.AbilityKit'; 60import { BusinessError } from '@kit.BasicServicesKit'; 61import { window } from '@kit.ArkUI'; 62 63let store: relationalStore.RdbStore | undefined = undefined; 64 65class EntryAbility extends UIAbility { 66 onWindowStageCreate(windowStage: window.WindowStage) { 67 const STORE_CONFIG: relationalStore.StoreConfig = { 68 name: "RdbTest.db", 69 securityLevel: relationalStore.SecurityLevel.S3 70 }; 71 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, IDENTITY UNLIMITED INT, ASSETDATA ASSET, ASSETSDATA ASSETS, FLOATARRAY floatvector(128))'; 72 relationalStore.getRdbStore(this.context, STORE_CONFIG).then(async (rdbStore: relationalStore.RdbStore) => { 73 store = rdbStore; 74 await (store as relationalStore.RdbStore).executeSql(SQL_CREATE_TABLE); 75 console.info('Get RdbStore successfully.'); 76 77 // 设置数据库版本 78 if (store != undefined) { 79 (store as relationalStore.RdbStore).version = 3; 80 // 获取数据库版本 81 console.info(`RdbStore version is ${store.version}`); 82 // 获取数据库是否重建 83 console.info(`RdbStore rebuilt is ${store.rebuilt}`); 84 } 85 }).catch((err: BusinessError) => { 86 console.error(`Get RdbStore failed, code is ${err.code}, message is ${err.message}`); 87 }); 88 } 89} 90``` 91 92## insert 93 94insert(table: string, values: ValuesBucket, callback: AsyncCallback<number>):void 95 96向目标表中插入一行数据，使用callback异步回调。由于共享内存大小限制为2Mb，因此单条数据的大小需小于2Mb，否则会查询失败。 97 98**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 99 100**参数：** 101 102| 参数名 | 类型 | 必填 | 说明 | 103| -------- | ----------------------------- | ---- | ---------------------------------------------------------- | 104| table | string | 是 | 指定的目标表名。 | 105| values | [ValuesBucket](arkts-apis-data-relationalStore-t.md#valuesbucket) | 是 | 表示要插入到表中的数据行。 | 106| callback | AsyncCallback<number> | 是 | 指定callback回调函数。如果操作成功，返回行ID；否则返回-1。 | 107 108**错误码：** 109 110以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。其中，14800011错误码处理可参考[数据库备份与恢复](../../database/data-backup-and-restore.md)。 111 112| **错误码ID** | **错误信息** | 113|-----------| ------------------------------------------------------------ | 114| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 115| 14800000 | Inner error. | 116| 14800011 | Failed to open the database because it is corrupted. | 117| 14800014 | The RdbStore or ResultSet is already closed. | 118| 14800015 | The database does not respond. | 119| 14800021 | SQLite: Generic error. Possible causes: Insert failed or the updated data does not exist. | 120| 14800022 | SQLite: Callback routine requested an abort. | 121| 14800023 | SQLite: Access permission denied. | 122| 14800024 | SQLite: The database file is locked. | 123| 14800025 | SQLite: A table in the database is locked. | 124| 14800026 | SQLite: The database is out of memory. | 125| 14800027 | SQLite: Attempt to write a readonly database. | 126| 14800028 | SQLite: Some kind of disk I/O error occurred. | 127| 14800029 | SQLite: The database is full. | 128| 14800030 | SQLite: Unable to open the database file. | 129| 14800031 | SQLite: TEXT or BLOB exceeds size limit. | 130| 14800032 | SQLite: Abort due to constraint violation. | 131| 14800033 | SQLite: Data type mismatch. | 132| 14800034 | SQLite: Library used incorrectly. | 133| 14800047 | The WAL file size exceeds the default limit. | 134 135**示例：** 136 137```ts 138let value1 = "Lisa"; 139let value2 = 18; 140let value3 = 100.5; 141let value4 = new Uint8Array([1, 2, 3, 4, 5]); 142 143// 以下三种方式可用 144const valueBucket1: relationalStore.ValuesBucket = { 145 'NAME': value1, 146 'AGE': value2, 147 'SALARY': value3, 148 'CODES': value4 149}; 150const valueBucket2: relationalStore.ValuesBucket = { 151 NAME: value1, 152 AGE: value2, 153 SALARY: value3, 154 CODES: value4 155}; 156const valueBucket3: relationalStore.ValuesBucket = { 157 "NAME": value1, 158 "AGE": value2, 159 "SALARY": value3, 160 "CODES": value4 161}; 162 163if (store != undefined) { 164 (store as relationalStore.RdbStore).insert("EMPLOYEE", valueBucket1, (err: BusinessError, rowId: number) => { 165 if (err) { 166 console.error(`Insert is failed, code is ${err.code},message is ${err.message}`); 167 return; 168 } 169 console.info(`Insert is successful, rowId = ${rowId}`); 170 }); 171} 172``` 173 174## insert<sup>10+</sup> 175 176insert(table: string, values: ValuesBucket, conflict: ConflictResolution, callback: AsyncCallback<number>):void 177 178向目标表中插入一行数据，使用callback异步回调。由于共享内存大小限制为2Mb，因此单条数据的大小需小于2Mb，否则会查询失败。 179 180**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 181 182**参数：** 183 184| 参数名 | 类型 | 必填 | 说明 | 185| -------- | ------------------------------------------- | ---- | ---------------------------------------------------------- | 186| table | string | 是 | 指定的目标表名。 | 187| values | [ValuesBucket](arkts-apis-data-relationalStore-t.md#valuesbucket) | 是 | 表示要插入到表中的数据行。 | 188| conflict | [ConflictResolution](arkts-apis-data-relationalStore-e.md#conflictresolution10)| 是 | 指定冲突解决模式。 | 189| callback | AsyncCallback<number> | 是 | 指定callback回调函数。如果操作成功，返回行ID；否则返回-1。 | 190 191**错误码：** 192 193以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。其中，14800011错误码处理可参考[数据库备份与恢复](../../database/data-backup-and-restore.md)。 194 195| **错误码ID** | **错误信息** | 196|-----------| ---------------------------------------------------- | 197| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 198| 14800000 | Inner error. | 199| 14800011 | Failed to open the database because it is corrupted. | 200| 14800014 | The RdbStore or ResultSet is already closed. | 201| 14800015 | The database does not respond. | 202| 14800021 | SQLite: Generic error. Possible causes: Insert failed or the updated data does not exist. | 203| 14800022 | SQLite: Callback routine requested an abort. | 204| 14800023 | SQLite: Access permission denied. | 205| 14800024 | SQLite: The database file is locked. | 206| 14800025 | SQLite: A table in the database is locked. | 207| 14800026 | SQLite: The database is out of memory. | 208| 14800027 | SQLite: Attempt to write a readonly database. | 209| 14800028 | SQLite: Some kind of disk I/O error occurred. | 210| 14800029 | SQLite: The database is full. | 211| 14800030 | SQLite: Unable to open the database file. | 212| 14800031 | SQLite: TEXT or BLOB exceeds size limit. | 213| 14800032 | SQLite: Abort due to constraint violation. | 214| 14800033 | SQLite: Data type mismatch. | 215| 14800034 | SQLite: Library used incorrectly. | 216| 14800047 | The WAL file size exceeds the default limit. | 217 218**示例：** 219 220```ts 221let value1 = "Lisa"; 222let value2 = 18; 223let value3 = 100.5; 224let value4 = new Uint8Array([1, 2, 3, 4, 5]); 225 226// 以下三种方式可用 227const valueBucket1: relationalStore.ValuesBucket = { 228 'NAME': value1, 229 'AGE': value2, 230 'SALARY': value3, 231 'CODES': value4 232}; 233const valueBucket2: relationalStore.ValuesBucket = { 234 NAME: value1, 235 AGE: value2, 236 SALARY: value3, 237 CODES: value4 238}; 239const valueBucket3: relationalStore.ValuesBucket = { 240 "NAME": value1, 241 "AGE": value2, 242 "SALARY": value3, 243 "CODES": value4 244}; 245 246if (store != undefined) { 247 (store as relationalStore.RdbStore).insert("EMPLOYEE", valueBucket1, relationalStore.ConflictResolution.ON_CONFLICT_REPLACE, 248 (err: BusinessError, rowId: number) => { 249 if (err) { 250 console.error(`Insert is failed, code is ${err.code},message is ${err.message}`); 251 return; 252 } 253 console.info(`Insert is successful, rowId = ${rowId}`); 254 }); 255} 256``` 257 258## insert 259 260insert(table: string, values: ValuesBucket):Promise<number> 261 262向目标表中插入一行数据，使用Promise异步回调。由于共享内存大小限制为2Mb，因此单条数据的大小需小于2Mb，否则会查询失败。 263 264**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 265 266**参数：** 267 268| 参数名 | 类型 | 必填 | 说明 | 269| ------ | ----------------------------- | ---- | -------------------------- | 270| table | string | 是 | 指定的目标表名。 | 271| values | [ValuesBucket](arkts-apis-data-relationalStore-t.md#valuesbucket) | 是 | 表示要插入到表中的数据行。 | 272 273**返回值**： 274 275| 类型 | 说明 | 276| --------------------- | ------------------------------------------------- | 277| Promise<number> | Promise对象。如果操作成功，返回行ID；否则返回-1。 | 278 279**错误码：** 280 281以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。其中，14800011错误码处理可参考[数据库备份与恢复](../../database/data-backup-and-restore.md)。 282 283| **错误码ID** | **错误信息** | 284|-----------| ------------------------------------------------------------ | 285| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 286| 14800000 | Inner error. | 287| 14800011 | Failed to open the database because it is corrupted. | 288| 14800014 | The RdbStore or ResultSet is already closed. | 289| 14800015 | The database does not respond. | 290| 14800021 | SQLite: Generic error. Possible causes: Insert failed or the updated data does not exist. | 291| 14800022 | SQLite: Callback routine requested an abort. | 292| 14800023 | SQLite: Access permission denied. | 293| 14800024 | SQLite: The database file is locked. | 294| 14800025 | SQLite: A table in the database is locked. | 295| 14800026 | SQLite: The database is out of memory. | 296| 14800027 | SQLite: Attempt to write a readonly database. | 297| 14800028 | SQLite: Some kind of disk I/O error occurred. | 298| 14800029 | SQLite: The database is full. | 299| 14800030 | SQLite: Unable to open the database file. | 300| 14800031 | SQLite: TEXT or BLOB exceeds size limit. | 301| 14800032 | SQLite: Abort due to constraint violation. | 302| 14800033 | SQLite: Data type mismatch. | 303| 14800034 | SQLite: Library used incorrectly. | 304| 14800047 | The WAL file size exceeds the default limit. | 305 306**示例：** 307 308```ts 309import { BusinessError } from '@kit.BasicServicesKit'; 310 311let value1 = "Lisa"; 312let value2 = 18; 313let value3 = 100.5; 314let value4 = new Uint8Array([1, 2, 3, 4, 5]); 315 316// 以下三种方式可用 317const valueBucket1: relationalStore.ValuesBucket = { 318 'NAME': value1, 319 'AGE': value2, 320 'SALARY': value3, 321 'CODES': value4 322}; 323const valueBucket2: relationalStore.ValuesBucket = { 324 NAME: value1, 325 AGE: value2, 326 SALARY: value3, 327 CODES: value4 328}; 329const valueBucket3: relationalStore.ValuesBucket = { 330 "NAME": value1, 331 "AGE": value2, 332 "SALARY": value3, 333 "CODES": value4 334}; 335 336if (store != undefined) { 337 (store as relationalStore.RdbStore).insert("EMPLOYEE", valueBucket1).then((rowId: number) => { 338 console.info(`Insert is successful, rowId = ${rowId}`); 339 }).catch((err: BusinessError) => { 340 console.error(`Insert is failed, code is ${err.code},message is ${err.message}`); 341 }); 342} 343``` 344 345## insert<sup>10+</sup> 346 347insert(table: string, values: ValuesBucket, conflict: ConflictResolution):Promise<number> 348 349向目标表中插入一行数据，使用Promise异步回调。由于共享内存大小限制为2Mb，因此单条数据的大小需小于2Mb，否则会查询失败。 350 351**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 352 353**参数：** 354 355| 参数名 | 类型 | 必填 | 说明 | 356| -------- | ------------------------------------------- | ---- | -------------------------- | 357| table | string | 是 | 指定的目标表名。 | 358| values | [ValuesBucket](arkts-apis-data-relationalStore-t.md#valuesbucket) | 是 | 表示要插入到表中的数据行。 | 359| conflict | [ConflictResolution](arkts-apis-data-relationalStore-e.md#conflictresolution10)| 是 | 指定冲突解决模式。 | 360 361**返回值**： 362 363| 类型 | 说明 | 364| --------------------- | ------------------------------------------------- | 365| Promise<number> | Promise对象。如果操作成功，返回行ID；否则返回-1。 | 366 367**错误码：** 368 369以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。其中，14800011错误码处理可参考[数据库备份与恢复](../../database/data-backup-and-restore.md)。 370 371| **错误码ID** | **错误信息** | 372|-----------| ------------------------------------------------------------ | 373| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 374| 14800000 | Inner error. | 375| 14800011 | Failed to open the database because it is corrupted. | 376| 14800014 | The RdbStore or ResultSet is already closed. | 377| 14800015 | The database does not respond. | 378| 14800021 | SQLite: Generic error. Possible causes: Insert failed or the updated data does not exist. | 379| 14800022 | SQLite: Callback routine requested an abort. | 380| 14800023 | SQLite: Access permission denied. | 381| 14800024 | SQLite: The database file is locked. | 382| 14800025 | SQLite: A table in the database is locked. | 383| 14800026 | SQLite: The database is out of memory. | 384| 14800027 | SQLite: Attempt to write a readonly database. | 385| 14800028 | SQLite: Some kind of disk I/O error occurred. | 386| 14800029 | SQLite: The database is full. | 387| 14800030 | SQLite: Unable to open the database file. | 388| 14800031 | SQLite: TEXT or BLOB exceeds size limit. | 389| 14800032 | SQLite: Abort due to constraint violation. | 390| 14800033 | SQLite: Data type mismatch. | 391| 14800034 | SQLite: Library used incorrectly. | 392| 14800047 | The WAL file size exceeds the default limit. | 393 394**示例：** 395 396```ts 397import { BusinessError } from '@kit.BasicServicesKit'; 398 399let value1 = "Lisa"; 400let value2 = 18; 401let value3 = 100.5; 402let value4 = new Uint8Array([1, 2, 3, 4, 5]); 403 404// 以下三种方式可用 405const valueBucket1: relationalStore.ValuesBucket = { 406 'NAME': value1, 407 'AGE': value2, 408 'SALARY': value3, 409 'CODES': value4 410}; 411const valueBucket2: relationalStore.ValuesBucket = { 412 NAME: value1, 413 AGE: value2, 414 SALARY: value3, 415 CODES: value4 416}; 417const valueBucket3: relationalStore.ValuesBucket = { 418 "NAME": value1, 419 "AGE": value2, 420 "SALARY": value3, 421 "CODES": value4 422}; 423 424if (store != undefined) { 425 (store as relationalStore.RdbStore).insert("EMPLOYEE", valueBucket1, relationalStore.ConflictResolution.ON_CONFLICT_REPLACE).then((rowId: number) => { 426 console.info(`Insert is successful, rowId = ${rowId}`); 427 }).catch((err: BusinessError) => { 428 console.error(`Insert is failed, code is ${err.code},message is ${err.message}`); 429 }); 430} 431``` 432 433## insertSync<sup>12+</sup> 434 435insertSync(table: string, values: ValuesBucket, conflict?: ConflictResolution):number 436 437向目标表中插入一行数据。由于共享内存大小限制为2Mb，因此单条数据的大小需小于2Mb，否则会查询失败。 438 439**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 440 441**参数：** 442 443| 参数名 | 类型 | 必填 | 说明 | 444| -------- | ------------------------------------------- | ---- | ------------------------------------------------------------ | 445| table | string | 是 | 指定的目标表名。 | 446| values | [ValuesBucket](arkts-apis-data-relationalStore-t.md#valuesbucket) | 是 | 表示要插入到表中的数据行。 | 447| conflict | [ConflictResolution](arkts-apis-data-relationalStore-e.md#conflictresolution10)| 否 | 指定冲突解决模式。默认值是relationalStore.ConflictResolution.ON_CONFLICT_NONE。 | 448 449**返回值**： 450 451| 类型 | 说明 | 452| ------ | ------------------------------------ | 453| number | 如果操作成功，返回行ID；否则返回-1。 | 454 455**错误码：** 456 457以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。其中，14800011错误码处理可参考[数据库备份与恢复](../../database/data-backup-and-restore.md)。 458 459| **错误码ID** | **错误信息** | 460| ------------ | ------------------------------------------------------------ | 461| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 462| 14800000 | Inner error. | 463| 14800011 | Failed to open the database because it is corrupted. | 464| 14800014 | The RdbStore or ResultSet is already closed. | 465| 14800015 | The database does not respond. | 466| 14800021 | SQLite: Generic error. Possible causes: Insert failed or the updated data does not exist. | 467| 14800022 | SQLite: Callback routine requested an abort. | 468| 14800023 | SQLite: Access permission denied. | 469| 14800024 | SQLite: The database file is locked. | 470| 14800025 | SQLite: A table in the database is locked. | 471| 14800026 | SQLite: The database is out of memory. | 472| 14800027 | SQLite: Attempt to write a readonly database. | 473| 14800028 | SQLite: Some kind of disk I/O error occurred. | 474| 14800029 | SQLite: The database is full. | 475| 14800030 | SQLite: Unable to open the database file. | 476| 14800031 | SQLite: TEXT or BLOB exceeds size limit. | 477| 14800032 | SQLite: Abort due to constraint violation. | 478| 14800033 | SQLite: Data type mismatch. | 479| 14800034 | SQLite: Library used incorrectly. | 480| 14800047 | The WAL file size exceeds the default limit. | 481 482**示例：** 483 484```ts 485let value1 = "Lisa"; 486let value2 = 18; 487let value3 = 100.5; 488let value4 = new Uint8Array([1, 2, 3, 4, 5]); 489 490// 以下三种方式可用 491const valueBucket1: relationalStore.ValuesBucket = { 492 'NAME': value1, 493 'AGE': value2, 494 'SALARY': value3, 495 'CODES': value4 496}; 497const valueBucket2: relationalStore.ValuesBucket = { 498 NAME: value1, 499 AGE: value2, 500 SALARY: value3, 501 CODES: value4 502}; 503const valueBucket3: relationalStore.ValuesBucket = { 504 "NAME": value1, 505 "AGE": value2, 506 "SALARY": value3, 507 "CODES": value4 508}; 509 510if (store != undefined) { 511 try { 512 let rowId: number = (store as relationalStore.RdbStore).insertSync("EMPLOYEE", valueBucket1, relationalStore.ConflictResolution.ON_CONFLICT_REPLACE); 513 console.info(`Insert is successful, rowId = ${rowId}`); 514 } catch (error) { 515 console.error(`Insert is failed, code is ${error.code},message is ${error.message}`); 516 } 517} 518``` 519 520## insertSync<sup>12+</sup> 521 522insertSync(table: string, values: sendableRelationalStore.ValuesBucket, conflict?: ConflictResolution):number 523 524传入Sendable数据，向目标表中插入一行数据。由于共享内存大小限制为2Mb，因此单条数据的大小需小于2Mb，否则会查询失败。 525 526**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 527 528**参数：** 529 530| 参数名 | 类型 | 必填 | 说明 | 531| -------- | ---------------------------------------------------------------------------------------------- | ---- | ------------------------------------------------------------------------------- | 532| table | string | 是 | 指定的目标表名。 | 533| values | [sendableRelationalStore.ValuesBucket](js-apis-data-sendableRelationalStore.md#valuesbucket) | 是 | 表示要插入到表中的可跨线程传递数据。 | 534| conflict | [ConflictResolution](arkts-apis-data-relationalStore-e.md#conflictresolution10) | 否 | 指定冲突解决模式。默认值是relationalStore.ConflictResolution.ON_CONFLICT_NONE。 | 535 536**返回值**： 537 538| 类型 | 说明 | 539| ------ | ------------------------------------ | 540| number | 如果操作成功，返回行ID；否则返回-1。 | 541 542**错误码：** 543 544以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。其中，14800011错误码处理可参考[数据库备份与恢复](../../database/data-backup-and-restore.md)。 545 546| **错误码ID** | **错误信息** | 547| ------------ | ------------------------------------------------------------ | 548| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 549| 14800000 | Inner error. | 550| 14800011 | Failed to open the database because it is corrupted. | 551| 14800014 | The RdbStore or ResultSet is already closed. | 552| 14800015 | The database does not respond. | 553| 14800021 | SQLite: Generic error. Possible causes: Insert failed or the updated data does not exist. | 554| 14800022 | SQLite: Callback routine requested an abort. | 555| 14800023 | SQLite: Access permission denied. | 556| 14800024 | SQLite: The database file is locked. | 557| 14800025 | SQLite: A table in the database is locked. | 558| 14800026 | SQLite: The database is out of memory. | 559| 14800027 | SQLite: Attempt to write a readonly database. | 560| 14800028 | SQLite: Some kind of disk I/O error occurred. | 561| 14800029 | SQLite: The database is full. | 562| 14800030 | SQLite: Unable to open the database file. | 563| 14800031 | SQLite: TEXT or BLOB exceeds size limit. | 564| 14800032 | SQLite: Abort due to constraint violation. | 565| 14800033 | SQLite: Data type mismatch. | 566| 14800034 | SQLite: Library used incorrectly. | 567| 14800047 | The WAL file size exceeds the default limit. | 568 569**示例：** 570 571```ts 572import { sendableRelationalStore } from '@kit.ArkData'; 573 574const valuesBucket: relationalStore.ValuesBucket = { 575 "NAME": 'hangman', 576 "AGE": 18, 577 "SALARY": 100.5, 578 "CODES": new Uint8Array([1, 2, 3]) 579}; 580const sendableValuesBucket = sendableRelationalStore.toSendableValuesBucket(valuesBucket); 581 582if (store != undefined) { 583 try { 584 let rowId: number = (store as relationalStore.RdbStore).insertSync("EMPLOYEE", sendableValuesBucket, relationalStore.ConflictResolution.ON_CONFLICT_REPLACE); 585 console.info(`Insert is successful, rowId = ${rowId}`); 586 } catch (error) { 587 console.error(`Insert is failed, code is ${error.code},message is ${error.message}`); 588 } 589} 590``` 591 592## batchInsert 593 594batchInsert(table: string, values: Array<ValuesBucket>, callback: AsyncCallback<number>):void 595 596向目标表中插入一组数据，使用callback异步回调。 597 598从API version 20开始，支持[向量数据库](arkts-apis-data-relationalStore-i.md#storeconfig)。 599 600**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 601 602**参数：** 603 604| 参数名 | 类型 | 必填 | 说明 | 605| -------- | ------------------------------------------ | ---- | ------------------------------------------------------------ | 606| table | string | 是 | 指定的目标表名。 | 607| values | Array<[ValuesBucket](arkts-apis-data-relationalStore-t.md#valuesbucket)> | 是 | 表示要插入到表中的一组数据。 | 608| callback | AsyncCallback<number> | 是 | 指定callback回调函数。如果操作成功，返回插入的数据个数，否则返回-1。 | 609 610**错误码：** 611 612以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。其中，14800011错误码处理可参考[数据库备份与恢复](../../database/data-backup-and-restore.md)。 613 614| **错误码ID** | **错误信息** | 615|-----------| ------------------------------------------------------------ | 616| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 617| 14800000 | Inner error. | 618| 14800011 | Failed to open the database because it is corrupted. | 619| 14800014 | The RdbStore or ResultSet is already closed. | 620| 14800015 | The database does not respond. | 621| 14800021 | SQLite: Generic error. Possible causes: Insert failed or the updated data does not exist. | 622| 14800022 | SQLite: Callback routine requested an abort. | 623| 14800023 | SQLite: Access permission denied. | 624| 14800024 | SQLite: The database file is locked. | 625| 14800025 | SQLite: A table in the database is locked. | 626| 14800026 | SQLite: The database is out of memory. | 627| 14800027 | SQLite: Attempt to write a readonly database. | 628| 14800028 | SQLite: Some kind of disk I/O error occurred. | 629| 14800029 | SQLite: The database is full. | 630| 14800030 | SQLite: Unable to open the database file. | 631| 14800031 | SQLite: TEXT or BLOB exceeds size limit. | 632| 14800032 | SQLite: Abort due to constraint violation. | 633| 14800033 | SQLite: Data type mismatch. | 634| 14800034 | SQLite: Library used incorrectly. | 635| 14800047 | The WAL file size exceeds the default limit. | 636 637**示例：** 638 639```ts 640let value1 = "Lisa"; 641let value2 = 18; 642let value3 = 100.5; 643let value4 = new Uint8Array([1, 2, 3, 4, 5]); 644let value5 = "Jack"; 645let value6 = 19; 646let value7 = 101.5; 647let value8 = new Uint8Array([6, 7, 8, 9, 10]); 648let value9 = "Tom"; 649let value10 = 20; 650let value11 = 102.5; 651let value12 = new Uint8Array([11, 12, 13, 14, 15]); 652 653const valueBucket1: relationalStore.ValuesBucket = { 654 'NAME': value1, 655 'AGE': value2, 656 'SALARY': value3, 657 'CODES': value4 658}; 659const valueBucket2: relationalStore.ValuesBucket = { 660 'NAME': value5, 661 'AGE': value6, 662 'SALARY': value7, 663 'CODES': value8 664}; 665const valueBucket3: relationalStore.ValuesBucket = { 666 'NAME': value9, 667 'AGE': value10, 668 'SALARY': value11, 669 'CODES': value12 670}; 671 672let valueBuckets = new Array(valueBucket1, valueBucket2, valueBucket3); 673if (store != undefined) { 674 (store as relationalStore.RdbStore).batchInsert("EMPLOYEE", valueBuckets, (err, insertNum) => { 675 if (err) { 676 console.error(`batchInsert is failed, code is ${err.code},message is ${err.message}`); 677 return; 678 } 679 console.info(`batchInsert is successful, the number of values that were inserted = ${insertNum}`); 680 }) 681} 682``` 683 684## batchInsert 685 686batchInsert(table: string, values: Array<ValuesBucket>):Promise<number> 687 688向目标表中插入一组数据，使用Promise异步回调。 689 690从API version 20开始，该接口支持[向量数据库](arkts-apis-data-relationalStore-i.md#storeconfig)使用。 691 692**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 693 694**参数：** 695 696| 参数名 | 类型 | 必填 | 说明 | 697| ------ | ------------------------------------------ | ---- | ---------------------------- | 698| table | string | 是 | 指定的目标表名。 | 699| values | Array<[ValuesBucket](arkts-apis-data-relationalStore-t.md#valuesbucket)> | 是 | 表示要插入到表中的一组数据。| 700 701**返回值**： 702 703| 类型 | 说明 | 704| --------------------- | ----------------------------------------------------------- | 705| Promise<number> | Promise对象。如果操作成功，返回插入的数据个数，否则返回-1。 | 706 707**错误码：** 708 709以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。其中，14800011错误码处理可参考[数据库备份与恢复](../../database/data-backup-and-restore.md)。 710 711| **错误码ID** | **错误信息** | 712|-----------| ------------------------------------------------------------ | 713| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 714| 14800000 | Inner error. | 715| 14800011 | Failed to open the database because it is corrupted. | 716| 14800014 | The RdbStore or ResultSet is already closed. | 717| 14800015 | The database does not respond. | 718| 14800021 | SQLite: Generic error. Possible causes: Insert failed or the updated data does not exist. | 719| 14800022 | SQLite: Callback routine requested an abort. | 720| 14800023 | SQLite: Access permission denied. | 721| 14800024 | SQLite: The database file is locked. | 722| 14800025 | SQLite: A table in the database is locked. | 723| 14800026 | SQLite: The database is out of memory. | 724| 14800027 | SQLite: Attempt to write a readonly database. | 725| 14800028 | SQLite: Some kind of disk I/O error occurred. | 726| 14800029 | SQLite: The database is full. | 727| 14800030 | SQLite: Unable to open the database file. | 728| 14800031 | SQLite: TEXT or BLOB exceeds size limit. | 729| 14800032 | SQLite: Abort due to constraint violation. | 730| 14800033 | SQLite: Data type mismatch. | 731| 14800034 | SQLite: Library used incorrectly. | 732| 14800047 | The WAL file size exceeds the default limit. | 733 734**示例：** 735 736关系型数据库： 737 738```ts 739import { BusinessError } from '@kit.BasicServicesKit'; 740 741let value1 = "Lisa"; 742let value2 = 18; 743let value3 = 100.5; 744let value4 = new Uint8Array([1, 2, 3, 4, 5]); 745let value5 = "Jack"; 746let value6 = 19; 747let value7 = 101.5; 748let value8 = new Uint8Array([6, 7, 8, 9, 10]); 749let value9 = "Tom"; 750let value10 = 20; 751let value11 = 102.5; 752let value12 = new Uint8Array([11, 12, 13, 14, 15]); 753 754const valueBucket1: relationalStore.ValuesBucket = { 755 'NAME': value1, 756 'AGE': value2, 757 'SALARY': value3, 758 'CODES': value4 759}; 760const valueBucket2: relationalStore.ValuesBucket = { 761 'NAME': value5, 762 'AGE': value6, 763 'SALARY': value7, 764 'CODES': value8 765}; 766const valueBucket3: relationalStore.ValuesBucket = { 767 'NAME': value9, 768 'AGE': value10, 769 'SALARY': value11, 770 'CODES': value12 771}; 772 773let valueBuckets = new Array(valueBucket1, valueBucket2, valueBucket3); 774if (store != undefined) { 775 (store as relationalStore.RdbStore).batchInsert("EMPLOYEE", valueBuckets).then((insertNum: number) => { 776 console.info(`batchInsert is successful, the number of values that were inserted = ${insertNum}`); 777 }).catch((err: BusinessError) => { 778 console.error(`batchInsert is failed, code is ${err.code},message is ${err.message}`); 779 }) 780} 781``` 782 783向量数据库： 784 785```ts 786let createSql = "CREATE TABLE IF NOT EXISTS test (id INTEGER PRIMARY KEY AUTOINCREMENT, data1 floatvector(2));"; 787await store!.execute(createSql, 0, undefined); // 创建关系表，第二个参数0表示不开启显示事务，第三个参数undefined表示sql未使用绑定参数化 788let floatVector = Float32Array.from([1.2, 2.3]); 789let valueBucketArray = new Array<relationalStore.ValuesBucket>(); 790for (let i = 0; i < 100; i++) { // 构造一个BucketArray用于写入 791 const row : relationalStore.ValuesBucket = { 792 "id" : i, 793 "data1" : floatVector, 794 } 795 valueBucketArray.push(row); 796} 797await store!.batchInsert("test", valueBucketArray); // 执行批量写入 798``` 799 800## batchInsertSync<sup>12+</sup> 801 802batchInsertSync(table: string, values: Array<ValuesBucket>):number 803 804向目标表中插入一组数据。 805 806**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 807 808**参数：** 809 810| 参数名 | 类型 | 必填 | 说明 | 811| ------ | ------------------------------------------ | ---- | ---------------------------- | 812| table | string | 是 | 指定的目标表名。 | 813| values | Array<[ValuesBucket](arkts-apis-data-relationalStore-t.md#valuesbucket)> | 是 | 表示要插入到表中的一组数据。 | 814 815**返回值**： 816 817| 类型 | 说明 | 818| ------ | ---------------------------------------------- | 819| number | 如果操作成功，返回插入的数据个数，否则返回-1。 | 820 821**错误码：** 822 823以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。其中，14800011错误码处理可参考[数据库备份与恢复](../../database/data-backup-and-restore.md)。 824 825| **错误码ID** | **错误信息** | 826| ------------ | ------------------------------------------------------------ | 827| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 828| 14800000 | Inner error. | 829| 14800011 | Failed to open the database because it is corrupted. | 830| 14800014 | The RdbStore or ResultSet is already closed. | 831| 14800015 | The database does not respond. | 832| 14800021 | SQLite: Generic error. Possible causes: Insert failed or the updated data does not exist. | 833| 14800022 | SQLite: Callback routine requested an abort. | 834| 14800023 | SQLite: Access permission denied. | 835| 14800024 | SQLite: The database file is locked. | 836| 14800025 | SQLite: A table in the database is locked. | 837| 14800026 | SQLite: The database is out of memory. | 838| 14800027 | SQLite: Attempt to write a readonly database. | 839| 14800028 | SQLite: Some kind of disk I/O error occurred. | 840| 14800029 | SQLite: The database is full. | 841| 14800030 | SQLite: Unable to open the database file. | 842| 14800031 | SQLite: TEXT or BLOB exceeds size limit. | 843| 14800032 | SQLite: Abort due to constraint violation. | 844| 14800033 | SQLite: Data type mismatch. | 845| 14800034 | SQLite: Library used incorrectly. | 846| 14800047 | The WAL file size exceeds the default limit. | 847 848**示例：** 849 850```ts 851let value1 = "Lisa"; 852let value2 = 18; 853let value3 = 100.5; 854let value4 = new Uint8Array([1, 2, 3, 4, 5]); 855let value5 = "Jack"; 856let value6 = 19; 857let value7 = 101.5; 858let value8 = new Uint8Array([6, 7, 8, 9, 10]); 859let value9 = "Tom"; 860let value10 = 20; 861let value11 = 102.5; 862let value12 = new Uint8Array([11, 12, 13, 14, 15]); 863 864const valueBucket1: relationalStore.ValuesBucket = { 865 'NAME': value1, 866 'AGE': value2, 867 'SALARY': value3, 868 'CODES': value4 869}; 870const valueBucket2: relationalStore.ValuesBucket = { 871 'NAME': value5, 872 'AGE': value6, 873 'SALARY': value7, 874 'CODES': value8 875}; 876const valueBucket3: relationalStore.ValuesBucket = { 877 'NAME': value9, 878 'AGE': value10, 879 'SALARY': value11, 880 'CODES': value12 881}; 882 883let valueBuckets = new Array(valueBucket1, valueBucket2, valueBucket3); 884if (store != undefined) { 885 try { 886 let insertNum: number = (store as relationalStore.RdbStore).batchInsertSync("EMPLOYEE", valueBuckets); 887 console.info(`batchInsert is successful, the number of values that were inserted = ${insertNum}`); 888 } catch (err) { 889 console.error(`batchInsert is failed, code is ${err.code},message is ${err.message}`); 890 } 891} 892``` 893 894## batchInsertWithConflictResolution<sup>18+</sup> 895 896batchInsertWithConflictResolution(table: string, values: Array<ValuesBucket>, conflict: ConflictResolution): Promise<number> 897 898向目标表中插入一组数据，可以通过conflict参数指定冲突解决模式。使用Promise异步回调。 899 900**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 901 902**参数：** 903 904| 参数名 | 类型 | 必填 | 说明 | 905| ------ | ------------------------------------------ | ---- | ---------------------------- | 906| table | string | 是 | 指定的目标表名。 | 907| values | Array<[ValuesBucket](arkts-apis-data-relationalStore-t.md#valuesbucket)> | 是 | 表示要插入到表中的一组数据。 | 908| conflict | [ConflictResolution](arkts-apis-data-relationalStore-e.md#conflictresolution10)| 是 | 指定冲突解决模式。 | 909 910**返回值**： 911 912| 类型 | 说明 | 913| ------ | ---------------------------------------------- | 914| Promise<number> | Promise对象。如果操作成功，返回插入的数据个数，否则返回-1。 | 915 916**错误码：** 917 918以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。其中，14800011错误码处理可参考[数据库备份与恢复](../../database/data-backup-and-restore.md)。 919 920| **错误码ID** | **错误信息** | 921| ------------ | ------------------------------------------------------------ | 922| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 923| 14800000 | Inner error. | 924| 14800011 | Failed to open the database because it is corrupted. | 925| 14800014 | The RdbStore or ResultSet is already closed. | 926| 14800015 | The database does not respond. | 927| 14800021 | SQLite: Generic error. Possible causes: Insert failed or the updated data does not exist. | 928| 14800022 | SQLite: Callback routine requested an abort. | 929| 14800023 | SQLite: Access permission denied. | 930| 14800024 | SQLite: The database file is locked. | 931| 14800025 | SQLite: A table in the database is locked. | 932| 14800026 | SQLite: The database is out of memory. | 933| 14800027 | SQLite: Attempt to write a readonly database. | 934| 14800028 | SQLite: Some kind of disk I/O error occurred. | 935| 14800029 | SQLite: The database is full. | 936| 14800030 | SQLite: Unable to open the database file. | 937| 14800031 | SQLite: TEXT or BLOB exceeds size limit. | 938| 14800032 | SQLite: Abort due to constraint violation. | 939| 14800033 | SQLite: Data type mismatch. | 940| 14800034 | SQLite: Library used incorrectly. | 941| 14800047 | The WAL file size exceeds the default limit. | 942 943**示例：** 944 945```ts 946import { BusinessError } from '@kit.BasicServicesKit'; 947 948let value1 = "Lisa"; 949let value2 = 18; 950let value3 = 100.5; 951let value4 = new Uint8Array([1, 2, 3, 4, 5]); 952let value5 = "Jack"; 953let value6 = 19; 954let value7 = 101.5; 955let value8 = new Uint8Array([6, 7, 8, 9, 10]); 956let value9 = "Tom"; 957let value10 = 20; 958let value11 = 102.5; 959let value12 = new Uint8Array([11, 12, 13, 14, 15]); 960 961const valueBucket1: relationalStore.ValuesBucket = { 962 'NAME': value1, 963 'AGE': value2, 964 'SALARY': value3, 965 'CODES': value4 966}; 967const valueBucket2: relationalStore.ValuesBucket = { 968 'NAME': value5, 969 'AGE': value6, 970 'SALARY': value7, 971 'CODES': value8 972}; 973const valueBucket3: relationalStore.ValuesBucket = { 974 'NAME': value9, 975 'AGE': value10, 976 'SALARY': value11, 977 'CODES': value12 978}; 979 980let valueBuckets = new Array(valueBucket1, valueBucket2, valueBucket3); 981if (store != undefined) { 982 (store as relationalStore.RdbStore).batchInsertWithConflictResolution("EMPLOYEE", valueBuckets, relationalStore.ConflictResolution.ON_CONFLICT_REPLACE).then((insertNum: number) => { 983 console.info(`batchInsert is successful, insertNum = ${insertNum}`); 984 }).catch((err: BusinessError) => { 985 console.error(`batchInsert is failed, code is ${err.code},message is ${err.message}`); 986 }); 987} 988``` 989 990## batchInsertWithConflictResolutionSync<sup>18+</sup> 991 992batchInsertWithConflictResolutionSync(table: string, values: Array<ValuesBucket>, conflict: ConflictResolution): number 993 994向目标表中插入一组数据。 995 996**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 997 998**参数：** 999 1000| 参数名 | 类型 | 必填 | 说明 | 1001| ------ | ------------------------------------------ | ---- | ---------------------------- | 1002| table | string | 是 | 指定的目标表名。 | 1003| values | Array<[ValuesBucket](arkts-apis-data-relationalStore-t.md#valuesbucket)> | 是 | 表示要插入到表中的一组数据。 | 1004| conflict | [ConflictResolution](arkts-apis-data-relationalStore-e.md#conflictresolution10)| 是 | 指定冲突解决模式。 | 1005 1006**返回值**： 1007 1008| 类型 | 说明 | 1009| ------ | ---------------------------------------------- | 1010| number | 如果操作成功，返回插入的数据个数，否则返回-1。 | 1011 1012**错误码：** 1013 1014以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。其中，14800011错误码处理可参考[数据库备份与恢复](../../database/data-backup-and-restore.md)。 1015 1016| **错误码ID** | **错误信息** | 1017| ------------ | ------------------------------------------------------------ | 1018| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1019| 14800000 | Inner error. | 1020| 14800011 | Failed to open the database because it is corrupted. | 1021| 14800014 | The RdbStore or ResultSet is already closed. | 1022| 14800015 | The database does not respond. | 1023| 14800021 | SQLite: Generic error. Possible causes: Insert failed or the updated data does not exist. | 1024| 14800022 | SQLite: Callback routine requested an abort. | 1025| 14800023 | SQLite: Access permission denied. | 1026| 14800024 | SQLite: The database file is locked. | 1027| 14800025 | SQLite: A table in the database is locked. | 1028| 14800026 | SQLite: The database is out of memory. | 1029| 14800027 | SQLite: Attempt to write a readonly database. | 1030| 14800028 | SQLite: Some kind of disk I/O error occurred. | 1031| 14800029 | SQLite: The database is full. | 1032| 14800030 | SQLite: Unable to open the database file. | 1033| 14800031 | SQLite: TEXT or BLOB exceeds size limit. | 1034| 14800032 | SQLite: Abort due to constraint violation. | 1035| 14800033 | SQLite: Data type mismatch. | 1036| 14800034 | SQLite: Library used incorrectly. | 1037| 14800047 | The WAL file size exceeds the default limit. | 1038 1039**示例：** 1040 1041```ts 1042let value1 = "Lisa"; 1043let value2 = 18; 1044let value3 = 100.5; 1045let value4 = new Uint8Array([1, 2, 3, 4, 5]); 1046let value5 = "Jack"; 1047let value6 = 19; 1048let value7 = 101.5; 1049let value8 = new Uint8Array([6, 7, 8, 9, 10]); 1050let value9 = "Tom"; 1051let value10 = 20; 1052let value11 = 102.5; 1053let value12 = new Uint8Array([11, 12, 13, 14, 15]); 1054 1055const valueBucket1: relationalStore.ValuesBucket = { 1056 'NAME': value1, 1057 'AGE': value2, 1058 'SALARY': value3, 1059 'CODES': value4 1060}; 1061const valueBucket2: relationalStore.ValuesBucket = { 1062 'NAME': value5, 1063 'AGE': value6, 1064 'SALARY': value7, 1065 'CODES': value8 1066}; 1067const valueBucket3: relationalStore.ValuesBucket = { 1068 'NAME': value9, 1069 'AGE': value10, 1070 'SALARY': value11, 1071 'CODES': value12 1072}; 1073 1074let valueBuckets = new Array(valueBucket1, valueBucket2, valueBucket3); 1075if (store != undefined) { 1076 try { 1077 let insertNum: number = (store as relationalStore.RdbStore).batchInsertWithConflictResolutionSync("EMPLOYEE", valueBuckets, relationalStore.ConflictResolution.ON_CONFLICT_REPLACE); 1078 console.info(`batchInsert is successful, the number of values that were inserted = ${insertNum}`); 1079 } catch (err) { 1080 console.error(`batchInsert is failed, code is ${err.code},message is ${err.message}`); 1081 } 1082} 1083``` 1084 1085## update 1086 1087update(values: ValuesBucket, predicates: RdbPredicates, callback: AsyncCallback<number>):void 1088 1089根据RdbPredicates的指定实例对象更新数据库中的数据，使用callback异步回调。由于共享内存大小限制为2Mb，因此单条数据的大小需小于2Mb，否则会查询失败。 1090 1091**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 1092 1093**参数：** 1094 1095| 参数名 | 类型 | 必填 | 说明 | 1096| ---------- | ------------------------------------ | ---- | ------------------------------------------------------------ | 1097| values | [ValuesBucket](arkts-apis-data-relationalStore-t.md#valuesbucket) | 是 | values指示数据库中要更新的数据行。键值对与数据库表的列名相关联。 | 1098| predicates | [RdbPredicates](arkts-apis-data-relationalStore-RdbPredicates.md) | 是 | RdbPredicates的实例对象指定的更新条件。 | 1099| callback | AsyncCallback<number> | 是 | 指定的callback回调方法。返回受影响的行数。 | 1100 1101**错误码：** 1102 1103以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。其中，14800011错误码处理可参考[数据库备份与恢复](../../database/data-backup-and-restore.md)。 1104 1105| **错误码ID** | **错误信息** | 1106|-----------| ------------------------------------------------------------ | 1107| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1108| 14800000 | Inner error. | 1109| 14800011 | Failed to open the database because it is corrupted. | 1110| 14800014 | The RdbStore or ResultSet is already closed. | 1111| 14800015 | The database does not respond. | 1112| 14800021 | SQLite: Generic error. Possible causes: Insert failed or the updated data does not exist. | 1113| 14800022 | SQLite: Callback routine requested an abort. | 1114| 14800023 | SQLite: Access permission denied. | 1115| 14800024 | SQLite: The database file is locked. | 1116| 14800025 | SQLite: A table in the database is locked. | 1117| 14800026 | SQLite: The database is out of memory. | 1118| 14800027 | SQLite: Attempt to write a readonly database. | 1119| 14800028 | SQLite: Some kind of disk I/O error occurred. | 1120| 14800029 | SQLite: The database is full. | 1121| 14800030 | SQLite: Unable to open the database file. | 1122| 14800031 | SQLite: TEXT or BLOB exceeds size limit. | 1123| 14800032 | SQLite: Abort due to constraint violation. | 1124| 14800033 | SQLite: Data type mismatch. | 1125| 14800034 | SQLite: Library used incorrectly. | 1126| 14800047 | The WAL file size exceeds the default limit. | 1127 1128**示例：** 1129 1130```ts 1131let value1 = "Rose"; 1132let value2 = 22; 1133let value3 = 200.5; 1134let value4 = new Uint8Array([1, 2, 3, 4, 5]); 1135 1136// 以下三种方式可用 1137const valueBucket1: relationalStore.ValuesBucket = { 1138 'NAME': value1, 1139 'AGE': value2, 1140 'SALARY': value3, 1141 'CODES': value4 1142}; 1143const valueBucket2: relationalStore.ValuesBucket = { 1144 NAME: value1, 1145 AGE: value2, 1146 SALARY: value3, 1147 CODES: value4 1148}; 1149const valueBucket3: relationalStore.ValuesBucket = { 1150 "NAME": value1, 1151 "AGE": value2, 1152 "SALARY": value3, 1153 "CODES": value4 1154}; 1155 1156let predicates = new relationalStore.RdbPredicates("EMPLOYEE"); 1157predicates.equalTo("NAME", "Lisa"); 1158if (store != undefined) { 1159 (store as relationalStore.RdbStore).update(valueBucket1, predicates, (err, rows) => { 1160 if (err) { 1161 console.error(`Updated failed, code is ${err.code},message is ${err.message}`); 1162 return; 1163 } 1164 console.info(`Updated row count: ${rows}`); 1165 }); 1166} 1167``` 1168 1169## update<sup>10+</sup> 1170 1171update(values: ValuesBucket, predicates: RdbPredicates, conflict: ConflictResolution, callback: AsyncCallback<number>):void 1172 1173根据RdbPredicates的指定实例对象更新数据库中的数据，使用callback异步回调。由于共享内存大小限制为2Mb，因此单条数据的大小需小于2Mb，否则会查询失败。 1174 1175**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 1176 1177**参数：** 1178 1179| 参数名 | 类型 | 必填 | 说明 | 1180| ---------- | ------------------------------------------- | ---- | ------------------------------------------------------------ | 1181| values | [ValuesBucket](arkts-apis-data-relationalStore-t.md#valuesbucket) | 是 | values指示数据库中要更新的数据行。键值对与数据库表的列名相关联。 | 1182| predicates | [RdbPredicates](arkts-apis-data-relationalStore-RdbPredicates.md) | 是 | RdbPredicates的实例对象指定的更新条件。 | 1183| conflict | [ConflictResolution](arkts-apis-data-relationalStore-e.md#conflictresolution10)| 是 | 指定冲突解决模式。 | 1184| callback | AsyncCallback<number> | 是 | 指定的callback回调方法。返回受影响的行数。 | 1185 1186**错误码：** 1187 1188以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。其中，14800011错误码处理可参考[数据库备份与恢复](../../database/data-backup-and-restore.md)。 1189 1190| **错误码ID** | **错误信息** | 1191|-----------| ------------------------------------------------------------ | 1192| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1193| 14800000 | Inner error. | 1194| 14800011 | Failed to open the database because it is corrupted. | 1195| 14800014 | The RdbStore or ResultSet is already closed. | 1196| 14800015 | The database does not respond. | 1197| 14800021 | SQLite: Generic error. Possible causes: Insert failed or the updated data does not exist. | 1198| 14800022 | SQLite: Callback routine requested an abort. | 1199| 14800023 | SQLite: Access permission denied. | 1200| 14800024 | SQLite: The database file is locked. | 1201| 14800025 | SQLite: A table in the database is locked. | 1202| 14800026 | SQLite: The database is out of memory. | 1203| 14800027 | SQLite: Attempt to write a readonly database. | 1204| 14800028 | SQLite: Some kind of disk I/O error occurred. | 1205| 14800029 | SQLite: The database is full. | 1206| 14800030 | SQLite: Unable to open the database file. | 1207| 14800031 | SQLite: TEXT or BLOB exceeds size limit. | 1208| 14800032 | SQLite: Abort due to constraint violation. | 1209| 14800033 | SQLite: Data type mismatch. | 1210| 14800034 | SQLite: Library used incorrectly. | 1211| 14800047 | The WAL file size exceeds the default limit. | 1212 1213**示例：** 1214 1215```ts 1216let value1 = "Rose"; 1217let value2 = 22; 1218let value3 = 200.5; 1219let value4 = new Uint8Array([1, 2, 3, 4, 5]); 1220 1221// 以下三种方式可用 1222const valueBucket1: relationalStore.ValuesBucket = { 1223 'NAME': value1, 1224 'AGE': value2, 1225 'SALARY': value3, 1226 'CODES': value4 1227}; 1228const valueBucket2: relationalStore.ValuesBucket = { 1229 NAME: value1, 1230 AGE: value2, 1231 SALARY: value3, 1232 CODES: value4 1233}; 1234const valueBucket3: relationalStore.ValuesBucket = { 1235 "NAME": value1, 1236 "AGE": value2, 1237 "SALARY": value3, 1238 "CODES": value4 1239}; 1240 1241let predicates = new relationalStore.RdbPredicates("EMPLOYEE"); 1242predicates.equalTo("NAME", "Lisa"); 1243if (store != undefined) { 1244 (store as relationalStore.RdbStore).update(valueBucket1, predicates, relationalStore.ConflictResolution.ON_CONFLICT_REPLACE, (err, rows) => { 1245 if (err) { 1246 console.error(`Updated failed, code is ${err.code},message is ${err.message}`); 1247 return; 1248 } 1249 console.info(`Updated row count: ${rows}`); 1250 }); 1251} 1252``` 1253 1254## update 1255 1256update(values: ValuesBucket, predicates: RdbPredicates):Promise<number> 1257 1258根据RdbPredicates的指定实例对象更新数据库中的数据，使用Promise异步回调。由于共享内存大小限制为2Mb，因此单条数据的大小需小于2Mb，否则会查询失败。 1259 1260**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 1261 1262**参数：** 1263 1264| 参数名 | 类型 | 必填 | 说明 | 1265| ------------ | ------------------------------------ | ---- | ------------------------------------------------------------ | 1266| values | [ValuesBucket](arkts-apis-data-relationalStore-t.md#valuesbucket) | 是 | values指示数据库中要更新的数据行。键值对与数据库表的列名相关联。 | 1267| predicates | [RdbPredicates](arkts-apis-data-relationalStore-RdbPredicates.md) | 是 | RdbPredicates的实例对象指定的更新条件。 | 1268 1269**返回值**： 1270 1271| 类型 | 说明 | 1272| --------------------- | ----------------------------------------- | 1273| Promise<number> | 指定的Promise回调方法。返回受影响的行数。 | 1274 1275**错误码：** 1276 1277以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。其中，14800011错误码处理可参考[数据库备份与恢复](../../database/data-backup-and-restore.md)。 1278 1279| **错误码ID** | **错误信息** | 1280|-----------| ------------------------------------------------------------ | 1281| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1282| 14800000 | Inner error. | 1283| 14800011 | Failed to open the database because it is corrupted. | 1284| 14800014 | The RdbStore or ResultSet is already closed. | 1285| 14800015 | The database does not respond. | 1286| 14800021 | SQLite: Generic error. Possible causes: Insert failed or the updated data does not exist. | 1287| 14800022 | SQLite: Callback routine requested an abort. | 1288| 14800023 | SQLite: Access permission denied. | 1289| 14800024 | SQLite: The database file is locked. | 1290| 14800025 | SQLite: A table in the database is locked. | 1291| 14800026 | SQLite: The database is out of memory. | 1292| 14800027 | SQLite: Attempt to write a readonly database. | 1293| 14800028 | SQLite: Some kind of disk I/O error occurred. | 1294| 14800029 | SQLite: The database is full. | 1295| 14800030 | SQLite: Unable to open the database file. | 1296| 14800031 | SQLite: TEXT or BLOB exceeds size limit. | 1297| 14800032 | SQLite: Abort due to constraint violation. | 1298| 14800033 | SQLite: Data type mismatch. | 1299| 14800034 | SQLite: Library used incorrectly. | 1300| 14800047 | The WAL file size exceeds the default limit. | 1301 1302**示例：** 1303 1304```ts 1305import { BusinessError } from '@kit.BasicServicesKit'; 1306 1307let value1 = "Rose"; 1308let value2 = 22; 1309let value3 = 200.5; 1310let value4 = new Uint8Array([1, 2, 3, 4, 5]); 1311 1312// 以下三种方式可用 1313const valueBucket1: relationalStore.ValuesBucket = { 1314 'NAME': value1, 1315 'AGE': value2, 1316 'SALARY': value3, 1317 'CODES': value4 1318}; 1319const valueBucket2: relationalStore.ValuesBucket = { 1320 NAME: value1, 1321 AGE: value2, 1322 SALARY: value3, 1323 CODES: value4 1324}; 1325const valueBucket3: relationalStore.ValuesBucket = { 1326 "NAME": value1, 1327 "AGE": value2, 1328 "SALARY": value3, 1329 "CODES": value4 1330}; 1331 1332let predicates = new relationalStore.RdbPredicates("EMPLOYEE"); 1333predicates.equalTo("NAME", "Lisa"); 1334if (store != undefined) { 1335 (store as relationalStore.RdbStore).update(valueBucket1, predicates).then(async (rows: number) => { 1336 console.info(`Updated row count: ${rows}`); 1337 }).catch((err: BusinessError) => { 1338 console.error(`Updated failed, code is ${err.code},message is ${err.message}`); 1339 }); 1340} 1341``` 1342 1343## update<sup>10+</sup> 1344 1345update(values: ValuesBucket, predicates: RdbPredicates, conflict: ConflictResolution):Promise<number> 1346 1347根据RdbPredicates的指定实例对象更新数据库中的数据，使用Promise异步回调。由于共享内存大小限制为2Mb，因此单条数据的大小需小于2Mb，否则会查询失败。 1348 1349**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 1350 1351**参数：** 1352 1353| 参数名 | 类型 | 必填 | 说明 | 1354| ---------- | ------------------------------------------- | ---- | ------------------------------------------------------------ | 1355| values | [ValuesBucket](arkts-apis-data-relationalStore-t.md#valuesbucket) | 是 | values指示数据库中要更新的数据行。键值对与数据库表的列名相关联。 | 1356| predicates | [RdbPredicates](arkts-apis-data-relationalStore-RdbPredicates.md) | 是 | RdbPredicates的实例对象指定的更新条件。 | 1357| conflict | [ConflictResolution](arkts-apis-data-relationalStore-e.md#conflictresolution10)| 是 | 指定冲突解决模式。 | 1358 1359**返回值**： 1360 1361| 类型 | 说明 | 1362| --------------------- | ----------------------------------------- | 1363| Promise<number> | 指定的Promise回调方法。返回受影响的行数。 | 1364 1365**错误码：** 1366 1367以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。其中，14800011错误码处理可参考[数据库备份与恢复](../../database/data-backup-and-restore.md)。 1368 1369| **错误码ID** | **错误信息** | 1370|-----------| ------------------------------------------------------------ | 1371| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1372| 14800000 | Inner error. | 1373| 14800011 | Failed to open the database because it is corrupted. | 1374| 14800014 | The RdbStore or ResultSet is already closed. | 1375| 14800015 | The database does not respond. | 1376| 14800021 | SQLite: Generic error. Possible causes: Insert failed or the updated data does not exist. | 1377| 14800022 | SQLite: Callback routine requested an abort. | 1378| 14800023 | SQLite: Access permission denied. | 1379| 14800024 | SQLite: The database file is locked. | 1380| 14800025 | SQLite: A table in the database is locked. | 1381| 14800026 | SQLite: The database is out of memory. | 1382| 14800027 | SQLite: Attempt to write a readonly database. | 1383| 14800028 | SQLite: Some kind of disk I/O error occurred. | 1384| 14800029 | SQLite: The database is full. | 1385| 14800030 | SQLite: Unable to open the database file. | 1386| 14800031 | SQLite: TEXT or BLOB exceeds size limit. | 1387| 14800032 | SQLite: Abort due to constraint violation. | 1388| 14800033 | SQLite: Data type mismatch. | 1389| 14800034 | SQLite: Library used incorrectly. | 1390| 14800047 | The WAL file size exceeds the default limit. | 1391 1392**示例：** 1393 1394```ts 1395import { BusinessError } from '@kit.BasicServicesKit'; 1396 1397let value1 = "Rose"; 1398let value2 = 22; 1399let value3 = 200.5; 1400let value4 = new Uint8Array([1, 2, 3, 4, 5]); 1401 1402// 以下三种方式可用 1403const valueBucket1: relationalStore.ValuesBucket = { 1404 'NAME': value1, 1405 'AGE': value2, 1406 'SALARY': value3, 1407 'CODES': value4 1408}; 1409const valueBucket2: relationalStore.ValuesBucket = { 1410 NAME: value1, 1411 AGE: value2, 1412 SALARY: value3, 1413 CODES: value4 1414}; 1415const valueBucket3: relationalStore.ValuesBucket = { 1416 "NAME": value1, 1417 "AGE": value2, 1418 "SALARY": value3, 1419 "CODES": value4 1420}; 1421 1422let predicates = new relationalStore.RdbPredicates("EMPLOYEE"); 1423predicates.equalTo("NAME", "Lisa"); 1424if (store != undefined) { 1425 (store as relationalStore.RdbStore).update(valueBucket1, predicates, relationalStore.ConflictResolution.ON_CONFLICT_REPLACE).then(async (rows: number) => { 1426 console.info(`Updated row count: ${rows}`); 1427 }).catch((err: BusinessError) => { 1428 console.error(`Updated failed, code is ${err.code},message is ${err.message}`); 1429 }); 1430} 1431``` 1432 1433## updateSync<sup>12+</sup> 1434 1435updateSync(values: ValuesBucket, predicates: RdbPredicates, conflict?: ConflictResolution):number 1436 1437根据RdbPredicates的指定实例对象更新数据库中的数据。由于共享内存大小限制为2Mb，因此单条数据的大小需小于2Mb，否则会查询失败。 1438 1439**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 1440 1441**参数：** 1442 1443| 参数名 | 类型 | 必填 | 说明 | 1444| ---------- | ------------------------------------------- | ---- | ------------------------------------------------------------ | 1445| values | [ValuesBucket](arkts-apis-data-relationalStore-t.md#valuesbucket) | 是 | values指示数据库中要更新的数据行。键值对与数据库表的列名相关联。 | 1446| predicates | [RdbPredicates](arkts-apis-data-relationalStore-RdbPredicates.md) | 是 | RdbPredicates的实例对象指定的更新条件。 | 1447| conflict | [ConflictResolution](arkts-apis-data-relationalStore-e.md#conflictresolution10)| 否 | 指定冲突解决模式。默认值是relationalStore.ConflictResolution.ON_CONFLICT_NONE。 | 1448 1449**返回值**： 1450 1451| 类型 | 说明 | 1452| ------ | ------------------ | 1453| number | 返回受影响的行数。 | 1454 1455**错误码：** 1456 1457以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。其中，14800011错误码处理可参考[数据库备份与恢复](../../database/data-backup-and-restore.md)。 1458 1459| **错误码ID** | **错误信息** | 1460| ------------ | ------------------------------------------------------------ | 1461| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1462| 14800000 | Inner error. | 1463| 14800011 | Failed to open the database because it is corrupted. | 1464| 14800014 | The RdbStore or ResultSet is already closed. | 1465| 14800015 | The database does not respond. | 1466| 14800021 | SQLite: Generic error. Possible causes: Insert failed or the updated data does not exist. | 1467| 14800022 | SQLite: Callback routine requested an abort. | 1468| 14800023 | SQLite: Access permission denied. | 1469| 14800024 | SQLite: The database file is locked. | 1470| 14800025 | SQLite: A table in the database is locked. | 1471| 14800026 | SQLite: The database is out of memory. | 1472| 14800027 | SQLite: Attempt to write a readonly database. | 1473| 14800028 | SQLite: Some kind of disk I/O error occurred. | 1474| 14800029 | SQLite: The database is full. | 1475| 14800030 | SQLite: Unable to open the database file. | 1476| 14800031 | SQLite: TEXT or BLOB exceeds size limit. | 1477| 14800032 | SQLite: Abort due to constraint violation. | 1478| 14800033 | SQLite: Data type mismatch. | 1479| 14800034 | SQLite: Library used incorrectly. | 1480| 14800047 | The WAL file size exceeds the default limit. | 1481 1482**示例：** 1483 1484```ts 1485let value1 = "Rose"; 1486let value2 = 22; 1487let value3 = 200.5; 1488let value4 = new Uint8Array([1, 2, 3, 4, 5]); 1489 1490// 以下三种方式可用 1491const valueBucket1: relationalStore.ValuesBucket = { 1492 'NAME': value1, 1493 'AGE': value2, 1494 'SALARY': value3, 1495 'CODES': value4 1496}; 1497const valueBucket2: relationalStore.ValuesBucket = { 1498 NAME: value1, 1499 AGE: value2, 1500 SALARY: value3, 1501 CODES: value4 1502}; 1503const valueBucket3: relationalStore.ValuesBucket = { 1504 "NAME": value1, 1505 "AGE": value2, 1506 "SALARY": value3, 1507 "CODES": value4 1508}; 1509 1510let predicates = new relationalStore.RdbPredicates("EMPLOYEE"); 1511predicates.equalTo("NAME", "Lisa"); 1512if (store != undefined) { 1513 try { 1514 let rows: number = (store as relationalStore.RdbStore).updateSync(valueBucket1, predicates, relationalStore.ConflictResolution.ON_CONFLICT_REPLACE); 1515 console.info(`Updated row count: ${rows}`); 1516 } catch (error) { 1517 console.error(`Updated failed, code is ${error.code},message is ${error.message}`); 1518 } 1519} 1520``` 1521 1522## delete 1523 1524delete(predicates: RdbPredicates, callback: AsyncCallback<number>):void 1525 1526根据RdbPredicates的指定实例对象从数据库中删除数据，使用callback异步回调。 1527 1528**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 1529 1530**参数：** 1531 1532| 参数名 | 类型 | 必填 | 说明 | 1533| ---------- | ------------------------------------ | ---- | ----------------------------------------- | 1534| predicates | [RdbPredicates](arkts-apis-data-relationalStore-RdbPredicates.md) | 是 | RdbPredicates的实例对象指定的删除条件。 | 1535| callback | AsyncCallback<number> | 是 | 指定callback回调函数。返回受影响的行数量。 | 1536 1537**错误码：** 1538 1539以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。其中，14800011错误码处理可参考[数据库备份与恢复](../../database/data-backup-and-restore.md)。 1540 1541| **错误码ID** | **错误信息** | 1542|-----------| ------------------------------------------------------------ | 1543| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1544| 14800000 | Inner error. | 1545| 14800011 | Failed to open the database because it is corrupted. | 1546| 14800014 | The RdbStore or ResultSet is already closed. | 1547| 14800015 | The database does not respond. | 1548| 14800021 | SQLite: Generic error. Possible causes: Insert failed or the updated data does not exist. | 1549| 14800022 | SQLite: Callback routine requested an abort. | 1550| 14800023 | SQLite: Access permission denied. | 1551| 14800024 | SQLite: The database file is locked. | 1552| 14800025 | SQLite: A table in the database is locked. | 1553| 14800026 | SQLite: The database is out of memory. | 1554| 14800027 | SQLite: Attempt to write a readonly database. | 1555| 14800028 | SQLite: Some kind of disk I/O error occurred. | 1556| 14800029 | SQLite: The database is full. | 1557| 14800030 | SQLite: Unable to open the database file. | 1558| 14800031 | SQLite: TEXT or BLOB exceeds size limit. | 1559| 14800032 | SQLite: Abort due to constraint violation. | 1560| 14800033 | SQLite: Data type mismatch. | 1561| 14800034 | SQLite: Library used incorrectly. | 1562| 14800047 | The WAL file size exceeds the default limit. | 1563 1564**示例：** 1565 1566```ts 1567let predicates = new relationalStore.RdbPredicates("EMPLOYEE"); 1568predicates.equalTo("NAME", "Lisa"); 1569if (store != undefined) { 1570 (store as relationalStore.RdbStore).delete(predicates, (err, rows) => { 1571 if (err) { 1572 console.error(`Delete failed, code is ${err.code},message is ${err.message}`); 1573 return; 1574 } 1575 console.info(`Delete rows: ${rows}`); 1576 }); 1577} 1578``` 1579 1580## delete 1581 1582delete(predicates: RdbPredicates):Promise<number> 1583 1584根据RdbPredicates的指定实例对象从数据库中删除数据，使用Promise异步回调。 1585 1586**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 1587 1588**参数：** 1589 1590| 参数名 | 类型 | 必填 | 说明 | 1591| ---------- | ------------------------------------ | ---- | ----------------------------------------- | 1592| predicates | [RdbPredicates](arkts-apis-data-relationalStore-RdbPredicates.md) | 是 | RdbPredicates的实例对象指定的删除条件。 | 1593 1594**返回值**： 1595 1596| 类型 | 说明 | 1597| --------------------- | ------------------------------- | 1598| Promise<number> | Promise对象。返回受影响的行数量。 | 1599 1600**错误码：** 1601 1602以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。其中，14800011错误码处理可参考[数据库备份与恢复](../../database/data-backup-and-restore.md)。 1603 1604| **错误码ID** | **错误信息** | 1605|-----------| ------------------------------------------------------------ | 1606| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1607| 14800000 | Inner error. | 1608| 14800011 | Failed to open the database because it is corrupted. | 1609| 14800014 | The RdbStore or ResultSet is already closed. | 1610| 14800015 | The database does not respond. | 1611| 14800021 | SQLite: Generic error. Possible causes: Insert failed or the updated data does not exist. | 1612| 14800022 | SQLite: Callback routine requested an abort. | 1613| 14800023 | SQLite: Access permission denied. | 1614| 14800024 | SQLite: The database file is locked. | 1615| 14800025 | SQLite: A table in the database is locked. | 1616| 14800026 | SQLite: The database is out of memory. | 1617| 14800027 | SQLite: Attempt to write a readonly database. | 1618| 14800028 | SQLite: Some kind of disk I/O error occurred. | 1619| 14800029 | SQLite: The database is full. | 1620| 14800030 | SQLite: Unable to open the database file. | 1621| 14800031 | SQLite: TEXT or BLOB exceeds size limit. | 1622| 14800032 | SQLite: Abort due to constraint violation. | 1623| 14800033 | SQLite: Data type mismatch. | 1624| 14800034 | SQLite: Library used incorrectly. | 1625| 14800047 | The WAL file size exceeds the default limit. | 1626 1627**示例：** 1628 1629```ts 1630import { BusinessError } from '@kit.BasicServicesKit'; 1631 1632let predicates = new relationalStore.RdbPredicates("EMPLOYEE"); 1633predicates.equalTo("NAME", "Lisa"); 1634if (store != undefined) { 1635 (store as relationalStore.RdbStore).delete(predicates).then((rows: number) => { 1636 console.info(`Delete rows: ${rows}`); 1637 }).catch((err: BusinessError) => { 1638 console.error(`Delete failed, code is ${err.code},message is ${err.message}`); 1639 }); 1640} 1641``` 1642 1643## deleteSync<sup>12+</sup> 1644 1645deleteSync(predicates: RdbPredicates):number 1646 1647根据RdbPredicates的指定实例对象从数据库中删除数据。 1648 1649**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 1650 1651**参数：** 1652 1653| 参数名 | 类型 | 必填 | 说明 | 1654| ---------- | ------------------------------- | ---- | --------------------------------------- | 1655| predicates | [RdbPredicates](arkts-apis-data-relationalStore-RdbPredicates.md) | 是 | RdbPredicates的实例对象指定的删除条件。 | 1656 1657**返回值**： 1658 1659| 类型 | 说明 | 1660| ------ | ------------------ | 1661| number | 返回受影响的行数量。 | 1662 1663**错误码：** 1664 1665以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。其中，14800011错误码处理可参考[数据库备份与恢复](../../database/data-backup-and-restore.md)。 1666 1667| **错误码ID** | **错误信息** | 1668| ------------ | ------------------------------------------------------------ | 1669| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1670| 14800000 | Inner error. | 1671| 14800011 | Failed to open the database because it is corrupted. | 1672| 14800014 | The RdbStore or ResultSet is already closed. | 1673| 14800015 | The database does not respond. | 1674| 14800021 | SQLite: Generic error. Possible causes: Insert failed or the updated data does not exist. | 1675| 14800022 | SQLite: Callback routine requested an abort. | 1676| 14800023 | SQLite: Access permission denied. | 1677| 14800024 | SQLite: The database file is locked. | 1678| 14800025 | SQLite: A table in the database is locked. | 1679| 14800026 | SQLite: The database is out of memory. | 1680| 14800027 | SQLite: Attempt to write a readonly database. | 1681| 14800028 | SQLite: Some kind of disk I/O error occurred. | 1682| 14800029 | SQLite: The database is full. | 1683| 14800030 | SQLite: Unable to open the database file. | 1684| 14800031 | SQLite: TEXT or BLOB exceeds size limit. | 1685| 14800032 | SQLite: Abort due to constraint violation. | 1686| 14800033 | SQLite: Data type mismatch. | 1687| 14800034 | SQLite: Library used incorrectly. | 1688| 14800047 | The WAL file size exceeds the default limit. | 1689 1690**示例：** 1691 1692```ts 1693let predicates = new relationalStore.RdbPredicates("EMPLOYEE"); 1694predicates.equalTo("NAME", "Lisa"); 1695if (store != undefined) { 1696 try { 1697 let rows: number = (store as relationalStore.RdbStore).deleteSync(predicates); 1698 console.info(`Delete rows: ${rows}`); 1699 } catch (err) { 1700 console.error(`Delete failed, code is ${err.code},message is ${err.message}`); 1701 } 1702} 1703``` 1704 1705## query<sup>10+</sup> 1706 1707query(predicates: RdbPredicates, callback: AsyncCallback<ResultSet>):void 1708 1709根据指定条件查询数据库中的数据，使用callback异步回调。由于共享内存大小限制为2Mb，因此单条数据的大小需小于2Mb，否则会查询失败。 1710 1711**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 1712 1713**参数：** 1714 1715| 参数名 | 类型 | 必填 | 说明 | 1716| ---------- | ------------------------------------------------------------ | ---- | ----------------------------------------------------------- | 1717| predicates | [RdbPredicates](arkts-apis-data-relationalStore-RdbPredicates.md) | 是 | RdbPredicates的实例对象指定的查询条件。 | 1718| callback | AsyncCallback<[ResultSet](arkts-apis-data-relationalStore-ResultSet.md)> | 是 | 指定callback回调函数。如果操作成功，则返回ResultSet对象。 | 1719 1720**错误码：** 1721 1722以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。 1723 1724| **错误码ID** | **错误信息** | 1725|-----------| ------------------------------------------------------------ | 1726| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1727| 14800000 | Inner error. | 1728| 14800014 | The RdbStore or ResultSet is already closed. | 1729| 14800015 | The database does not respond. | 1730 1731**示例：** 1732 1733```ts 1734let predicates = new relationalStore.RdbPredicates("EMPLOYEE"); 1735predicates.equalTo("NAME", "Rose"); 1736if (store != undefined) { 1737 (store as relationalStore.RdbStore).query(predicates, async (err, resultSet) => { 1738 if (err) { 1739 console.error(`Query failed, code is ${err.code},message is ${err.message}`); 1740 return; 1741 } 1742 console.info(`ResultSet column names: ${resultSet.columnNames}, column count: ${resultSet.columnCount}`); 1743 // resultSet是一个数据集合的游标，默认指向第-1个记录，有效的数据从0开始。 1744 try { 1745 while (resultSet.goToNextRow()) { 1746 const id = resultSet.getLong(resultSet.getColumnIndex("ID")); 1747 const name = resultSet.getString(resultSet.getColumnIndex("NAME")); 1748 const age = resultSet.getLong(resultSet.getColumnIndex("AGE")); 1749 const salary = resultSet.getDouble(resultSet.getColumnIndex("SALARY")); 1750 console.info(`id=${id}, name=${name}, age=${age}, salary=${salary}`); 1751 } 1752 } catch (err) { 1753 console.error(`Query failed, code is ${err.code},message is ${err.message}`); 1754 } finally { 1755 // 释放数据集的内存，若不释放可能会引起fd泄露与内存泄露 1756 resultSet.close(); 1757 } 1758 }); 1759} 1760``` 1761 1762## query 1763 1764query(predicates: RdbPredicates, columns: Array<string>, callback: AsyncCallback<ResultSet>):void 1765 1766根据指定条件查询数据库中的数据，使用callback异步回调。由于共享内存大小限制为2Mb，因此单条数据的大小需小于2Mb，否则会查询失败。 1767 1768**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 1769 1770**参数：** 1771 1772| 参数名 | 类型 | 必填 | 说明 | 1773| ---------- | ------------------------------------------------------------ | ---- | ----------------------------------------------------------- | 1774| predicates | [RdbPredicates](arkts-apis-data-relationalStore-RdbPredicates.md) | 是 | RdbPredicates的实例对象指定的查询条件。 | 1775| columns | Array<string> | 是 | 表示要查询的列。如果值为空，则查询应用于所有列。 | 1776| callback | AsyncCallback<[ResultSet](arkts-apis-data-relationalStore-ResultSet.md)> | 是 | 指定callback回调函数。如果操作成功，则返回ResultSet对象。 | 1777 1778**错误码：** 1779 1780以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。 1781 1782| **错误码ID** | **错误信息** | 1783|-----------| ------------------------------------------------------------ | 1784| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1785| 14800000 | Inner error. | 1786| 14800014 | The RdbStore or ResultSet is already closed. | 1787| 14800015 | The database does not respond. | 1788 1789**示例：** 1790 1791```ts 1792let predicates = new relationalStore.RdbPredicates("EMPLOYEE"); 1793predicates.equalTo("NAME", "Rose"); 1794if (store != undefined) { 1795 (store as relationalStore.RdbStore).query(predicates, ["ID", "NAME", "AGE", "SALARY", "CODES"], async (err, resultSet) => { 1796 if (err) { 1797 console.error(`Query failed, code is ${err.code},message is ${err.message}`); 1798 return; 1799 } 1800 console.info(`ResultSet column names: ${resultSet.columnNames}, column count: ${resultSet.columnCount}`); 1801 // resultSet是一个数据集合的游标，默认指向第-1个记录，有效的数据从0开始。 1802 try { 1803 while (resultSet.goToNextRow()) { 1804 const id = resultSet.getLong(resultSet.getColumnIndex("ID")); 1805 const name = resultSet.getString(resultSet.getColumnIndex("NAME")); 1806 const age = resultSet.getLong(resultSet.getColumnIndex("AGE")); 1807 const salary = resultSet.getDouble(resultSet.getColumnIndex("SALARY")); 1808 console.info(`id=${id}, name=${name}, age=${age}, salary=${salary}`); 1809 } 1810 } catch (err) { 1811 console.error(`Query failed, code is ${err.code},message is ${err.message}`); 1812 } finally { 1813 // 释放数据集的内存，若不释放可能会引起fd泄露与内存泄露 1814 resultSet.close(); 1815 } 1816 }); 1817} 1818``` 1819 1820## query 1821 1822query(predicates: RdbPredicates, columns?: Array<string>):Promise<ResultSet> 1823 1824根据指定条件查询数据库中的数据，使用Promise异步回调。由于共享内存大小限制为2Mb，因此单条数据的大小需小于2Mb，否则会查询失败。 1825 1826**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 1827 1828**参数：** 1829 1830| 参数名 | 类型 | 必填 | 说明 | 1831| ---------- | ------------------------------------ | ---- | ------------------------------------------------ | 1832| predicates | [RdbPredicates](arkts-apis-data-relationalStore-RdbPredicates.md) | 是 | RdbPredicates的实例对象指定的查询条件。 | 1833| columns | Array<string> | 否 | 表示要查询的列。如果值为空，则查询应用于所有列。 | 1834 1835**返回值**： 1836 1837| 类型 | 说明 | 1838| ------------------------------------------------------- | -------------------------------------------------- | 1839| Promise<[ResultSet](arkts-apis-data-relationalStore-ResultSet.md)> | Promise对象。如果操作成功，则返回ResultSet对象。 | 1840 1841**错误码：** 1842 1843以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。 1844 1845| **错误码ID** | **错误信息** | 1846|-----------| ------------------------------------------------------------ | 1847| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1848| 14800000 | Inner error. | 1849| 14800014 | The RdbStore or ResultSet is already closed. | 1850| 14800015 | The database does not respond. | 1851 1852**示例：** 1853 1854```ts 1855import { BusinessError } from '@kit.BasicServicesKit'; 1856 1857let predicates = new relationalStore.RdbPredicates("EMPLOYEE"); 1858predicates.equalTo("NAME", "Rose"); 1859if (store != undefined) { 1860 (store as relationalStore.RdbStore).query(predicates, ["ID", "NAME", "AGE", "SALARY", "CODES"]).then(async (resultSet: relationalStore.ResultSet) => { 1861 console.info(`ResultSet column names: ${resultSet.columnNames}, column count: ${resultSet.columnCount}`); 1862 // resultSet是一个数据集合的游标，默认指向第-1个记录，有效的数据从0开始。 1863 try { 1864 while (resultSet.goToNextRow()) { 1865 const id = resultSet.getLong(resultSet.getColumnIndex("ID")); 1866 const name = resultSet.getString(resultSet.getColumnIndex("NAME")); 1867 const age = resultSet.getLong(resultSet.getColumnIndex("AGE")); 1868 const salary = resultSet.getDouble(resultSet.getColumnIndex("SALARY")); 1869 console.info(`id=${id}, name=${name}, age=${age}, salary=${salary}`); 1870 } 1871 } catch (err) { 1872 console.error(`Query failed, code is ${err.code},message is ${err.message}`); 1873 } finally { 1874 // 释放数据集的内存，若不释放可能会引起fd泄露与内存泄露 1875 resultSet.close(); 1876 } 1877 }).catch((err: BusinessError) => { 1878 console.error(`Query failed, code is ${err.code},message is ${err.message}`); 1879 }); 1880} 1881``` 1882 1883## querySync<sup>12+</sup> 1884 1885querySync(predicates: RdbPredicates, columns?: Array<string>):ResultSet 1886 1887根据指定条件查询数据库中的数据。对query同步接口获得的resultSet进行操作时，若逻辑复杂且循环次数过多，可能造成freeze问题，建议将此步骤放到[taskpool](../apis-arkts/js-apis-taskpool.md)线程中执行。 1888 1889**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 1890 1891**参数：** 1892 1893| 参数名 | 类型 | 必填 | 说明 | 1894| ---------- | ------------------------------- | ---- | ------------------------------------------------------------ | 1895| predicates | [RdbPredicates](arkts-apis-data-relationalStore-RdbPredicates.md) | 是 | RdbPredicates的实例对象指定的查询条件。 | 1896| columns | Array<string> | 否 | 表示要查询的列。如果值为空，则查询应用于所有列。默认值为空。 | 1897 1898**返回值**： 1899 1900| 类型 | 说明 | 1901| ----------------------- | ----------------------------------- | 1902| [ResultSet](arkts-apis-data-relationalStore-ResultSet.md) | 如果操作成功，则返回ResultSet对象。 | 1903 1904**错误码：** 1905 1906以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。 1907 1908| **错误码ID** | **错误信息** | 1909| ------------ | ------------------------------------------------------------ | 1910| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1911| 14800000 | Inner error. | 1912| 14800014 | The RdbStore or ResultSet is already closed. | 1913| 14800015 | The database does not respond. | 1914 1915**示例：** 1916 1917```ts 1918let predicates = new relationalStore.RdbPredicates("EMPLOYEE"); 1919predicates.equalTo("NAME", "Rose"); 1920if (store != undefined) { 1921 let resultSet: relationalStore.ResultSet | undefined; 1922 try { 1923 resultSet = store.querySync(predicates, ["ID", "NAME", "AGE", "SALARY", "CODES"]); 1924 console.info(`ResultSet column names: ${resultSet.columnNames}, column count: ${resultSet.columnCount}`); 1925 // resultSet是一个数据集合的游标，默认指向第-1个记录，有效的数据从0开始。 1926 while (resultSet.goToNextRow()) { 1927 const id = resultSet.getLong(resultSet.getColumnIndex("ID")); 1928 const name = resultSet.getString(resultSet.getColumnIndex("NAME")); 1929 const age = resultSet.getLong(resultSet.getColumnIndex("AGE")); 1930 const salary = resultSet.getDouble(resultSet.getColumnIndex("SALARY")); 1931 console.info(`id=${id}, name=${name}, age=${age}, salary=${salary}`); 1932 } 1933 } catch (err) { 1934 console.error(`Query failed, code is ${err.code}, message is ${err.message}`); 1935 } finally { 1936 // 释放数据集的内存，若不释放可能会引起fd泄露与内存泄露 1937 if (resultSet) { 1938 resultSet.close(); 1939 } 1940 } 1941} 1942``` 1943 1944## remoteQuery 1945 1946remoteQuery(device: string, table: string, predicates: RdbPredicates, columns: Array<string> , callback: AsyncCallback<ResultSet>): void 1947 1948根据指定条件查询远程设备数据库中的数据。使用callback异步回调。 1949 1950> **说明：** 1951> 1952> 其中device通过调用[deviceManager.getAvailableDeviceListSync](../apis-distributedservice-kit/js-apis-distributedDeviceManager.md#getavailabledevicelistsync)方法得到。 1953 1954**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 1955 1956**参数：** 1957 1958| 参数名 | 类型 | 必填 | 说明 | 1959| ---------- | -------------------------------------------- | ---- | --------------------------------------------------------- | 1960| device | string | 是 | 指定的远程设备ID。 | 1961| table | string | 是 | 指定的目标表名。 | 1962| predicates | [RdbPredicates](arkts-apis-data-relationalStore-RdbPredicates.md) | 是 | RdbPredicates的实例对象，指定查询的条件。 | 1963| columns | Array<string> | 是 | 表示要查询的列。如果值为空，则查询应用于所有列。 | 1964| callback | AsyncCallback<[ResultSet](arkts-apis-data-relationalStore-ResultSet.md)> | 是 | 指定callback回调函数。如果操作成功，则返回ResultSet对象。 | 1965 1966**错误码：** 1967 1968以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。 1969 1970| **错误码ID** | **错误信息** | 1971|-----------| ------------------------------------------------------------ | 1972| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1973| 801 | Capability not supported. | 1974| 14800000 | Inner error. | 1975| 14800014 | The RdbStore or ResultSet is already closed. | 1976 1977**示例：** 1978 1979```ts 1980import { distributedDeviceManager } from '@kit.DistributedServiceKit'; 1981import { BusinessError } from '@kit.BasicServicesKit'; 1982 1983let dmInstance: distributedDeviceManager.DeviceManager; 1984let deviceId: string | undefined = undefined; 1985 1986try { 1987 dmInstance = distributedDeviceManager.createDeviceManager("com.example.appdatamgrverify"); 1988 let devices = dmInstance.getAvailableDeviceListSync(); 1989 if (devices != undefined) { 1990 deviceId = devices[0].networkId; 1991 } 1992} catch (err) { 1993 let code = (err as BusinessError).code; 1994 let message = (err as BusinessError).message; 1995 console.error("createDeviceManager errCode:" + code + ",errMessage:" + message); 1996} 1997 1998let predicates = new relationalStore.RdbPredicates('EMPLOYEE'); 1999predicates.greaterThan("id", 0); 2000if (store != undefined && deviceId != undefined) { 2001 (store as relationalStore.RdbStore).remoteQuery(deviceId, "EMPLOYEE", predicates, ["ID", "NAME", "AGE", "SALARY", "CODES"]).then(async (resultSet: relationalStore.ResultSet) => { 2002 console.info(`ResultSet column names: ${resultSet.columnNames}, column count: ${resultSet.columnCount}`); 2003 // resultSet是一个数据集合的游标，默认指向第-1个记录，有效的数据从0开始。 2004 try { 2005 while (resultSet.goToNextRow()) { 2006 const id = resultSet.getLong(resultSet.getColumnIndex("ID")); 2007 const name = resultSet.getString(resultSet.getColumnIndex("NAME")); 2008 const age = resultSet.getLong(resultSet.getColumnIndex("AGE")); 2009 const salary = resultSet.getDouble(resultSet.getColumnIndex("SALARY")); 2010 console.info(`id=${id}, name=${name}, age=${age}, salary=${salary}`); 2011 } 2012 } catch (err) { 2013 console.error(`Query failed, code is ${err.code},message is ${err.message}`); 2014 } finally { 2015 // 释放数据集的内存，若不释放可能会引起fd泄露与内存泄露 2016 resultSet.close(); 2017 } 2018 }).catch((err: BusinessError) => { 2019 console.error(`Failed to remoteQuery, code is ${err.code},message is ${err.message}`); 2020 }); 2021} 2022``` 2023 2024## remoteQuery 2025 2026remoteQuery(device: string, table: string, predicates: RdbPredicates, columns: Array<string>): Promise<ResultSet> 2027 2028根据指定条件查询远程设备数据库中的数据。使用Promise异步回调。 2029 2030> **说明：** 2031> 2032> 其中device通过调用[deviceManager.getAvailableDeviceListSync](../apis-distributedservice-kit/js-apis-distributedDeviceManager.md#getavailabledevicelistsync)方法得到。 2033 2034**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 2035 2036**参数：** 2037 2038| 参数名 | 类型 | 必填 | 说明 | 2039| ---------- | ------------------------------------ | ---- | ------------------------------------------------ | 2040| device | string | 是 | 指定的远程设备ID。 | 2041| table | string | 是 | 指定的目标表名。 | 2042| predicates | [RdbPredicates](arkts-apis-data-relationalStore-RdbPredicates.md) | 是 | RdbPredicates的实例对象，指定查询的条件。 | 2043| columns | Array<string> | 是 | 表示要查询的列。如果值为空，则查询应用于所有列。 | 2044 2045**返回值**： 2046 2047| 类型 | 说明 | 2048| ------------------------------------------------------------ | -------------------------------------------------- | 2049| Promise<[ResultSet](arkts-apis-data-relationalStore-ResultSet.md)> | Promise对象。如果操作成功，则返回ResultSet对象。 | 2050 2051**错误码：** 2052 2053以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。 2054 2055| **错误码ID** | **错误信息** | 2056|-----------| ------------------------------------------------------------ | 2057| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 2058| 801 | Capability not supported. | 2059| 14800000 | Inner error. | 2060| 14800014 | The RdbStore or ResultSet is already closed. | 2061 2062**示例：** 2063 2064```ts 2065import { distributedDeviceManager } from '@kit.DistributedServiceKit'; 2066import { BusinessError } from '@kit.BasicServicesKit'; 2067 2068let dmInstance: distributedDeviceManager.DeviceManager; 2069let deviceId: string | undefined = undefined; 2070 2071try { 2072 dmInstance = distributedDeviceManager.createDeviceManager("com.example.appdatamgrverify"); 2073 let devices: Array<distributedDeviceManager.DeviceBasicInfo> = dmInstance.getAvailableDeviceListSync(); 2074 if (devices != undefined) { 2075 deviceId = devices[0].networkId; 2076 } 2077} catch (err) { 2078 let code = (err as BusinessError).code; 2079 let message = (err as BusinessError).message; 2080 console.error("createDeviceManager errCode:" + code + ",errMessage:" + message); 2081} 2082 2083let predicates = new relationalStore.RdbPredicates('EMPLOYEE'); 2084predicates.greaterThan("id", 0); 2085if (store != undefined && deviceId != undefined) { 2086 (store as relationalStore.RdbStore).remoteQuery(deviceId, "EMPLOYEE", predicates, ["ID", "NAME", "AGE", "SALARY", "CODES"]).then(async (resultSet: relationalStore.ResultSet) => { 2087 console.info(`ResultSet column names: ${resultSet.columnNames}, column count: ${resultSet.columnCount}`); 2088 // resultSet是一个数据集合的游标，默认指向第-1个记录，有效的数据从0开始。 2089 try { 2090 while (resultSet.goToNextRow()) { 2091 const id = resultSet.getLong(resultSet.getColumnIndex("ID")); 2092 const name = resultSet.getString(resultSet.getColumnIndex("NAME")); 2093 const age = resultSet.getLong(resultSet.getColumnIndex("AGE")); 2094 const salary = resultSet.getDouble(resultSet.getColumnIndex("SALARY")); 2095 console.info(`id=${id}, name=${name}, age=${age}, salary=${salary}`); 2096 } 2097 } catch (err) { 2098 console.error(`Query failed, code is ${err.code},message is ${err.message}`); 2099 } finally { 2100 // 释放数据集的内存，若不释放可能会引起fd泄露与内存泄露 2101 resultSet.close(); 2102 } 2103 }).catch((err: BusinessError) => { 2104 console.error(`Failed to remoteQuery, code is ${err.code},message is ${err.message}`); 2105 }); 2106} 2107``` 2108 2109## querySql<sup>10+</sup> 2110 2111querySql(sql: string, callback: AsyncCallback<ResultSet>):void 2112 2113根据指定SQL语句查询数据库中的数据，SQL语句中的各种表达式和操作符之间的关系操作符号不超过1000个，使用callback异步回调。 2114 2115该接口支持[向量数据库](arkts-apis-data-relationalStore-i.md#storeconfig)使用，当前支持的语法见[规格限制](../../database/data-persistence-by-vector-store.md#规格限制)。 2116 2117聚合函数不支持嵌套使用。 2118 2119**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 2120 2121**参数：** 2122 2123| 参数名 | 类型 | 必填 | 说明 | 2124| -------- | -------------------------------------------- | ---- |---------------------------------------| 2125| sql | string | 是 | 指定要执行的SQL语句。 | 2126| callback | AsyncCallback<[ResultSet](arkts-apis-data-relationalStore-ResultSet.md)> | 是 | 指定callback回调函数。如果操作成功，则返回ResultSet对象。 | 2127 2128**错误码：** 2129 2130以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。 2131 2132| **错误码ID** | **错误信息** | 2133|-----------| ------------------------------------------------------------ | 2134| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 2135| 14800000 | Inner error. | 2136| 14800014 | The RdbStore or ResultSet is already closed. | 2137| 14800015 | The database does not respond. | 2138 2139**示例：** 2140 2141关系型数据库： 2142 2143```ts 2144if (store != undefined) { 2145 (store as relationalStore.RdbStore).querySql("SELECT * FROM EMPLOYEE CROSS JOIN BOOK WHERE BOOK.NAME = 'sanguo'", async (err, resultSet) => { 2146 if (err) { 2147 console.error(`Query failed, code is ${err.code},message is ${err.message}`); 2148 return; 2149 } 2150 console.info(`ResultSet column names: ${resultSet.columnNames}, column count: ${resultSet.columnCount}`); 2151 // resultSet是一个数据集合的游标，默认指向第-1个记录，有效的数据从0开始。 2152 try { 2153 while (resultSet.goToNextRow()) { 2154 const id = resultSet.getLong(resultSet.getColumnIndex("ID")); 2155 const name = resultSet.getString(resultSet.getColumnIndex("NAME")); 2156 const age = resultSet.getLong(resultSet.getColumnIndex("AGE")); 2157 const salary = resultSet.getDouble(resultSet.getColumnIndex("SALARY")); 2158 console.info(`id=${id}, name=${name}, age=${age}, salary=${salary}`); 2159 } 2160 } catch (err) { 2161 console.error(`Query failed, code is ${err.code},message is ${err.message}`); 2162 } finally { 2163 // 释放数据集的内存，若不释放可能会引起fd泄露与内存泄露 2164 resultSet.close(); 2165 } 2166 }); 2167} 2168``` 2169 2170向量数据库： 2171 2172```ts 2173// 相似度的计算符号是<->，余弦距离的计算符号是<=> 2174const querySql = "select id, repr <-> '[1.5,5.6]' as distance from test ORDER BY repr <-> '[1.5,5.6]' limit 10 offset 1;"; 2175let resultSet = await store.querySql(querySql); 2176 2177// 聚合查询，其中group by支持多列 2178const querySql1 = "select id, repr from test group by id, repr having max(repr<=>'[1.5,5.6]');"; 2179let resultSet1 = await store.querySql(querySql1); 2180 2181// 子查询，最大支持嵌套32层 2182const querySql2 = "select * from test where id in (select id from test1)"; 2183let resultSet2 = await store.querySql(querySql2); 2184``` 2185 2186## querySql 2187 2188querySql(sql: string, bindArgs: Array<ValueType>, callback: AsyncCallback<ResultSet>):void 2189 2190根据指定SQL语句查询数据库中的数据，SQL语句中的各种表达式和操作符之间的关系操作符号不超过1000个，使用callback异步回调。 2191 2192该接口支持[向量数据库](arkts-apis-data-relationalStore-i.md#storeconfig)使用，当前支持的语法见[规格限制](../../database/data-persistence-by-vector-store.md#规格限制)。 2193 2194聚合函数不支持嵌套使用。 2195 2196**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 2197 2198**参数：** 2199 2200| 参数名 | 类型 | 必填 | 说明 | 2201| -------- | -------------------------------------------- | ---- | ------------------------------------------------------------ | 2202| sql | string | 是 | 指定要执行的SQL语句。 | 2203| bindArgs | Array<[ValueType](arkts-apis-data-relationalStore-t.md#valuetype)> | 是 | SQL语句中参数的值。该值与sql参数语句中的占位符相对应。当sql参数语句完整时，该参数需为空数组。 | 2204| callback | AsyncCallback<[ResultSet](arkts-apis-data-relationalStore-ResultSet.md)> | 是 | 指定callback回调函数。如果操作成功，则返回ResultSet对象。 | 2205 2206**错误码：** 2207 2208以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。 2209 2210| **错误码ID** | **错误信息** | 2211|-----------| ------------------------------------------------------------ | 2212| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 2213| 14800000 | Inner error. | 2214| 14800014 | The RdbStore or ResultSet is already closed. | 2215| 14800015 | The database does not respond. | 2216 2217**示例：** 2218 2219```ts 2220if (store != undefined) { 2221 (store as relationalStore.RdbStore).querySql("SELECT * FROM EMPLOYEE CROSS JOIN BOOK WHERE BOOK.NAME = ?", ['sanguo'], async (err, resultSet) => { 2222 if (err) { 2223 console.error(`Query failed, code is ${err.code},message is ${err.message}`); 2224 return; 2225 } 2226 console.info(`ResultSet column names: ${resultSet.columnNames}, column count: ${resultSet.columnCount}`); 2227 // resultSet是一个数据集合的游标，默认指向第-1个记录，有效的数据从0开始。 2228 try { 2229 while (resultSet.goToNextRow()) { 2230 const id = resultSet.getLong(resultSet.getColumnIndex("ID")); 2231 const name = resultSet.getString(resultSet.getColumnIndex("NAME")); 2232 const age = resultSet.getLong(resultSet.getColumnIndex("AGE")); 2233 const salary = resultSet.getDouble(resultSet.getColumnIndex("SALARY")); 2234 console.info(`id=${id}, name=${name}, age=${age}, salary=${salary}`); 2235 } 2236 } catch (err) { 2237 console.error(`Query failed, code is ${err.code},message is ${err.message}`); 2238 } finally { 2239 // 释放数据集的内存，若不释放可能会引起fd泄露与内存泄露 2240 resultSet.close(); 2241 } 2242 }); 2243} 2244``` 2245 2246## querySql 2247 2248querySql(sql: string, bindArgs?: Array<ValueType>):Promise<ResultSet> 2249 2250根据指定SQL语句查询数据库中的数据，SQL语句中的各种表达式和操作符之间的关系操作符号不超过1000个，使用Promise异步回调。 2251 2252该接口支持[向量数据库](arkts-apis-data-relationalStore-i.md#storeconfig)使用，当前支持的语法见[规格限制](../../database/data-persistence-by-vector-store.md#规格限制)。 2253 2254聚合函数不支持嵌套使用。 2255 2256**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 2257 2258**参数：** 2259 2260| 参数名 | 类型 | 必填 | 说明 | 2261| -------- | ------------------------------------ | ---- | ------------------------------------------------------------ | 2262| sql | string | 是 | 指定要执行的SQL语句。 | 2263| bindArgs | Array<[ValueType](arkts-apis-data-relationalStore-t.md#valuetype)> | 否 | SQL语句中参数的值。该值与sql参数语句中的占位符相对应。当sql参数语句完整时，该参数不填。 | 2264 2265**返回值**： 2266 2267| 类型 | 说明 | 2268| ------------------------------------------------------- | -------------------------------------------------- | 2269| Promise<[ResultSet](arkts-apis-data-relationalStore-ResultSet.md)> | Promise对象。如果操作成功，则返回ResultSet对象。 | 2270 2271**错误码：** 2272 2273以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。 2274 2275| **错误码ID** | **错误信息** | 2276|-----------| ------------------------------------------------------------ | 2277| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 2278| 14800000 | Inner error. | 2279| 14800014 | The RdbStore or ResultSet is already closed. | 2280| 14800015 | The database does not respond. | 2281 2282**示例：** 2283 2284关系型数据库： 2285 2286```ts 2287import { BusinessError } from '@kit.BasicServicesKit'; 2288 2289if (store != undefined) { 2290 (store as relationalStore.RdbStore).querySql("SELECT * FROM EMPLOYEE CROSS JOIN BOOK WHERE BOOK.NAME = 'sanguo'").then(async (resultSet: relationalStore.ResultSet) => { 2291 console.info(`ResultSet column names: ${resultSet.columnNames}, column count: ${resultSet.columnCount}`); 2292 // resultSet是一个数据集合的游标，默认指向第-1个记录，有效的数据从0开始。 2293 try { 2294 while (resultSet.goToNextRow()) { 2295 const id = resultSet.getLong(resultSet.getColumnIndex("ID")); 2296 const name = resultSet.getString(resultSet.getColumnIndex("NAME")); 2297 const age = resultSet.getLong(resultSet.getColumnIndex("AGE")); 2298 const salary = resultSet.getDouble(resultSet.getColumnIndex("SALARY")); 2299 console.info(`id=${id}, name=${name}, age=${age}, salary=${salary}`); 2300 } 2301 } catch (err) { 2302 console.error(`Query failed, code is ${err.code},message is ${err.message}`); 2303 } finally { 2304 // 释放数据集的内存，若不释放可能会引起fd泄露与内存泄露 2305 resultSet.close(); 2306 } 2307 }).catch((err: BusinessError) => { 2308 console.error(`Query failed, code is ${err.code},message is ${err.message}`); 2309 }); 2310} 2311``` 2312 2313向量数据库： 2314 2315```ts 2316// 查询id为1，与[1.5, 2.5]相似度小于0.5，且以相似度进行升序排序的前10条数据 2317const querySql = "select id, repr <-> ? as distance from test where id = ? and repr <-> ? < 0.5 ORDER BY repr <-> ? limit 10;"; 2318const vectorValue: Float32Array = new Float32Array([1.5, 2.5]); 2319let resultSet = await store.querySql(querySql, [vectorValue, 1, vectorValue, vectorValue]); 2320``` 2321 2322## querySqlSync<sup>12+</sup> 2323 2324querySqlSync(sql: string, bindArgs?: Array<ValueType>):ResultSet 2325 2326根据指定SQL语句查询数据库中的数据，SQL语句中的各种表达式和操作符之间的关系操作符号不超过1000个。对query同步接口获得的resultSet进行操作时，若逻辑复杂且循环次数过多，可能造成freeze问题，建议将此步骤放到[taskpool](../apis-arkts/js-apis-taskpool.md)线程中执行。 2327 2328**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 2329 2330**参数：** 2331 2332| 参数名 | 类型 | 必填 | 说明 | 2333| -------- | ------------------------------------ | ---- | ------------------------------------------------------------ | 2334| sql | string | 是 | 指定要执行的SQL语句。 | 2335| bindArgs | Array<[ValueType](arkts-apis-data-relationalStore-t.md#valuetype)> | 否 | SQL语句中参数的值。该值与sql参数语句中的占位符相对应。当sql参数语句完整时，该参数不填。默认值为空。 | 2336 2337**返回值**： 2338 2339| 类型 | 说明 | 2340| ----------------------- | ----------------------------------- | 2341| [ResultSet](arkts-apis-data-relationalStore-ResultSet.md) | 如果操作成功，则返回ResultSet对象。 | 2342 2343**错误码：** 2344 2345以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。 2346 2347| **错误码ID** | **错误信息** | 2348| ------------ | ------------------------------------------------------------ | 2349| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 2350| 14800000 | Inner error. | 2351| 14800014 | The RdbStore or ResultSet is already closed. | 2352| 14800015 | The database does not respond. | 2353 2354**示例：** 2355 2356```ts 2357if (store != undefined) { 2358 let resultSet: relationalStore.ResultSet | undefined; 2359 try { 2360 resultSet = store.querySqlSync("SELECT * FROM EMPLOYEE CROSS JOIN BOOK WHERE BOOK.NAME = 'sanguo'"); 2361 console.info(`ResultSet column names: ${resultSet.columnNames}, column count: ${resultSet.columnCount}`); 2362 // resultSet是一个数据集合的游标，默认指向第-1个记录，有效的数据从0开始。 2363 while (resultSet.goToNextRow()) { 2364 const id = resultSet.getLong(resultSet.getColumnIndex("ID")); 2365 const name = resultSet.getString(resultSet.getColumnIndex("NAME")); 2366 const age = resultSet.getLong(resultSet.getColumnIndex("AGE")); 2367 const salary = resultSet.getDouble(resultSet.getColumnIndex("SALARY")); 2368 console.info(`id=${id}, name=${name}, age=${age}, salary=${salary}`); 2369 } 2370 } catch (err) { 2371 console.error(`Query failed, code is ${err.code},message is ${err.message}`); 2372 } finally { 2373 // 释放数据集的内存，若不释放可能会引起fd泄露与内存泄露 2374 if (resultSet) { 2375 resultSet.close(); 2376 } 2377 } 2378} 2379``` 2380 2381## executeSql<sup>10+</sup> 2382 2383executeSql(sql: string, callback: AsyncCallback<void>):void 2384 2385执行指定的SQL语句，语句中的各种表达式和操作符之间的关系操作符号不超过1000个，使用callback异步回调。 2386 2387此接口不支持执行查询、附加数据库和事务操作，可以使用[querySql](#querysql10)、[query](#query10)、[attach](#attach12)、[beginTransaction](#begintransaction)、[commit](#commit)等接口代替。 2388 2389不支持分号分隔的多条语句。 2390 2391**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 2392 2393**参数：** 2394 2395| 参数名 | 类型 | 必填 | 说明 | 2396| -------- | ------------------------------------ | ---- | ------------------------------------------------------------ | 2397| sql | string | 是 | 指定要执行的SQL语句。 | 2398| callback | AsyncCallback<void> | 是 | 指定callback回调函数。 | 2399 2400**错误码：** 2401 2402以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。其中，14800011错误码处理可参考[数据库备份与恢复](../../database/data-backup-and-restore.md)。 2403 2404| **错误码ID** | **错误信息** | 2405|-----------| ------------------------------------------------------------ | 2406| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 2407| 801 | Capability not supported the sql(attach,begin,commit,rollback etc.). | 2408| 14800000 | Inner error. | 2409| 14800011 | Failed to open the database because it is corrupted. | 2410| 14800014 | The RdbStore or ResultSet is already closed. | 2411| 14800015 | The database does not respond. | 2412| 14800021 | SQLite: Generic error. Possible causes: Insert failed or the updated data does not exist. | 2413| 14800022 | SQLite: Callback routine requested an abort. | 2414| 14800023 | SQLite: Access permission denied. | 2415| 14800024 | SQLite: The database file is locked. | 2416| 14800025 | SQLite: A table in the database is locked. | 2417| 14800026 | SQLite: The database is out of memory. | 2418| 14800027 | SQLite: Attempt to write a readonly database. | 2419| 14800028 | SQLite: Some kind of disk I/O error occurred. | 2420| 14800029 | SQLite: The database is full. | 2421| 14800030 | SQLite: Unable to open the database file. | 2422| 14800031 | SQLite: TEXT or BLOB exceeds size limit. | 2423| 14800032 | SQLite: Abort due to constraint violation. | 2424| 14800033 | SQLite: Data type mismatch. | 2425| 14800034 | SQLite: Library used incorrectly. | 2426| 14800047 | The WAL file size exceeds the default limit. | 2427 2428**示例：** 2429 2430```ts 2431const SQL_DELETE_TABLE = "DELETE FROM test WHERE name = 'zhangsan'"; 2432if (store != undefined) { 2433 (store as relationalStore.RdbStore).executeSql(SQL_DELETE_TABLE, (err) => { 2434 if (err) { 2435 console.error(`ExecuteSql failed, code is ${err.code},message is ${err.message}`); 2436 return; 2437 } 2438 console.info('Delete table done.'); 2439 }); 2440} 2441``` 2442 2443## executeSql 2444 2445executeSql(sql: string, bindArgs: Array<ValueType>, callback: AsyncCallback<void>):void 2446 2447执行指定的SQL语句，语句中的各种表达式和操作符之间的关系操作符号不超过1000个，使用callback异步回调。 2448 2449此接口不支持执行查询、附加数据库和事务操作，可以使用[querySql](#querysql10)、[query](#query10)、[attach](#attach12)、[beginTransaction](#begintransaction)、[commit](#commit)等接口代替。 2450 2451不支持分号分隔的多条语句。 2452 2453**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 2454 2455**参数：** 2456 2457| 参数名 | 类型 | 必填 | 说明 | 2458| -------- | ------------------------------------ | ---- | ------------------------------------------------------------ | 2459| sql | string | 是 | 指定要执行的SQL语句。 | 2460| bindArgs | Array<[ValueType](arkts-apis-data-relationalStore-t.md#valuetype)> | 是 | SQL语句中参数的值。该值与sql参数语句中的占位符相对应。当sql参数语句完整时，该参数需为空数组。 | 2461| callback | AsyncCallback<void> | 是 | 指定callback回调函数。 | 2462 2463**错误码：** 2464 2465以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。其中，14800011错误码处理可参考[数据库备份与恢复](../../database/data-backup-and-restore.md)。 2466 2467| **错误码ID** | **错误信息** | 2468|-----------| ------------------------------------------------------------ | 2469| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 2470| 801 | Capability not supported the sql(attach,begin,commit,rollback etc.). | 2471| 14800000 | Inner error. | 2472| 14800011 | Failed to open the database because it is corrupted. | 2473| 14800014 | The RdbStore or ResultSet is already closed. | 2474| 14800015 | The database does not respond. | 2475| 14800021 | SQLite: Generic error. Possible causes: Insert failed or the updated data does not exist. | 2476| 14800022 | SQLite: Callback routine requested an abort. | 2477| 14800023 | SQLite: Access permission denied. | 2478| 14800024 | SQLite: The database file is locked. | 2479| 14800025 | SQLite: A table in the database is locked. | 2480| 14800026 | SQLite: The database is out of memory. | 2481| 14800027 | SQLite: Attempt to write a readonly database. | 2482| 14800028 | SQLite: Some kind of disk I/O error occurred. | 2483| 14800029 | SQLite: The database is full. | 2484| 14800030 | SQLite: Unable to open the database file. | 2485| 14800031 | SQLite: TEXT or BLOB exceeds size limit. | 2486| 14800032 | SQLite: Abort due to constraint violation. | 2487| 14800033 | SQLite: Data type mismatch. | 2488| 14800034 | SQLite: Library used incorrectly. | 2489| 14800047 | The WAL file size exceeds the default limit. | 2490 2491**示例：** 2492 2493```ts 2494const SQL_DELETE_TABLE = "DELETE FROM test WHERE name = ?"; 2495if (store != undefined) { 2496 (store as relationalStore.RdbStore).executeSql(SQL_DELETE_TABLE, ['zhangsan'], (err) => { 2497 if (err) { 2498 console.error(`ExecuteSql failed, code is ${err.code},message is ${err.message}`); 2499 return; 2500 } 2501 console.info('Delete table done.'); 2502 }); 2503} 2504``` 2505 2506## executeSql 2507 2508executeSql(sql: string, bindArgs?: Array<ValueType>):Promise<void> 2509 2510执行指定的SQL语句，语句中的各种表达式和操作符之间的关系操作符号不超过1000个，使用Promise异步回调。 2511 2512此接口不支持执行查询、附加数据库和事务操作，可以使用[querySql](#querysql10)、[query](#query10)、[attach](#attach12)、[beginTransaction](#begintransaction)、[commit](#commit)等接口代替。 2513 2514不支持分号分隔的多条语句。 2515 2516**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 2517 2518**参数：** 2519 2520| 参数名 | 类型 | 必填 | 说明 | 2521| -------- | ------------------------------------ | ---- | ------------------------------------------------------------ | 2522| sql | string | 是 | 指定要执行的SQL语句。 | 2523| bindArgs | Array<[ValueType](arkts-apis-data-relationalStore-t.md#valuetype)> | 否 | SQL语句中参数的值。该值与sql参数语句中的占位符相对应。当sql参数语句完整时，该参数不填。 | 2524 2525**返回值**： 2526 2527| 类型 | 说明 | 2528| ------------------- | ------------------------- | 2529| Promise<void> | 无返回结果的Promise对象。 | 2530 2531**错误码：** 2532 2533以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。其中，14800011错误码处理可参考[数据库备份与恢复](../../database/data-backup-and-restore.md)。 2534 2535| **错误码ID** | **错误信息** | 2536|-----------| ------------------------------------------------------------ | 2537| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 2538| 801 | Capability not supported the sql(attach,begin,commit,rollback etc.). | 2539| 14800000 | Inner error. | 2540| 14800011 | Failed to open the database because it is corrupted. | 2541| 14800014 | The RdbStore or ResultSet is already closed. | 2542| 14800015 | The database does not respond. | 2543| 14800021 | SQLite: Generic error. Possible causes: Insert failed or the updated data does not exist. | 2544| 14800022 | SQLite: Callback routine requested an abort. | 2545| 14800023 | SQLite: Access permission denied. | 2546| 14800024 | SQLite: The database file is locked. | 2547| 14800025 | SQLite: A table in the database is locked. | 2548| 14800026 | SQLite: The database is out of memory. | 2549| 14800027 | SQLite: Attempt to write a readonly database. | 2550| 14800028 | SQLite: Some kind of disk I/O error occurred. | 2551| 14800029 | SQLite: The database is full. | 2552| 14800030 | SQLite: Unable to open the database file. | 2553| 14800031 | SQLite: TEXT or BLOB exceeds size limit. | 2554| 14800032 | SQLite: Abort due to constraint violation. | 2555| 14800033 | SQLite: Data type mismatch. | 2556| 14800034 | SQLite: Library used incorrectly. | 2557| 14800047 | The WAL file size exceeds the default limit. | 2558 2559**示例：** 2560 2561```ts 2562import { BusinessError } from '@kit.BasicServicesKit'; 2563 2564const SQL_DELETE_TABLE = "DELETE FROM test WHERE name = 'zhangsan'"; 2565if (store != undefined) { 2566 (store as relationalStore.RdbStore).executeSql(SQL_DELETE_TABLE).then(() => { 2567 console.info('Delete table done.'); 2568 }).catch((err: BusinessError) => { 2569 console.error(`ExecuteSql failed, code is ${err.code},message is ${err.message}`); 2570 }); 2571} 2572``` 2573 2574## execute<sup>12+</sup> 2575 2576execute(sql: string, args?: Array<ValueType>):Promise<ValueType> 2577 2578执行包含指定参数的SQL语句，语句中的各种表达式和操作符之间的关系操作符号不超过1000个，返回值类型为ValueType，使用Promise异步回调。 2579 2580该接口支持执行增删改操作，支持执行PRAGMA语法的sql，支持对表的操作（建表、删表、修改表），返回结果类型由执行具体sql的结果决定。 2581 2582此接口不支持执行查询、附加数据库和事务操作，可以使用[querySql](#querysql10)、[query](#query10)、[attach](#attach12)、[beginTransaction](#begintransaction)、[commit](#commit)等接口代替。 2583 2584向量数据库使用该接口执行插入操作，数据来源于子查询时，支持全字段插入，暂不支持部分字段插入。 2585 2586不支持分号分隔的多条语句。 2587 2588**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 2589 2590**参数：** 2591 2592| 参数名 | 类型 | 必填 | 说明 | 2593| -------- | ------------------------------------ | ---- | ------------------------------------------------------------ | 2594| sql | string | 是 | 指定要执行的SQL语句。 | 2595| args | Array<[ValueType](arkts-apis-data-relationalStore-t.md#valuetype)> | 否 | SQL语句中参数的值。该值与sql参数语句中的占位符相对应。当sql参数语句完整时，该参数不填。 | 2596 2597**返回值**： 2598 2599| 类型 | 说明 | 2600| ------------------- | ------------------------- | 2601| Promise<[ValueType](arkts-apis-data-relationalStore-t.md#valuetype)> | Promise对象，返回sql执行后的结果。 | 2602 2603**错误码：** 2604 2605以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。其中，14800011错误码处理可参考[数据库备份与恢复](../../database/data-backup-and-restore.md)。 2606 2607| **错误码ID** | **错误信息** | 2608|-----------| ------------------------------------------------------------ | 2609| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 2610| 801 | Capability not supported the sql(attach,begin,commit,rollback etc.). | 2611| 14800000 | Inner error. | 2612| 14800011 | Failed to open the database because it is corrupted. | 2613| 14800014 | The RdbStore or ResultSet is already closed. | 2614| 14800015 | The database does not respond. | 2615| 14800021 | SQLite: Generic error. Possible causes: Insert failed or the updated data does not exist. | 2616| 14800022 | SQLite: Callback routine requested an abort. | 2617| 14800023 | SQLite: Access permission denied. | 2618| 14800024 | SQLite: The database file is locked. | 2619| 14800025 | SQLite: A table in the database is locked. | 2620| 14800026 | SQLite: The database is out of memory. | 2621| 14800027 | SQLite: Attempt to write a readonly database. | 2622| 14800028 | SQLite: Some kind of disk I/O error occurred. | 2623| 14800029 | SQLite: The database is full. | 2624| 14800030 | SQLite: Unable to open the database file. | 2625| 14800031 | SQLite: TEXT or BLOB exceeds size limit. | 2626| 14800032 | SQLite: Abort due to constraint violation. | 2627| 14800033 | SQLite: Data type mismatch. | 2628| 14800034 | SQLite: Library used incorrectly. | 2629| 14800047 | The WAL file size exceeds the default limit. | 2630 2631**示例：** 2632 2633关系型数据库： 2634 2635```ts 2636import { BusinessError } from '@kit.BasicServicesKit'; 2637 2638// 校验数据库完整性 2639if (store != undefined) { 2640 const SQL_CHECK_INTEGRITY = 'PRAGMA integrity_check'; 2641 (store as relationalStore.RdbStore).execute(SQL_CHECK_INTEGRITY).then((data) => { 2642 console.info(`check result: ${data}`); 2643 }).catch((err: BusinessError) => { 2644 console.error(`check failed, code is ${err.code}, message is ${err.message}`); 2645 }); 2646} 2647 2648// 删除表中所有数据 2649if (store != undefined) { 2650 const SQL_DELETE_TABLE = 'DELETE FROM test'; 2651 (store as relationalStore.RdbStore).execute(SQL_DELETE_TABLE).then((data) => { 2652 console.info(`delete result: ${data}`); 2653 }).catch((err: BusinessError) => { 2654 console.error(`delete failed, code is ${err.code}, message is ${err.message}`); 2655 }); 2656} 2657 2658// 删表 2659if (store != undefined) { 2660 const SQL_DROP_TABLE = 'DROP TABLE test'; 2661 (store as relationalStore.RdbStore).execute(SQL_DROP_TABLE).then((data) => { 2662 console.info(`drop result: ${data}`); 2663 }).catch((err: BusinessError) => { 2664 console.error(`drop failed, code is ${err.code}, message is ${err.message}`); 2665 }); 2666} 2667``` 2668 2669向量数据库： 2670 2671```ts 2672// FLOATVECTOR(2)是维度为2的向量属性，后续操作repr需依照该维度进行。 2673let createSql = "CREATE TABLE test (ID INTEGER PRIMARY KEY,REPR FLOATVECTOR(2));"; 2674// 建表 2675await store!.execute(createSql); 2676// 使用参数绑定插入数据 2677let insertSql = "insert into test VALUES(?, ?);"; 2678const vectorValue: Float32Array = Float32Array.from([1.5, 6.6]); 2679await store!.execute(insertSql, [0, vectorValue]); 2680// 不使用绑定参数直接执行 2681await store!.execute("insert into test values(1, '[3.5, 1.8]');"); 2682``` 2683 2684## execute<sup>12+</sup> 2685 2686execute(sql: string, txId: number, args?: Array<ValueType>): Promise<ValueType> 2687 2688执行包含指定参数的SQL语句，语句中的各种表达式和操作符之间的关系操作符号不超过1000个，使用Promise异步回调。 2689 2690该接口仅支持[向量数据库](arkts-apis-data-relationalStore-i.md#storeconfig)使用。使用该接口执行插入操作，数据来源于子查询时，支持全字段插入，暂不支持部分字段插入。 2691 2692此接口不支持执行查询，可以使用[querySql](#querysql10)接口代替。 2693 2694不支持分号分隔的多条语句。 2695 2696**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 2697 2698**参数：** 2699 2700| 参数名 | 类型 | 必填 | 说明 | 2701| -------- | ------------------------------------ | ---- | ------------------------------------------------------------ | 2702| sql | string | 是 | 指定要执行的SQL语句。 | 2703| txId | number | 是 | 通过[beginTrans](#begintrans12)获取的事务ID，如果传0，该语句默认在单独事务内。 | 2704| args | Array<[ValueType](arkts-apis-data-relationalStore-t.md#valuetype)> | 否 | SQL语句中参数的值。该值与sql参数语句中的占位符相对应。该参数不填，填null或者填undefined，都认为是sql参数语句完整。 | 2705 2706**返回值**： 2707 2708| 类型 | 说明 | 2709| ------------------- | ------------------------- | 2710| Promise<[ValueType](arkts-apis-data-relationalStore-t.md#valuetype)> | Promise对象，返回null。 | 2711 2712**错误码：** 2713 2714以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。其中，14800011错误码处理可参考[数据库备份与恢复](../../database/data-backup-and-restore.md)。 2715 2716| **错误码ID** | **错误信息** | 2717|-----------| ------------------------------------------------------------ | 2718| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 2719| 801 | Capability not supported the sql(attach,begin,commit,rollback etc.). | 2720| 14800000 | Inner error. | 2721| 14800011 | Failed to open the database because it is corrupted. | 2722| 14800014 | The RdbStore or ResultSet is already closed. | 2723| 14800015 | The database does not respond. | 2724| 14800021 | SQLite: Generic error. Possible causes: Insert failed or the updated data does not exist. | 2725| 14800022 | SQLite: Callback routine requested an abort. | 2726| 14800023 | SQLite: Access permission denied. | 2727| 14800024 | SQLite: The database file is locked. | 2728| 14800025 | SQLite: A table in the database is locked. | 2729| 14800026 | SQLite: The database is out of memory. | 2730| 14800027 | SQLite: Attempt to write a readonly database. | 2731| 14800028 | SQLite: Some kind of disk I/O error occurred. | 2732| 14800029 | SQLite: The database is full. | 2733| 14800030 | SQLite: Unable to open the database file. | 2734| 14800031 | SQLite: TEXT or BLOB exceeds size limit. | 2735| 14800032 | SQLite: Abort due to constraint violation. | 2736| 14800033 | SQLite: Data type mismatch. | 2737| 14800034 | SQLite: Library used incorrectly. | 2738| 14800047 | The WAL file size exceeds the default limit. | 2739 2740**示例：** 2741 2742```ts 2743import { BusinessError } from '@kit.BasicServicesKit'; 2744if (store != null) { 2745 let txId: number; 2746 (store as relationalStore.RdbStore).beginTrans().then((temTxId: number) => { 2747 txId = temTxId; 2748 (store as relationalStore.RdbStore).execute("DELETE FROM TEST WHERE age = ? OR age = ?", txId, ["18", "20"]) 2749 .then(() => { 2750 if (txId !== undefined) { 2751 (store as relationalStore.RdbStore).commit(txId); 2752 } 2753 }) 2754 .catch((err: BusinessError) => { 2755 if (txId !== undefined) { 2756 (store as relationalStore.RdbStore).rollback(txId); 2757 } 2758 console.error(`execute sql failed, code is ${err.code},message is ${err.message}`); 2759 }); 2760 }); 2761} 2762``` 2763 2764## executeSync<sup>12+</sup> 2765 2766executeSync(sql: string, args?: Array<ValueType>): ValueType 2767 2768执行包含指定参数的SQL语句，语句中的各种表达式和操作符之间的关系操作符号不超过1000个，返回值类型为ValueType。 2769 2770该接口支持执行增删改操作，支持执行PRAGMA语法的sql，支持对表的操作（建表、删表、修改表），返回结果类型由执行具体sql的结果决定。 2771 2772此接口不支持执行查询、附加数据库和事务操作，可以使用[querySql](#querysql10)、[query](#query10)、[attach](#attach12)、[beginTransaction](#begintransaction)、[commit](#commit)等接口代替。 2773 2774不支持分号分隔的多条语句。 2775 2776**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 2777 2778**参数：** 2779 2780| 参数名 | 类型 | 必填 | 说明 | 2781| ------ | ------------------------------------ | ---- | ------------------------------------------------------------ | 2782| sql | string | 是 | 指定要执行的SQL语句。 | 2783| args | Array<[ValueType](arkts-apis-data-relationalStore-t.md#valuetype)> | 否 | SQL语句中参数的值。该值与sql参数语句中的占位符相对应。该参数不填，或者填null或undefined，都认为是sql参数语句完整。默认值为空。 | 2784 2785**返回值**： 2786 2787| 类型 | 说明 | 2788| ----------------------- | ------------------- | 2789| [ValueType](arkts-apis-data-relationalStore-t.md#valuetype) | 返回sql执行后的结果 | 2790 2791**错误码：** 2792 2793以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。其中，14800011错误码处理可参考[数据库备份与恢复](../../database/data-backup-and-restore.md)。 2794 2795| **错误码ID** | **错误信息** | 2796| ------------ | ------------------------------------------------------------ | 2797| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 2798| 14800000 | Inner error. | 2799| 14800011 | Failed to open the database because it is corrupted. | 2800| 14800014 | The RdbStore or ResultSet is already closed. | 2801| 14800015 | The database does not respond. | 2802| 14800021 | SQLite: Generic error. Possible causes: Insert failed or the updated data does not exist. | 2803| 14800022 | SQLite: Callback routine requested an abort. | 2804| 14800023 | SQLite: Access permission denied. | 2805| 14800024 | SQLite: The database file is locked. | 2806| 14800025 | SQLite: A table in the database is locked. | 2807| 14800026 | SQLite: The database is out of memory. | 2808| 14800027 | SQLite: Attempt to write a readonly database. | 2809| 14800028 | SQLite: Some kind of disk I/O error occurred. | 2810| 14800029 | SQLite: The database is full. | 2811| 14800030 | SQLite: Unable to open the database file. | 2812| 14800031 | SQLite: TEXT or BLOB exceeds size limit. | 2813| 14800032 | SQLite: Abort due to constraint violation. | 2814| 14800033 | SQLite: Data type mismatch. | 2815| 14800034 | SQLite: Library used incorrectly. | 2816| 14800047 | The WAL file size exceeds the default limit. | 2817 2818**示例：** 2819 2820```ts 2821// 校验数据库完整性 2822if (store != undefined) { 2823 const SQL_CHECK_INTEGRITY = 'PRAGMA integrity_check'; 2824 try { 2825 let data = (store as relationalStore.RdbStore).executeSync(SQL_CHECK_INTEGRITY); 2826 console.info(`check result: ${data}`); 2827 } catch (err) { 2828 console.error(`check failed, code is ${err.code}, message is ${err.message}`); 2829 } 2830} 2831 2832// 删除表中所有数据 2833if (store != undefined) { 2834 const SQL_DELETE_TABLE = 'DELETE FROM test'; 2835 try { 2836 let data = (store as relationalStore.RdbStore).executeSync(SQL_DELETE_TABLE); 2837 console.info(`delete result: ${data}`); 2838 } catch (err) { 2839 console.error(`delete failed, code is ${err.code}, message is ${err.message}`); 2840 } 2841} 2842 2843// 删表 2844if (store != undefined) { 2845 const SQL_DROP_TABLE = 'DROP TABLE test'; 2846 try { 2847 let data = (store as relationalStore.RdbStore).executeSync(SQL_DROP_TABLE); 2848 console.info(`drop result: ${data}`); 2849 } catch (err) { 2850 console.error(`drop failed, code is ${err.code}, message is ${err.message}`); 2851 } 2852} 2853``` 2854 2855## getModifyTime<sup>10+</sup> 2856 2857getModifyTime(table: string, columnName: string, primaryKeys: PRIKeyType[], callback: AsyncCallback<ModifyTime>): void 2858 2859获取数据库表中数据的最后修改时间，使用callback异步回调。 2860 2861**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 2862 2863**参数：** 2864 2865| 参数名 | 类型 | 必填 | 说明 | 2866| ----------- | ------------------------------------------------ | ---- | ------------------------------------------------------------ | 2867| table | string | 是 | 指定要查询的数据库表的表名。 | 2868| columnName | string | 是 | 指定要查询的数据库表的列名。 | 2869| primaryKeys | [PRIKeyType](arkts-apis-data-relationalStore-t.md#prikeytype10)[] | 是 | 指定要查询的行的主键。<br>如果数据库表无主键，参数columnName需传入"rowid"，此时primaryKeys为要查询的数据库表的行号。<br>如果数据库表无主键，参数columnName传入不为"rowid"，返回对应的错误码。 | 2870| callback | AsyncCallback<[ModifyTime](arkts-apis-data-relationalStore-t.md#modifytime10)> | 是 | 指定callback回调函数。如果操作成功，则返回ModifyTime对象，表示数据的最后修改时间。 | 2871 2872**错误码：** 2873 2874以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。其中，14800011错误码处理可参考[数据库备份与恢复](../../database/data-backup-and-restore.md)。 2875 2876| **错误码ID** | **错误信息** | 2877|-----------| ------------------------------------------------------------ | 2878| 401 | Parameter error. Possible causes: 1. Need 3 - 4 parameter(s)! 2. The RdbStore must be not nullptr. 3. The tablesNames must be not empty string. 4. The columnName must be not empty string. 5. The PRIKey must be number or string. | 2879| 801 | Capability not supported. | 2880| 14800000 | Inner error. | 2881| 14800011 | Failed to open the database because it is corrupted. | 2882| 14800014 | The RdbStore or ResultSet is already closed. | 2883| 14800015 | The database does not respond. | 2884| 14800021 | SQLite: Generic error. Possible causes: Insert failed or the updated data does not exist. | 2885| 14800022 | SQLite: Callback routine requested an abort. | 2886| 14800023 | SQLite: Access permission denied. | 2887| 14800024 | SQLite: The database file is locked. | 2888| 14800025 | SQLite: A table in the database is locked. | 2889| 14800026 | SQLite: The database is out of memory. | 2890| 14800027 | SQLite: Attempt to write a readonly database. | 2891| 14800028 | SQLite: Some kind of disk I/O error occurred. | 2892| 14800029 | SQLite: The database is full. | 2893| 14800030 | SQLite: Unable to open the database file. | 2894| 14800031 | SQLite: TEXT or BLOB exceeds size limit. | 2895| 14800032 | SQLite: Abort due to constraint violation. | 2896| 14800033 | SQLite: Data type mismatch. | 2897| 14800034 | SQLite: Library used incorrectly. | 2898 2899**示例：** 2900 2901```ts 2902let PRIKey = [1, 4, 2, 3]; 2903if (store != undefined) { 2904 (store as relationalStore.RdbStore).getModifyTime("EMPLOYEE", "NAME", PRIKey, (err, modifyTime: relationalStore.ModifyTime) => { 2905 if (err) { 2906 console.error(`getModifyTime failed, code is ${err.code},message is ${err.message}`); 2907 return; 2908 } 2909 let size = modifyTime.size; 2910 }); 2911} 2912``` 2913 2914## getModifyTime<sup>10+</sup> 2915 2916getModifyTime(table: string, columnName: string, primaryKeys: PRIKeyType[]): Promise<ModifyTime> 2917 2918获取数据库表中数据的最后修改时间，使用Promise异步回调。 2919 2920**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 2921 2922**参数：** 2923 2924| 参数名 | 类型 | 必填 | 说明 | 2925| ----------- | ----------------------------- | ---- | ------------------------------------------------------------ | 2926| table | string | 是 | 指定要查询的数据库表的表名。 | 2927| columnName | string | 是 | 指定要查询的数据库表的列名。 | 2928| primaryKeys | [PRIKeyType](arkts-apis-data-relationalStore-t.md#prikeytype10)[] | 是 | 指定要查询的行的主键。<br>如果数据库表无主键，参数columnName需传入"rowid"，此时primaryKeys为要查询的数据库表的行号。<br>如果数据库表无主键，参数columnName传入不为"rowid"，返回对应的错误码。 | 2929 2930**返回值**： 2931 2932| 类型 | 说明 | 2933| ------------------------------------------ | --------------------------------------------------------- | 2934| Promise<[ModifyTime](arkts-apis-data-relationalStore-t.md#modifytime10)> | 返回ModifyTime类型的Promise对象，表示数据最后的修改时间。 | 2935 2936**错误码：** 2937 2938以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。其中，14800011错误码处理可参考[数据库备份与恢复](../../database/data-backup-and-restore.md)。 2939 2940| **错误码ID** | **错误信息** | 2941|-----------| ------------------------------------------------------------ | 2942| 401 | Parameter error. Possible causes: 1. Need 3 - 4 parameter(s)! 2. The RdbStore must be not nullptr.3. The tablesNames must be not empty string. 4. The columnName must be not empty string. 5. The PRIKey must be number or string. | 2943| 801 | Capability not supported. | 2944| 14800000 | Inner error. | 2945| 14800011 | Failed to open the database because it is corrupted. | 2946| 14800014 | The RdbStore or ResultSet is already closed. | 2947| 14800015 | The database does not respond. | 2948| 14800021 | SQLite: Generic error. Possible causes: Insert failed or the updated data does not exist. | 2949| 14800022 | SQLite: Callback routine requested an abort. | 2950| 14800023 | SQLite: Access permission denied. | 2951| 14800024 | SQLite: The database file is locked. | 2952| 14800025 | SQLite: A table in the database is locked. | 2953| 14800026 | SQLite: The database is out of memory. | 2954| 14800027 | SQLite: Attempt to write a readonly database. | 2955| 14800028 | SQLite: Some kind of disk I/O error occurred. | 2956| 14800029 | SQLite: The database is full. | 2957| 14800030 | SQLite: Unable to open the database file. | 2958| 14800031 | SQLite: TEXT or BLOB exceeds size limit. | 2959| 14800032 | SQLite: Abort due to constraint violation. | 2960| 14800033 | SQLite: Data type mismatch. | 2961| 14800034 | SQLite: Library used incorrectly. | 2962 2963**示例：** 2964 2965```ts 2966import { BusinessError } from '@kit.BasicServicesKit'; 2967 2968let PRIKey = [1, 2, 3]; 2969if (store != undefined) { 2970 (store as relationalStore.RdbStore).getModifyTime("EMPLOYEE", "NAME", PRIKey) 2971 .then((modifyTime: relationalStore.ModifyTime) => { 2972 let size = modifyTime.size; 2973 }) 2974 .catch((err: BusinessError) => { 2975 console.error(`getModifyTime failed, code is ${err.code},message is ${err.message}`); 2976 }); 2977} 2978``` 2979 2980## beginTransaction 2981 2982beginTransaction():void 2983 2984在开始执行SQL语句之前，开始事务。 2985此接口不允许嵌套事务，且不支持在多进程或多线程中使用。 2986 2987**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 2988 2989**错误码：** 2990 2991以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。其中，14800011错误码处理可参考[数据库备份与恢复](../../database/data-backup-and-restore.md)。 2992 2993| **错误码ID** | **错误信息** | 2994|-----------| ------------------------------------------------------------ | 2995| 401 | Parameter error. Possible causes: The RdbStore verification failed. | 2996| 14800000 | Inner error. | 2997| 14800011 | Failed to open the database because it is corrupted. | 2998| 14800014 | The RdbStore or ResultSet is already closed. | 2999| 14800015 | The database does not respond. | 3000| 14800021 | SQLite: Generic error. Possible causes: Insert failed or the updated data does not exist. | 3001| 14800022 | SQLite: Callback routine requested an abort. | 3002| 14800023 | SQLite: Access permission denied. | 3003| 14800024 | SQLite: The database file is locked. | 3004| 14800025 | SQLite: A table in the database is locked. | 3005| 14800026 | SQLite: The database is out of memory. | 3006| 14800027 | SQLite: Attempt to write a readonly database. | 3007| 14800028 | SQLite: Some kind of disk I/O error occurred. | 3008| 14800029 | SQLite: The database is full. | 3009| 14800030 | SQLite: Unable to open the database file. | 3010| 14800031 | SQLite: TEXT or BLOB exceeds size limit. | 3011| 14800032 | SQLite: Abort due to constraint violation. | 3012| 14800033 | SQLite: Data type mismatch. | 3013| 14800034 | SQLite: Library used incorrectly. | 3014| 14800047 | The WAL file size exceeds the default limit. | 3015 3016**示例：** 3017 3018```ts 3019let value1 = "Lisa"; 3020let value2 = 18; 3021let value3 = 100.5; 3022let value4 = new Uint8Array([1, 2, 3]); 3023 3024if (store != undefined) { 3025 (store as relationalStore.RdbStore).beginTransaction(); 3026 const valueBucket: relationalStore.ValuesBucket = { 3027 'NAME': value1, 3028 'AGE': value2, 3029 'SALARY': value3, 3030 'CODES': value4 3031 }; 3032 (store as relationalStore.RdbStore).insert("test", valueBucket); 3033 (store as relationalStore.RdbStore).commit(); 3034} 3035``` 3036 3037## beginTrans<sup>12+</sup> 3038 3039beginTrans(): Promise<number> 3040 3041在开始执行SQL语句之前，开始事务，使用Promise异步回调。 3042 3043与[beginTransaction](#begintransaction)的区别在于：该接口会返回事务ID，[execute](#execute12-1)可以指定不同事务ID达到事务隔离目的。 3044 3045该接口仅支持[向量数据库](arkts-apis-data-relationalStore-i.md#storeconfig)使用。 3046 3047**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 3048 3049**返回值**： 3050 3051| 类型 | 说明 | 3052| ------------------- | ------------------------- | 3053| Promise<number> | Promise对象，返回事务ID。 | 3054 3055**错误码：** 3056 3057以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。其中，14800011错误码处理可参考[数据库备份与恢复](../../database/data-backup-and-restore.md)。 3058 3059| **错误码ID** | **错误信息** | 3060|-----------| ------------------------------------------------------------ | 3061| 401 | Parameter error. Possible causes: The RdbStore verification failed. | 3062| 801 | Capability not supported the sql(attach,begin,commit,rollback etc.). | 3063| 14800000 | Inner error. | 3064| 14800011 | Failed to open the database because it is corrupted. | 3065| 14800014 | The RdbStore or ResultSet is already closed. | 3066| 14800015 | The database does not respond. | 3067| 14800021 | SQLite: Generic error. Possible causes: Insert failed or the updated data does not exist. | 3068| 14800022 | SQLite: Callback routine requested an abort. | 3069| 14800023 | SQLite: Access permission denied. | 3070| 14800024 | SQLite: The database file is locked. | 3071| 14800025 | SQLite: A table in the database is locked. | 3072| 14800026 | SQLite: The database is out of memory. | 3073| 14800027 | SQLite: Attempt to write a readonly database. | 3074| 14800028 | SQLite: Some kind of disk I/O error occurred. | 3075| 14800029 | SQLite: The database is full. | 3076| 14800030 | SQLite: Unable to open the database file. | 3077| 14800031 | SQLite: TEXT or BLOB exceeds size limit. | 3078| 14800032 | SQLite: Abort due to constraint violation. | 3079| 14800033 | SQLite: Data type mismatch. | 3080| 14800034 | SQLite: Library used incorrectly. | 3081| 14800047 | The WAL file size exceeds the default limit. | 3082 3083**示例：** 3084 3085```ts 3086import { BusinessError } from '@kit.BasicServicesKit'; 3087if (store != null) { 3088 let txId: number; 3089 (store as relationalStore.RdbStore).beginTrans().then((temTxId: number) => { 3090 txId = temTxId; 3091 (store as relationalStore.RdbStore).execute("DELETE FROM TEST WHERE age = ? OR age = ?", txId, ["18", "20"]) 3092 .then(() => { 3093 if (txId !== undefined) { 3094 (store as relationalStore.RdbStore).commit(txId); 3095 } 3096 }) 3097 .catch((err: BusinessError) => { 3098 if (txId !== undefined) { 3099 (store as relationalStore.RdbStore).rollback(txId); 3100 } 3101 console.error(`execute sql failed, code is ${err.code},message is ${err.message}`); 3102 }); 3103 }); 3104} 3105``` 3106 3107## createTransaction<sup>14+</sup> 3108 3109createTransaction(options?: TransactionOptions): Promise<Transaction> 3110 3111创建一个事务对象并开始事务，使用Promise异步回调。 3112 3113与[beginTransaction](#begintransaction)的区别在于：createTransaction接口会返回一个事务对象，不同事务对象之间是隔离的。使用事务对象进行插入、删除或更新数据等操作，无法被注册数据变更通知[on('dataChange')](#ondatachange)监听到。 3114 3115一个store最多支持同时存在四个事务对象，超过后会返回14800015错误码，此时需要检查是否持有事务对象时间过长或并发事务过多，若确认无法通过上述优化解决问题，建议等待现有事务释放后，再尝试新建事务对象。 3116 3117优先使用createTransaction，不再推荐使用beginTransaction。 3118 3119**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 3120 3121**参数：** 3122 3123| 参数名 | 类型 | 必填 | 说明 | 3124| ----------- | ----------------------------- | ---- | ------------------------------------------------------------ | 3125| options | [TransactionOptions](arkts-apis-data-relationalStore-i.md#transactionoptions14) | 否 | 表示事务对象的配置信息。 | 3126 3127**返回值**： 3128 3129| 类型 | 说明 | 3130| ------------------- | ------------------------- | 3131| Promise<[Transaction](arkts-apis-data-relationalStore-Transaction.md)> | Promise对象，返回事务对象。 | 3132 3133**错误码：** 3134 3135以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。其中，14800011错误码处理可参考[数据库备份与恢复](../../database/data-backup-and-restore.md)。 3136 3137| **错误码ID** | **错误信息** | 3138|-----------| ------------------------------------------------------------ | 3139| 14800000 | Inner error. | 3140| 14800011 | Failed to open the database because it is corrupted. | 3141| 14800014 | The RdbStore or ResultSet is already closed. | 3142| 14800015 | The database is busy. | 3143| 14800023 | SQLite: Access permission denied. | 3144| 14800024 | SQLite: The database file is locked. | 3145| 14800026 | SQLite: The database is out of memory. | 3146| 14800028 | SQLite: Some kind of disk I/O error occurred. | 3147| 14800029 | SQLite: The database is full. | 3148| 14800030 | SQLite: Unable to open the database file. | 3149 3150**示例：** 3151 3152```ts 3153import { BusinessError } from '@kit.BasicServicesKit'; 3154 3155if (store != undefined) { 3156 (store as relationalStore.RdbStore).createTransaction().then(async (transaction: relationalStore.Transaction) => { 3157 transaction.execute("DELETE FROM test WHERE age = ? OR age = ?", [21, 20]).then(() => { 3158 transaction.commit(); 3159 }).catch((e: BusinessError) => { 3160 transaction.rollback(); 3161 console.error(`execute sql failed, code is ${e.code},message is ${e.message}`); 3162 }); 3163 }).catch((err: BusinessError) => { 3164 console.error(`createTransaction failed, code is ${err.code},message is ${err.message}`); 3165 }); 3166} 3167``` 3168 3169## commit 3170 3171commit():void 3172 3173提交已执行的SQL语句，跟[beginTransaction](#begintransaction)配合使用。 3174此接口不允许嵌套事务，且不支持在多进程或多线程中使用。 3175 3176**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 3177 3178**错误码：** 3179 3180以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。其中，14800011错误码处理可参考[数据库备份与恢复](../../database/data-backup-and-restore.md)。 3181 3182| **错误码ID** | **错误信息** | 3183|-----------| ------------------------------------------------------------ | 3184| 401 | Parameter error. Possible causes: The RdbStore verification failed. | 3185| 14800000 | Inner error. | 3186| 14800011 | Failed to open the database because it is corrupted. | 3187| 14800014 | The RdbStore or ResultSet is already closed. | 3188| 14800015 | The database does not respond. | 3189| 14800021 | SQLite: Generic error. Possible causes: Insert failed or the updated data does not exist. | 3190| 14800022 | SQLite: Callback routine requested an abort. | 3191| 14800023 | SQLite: Access permission denied. | 3192| 14800024 | SQLite: The database file is locked. | 3193| 14800025 | SQLite: A table in the database is locked. | 3194| 14800026 | SQLite: The database is out of memory. | 3195| 14800027 | SQLite: Attempt to write a readonly database. | 3196| 14800028 | SQLite: Some kind of disk I/O error occurred. | 3197| 14800029 | SQLite: The database is full. | 3198| 14800030 | SQLite: Unable to open the database file. | 3199| 14800031 | SQLite: TEXT or BLOB exceeds size limit. | 3200| 14800032 | SQLite: Abort due to constraint violation. | 3201| 14800033 | SQLite: Data type mismatch. | 3202| 14800034 | SQLite: Library used incorrectly. | 3203 3204**示例：** 3205 3206```ts 3207let value1 = "Lisa"; 3208let value2 = 18; 3209let value3 = 100.5; 3210let value4 = new Uint8Array([1, 2, 3]); 3211 3212if (store != undefined) { 3213 (store as relationalStore.RdbStore).beginTransaction(); 3214 const valueBucket: relationalStore.ValuesBucket = { 3215 'NAME': value1, 3216 'AGE': value2, 3217 'SALARY': value3, 3218 'CODES': value4 3219 }; 3220 (store as relationalStore.RdbStore).insert("test", valueBucket); 3221 (store as relationalStore.RdbStore).commit(); 3222} 3223``` 3224 3225## commit<sup>12+</sup> 3226 3227commit(txId : number):Promise<void> 3228 3229提交已执行的SQL语句，跟[beginTrans](#begintrans12)配合使用。 3230 3231该接口仅支持[向量数据库](arkts-apis-data-relationalStore-i.md#storeconfig)使用。 3232 3233**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 3234 3235**参数：** 3236 3237| 参数名 | 类型 | 必填 | 说明 | 3238| -------- | ------------------------------------ | ---- | ------------------------------------------------------------ | 3239| txId | number | 是 | 通过[beginTrans](#begintrans12)获取的事务ID。 | 3240 3241**返回值**： 3242 3243| 类型 | 说明 | 3244| ------------------- | ------------------------- | 3245| Promise<void> | 无返回结果的Promise对象。 | 3246 3247**错误码：** 3248 3249以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。其中，14800011错误码处理可参考[数据库备份与恢复](../../database/data-backup-and-restore.md)。 3250 3251| **错误码ID** | **错误信息** | 3252|-----------| ------------------------------------------------------------ | 3253| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 3254| 14800000 | Inner error. | 3255| 14800011 | Failed to open the database because it is corrupted. | 3256| 14800014 | The RdbStore or ResultSet is already closed. | 3257| 14800015 | The database does not respond. | 3258| 14800021 | SQLite: Generic error. Possible causes: Insert failed or the updated data does not exist. | 3259| 14800022 | SQLite: Callback routine requested an abort. | 3260| 14800023 | SQLite: Access permission denied. | 3261| 14800024 | SQLite: The database file is locked. | 3262| 14800025 | SQLite: A table in the database is locked. | 3263| 14800026 | SQLite: The database is out of memory. | 3264| 14800027 | SQLite: Attempt to write a readonly database. | 3265| 14800028 | SQLite: Some kind of disk I/O error occurred. | 3266| 14800029 | SQLite: The database is full. | 3267| 14800030 | SQLite: Unable to open the database file. | 3268| 14800031 | SQLite: TEXT or BLOB exceeds size limit. | 3269| 14800032 | SQLite: Abort due to constraint violation. | 3270| 14800033 | SQLite: Data type mismatch. | 3271| 14800034 | SQLite: Library used incorrectly. | 3272 3273**示例：** 3274 3275```ts 3276import { BusinessError } from '@kit.BasicServicesKit'; 3277if (store != null) { 3278 let txId: number; 3279 (store as relationalStore.RdbStore).beginTrans().then((temTxId: number) => { 3280 txId = temTxId; 3281 (store as relationalStore.RdbStore).execute("DELETE FROM TEST WHERE age = ? OR age = ?", txId, ["18", "20"]) 3282 .then(() => { 3283 if (txId !== undefined) { 3284 (store as relationalStore.RdbStore).commit(txId); 3285 } 3286 }) 3287 .catch((err: BusinessError) => { 3288 if (txId !== undefined) { 3289 (store as relationalStore.RdbStore).rollback(txId); 3290 } 3291 console.error(`execute sql failed, code is ${err.code},message is ${err.message}`); 3292 }); 3293 }); 3294} 3295``` 3296 3297## rollBack 3298 3299rollBack():void 3300 3301回滚已经执行的SQL语句。 3302此接口不允许嵌套事务，且不支持在多进程或多线程中使用。 3303 3304**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 3305 3306**错误码：** 3307 3308以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。其中，14800011错误码处理可参考[数据库备份与恢复](../../database/data-backup-and-restore.md)。 3309 3310| **错误码ID** | **错误信息** | 3311|-----------| ------------------------------------------------------------ | 3312| 401 | Parameter error. Possible causes: The RdbStore verification failed. | 3313| 14800000 | Inner error. | 3314| 14800011 | Failed to open the database because it is corrupted. | 3315| 14800014 | The RdbStore or ResultSet is already closed. | 3316| 14800015 | The database does not respond. | 3317| 14800021 | SQLite: Generic error. Possible causes: Insert failed or the updated data does not exist. | 3318| 14800022 | SQLite: Callback routine requested an abort. | 3319| 14800023 | SQLite: Access permission denied. | 3320| 14800024 | SQLite: The database file is locked. | 3321| 14800025 | SQLite: A table in the database is locked. | 3322| 14800026 | SQLite: The database is out of memory. | 3323| 14800027 | SQLite: Attempt to write a readonly database. | 3324| 14800028 | SQLite: Some kind of disk I/O error occurred. | 3325| 14800029 | SQLite: The database is full. | 3326| 14800030 | SQLite: Unable to open the database file. | 3327| 14800031 | SQLite: TEXT or BLOB exceeds size limit. | 3328| 14800032 | SQLite: Abort due to constraint violation. | 3329| 14800033 | SQLite: Data type mismatch. | 3330| 14800034 | SQLite: Library used incorrectly. | 3331 3332**示例：** 3333 3334```ts 3335import { BusinessError } from '@kit.BasicServicesKit'; 3336 3337let value1 = "Lisa"; 3338let value2 = 18; 3339let value3 = 100.5; 3340let value4 = new Uint8Array([1, 2, 3]); 3341 3342if (store != undefined) { 3343 try { 3344 (store as relationalStore.RdbStore).beginTransaction(); 3345 const valueBucket: relationalStore.ValuesBucket = { 3346 'NAME': value1, 3347 'AGE': value2, 3348 'SALARY': value3, 3349 'CODES': value4 3350 }; 3351 (store as relationalStore.RdbStore).insert("test", valueBucket); 3352 (store as relationalStore.RdbStore).commit(); 3353 } catch (err) { 3354 let code = (err as BusinessError).code; 3355 let message = (err as BusinessError).message; 3356 console.error(`Transaction failed, code is ${code},message is ${message}`); 3357 (store as relationalStore.RdbStore).rollBack(); 3358 } 3359} 3360``` 3361 3362## rollback<sup>12+</sup> 3363 3364rollback(txId : number):Promise<void> 3365 3366回滚已经执行的SQL语句，跟[beginTrans](#begintrans12)配合使用。 3367 3368该接口仅支持[向量数据库](arkts-apis-data-relationalStore-i.md#storeconfig)使用。 3369 3370**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 3371 3372**参数：** 3373 3374| 参数名 | 类型 | 必填 | 说明 | 3375| -------- | ------------------------------------ | ---- | ------------------------------------------------------------ | 3376| txId | number | 是 | 通过[beginTrans](#begintrans12)获取的事务ID。 | 3377 3378**返回值**： 3379 3380| 类型 | 说明 | 3381| ------------------- | ------------------------- | 3382| Promise<void> | 无返回结果的Promise对象。 | 3383 3384**错误码：** 3385 3386以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。其中，14800011错误码处理可参考[数据库备份与恢复](../../database/data-backup-and-restore.md)。 3387 3388| **错误码ID** | **错误信息** | 3389|-----------| ------------------------------------------------------------ | 3390| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 3391| 14800000 | Inner error. | 3392| 14800011 | Failed to open the database because it is corrupted. | 3393| 14800014 | The RdbStore or ResultSet is already closed. | 3394| 14800015 | The database does not respond. | 3395| 14800021 | SQLite: Generic error. Possible causes: Insert failed or the updated data does not exist. | 3396| 14800022 | SQLite: Callback routine requested an abort. | 3397| 14800023 | SQLite: Access permission denied. | 3398| 14800024 | SQLite: The database file is locked. | 3399| 14800025 | SQLite: A table in the database is locked. | 3400| 14800026 | SQLite: The database is out of memory. | 3401| 14800027 | SQLite: Attempt to write a readonly database. | 3402| 14800028 | SQLite: Some kind of disk I/O error occurred. | 3403| 14800029 | SQLite: The database is full. | 3404| 14800030 | SQLite: Unable to open the database file. | 3405| 14800031 | SQLite: TEXT or BLOB exceeds size limit. | 3406| 14800032 | SQLite: Abort due to constraint violation. | 3407| 14800033 | SQLite: Data type mismatch. | 3408| 14800034 | SQLite: Library used incorrectly. | 3409 3410**示例：** 3411 3412```ts 3413import { BusinessError } from '@kit.BasicServicesKit'; 3414if (store != null) { 3415 let txId: number; 3416 (store as relationalStore.RdbStore).beginTrans().then((temTxId: number) => { 3417 txId = temTxId; 3418 (store as relationalStore.RdbStore).execute("DELETE FROM TEST WHERE age = ? OR age = ?", txId, ["18", "20"]) 3419 .then(() => { 3420 if (txId !== undefined) { 3421 (store as relationalStore.RdbStore).commit(txId); 3422 } 3423 }) 3424 .catch((err: BusinessError) => { 3425 if (txId !== undefined) { 3426 (store as relationalStore.RdbStore).rollback(txId); 3427 } 3428 console.error(`execute sql failed, code is ${err.code},message is ${err.message}`); 3429 }); 3430 }); 3431} 3432``` 3433 3434## backup 3435 3436backup(destName:string, callback: AsyncCallback<void>):void 3437 3438以指定名称备份数据库，使用callback异步回调。 3439 3440该接口支持[向量数据库](arkts-apis-data-relationalStore-i.md#storeconfig)使用。 3441 3442**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 3443 3444**参数：** 3445 3446| 参数名 | 类型 | 必填 | 说明 | 3447| -------- | ------------------------- | ---- | ------------------------ | 3448| destName | string | 是 | 指定数据库的备份文件名。 | 3449| callback | AsyncCallback<void> | 是 | 指定callback回调函数。 | 3450 3451**错误码：** 3452 3453以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。其中，14800011错误码处理可参考[数据库备份与恢复](../../database/data-backup-and-restore.md)。 3454 3455| **错误码ID** | **错误信息** | 3456|-----------| ------------------------------------------------------------ | 3457| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 3458| 14800000 | Inner error. | 3459| 14800010 | Failed to open or delete the database by an invalid database path. | 3460| 14800011 | Failed to open the database because it is corrupted. | 3461| 14800014 | The RdbStore or ResultSet is already closed. | 3462| 14800015 | The database does not respond. | 3463| 14800021 | SQLite: Generic error. Possible causes: Insert failed or the updated data does not exist. | 3464| 14800022 | SQLite: Callback routine requested an abort. | 3465| 14800023 | SQLite: Access permission denied. | 3466| 14800024 | SQLite: The database file is locked. | 3467| 14800025 | SQLite: A table in the database is locked. | 3468| 14800026 | SQLite: The database is out of memory. | 3469| 14800027 | SQLite: Attempt to write a readonly database. | 3470| 14800028 | SQLite: Some kind of disk I/O error occurred. | 3471| 14800029 | SQLite: The database is full. | 3472| 14800030 | SQLite: Unable to open the database file. | 3473| 14800031 | SQLite: TEXT or BLOB exceeds size limit. | 3474| 14800032 | SQLite: Abort due to constraint violation. | 3475| 14800033 | SQLite: Data type mismatch. | 3476| 14800034 | SQLite: Library used incorrectly. | 3477 3478**示例：** 3479 3480```ts 3481if (store != undefined) { 3482 (store as relationalStore.RdbStore).backup("dbBackup.db", (err) => { 3483 if (err) { 3484 console.error(`Backup failed, code is ${err.code},message is ${err.message}`); 3485 return; 3486 } 3487 console.info('Backup success.'); 3488 }); 3489} 3490``` 3491 3492## backup 3493 3494backup(destName:string): Promise<void> 3495 3496以指定名称备份数据库，使用Promise异步回调。 3497 3498该接口支持[向量数据库](arkts-apis-data-relationalStore-i.md#storeconfig)使用。 3499 3500**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 3501 3502**参数：** 3503 3504| 参数名 | 类型 | 必填 | 说明 | 3505| -------- | ------ | ---- | ------------------------ | 3506| destName | string | 是 | 指定数据库的备份文件名。 | 3507 3508**返回值**： 3509 3510| 类型 | 说明 | 3511| ------------------- | ------------------------- | 3512| Promise<void> | 无返回结果的Promise对象。 | 3513 3514**错误码：** 3515 3516以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。其中，14800011错误码处理可参考[数据库备份与恢复](../../database/data-backup-and-restore.md)。 3517 3518| **错误码ID** | **错误信息** | 3519|-----------| ------------------------------------------------------------ | 3520| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 3521| 14800000 | Inner error. | 3522| 14800011 | Failed to open the database because it is corrupted. | 3523| 14800014 | The RdbStore or ResultSet is already closed. | 3524| 14800015 | The database does not respond. | 3525| 14800021 | SQLite: Generic error. Possible causes: Insert failed or the updated data does not exist. | 3526| 14800022 | SQLite: Callback routine requested an abort. | 3527| 14800023 | SQLite: Access permission denied. | 3528| 14800024 | SQLite: The database file is locked. | 3529| 14800025 | SQLite: A table in the database is locked. | 3530| 14800026 | SQLite: The database is out of memory. | 3531| 14800027 | SQLite: Attempt to write a readonly database. | 3532| 14800028 | SQLite: Some kind of disk I/O error occurred. | 3533| 14800029 | SQLite: The database is full. | 3534| 14800030 | SQLite: Unable to open the database file. | 3535| 14800031 | SQLite: TEXT or BLOB exceeds size limit. | 3536| 14800032 | SQLite: Abort due to constraint violation. | 3537| 14800033 | SQLite: Data type mismatch. | 3538| 14800034 | SQLite: Library used incorrectly. | 3539 3540**示例：** 3541 3542```ts 3543import { BusinessError } from '@kit.BasicServicesKit'; 3544 3545if (store != undefined) { 3546 let promiseBackup = (store as relationalStore.RdbStore).backup("dbBackup.db"); 3547 promiseBackup.then(() => { 3548 console.info('Backup success.'); 3549 }).catch((err: BusinessError) => { 3550 console.error(`Backup failed, code is ${err.code},message is ${err.message}`); 3551 }); 3552} 3553``` 3554 3555## restore 3556 3557restore(srcName:string, callback: AsyncCallback<void>):void 3558 3559从指定的数据库备份文件恢复数据库，使用callback异步回调。 3560 3561该接口支持[向量数据库](arkts-apis-data-relationalStore-i.md#storeconfig)使用。 3562 3563**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 3564 3565**参数：** 3566 3567| 参数名 | 类型 | 必填 | 说明 | 3568| -------- | ------------------------- | ---- | ------------------------ | 3569| srcName | string | 是 | 指定数据库的备份文件名。 | 3570| callback | AsyncCallback<void> | 是 | 指定callback回调函数。 | 3571 3572**错误码：** 3573 3574以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。其中，14800011错误码处理可参考[数据库备份与恢复](../../database/data-backup-and-restore.md)。 3575 3576| **错误码ID** | **错误信息** | 3577|-----------| ------------------------------------------------------------ | 3578| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 3579| 14800000 | Inner error. | 3580| 14800011 | Failed to open the database because it is corrupted. | 3581| 14800014 | The RdbStore or ResultSet is already closed. | 3582| 14800015 | The database does not respond. | 3583| 14800021 | SQLite: Generic error. Possible causes: Insert failed or the updated data does not exist. | 3584| 14800022 | SQLite: Callback routine requested an abort. | 3585| 14800023 | SQLite: Access permission denied. | 3586| 14800024 | SQLite: The database file is locked. | 3587| 14800025 | SQLite: A table in the database is locked. | 3588| 14800026 | SQLite: The database is out of memory. | 3589| 14800027 | SQLite: Attempt to write a readonly database. | 3590| 14800028 | SQLite: Some kind of disk I/O error occurred. | 3591| 14800029 | SQLite: The database is full. | 3592| 14800030 | SQLite: Unable to open the database file. | 3593| 14800031 | SQLite: TEXT or BLOB exceeds size limit. | 3594| 14800032 | SQLite: Abort due to constraint violation. | 3595| 14800033 | SQLite: Data type mismatch. | 3596| 14800034 | SQLite: Library used incorrectly. | 3597 3598**示例：** 3599 3600```ts 3601if (store != undefined) { 3602 (store as relationalStore.RdbStore).restore("dbBackup.db", (err) => { 3603 if (err) { 3604 console.error(`Restore failed, code is ${err.code},message is ${err.message}`); 3605 return; 3606 } 3607 console.info('Restore success.'); 3608 }); 3609} 3610``` 3611 3612## restore 3613 3614restore(srcName:string): Promise<void> 3615 3616从指定的数据库备份文件恢复数据库，使用Promise异步回调。 3617 3618该接口支持[向量数据库](arkts-apis-data-relationalStore-i.md#storeconfig)使用。 3619 3620**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 3621 3622**参数：** 3623 3624| 参数名 | 类型 | 必填 | 说明 | 3625| ------- | ------ | ---- | ------------------------ | 3626| srcName | string | 是 | 指定数据库的备份文件名。 | 3627 3628**返回值**： 3629 3630| 类型 | 说明 | 3631| ------------------- | ------------------------- | 3632| Promise<void> | 无返回结果的Promise对象。 | 3633 3634**错误码：** 3635 3636以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。其中，14800011错误码处理可参考[数据库备份与恢复](../../database/data-backup-and-restore.md)。 3637 3638| **错误码ID** | **错误信息** | 3639|-----------| ------------------------------------------------------------ | 3640| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 3641| 14800000 | Inner error. | 3642| 14800011 | Failed to open the database because it is corrupted. | 3643| 14800014 | The RdbStore or ResultSet is already closed. | 3644| 14800015 | The database does not respond. | 3645| 14800021 | SQLite: Generic error. Possible causes: Insert failed or the updated data does not exist. | 3646| 14800022 | SQLite: Callback routine requested an abort. | 3647| 14800023 | SQLite: Access permission denied. | 3648| 14800024 | SQLite: The database file is locked. | 3649| 14800025 | SQLite: A table in the database is locked. | 3650| 14800026 | SQLite: The database is out of memory. | 3651| 14800027 | SQLite: Attempt to write a readonly database. | 3652| 14800028 | SQLite: Some kind of disk I/O error occurred. | 3653| 14800029 | SQLite: The database is full. | 3654| 14800030 | SQLite: Unable to open the database file. | 3655| 14800031 | SQLite: TEXT or BLOB exceeds size limit. | 3656| 14800032 | SQLite: Abort due to constraint violation. | 3657| 14800033 | SQLite: Data type mismatch. | 3658| 14800034 | SQLite: Library used incorrectly. | 3659 3660**示例：** 3661 3662```ts 3663import { BusinessError } from '@kit.BasicServicesKit'; 3664 3665if (store != undefined) { 3666 let promiseRestore = (store as relationalStore.RdbStore).restore("dbBackup.db"); 3667 promiseRestore.then(() => { 3668 console.info('Restore success.'); 3669 }).catch((err: BusinessError) => { 3670 console.error(`Restore failed, code is ${err.code},message is ${err.message}`); 3671 }); 3672} 3673``` 3674 3675## setDistributedTables 3676 3677setDistributedTables(tables: Array<string>, callback: AsyncCallback<void>): void 3678 3679设置分布式数据库表，使用callback异步回调。 3680 3681**需要权限：** ohos.permission.DISTRIBUTED_DATASYNC 3682 3683**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 3684 3685**参数：** 3686 3687| 参数名 | 类型 | 必填 | 说明 | 3688| -------- | ------------------------- | ---- | ---------------------- | 3689| tables | Array<string> | 是 | 要设置的分布式数据库的表名。 | 3690| callback | AsyncCallback<void> | 是 | 指定callback回调函数。 | 3691 3692**错误码：** 3693 3694以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。 3695 3696| **错误码ID** | **错误信息** | 3697|-----------| ------------------------------------------------------------ | 3698| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 3699| 801 | Capability not supported. | 3700| 14800000 | Inner error. | 3701| 14800014 | The RdbStore or ResultSet is already closed. | 3702 3703**示例：** 3704 3705```ts 3706if (store != undefined) { 3707 (store as relationalStore.RdbStore).setDistributedTables(["EMPLOYEE"], (err) => { 3708 if (err) { 3709 console.error(`SetDistributedTables failed, code is ${err.code},message is ${err.message}`); 3710 return; 3711 } 3712 console.info('SetDistributedTables successfully.'); 3713 }); 3714} 3715``` 3716 3717## setDistributedTables 3718 3719 setDistributedTables(tables: Array<string>): Promise<void> 3720 3721设置分布式数据库表，使用Promise异步回调。 3722 3723**需要权限：** ohos.permission.DISTRIBUTED_DATASYNC 3724 3725**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 3726 3727**参数：** 3728 3729| 参数名 | 类型 | 必填 | 说明 | 3730| ------ | ------------------------ | ---- | ------------------------ | 3731| tables | Array<string> | 是 | 要设置的分布式数据库的表名。 | 3732 3733**返回值**： 3734 3735| 类型 | 说明 | 3736| ------------------- | ------------------------- | 3737| Promise<void> | 无返回结果的Promise对象。 | 3738 3739**错误码：** 3740 3741以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。 3742 3743| **错误码ID** | **错误信息** | 3744|-----------| ------------------------------------------------------------ | 3745| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 3746| 801 | Capability not supported. | 3747| 14800000 | Inner error. | 3748| 14800014 | The RdbStore or ResultSet is already closed. | 3749 3750**示例：** 3751 3752```ts 3753import { BusinessError } from '@kit.BasicServicesKit'; 3754 3755if (store != undefined) { 3756 (store as relationalStore.RdbStore).setDistributedTables(["EMPLOYEE"]).then(() => { 3757 console.info('SetDistributedTables successfully.'); 3758 }).catch((err: BusinessError) => { 3759 console.error(`SetDistributedTables failed, code is ${err.code},message is ${err.message}`); 3760 }); 3761} 3762``` 3763 3764## setDistributedTables<sup>10+</sup> 3765 3766setDistributedTables(tables: Array<string>, type: DistributedType, callback: AsyncCallback<void>): void 3767 3768设置分布式数据库表，使用callback异步回调。 3769 3770**需要权限：** ohos.permission.DISTRIBUTED_DATASYNC 3771 3772**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 3773 3774**参数：** 3775 3776| 参数名 | 类型 | 必填 | 说明 | 3777| -------- | ------------------------------------- | ---- | ---------------------------- | 3778| tables | Array<string> | 是 | 要设置的分布式数据库的表名。 | 3779| type | [DistributedType](arkts-apis-data-relationalStore-e.md#distributedtype10) | 是 | 表的分布式类型。 | 3780| callback | AsyncCallback<void> | 是 | 指定callback回调函数。 | 3781 3782**错误码：** 3783 3784以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。 3785 3786| **错误码ID** | **错误信息** | 3787|-----------| ------------------------------------------------------------ | 3788| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 3789| 801 | Capability not supported. | 3790| 14800000 | Inner error. | 3791| 14800014 | The RdbStore or ResultSet is already closed. | 3792| 14800051 | The type of the distributed table does not match. | 3793 3794**示例：** 3795 3796```ts 3797if (store != undefined) { 3798 (store as relationalStore.RdbStore).setDistributedTables(["EMPLOYEE"], relationalStore.DistributedType.DISTRIBUTED_CLOUD, (err) => { 3799 if (err) { 3800 console.error(`SetDistributedTables failed, code is ${err.code},message is ${err.message}`); 3801 return; 3802 } 3803 console.info('SetDistributedTables successfully.'); 3804 }); 3805} 3806``` 3807 3808## setDistributedTables<sup>10+</sup> 3809 3810setDistributedTables(tables: Array<string>, type: DistributedType, config: DistributedConfig, callback: AsyncCallback<void>): void 3811 3812设置分布式数据库表，使用callback异步回调。 3813 3814**需要权限：** ohos.permission.DISTRIBUTED_DATASYNC 3815 3816**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 3817 3818**参数：** 3819 3820| 参数名 | 类型 | 必填 | 说明 | 3821| -------- | ----------------------------------- | --- |-----------------| 3822| tables | Array<string> | 是 | 要设置的分布式数据库的表名。 | 3823| type | [DistributedType](arkts-apis-data-relationalStore-e.md#distributedtype10) | 是 | 表的分布式类型。 | 3824| config | [DistributedConfig](arkts-apis-data-relationalStore-i.md#distributedconfig10) | 是 | 表的分布式配置信息。 | 3825| callback | AsyncCallback<void> | 是 | 指定callback回调函数。 | 3826 3827**错误码：** 3828 3829以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。 3830 3831| **错误码ID** | **错误信息** | 3832|-----------| ------------------------------------------------------------ | 3833| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 3834| 801 | Capability not supported. | 3835| 14800000 | Inner error. | 3836| 14800014 | The RdbStore or ResultSet is already closed. | 3837| 14800051 | The type of the distributed table does not match. | 3838 3839**示例：** 3840 3841```ts 3842if (store != undefined) { 3843 (store as relationalStore.RdbStore).setDistributedTables(["EMPLOYEE"], relationalStore.DistributedType.DISTRIBUTED_CLOUD, { 3844 autoSync: true 3845 }, (err) => { 3846 if (err) { 3847 console.error(`SetDistributedTables failed, code is ${err.code},message is ${err.message}`); 3848 return; 3849 } 3850 console.info('SetDistributedTables successfully.'); 3851 }); 3852} 3853``` 3854 3855## setDistributedTables<sup>10+</sup> 3856 3857 setDistributedTables(tables: Array<string>, type?: DistributedType, config?: DistributedConfig): Promise<void> 3858 3859设置分布式数据库表，使用Promise异步回调。 3860 3861**需要权限：** ohos.permission.DISTRIBUTED_DATASYNC 3862 3863**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 3864 3865**参数：** 3866 3867| 参数名 | 类型 | 必填 | 说明 | 3868| ------ | ----------------------------------------- | ---- |-----------------------------------------------------------------| 3869| tables | Array<string> | 是 | 要设置的分布式数据库的表名。 | 3870| type | [DistributedType](arkts-apis-data-relationalStore-e.md#distributedtype10) | 否 | 表的分布式类型。默认值是relationalStore.DistributedType.DISTRIBUTED_DEVICE。 | 3871| config | [DistributedConfig](arkts-apis-data-relationalStore-i.md#distributedconfig10) | 否 | 表的分布式配置信息。不传入时默认autoSync为false，即只支持手动同步。 | 3872 3873**返回值**： 3874 3875| 类型 | 说明 | 3876| ------------------- | ------------------------- | 3877| Promise<void> | 无返回结果的Promise对象。 | 3878 3879**错误码：** 3880 3881以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。 3882 3883| **错误码ID** | **错误信息** | 3884|-----------| ------------------------------------------------------------ | 3885| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 3886| 801 | Capability not supported. | 3887| 14800000 | Inner error. | 3888| 14800014 | The RdbStore or ResultSet is already closed. | 3889| 14800051 | The type of the distributed table does not match. | 3890 3891**示例：** 3892 3893```ts 3894import { BusinessError } from '@kit.BasicServicesKit'; 3895 3896if (store != undefined) { 3897 (store as relationalStore.RdbStore).setDistributedTables(["EMPLOYEE"], relationalStore.DistributedType.DISTRIBUTED_CLOUD, { 3898 autoSync: true 3899 }).then(() => { 3900 console.info('SetDistributedTables successfully.'); 3901 }).catch((err: BusinessError) => { 3902 console.error(`SetDistributedTables failed, code is ${err.code},message is ${err.message}`); 3903 }); 3904} 3905``` 3906 3907## obtainDistributedTableName 3908 3909obtainDistributedTableName(device: string, table: string, callback: AsyncCallback<string>): void 3910 3911根据远程设备的本地表名获取指定远程设备的分布式表名。在查询远程设备数据库时，需要使用分布式表名，使用callback异步回调。 3912 3913> **说明：** 3914> 3915> 其中device通过调用[deviceManager.getAvailableDeviceListSync](../apis-distributedservice-kit/js-apis-distributedDeviceManager.md#getavailabledevicelistsync)方法得到。 3916 3917**需要权限：** ohos.permission.DISTRIBUTED_DATASYNC 3918 3919**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 3920 3921**参数：** 3922 3923| 参数名 | 类型 | 必填 | 说明 | 3924| -------- | --------------------------- | ---- | ------------------------------------------------------------ | 3925| device | string | 是 | 远程设备ID 。 | 3926| table | string | 是 | 远程设备的本地表名。 | 3927| callback | AsyncCallback<string> | 是 | 指定的callback回调函数。如果操作成功，返回远程设备的分布式表名。 | 3928 3929**错误码：** 3930 3931以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。 3932 3933| **错误码ID** | **错误信息** | 3934|-----------| ------------------------------------------------------------ | 3935| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 3936| 801 | Capability not supported. | 3937| 14800000 | Inner error. | 3938| 14800014 | The RdbStore or ResultSet is already closed. | 3939 3940**示例：** 3941 3942```ts 3943import { distributedDeviceManager } from '@kit.DistributedServiceKit'; 3944import { BusinessError } from '@kit.BasicServicesKit'; 3945 3946let dmInstance: distributedDeviceManager.DeviceManager; 3947let deviceId: string | undefined = undefined; 3948 3949try { 3950 dmInstance = distributedDeviceManager.createDeviceManager("com.example.appdatamgrverify"); 3951 let devices = dmInstance.getAvailableDeviceListSync(); 3952 deviceId = devices[0].networkId; 3953} catch (err) { 3954 let code = (err as BusinessError).code; 3955 let message = (err as BusinessError).message; 3956 console.error("createDeviceManager errCode:" + code + ",errMessage:" + message); 3957} 3958 3959if (store != undefined && deviceId != undefined) { 3960 (store as relationalStore.RdbStore).obtainDistributedTableName(deviceId, "EMPLOYEE", (err, tableName) => { 3961 if (err) { 3962 console.error(`ObtainDistributedTableName failed, code is ${err.code},message is ${err.message}`); 3963 return; 3964 } 3965 console.info(`ObtainDistributedTableName successfully, tableName= ${tableName}`); 3966 }); 3967} 3968``` 3969 3970## obtainDistributedTableName 3971 3972 obtainDistributedTableName(device: string, table: string): Promise<string> 3973 3974根据远程设备的本地表名获取指定远程设备的分布式表名。在查询远程设备数据库时，需要使用分布式表名，使用Promise异步回调。 3975 3976> **说明：** 3977> 3978> 其中device通过调用[deviceManager.getAvailableDeviceListSync](../apis-distributedservice-kit/js-apis-distributedDeviceManager.md#getavailabledevicelistsync)方法得到。 3979 3980**需要权限：** ohos.permission.DISTRIBUTED_DATASYNC 3981 3982**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 3983 3984**参数：** 3985 3986| 参数名 | 类型 | 必填 | 说明 | 3987| ------ | ------ | ---- | -------------------- | 3988| device | string | 是 | 远程设备ID。 | 3989| table | string | 是 | 远程设备的本地表名。 | 3990 3991**返回值**： 3992 3993| 类型 | 说明 | 3994| --------------------- | ----------------------------------------------------- | 3995| Promise<string> | Promise对象。如果操作成功，返回远程设备的分布式表名。 | 3996 3997**错误码：** 3998 3999以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。 4000 4001| **错误码ID** | **错误信息** | 4002|-----------| ------------------------------------------------------------ | 4003| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 4004| 801 | Capability not supported. | 4005| 14800000 | Inner error. | 4006| 14800014 | The RdbStore or ResultSet is already closed. | 4007 4008**示例：** 4009 4010```ts 4011import { distributedDeviceManager } from '@kit.DistributedServiceKit'; 4012import { BusinessError } from '@kit.BasicServicesKit'; 4013 4014let dmInstance: distributedDeviceManager.DeviceManager; 4015let deviceId: string | undefined = undefined; 4016 4017try { 4018 dmInstance = distributedDeviceManager.createDeviceManager("com.example.appdatamgrverify"); 4019 let devices = dmInstance.getAvailableDeviceListSync(); 4020 deviceId = devices[0].networkId; 4021} catch (err) { 4022 let code = (err as BusinessError).code; 4023 let message = (err as BusinessError).message; 4024 console.error("createDeviceManager errCode:" + code + ",errMessage:" + message); 4025} 4026 4027if (store != undefined && deviceId != undefined) { 4028 (store as relationalStore.RdbStore).obtainDistributedTableName(deviceId, "EMPLOYEE").then((tableName: string) => { 4029 console.info(`ObtainDistributedTableName successfully, tableName= ${tableName}`); 4030 }).catch((err: BusinessError) => { 4031 console.error(`ObtainDistributedTableName failed, code is ${err.code},message is ${err.message}`); 4032 }); 4033} 4034``` 4035 4036## sync 4037 4038sync(mode: SyncMode, predicates: RdbPredicates, callback: AsyncCallback<Array<[string, number]>>): void 4039 4040在设备之间同步数据，使用callback异步回调。 4041 4042**需要权限：** ohos.permission.DISTRIBUTED_DATASYNC 4043 4044**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 4045 4046**参数：** 4047 4048| 参数名 | 类型 | 必填 | 说明 | 4049| ---------- | -------------------------------------------------- | ---- | ------------------------------------------------------------ | 4050| mode | [SyncMode](arkts-apis-data-relationalStore-e.md#syncmode) | 是 | 指同步模式。该值可以是relationalStore.SyncMode.SYNC_MODE_PUSH、relationalStore.SyncMode.SYNC_MODE_PULL。 | 4051| predicates | [RdbPredicates](arkts-apis-data-relationalStore-RdbPredicates.md) | 是 | 约束同步数据和设备。 | 4052| callback | AsyncCallback<Array<[string, number]>> | 是 | 指定的callback回调函数，用于向调用者发送同步结果。string：设备ID；number：每个设备同步状态，0表示成功，1表示失败。 | 4053 4054**错误码：** 4055 4056以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。 4057 4058| **错误码ID** | **错误信息** | 4059|-----------| ------------------------------------------------------------ | 4060| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 4061| 801 | Capability not supported. | 4062| 14800000 | Inner error. | 4063| 14800014 | The RdbStore or ResultSet is already closed. | 4064 4065**示例：** 4066 4067```ts 4068import { distributedDeviceManager } from '@kit.DistributedServiceKit'; 4069import { BusinessError } from '@kit.BasicServicesKit'; 4070 4071let dmInstance: distributedDeviceManager.DeviceManager; 4072let deviceIds: Array<string> = []; 4073 4074try { 4075 dmInstance = distributedDeviceManager.createDeviceManager("com.example.appdatamgrverify"); 4076 let devices: Array<distributedDeviceManager.DeviceBasicInfo> = dmInstance.getAvailableDeviceListSync(); 4077 for (let i = 0; i < devices.length; i++) { 4078 deviceIds[i] = devices[i].networkId!; 4079 } 4080} catch (err) { 4081 let code = (err as BusinessError).code; 4082 let message = (err as BusinessError).message; 4083 console.error("createDeviceManager errCode:" + code + ",errMessage:" + message); 4084} 4085 4086let predicates = new relationalStore.RdbPredicates('EMPLOYEE'); 4087predicates.inDevices(deviceIds); 4088if (store != undefined) { 4089 (store as relationalStore.RdbStore).sync(relationalStore.SyncMode.SYNC_MODE_PUSH, predicates, (err, result) => { 4090 if (err) { 4091 console.error(`Sync failed, code is ${err.code},message is ${err.message}`); 4092 return; 4093 } 4094 console.info('Sync done.'); 4095 for (let i = 0; i < result.length; i++) { 4096 console.info(`device= ${result[i][0]}, status= ${result[i][1]}`); 4097 } 4098 }); 4099} 4100``` 4101 4102## sync 4103 4104 sync(mode: SyncMode, predicates: RdbPredicates): Promise<Array<[string, number]>> 4105 4106在设备之间同步数据，使用Promise异步回调。 4107 4108**需要权限：** ohos.permission.DISTRIBUTED_DATASYNC 4109 4110**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 4111 4112**参数：** 4113 4114| 参数名 | 类型 | 必填 | 说明 | 4115| ---------- | ------------------------------------ | ---- | ------------------------------ | 4116| mode | [SyncMode](arkts-apis-data-relationalStore-e.md#syncmode) | 是 | 指同步模式。该值可以是relationalStore.SyncMode.SYNC_MODE_PUSH、relationalStore.SyncMode.SYNC_MODE_PULL。 | 4117| predicates | [RdbPredicates](arkts-apis-data-relationalStore-RdbPredicates.md) | 是 | 约束同步数据和设备。 | 4118 4119**返回值**： 4120 4121| 类型 | 说明 | 4122| -------------------------------------------- | ------------------------------------------------------------ | 4123| Promise<Array<[string, number]>> | Promise对象，用于向调用者发送同步结果。string：设备ID；number：每个设备同步状态，0表示成功，1表示失败。 | 4124 4125**错误码：** 4126 4127以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。 4128 4129| **错误码ID** | **错误信息** | 4130|-----------| ------------------------------------------------------------ | 4131| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 4132| 801 | Capability not supported. | 4133| 14800000 | Inner error. | 4134| 14800014 | The RdbStore or ResultSet is already closed. | 4135 4136**示例：** 4137 4138```ts 4139import { distributedDeviceManager } from '@kit.DistributedServiceKit'; 4140import { BusinessError } from '@kit.BasicServicesKit'; 4141 4142let dmInstance: distributedDeviceManager.DeviceManager; 4143let deviceIds: Array<string> = []; 4144 4145try { 4146 dmInstance = distributedDeviceManager.createDeviceManager("com.example.appdatamgrverify"); 4147 let devices: Array<distributedDeviceManager.DeviceBasicInfo> = dmInstance.getAvailableDeviceListSync(); 4148 for (let i = 0; i < devices.length; i++) { 4149 deviceIds[i] = devices[i].networkId!; 4150 } 4151} catch (err) { 4152 let code = (err as BusinessError).code; 4153 let message = (err as BusinessError).message; 4154 console.error("createDeviceManager errCode:" + code + ",errMessage:" + message); 4155} 4156 4157let predicates = new relationalStore.RdbPredicates('EMPLOYEE'); 4158predicates.inDevices(deviceIds); 4159if (store != undefined) { 4160 (store as relationalStore.RdbStore).sync(relationalStore.SyncMode.SYNC_MODE_PUSH, predicates).then((result: Object[][]) => { 4161 console.info('Sync done.'); 4162 for (let i = 0; i < result.length; i++) { 4163 console.info(`device= ${result[i][0]}, status= ${result[i][1]}`); 4164 } 4165 }).catch((err: BusinessError) => { 4166 console.error(`Sync failed, code is ${err.code},message is ${err.message}`); 4167 }); 4168} 4169``` 4170 4171## cloudSync<sup>10+</sup> 4172 4173cloudSync(mode: SyncMode, progress: Callback<ProgressDetails>, callback: AsyncCallback<void>): void 4174 4175手动执行对所有分布式表的端云同步，使用callback异步回调。使用该接口需要实现云服务功能。 4176 4177**系统能力：** SystemCapability.DistributedDataManager.CloudSync.Client 4178 4179**参数：** 4180 4181| 参数名 | 类型 | 必填 | 说明 | 4182| -------- | ----------------------------------------------------- | ---- | -------------------------------------------------- | 4183| mode | [SyncMode](arkts-apis-data-relationalStore-e.md#syncmode) | 是 | 表示数据库的同步模式。 | 4184| progress | Callback<[ProgressDetails](arkts-apis-data-relationalStore-i.md#progressdetails10)> | 是 | 用来处理数据库同步详细信息的回调函数。 | 4185| callback | AsyncCallback<void> | 是 | 指定的callback回调函数，用于向调用者发送同步结果。 | 4186 4187**错误码：** 4188 4189以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。 4190 4191| **错误码ID** | **错误信息** | 4192|-----------|-------| 4193| 401 | Parameter error. Possible causes: 1. Need 2 - 4 parameter(s). 2. The RdbStore must be not nullptr. 3. The mode must be a SyncMode of cloud. 4. The progress must be a callback type. 5. The callback must be a function. | 4194| 801 | Capability not supported. | 4195| 14800014 | The RdbStore or ResultSet is already closed. | 4196 4197**示例：** 4198 4199```ts 4200if (store != undefined) { 4201 (store as relationalStore.RdbStore).cloudSync(relationalStore.SyncMode.SYNC_MODE_CLOUD_FIRST, (progressDetails) => { 4202 console.info(`Progress: ${progressDetails}`); 4203 }, (err) => { 4204 if (err) { 4205 console.error(`Cloud sync failed, code is ${err.code},message is ${err.message}`); 4206 return; 4207 } 4208 console.info('Cloud sync succeeded'); 4209 }); 4210} 4211``` 4212 4213## cloudSync<sup>10+</sup> 4214 4215cloudSync(mode: SyncMode, progress: Callback<ProgressDetails>): Promise<void> 4216 4217手动执行对所有分布式表的端云同步，使用Promise异步回调。使用该接口需要实现云服务功能。 4218 4219**系统能力：** SystemCapability.DistributedDataManager.CloudSync.Client 4220 4221**参数：** 4222 4223| 参数名 | 类型 | 必填 | 说明 | 4224| -------- | ----------------------------------------------------- | ---- | -------------------------------------- | 4225| mode | [SyncMode](arkts-apis-data-relationalStore-e.md#syncmode) | 是 | 表示数据库的同步模式。 | 4226| progress | Callback<[ProgressDetails](arkts-apis-data-relationalStore-i.md#progressdetails10)> | 是 | 用来处理数据库同步详细信息的回调函数。 | 4227 4228**返回值**： 4229 4230| 类型 | 说明 | 4231| ------------------- | --------------------------------------- | 4232| Promise<void> | Promise对象，用于向调用者发送同步结果。 | 4233 4234**错误码：** 4235 4236以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。 4237 4238| **错误码ID** | **错误信息** | 4239|-----------|------------------| 4240| 401 | Parameter error. Possible causes: 1. Need 2 - 4 parameter(s). 2. The RdbStore must be not nullptr. 3. The mode must be a SyncMode of cloud. 4. The progress must be a callback type. | 4241| 801 | Capability not supported. | 4242| 14800014 | The RdbStore or ResultSet is already closed. | 4243 4244**示例：** 4245 4246```ts 4247import { BusinessError } from '@kit.BasicServicesKit'; 4248 4249if (store != undefined) { 4250 (store as relationalStore.RdbStore).cloudSync(relationalStore.SyncMode.SYNC_MODE_CLOUD_FIRST, (progressDetail: relationalStore.ProgressDetails) => { 4251 console.info(`progress: ${progressDetail}`); 4252 }).then(() => { 4253 console.info('Cloud sync succeeded'); 4254 }).catch((err: BusinessError) => { 4255 console.error(`cloudSync failed, code is ${err.code},message is ${err.message}`); 4256 }); 4257} 4258``` 4259 4260## cloudSync<sup>10+</sup> 4261 4262cloudSync(mode: SyncMode, tables: string[], progress: Callback<ProgressDetails>, callback: AsyncCallback<void>): void 4263 4264手动执行对指定表的端云同步，使用callback异步回调。使用该接口需要实现云服务功能。 4265 4266**系统能力：** SystemCapability.DistributedDataManager.CloudSync.Client 4267 4268**参数：** 4269 4270| 参数名 | 类型 | 必填 | 说明 | 4271| -------- | ----------------------------------------------------- | ---- | -------------------------------------------------- | 4272| mode | [SyncMode](arkts-apis-data-relationalStore-e.md#syncmode) | 是 | 表示数据库的同步模式。 | 4273| tables | string[] | 是 | 指定同步的表名。 | 4274| progress | Callback<[ProgressDetails](arkts-apis-data-relationalStore-i.md#progressdetails10)> | 是 | 用来处理数据库同步详细信息的回调函数。 | 4275| callback | AsyncCallback<void> | 是 | 指定的callback回调函数，用于向调用者发送同步结果。 | 4276 4277**错误码：** 4278 4279以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。 4280 4281| **错误码ID** | **错误信息** | 4282|-----------|-------| 4283| 401 | Parameter error. Possible causes: 1. Need 2 - 4 parameter(s). 2. The RdbStore must be not nullptr. 3. The mode must be a SyncMode of cloud. 4. The tablesNames must be not empty. 5. The progress must be a callback type. 6.The callback must be a function.| 4284| 801 | Capability not supported. | 4285| 14800014 | The RdbStore or ResultSet is already closed. | 4286 4287**示例：** 4288 4289```ts 4290const tables = ["table1", "table2"]; 4291 4292if (store != undefined) { 4293 (store as relationalStore.RdbStore).cloudSync(relationalStore.SyncMode.SYNC_MODE_CLOUD_FIRST, tables, (progressDetail: relationalStore.ProgressDetails) => { 4294 console.info(`Progress: ${progressDetail}`); 4295 }, (err) => { 4296 if (err) { 4297 console.error(`Cloud sync failed, code is ${err.code},message is ${err.message}`); 4298 return; 4299 } 4300 console.info('Cloud sync succeeded'); 4301 }); 4302}; 4303``` 4304 4305## cloudSync<sup>10+</sup> 4306 4307cloudSync(mode: SyncMode, tables: string[], progress: Callback<ProgressDetails>): Promise<void> 4308 4309手动执行对指定表的端云同步，使用Promise异步回调。使用该接口需要实现云服务功能。 4310 4311**系统能力：** SystemCapability.DistributedDataManager.CloudSync.Client 4312 4313**参数：** 4314 4315| 参数名 | 类型 | 必填 | 说明 | 4316| -------- | ----------------------------------------------------- | ---- | -------------------------------------- | 4317| mode | [SyncMode](arkts-apis-data-relationalStore-e.md#syncmode) | 是 | 表示数据库的同步模式。 | 4318| tables | string[] | 是 | 指定同步的表名。 | 4319| progress | Callback<[ProgressDetails](arkts-apis-data-relationalStore-i.md#progressdetails10)> | 是 | 用来处理数据库同步详细信息的回调函数。 | 4320 4321**返回值**： 4322 4323| 类型 | 说明 | 4324| ------------------- | --------------------------------------- | 4325| Promise<void> | Promise对象，用于向调用者发送同步结果。 | 4326 4327**错误码：** 4328 4329以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。 4330 4331| **错误码ID** | **错误信息** | 4332|-----------|---------------| 4333| 401 | Parameter error. Possible causes: 1. Need 2 - 4 parameter(s). 2. The RdbStore must be not nullptr. 3. The mode must be a SyncMode of cloud. 4. The tablesNames must be not empty. 5. The progress must be a callback type | 4334| 801 | Capability not supported. | 4335| 14800014 | The RdbStore or ResultSet is already closed. | 4336 4337**示例：** 4338 4339```ts 4340import { BusinessError } from '@kit.BasicServicesKit'; 4341 4342const tables = ["table1", "table2"]; 4343 4344if (store != undefined) { 4345 (store as relationalStore.RdbStore).cloudSync(relationalStore.SyncMode.SYNC_MODE_CLOUD_FIRST, tables, (progressDetail: relationalStore.ProgressDetails) => { 4346 console.info(`progress: ${progressDetail}`); 4347 }).then(() => { 4348 console.info('Cloud sync succeeded'); 4349 }).catch((err: BusinessError) => { 4350 console.error(`cloudSync failed, code is ${err.code},message is ${err.message}`); 4351 }); 4352}; 4353``` 4354 4355## on('dataChange') 4356 4357on(event: 'dataChange', type: SubscribeType, observer: Callback<Array<string>>): void 4358 4359注册数据库的数据变更的事件监听。当分布式数据库中的数据发生更改时，将调用回调。 4360 4361**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 4362 4363**参数：** 4364 4365| 参数名 | 类型 | 必填 | 说明 | 4366| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 4367| event | string | 是 | 取值为'dataChange'，表示数据更改。 | 4368| type | [SubscribeType](arkts-apis-data-relationalStore-e.md#subscribetype) | 是 | 订阅类型。 | 4369| observer | Callback<Array<string>> | 是 | 指分布式数据库中数据更改事件的观察者。Array<string>为数据库中的数据发生改变的对端设备ID。 | 4370 4371**错误码：** 4372 4373以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。 4374 4375| **错误码ID** | **错误信息** | 4376|-----------|-------------| 4377| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 4378| 801 | Capability not supported. | 4379| 14800014 | The RdbStore or ResultSet is already closed. | 4380 4381**示例：** 4382 4383```ts 4384import { BusinessError } from '@kit.BasicServicesKit'; 4385 4386let storeObserver = (devices: Array<string>) => { 4387 if (devices !== undefined) { 4388 for (let i = 0; i < devices.length; i++) { 4389 console.info(`device= ${devices[i]} data changed`); 4390 } 4391 } 4392}; 4393 4394try { 4395 if (store != undefined) { 4396 (store as relationalStore.RdbStore).on('dataChange', relationalStore.SubscribeType.SUBSCRIBE_TYPE_REMOTE, storeObserver); 4397 } 4398} catch (err) { 4399 let code = (err as BusinessError).code; 4400 let message = (err as BusinessError).message; 4401 console.error(`Register observer failed, code is ${code},message is ${message}`); 4402} 4403``` 4404 4405## on('dataChange')<sup>10+</sup> 4406 4407on(event: 'dataChange', type: SubscribeType, observer: Callback<Array<string>>\| Callback<Array<ChangeInfo>>): void 4408 4409注册数据库的数据变更的事件监听。当分布式数据库或本地数据库中的数据发生更改时，将调用回调。 4410 4411**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 4412 4413**参数：** 4414 4415| 参数名 | 类型 | 必填 | 说明 | 4416| -------- | ----------------------------------- | ---- | ------------------------------------------- | 4417| event | string | 是 | 取值为'dataChange'，表示数据更改。 | 4418| type | [SubscribeType](arkts-apis-data-relationalStore-e.md#subscribetype) | 是 | 订阅类型。 | 4419| observer | Callback<Array<string>> \| Callback<Array<[ChangeInfo](arkts-apis-data-relationalStore-i.md#changeinfo10)>> | 是 | 回调函数。<br>当type为SUBSCRIBE_TYPE_REMOTE，observer类型需为Callback<Array<string>>，其中Array<string>为数据库中的数据发生改变的对端设备ID。<br>当type为SUBSCRIBE_TYPE_CLOUD，observer类型需为Callback<Array<string>>，其中Array<string>为数据库中的数据发生改变的云端账号。<br>当type为SUBSCRIBE_TYPE_CLOUD_DETAILS，observer类型需为Callback<Array<ChangeInfo>>，其中Array<ChangeInfo>为数据库端云同步过程的详情。<br>当type为SUBSCRIBE_TYPE_LOCAL_DETAILS，observer类型需为Callback<Array<ChangeInfo>>，其中Array<ChangeInfo>为本地数据库中的数据更改的详情。 | 4420 4421**错误码：** 4422 4423以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。 4424 4425| **错误码ID** | **错误信息** | 4426|-----------|-------------| 4427| 202 | Permission verification failed, application which is not a system application uses system API. | 4428| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 4429| 801 | Capability not supported. | 4430| 14800014 | The RdbStore or ResultSet is already closed. | 4431 4432**示例1：type为SUBSCRIBE_TYPE_REMOTE** 4433 4434```ts 4435import { BusinessError } from '@kit.BasicServicesKit'; 4436 4437let storeObserver = (devices: Array<string>) => { 4438 if (devices !== undefined) { 4439 for (let i = 0; i < devices.length; i++) { 4440 console.info(`device= ${devices[i]} data changed`); 4441 } 4442 } 4443}; 4444 4445try { 4446 if (store != undefined) { 4447 (store as relationalStore.RdbStore).on('dataChange', relationalStore.SubscribeType.SUBSCRIBE_TYPE_REMOTE, storeObserver); 4448 } 4449} catch (err) { 4450 let code = (err as BusinessError).code; 4451 let message = (err as BusinessError).message; 4452 console.error(`Register observer failed, code is ${code},message is ${message}`); 4453} 4454``` 4455 4456**示例2：type为SUBSCRIBE_TYPE_LOCAL_DETAILS** 4457 4458```ts 4459import { BusinessError } from '@kit.BasicServicesKit'; 4460 4461let changeInfos = (changeInfos: Array<relationalStore.ChangeInfo>) => { 4462 for (let i = 0; i < changeInfos.length; i++) { 4463 console.info(`changeInfos = ${JSON.stringify(changeInfos[i])}`); 4464 } 4465}; 4466 4467try { 4468 if (store != undefined) { 4469 (store as relationalStore.RdbStore).on('dataChange', relationalStore.SubscribeType.SUBSCRIBE_TYPE_LOCAL_DETAILS, changeInfos); 4470 } 4471} catch (err) { 4472 let code = (err as BusinessError).code; 4473 let message = (err as BusinessError).message; 4474 console.error(`on dataChange fail, code is ${code},message is ${message}`); 4475} 4476 4477let value1 = "Lisa"; 4478let value2 = 18; 4479let value3 = 100.5; 4480let value4 = new Uint8Array([1, 2, 3]); 4481 4482try { 4483 const valueBucket: relationalStore.ValuesBucket = { 4484 'name': value1, 4485 'age': value2, 4486 'salary': value3, 4487 'blobType': value4 4488 }; 4489 4490 if (store != undefined) { 4491 (store as relationalStore.RdbStore).insert('test', valueBucket); 4492 } 4493} catch (err) { 4494 let code = (err as BusinessError).code; 4495 let message = (err as BusinessError).message; 4496 console.error(`insert fail, code is ${code},message is ${message}`); 4497} 4498``` 4499 4500## on<sup>10+</sup> 4501 4502on(event: string, interProcess: boolean, observer: Callback\<void>): void 4503 4504注册数据库的进程内或者进程间事件监听。当调用[emit](#emit10)接口时，将调用回调。 4505 4506**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 4507 4508**参数：** 4509 4510| 参数名 | 类型 | 必填 | 说明 | 4511| ------------ | --------------- | ---- | ------------------------------------------------------------ | 4512| event | string | 是 | 订阅事件名称，与emit接口触发事件时的名称一致。 | 4513| interProcess | boolean | 是 | 指定是进程间还是本进程订阅。<br/> true：进程间。<br/> false：本进程。 | 4514| observer | Callback\<void> | 是 | 回调函数。 | 4515 4516**错误码：** 4517 4518以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。 4519 4520| **错误码ID** | **错误信息** | 4521|-----------|-------------| 4522| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 4523| 801 | Capability not supported. | 4524| 14800000 | Inner error. | 4525| 14800014 | The RdbStore or ResultSet is already closed. | 4526| 14800050 | Failed to obtain the subscription service. | 4527 4528**示例：** 4529 4530```ts 4531import { BusinessError } from '@kit.BasicServicesKit'; 4532 4533let storeObserver = () => { 4534 console.info(`storeObserver`); 4535}; 4536 4537try { 4538 if (store != undefined) { 4539 (store as relationalStore.RdbStore).on('storeObserver', false, storeObserver); 4540 } 4541} catch (err) { 4542 let code = (err as BusinessError).code; 4543 let message = (err as BusinessError).message; 4544 console.error(`Register observer failed, code is ${code},message is ${message}`); 4545} 4546``` 4547 4548## on('autoSyncProgress')<sup>11+</sup> 4549 4550on(event: 'autoSyncProgress', progress: Callback<ProgressDetails>): void 4551 4552在已打开端云同步，并且网络状态正常的条件下，注册自动同步进度通知，自动同步进行时调用回调。 4553 4554**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 4555 4556**参数：** 4557 4558| 参数名 | 类型 | 必填 | 说明 | 4559| ------------ |---------------------------------| ---- |-----------------------------------| 4560| event | string | 是 | 取值为'autoSyncProgress'，表示自动同步进度通知。 | 4561| progress | Callback<[ProgressDetails](arkts-apis-data-relationalStore-i.md#progressdetails10)> | 是 | 回调函数。 | 4562 4563**错误码：** 4564 4565以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。 4566 4567| **错误码ID** | **错误信息** | 4568|-----------|--------| 4569| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 4570| 801 | Capability not supported. | 4571| 14800014 | The RdbStore or ResultSet is already closed. | 4572 4573**示例：** 4574 4575```ts 4576import { BusinessError } from '@kit.BasicServicesKit'; 4577 4578let progressDetail = (progressDetail: relationalStore.ProgressDetails) => { 4579 console.info(`progress: ${progressDetail}`); 4580}; 4581 4582try { 4583 if (store != undefined) { 4584 (store as relationalStore.RdbStore).on('autoSyncProgress', progressDetail); 4585 } 4586} catch (err) { 4587 let code = (err as BusinessError).code; 4588 let message = (err as BusinessError).message; 4589 console.error(`Register observer failed, code is ${code},message is ${message}`); 4590} 4591``` 4592 4593## on('statistics')<sup>12+</sup> 4594 4595on(event: 'statistics', observer: Callback<SqlExecutionInfo>): void 4596 4597订阅SQL统计信息。 4598 4599**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 4600 4601**参数：** 4602 4603| 参数名 | 类型 | 必填 | 说明 | 4604| ------------ |---------------------------------| ---- |-----------------------------------| 4605| event | string | 是 | 订阅事件名称，取值为'statistics'，表示sql执行时间的统计。 | 4606| observer | Callback<[SqlExecutionInfo](arkts-apis-data-relationalStore-i.md#sqlexecutioninfo12)> | 是 | 回调函数。用于返回数据库中SQL执行时间的统计信息。 | 4607 4608**错误码：** 4609 4610以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。 4611 4612| **错误码ID** | **错误信息** | 4613|-----------|--------| 4614| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 4615| 801 | Capability not supported. | 4616| 14800000 | Inner error. | 4617| 14800014 | The RdbStore or ResultSet is already closed. | 4618 4619**示例：** 4620 4621```ts 4622import { BusinessError } from '@kit.BasicServicesKit'; 4623 4624let sqlExecutionInfo = (sqlExecutionInfo: relationalStore.SqlExecutionInfo) => { 4625 console.info(`sql: ${sqlExecutionInfo.sql[0]}`); 4626 console.info(`totalTime: ${sqlExecutionInfo.totalTime}`); 4627 console.info(`waitTime: ${sqlExecutionInfo.waitTime}`); 4628 console.info(`prepareTime: ${sqlExecutionInfo.prepareTime}`); 4629 console.info(`executeTime: ${sqlExecutionInfo.executeTime}`); 4630}; 4631 4632try { 4633 if (store != undefined) { 4634 (store as relationalStore.RdbStore).on('statistics', sqlExecutionInfo); 4635 } 4636} catch (err) { 4637 let code = (err as BusinessError).code; 4638 let message = (err as BusinessError).message; 4639 console.error(`Register observer failed, code is ${code},message is ${message}`); 4640} 4641 4642try { 4643 let value1 = "Lisa"; 4644 let value2 = 18; 4645 let value3 = 100.5; 4646 let value4 = new Uint8Array([1, 2, 3, 4, 5]); 4647 4648 const valueBucket: relationalStore.ValuesBucket = { 4649 'NAME': value1, 4650 'AGE': value2, 4651 'SALARY': value3, 4652 'CODES': value4 4653 }; 4654 if (store != undefined) { 4655 (store as relationalStore.RdbStore).insert('test', valueBucket); 4656 } 4657} catch (err) { 4658 console.error(`insert fail, code:${err.code}, message: ${err.message}`); 4659} 4660``` 4661 4662## on('sqliteErrorOccurred')<sup>20+</sup> 4663 4664on(event: 'sqliteErrorOccurred', observer: Callback<ExceptionMessage>): void 4665 4666记录执行SQL语句时的异常日志。 4667 4668**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 4669 4670**参数：** 4671 4672| 参数名 | 类型 | 必填 | 说明 | 4673| ------------ |---------------------------------| ---- |-----------------------------------| 4674| event | string | 是 | 订阅事件名称，取值为'sqliteErrorOccurred'，记录SQL语句执行过程中的错误信息。 | 4675| observer | Callback<[ExceptionMessage](arkts-apis-data-relationalStore-i.md#exceptionmessage20)> | 是 | 回调函数。用于返回SQL执行时出现的异常信息。 | 4676 4677**错误码：** 4678 4679以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。 4680 4681| **错误码ID** | **错误信息** | 4682|-----------|--------| 4683| 801 | Capability not supported. | 4684| 14800014 | The RdbStore or ResultSet is already closed. | 4685 4686**示例：** 4687 4688```ts 4689import { BusinessError } from '@kit.BasicServicesKit'; 4690 4691try { 4692 if (store != undefined) { 4693 store.on('sqliteErrorOccurred', exceptionMessage => { 4694 let sqliteCode = exceptionMessage.code; 4695 let sqliteMessage = exceptionMessage.message; 4696 let errSQL = exceptionMessage.sql; 4697 console.error(`error log is ${sqliteCode}, errMessage is ${sqliteMessage}, errSQL is ${errSQL}`); 4698 }) 4699 } 4700} catch (err) { 4701 let code = (err as BusinessError).code; 4702 let message = (err as BusinessError).message; 4703 console.error(`Register observer failed, code is ${code},message is ${message}`); 4704} 4705const CREATE_TABLE_TEST = "CREATE TABLE IF NOT EXISTS test (" + "id INTEGER PRIMARY KEY AUTOINCREMENT, " + 4706 "name TEXT NOT NULL, " + "age INTEGER, " + "salary REAL)"; 4707try { 4708 let value = new Uint8Array([1, 2, 3, 4, 5]); 4709 const valueBucket: relationalStore.ValuesBucket = { 4710 'name': "Lisa", 4711 'age': 18, 4712 'salary': 100.5, 4713 'codes': value, 4714 }; 4715 await store.executeSql(CREATE_TABLE_TEST); 4716 if (store != undefined) { 4717 (store as relationalStore.RdbStore).insert('test', valueBucket); 4718 } 4719} catch (err) { 4720 console.error(`Insert fail, code:${err.code}, message: ${err.message}`); 4721} 4722 4723``` 4724 4725## on('perfStat')<sup>20+</sup> 4726 4727on(event: 'perfStat', observer: Callback<SqlExecutionInfo>): void 4728 4729订阅SQL统计信息。使用[createTransaction](#createtransaction14)创建的事务进行相关操作（[Transaction](arkts-apis-data-relationalStore-Transaction.md)），只会在事务结束（COMMIT/ROLLBACK）时通知一次统计信息。 4730 4731**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 4732 4733**参数：** 4734 4735| 参数名 | 类型 | 必填 | 说明 | 4736| ------------ |---------------------------------| ---- |-----------------------------------| 4737| event | string | 是 | 订阅事件名称，取值为'perfStat'，统计执行SQL的时间。 | 4738| observer | Callback<[SqlExecutionInfo](arkts-apis-data-relationalStore-i.md#sqlexecutioninfo12)> | 是 | 回调函数。用于返回数据库执行SQL的时间。 | 4739 4740**错误码：** 4741 4742以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。 4743 4744| **错误码ID** | **错误信息** | 4745|-----------|--------| 4746| 801 | Capability not supported. | 4747| 14800014 | The RdbStore or ResultSet is already closed. | 4748 4749**示例：** 4750 4751```ts 4752import { BusinessError } from '@kit.BasicServicesKit'; 4753 4754let sqlExecutionInfo = (sqlExecutionInfo: relationalStore.SqlExecutionInfo) => { 4755 console.info(`sql: ${sqlExecutionInfo.sql[0]}`); 4756 console.info(`totalTime: ${sqlExecutionInfo.totalTime}`); 4757 console.info(`waitTime: ${sqlExecutionInfo.waitTime}`); 4758 console.info(`prepareTime: ${sqlExecutionInfo.prepareTime}`); 4759 console.info(`executeTime: ${sqlExecutionInfo.executeTime}`); 4760}; 4761 4762try { 4763 if (store != undefined) { 4764 (store as relationalStore.RdbStore).on('perfStat', sqlExecutionInfo); 4765 } 4766} catch (err) { 4767 let code = (err as BusinessError).code; 4768 let message = (err as BusinessError).message; 4769 console.error(`Register observer failed, code is ${code},message is ${message}`); 4770} 4771 4772try { 4773 let value1 = "Lisa"; 4774 let value2 = 18; 4775 let value3 = 100.5; 4776 let value4 = new Uint8Array([1, 2, 3, 4, 5]); 4777 4778 const valueBucket: relationalStore.ValuesBucket = { 4779 'NAME': value1, 4780 'AGE': value2, 4781 'SALARY': value3, 4782 'CODES': value4 4783 }; 4784 if (store != undefined) { 4785 (store as relationalStore.RdbStore).insert('test', valueBucket); 4786 } 4787} catch (err) { 4788 console.error(`insert fail, code:${err.code}, message: ${err.message}`); 4789} 4790``` 4791 4792## off('dataChange') 4793 4794off(event:'dataChange', type: SubscribeType, observer: Callback<Array<string>>): void 4795 4796取消数据变更的事件监听。 4797 4798**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 4799 4800**参数：** 4801 4802| 参数名 | 类型 | 必填 | 说明 | 4803| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 4804| event | string | 是 | 取值为'dataChange'，表示数据更改。 | 4805| type | [SubscribeType](arkts-apis-data-relationalStore-e.md#subscribetype) | 是 | 订阅类型。 | 4806| observer | Callback<Array<string>> | 是 | 指已注册的数据更改观察者。Array<string>为数据库中的数据发生改变的对端设备ID。 | 4807 4808**错误码：** 4809 4810以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。 4811 4812| **错误码ID** | **错误信息** | 4813|-----------|-------------| 4814| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 4815| 801 | Capability not supported. | 4816| 14800014 | The RdbStore or ResultSet is already closed. | 4817 4818**示例：** 4819 4820```ts 4821import { BusinessError } from '@kit.BasicServicesKit'; 4822 4823let storeObserver = (devices: Array<string>) => { 4824 if (devices !== undefined) { 4825 for (let i = 0; i < devices.length; i++) { 4826 console.info(`device= ${devices[i]} data changed`); 4827 } 4828 } 4829}; 4830 4831try { 4832 if (store != undefined) { 4833 // 此处不能使用Lambda表达式 4834 (store as relationalStore.RdbStore).on('dataChange', relationalStore.SubscribeType.SUBSCRIBE_TYPE_REMOTE, storeObserver); 4835 } 4836} catch (err) { 4837 let code = (err as BusinessError).code; 4838 let message = (err as BusinessError).message; 4839 console.error(`Register observer failed, code is ${code},message is ${message}`); 4840} 4841 4842try { 4843 if (store != undefined) { 4844 (store as relationalStore.RdbStore).off('dataChange', relationalStore.SubscribeType.SUBSCRIBE_TYPE_REMOTE, storeObserver); 4845 } 4846} catch (err) { 4847 let code = (err as BusinessError).code; 4848 let message = (err as BusinessError).message; 4849 console.error(`Unregister observer failed, code is ${code},message is ${message}`); 4850} 4851``` 4852 4853## off('dataChange')<sup>10+</sup> 4854 4855off(event:'dataChange', type: SubscribeType, observer?: Callback<Array<string>>\| Callback<Array<ChangeInfo>>): void 4856 4857取消数据变更的事件监听。 4858 4859**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 4860 4861**参数：** 4862 4863| 参数名 | 类型 | 必填 | 说明 | 4864| -------- | ---------------------------------- | ---- | ------------------------------------------ | 4865| event | string | 是 | 取值为'dataChange'，表示数据更改。 | 4866| type | [SubscribeType](arkts-apis-data-relationalStore-e.md#subscribetype) | 是 | 订阅类型。 | 4867| observer | Callback<Array<string>>\| Callback<Array<[ChangeInfo](arkts-apis-data-relationalStore-i.md#changeinfo10)>> | 否 | 回调函数。<br/>当type为SUBSCRIBE_TYPE_REMOTE，observer类型需为Callback<Array<string>>，其中Array<string>为数据库中的数据发生改变的对端设备ID。<br/> 当type为SUBSCRIBE_TYPE_CLOUD，observer类型需为Callback<Array<string>>，其中Array<string>为数据库中的数据发生改变的云端账号。<br/> 当type为SUBSCRIBE_TYPE_CLOUD_DETAILS，observer类型需为Callback<Array<ChangeInfo>>，其中Array<ChangeInfo>为数据库端云同步过程的详情。<br>当type为SUBSCRIBE_TYPE_LOCAL_DETAILS，observer类型需为Callback<Array<ChangeInfo>>，其中Array<ChangeInfo>为本地数据库中的数据更改的详情。<br>当observer没有传入时，表示取消当前type类型下所有数据变更的事件监听。 | 4868 4869**错误码：** 4870 4871以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。 4872 4873| **错误码ID** | **错误信息** | 4874|-----------|-------------| 4875| 202 | Permission verification failed, application which is not a system application uses system API. | 4876| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 4877| 801 | Capability not supported. | 4878| 14800014 | The RdbStore or ResultSet is already closed. | 4879 4880**示例：** 4881 4882```ts 4883import { BusinessError } from '@kit.BasicServicesKit'; 4884 4885let storeObserver = (devices: Array<string>) => { 4886 if (devices !== undefined) { 4887 for (let i = 0; i < devices.length; i++) { 4888 console.info(`device= ${devices[i]} data changed`); 4889 } 4890 } 4891}; 4892 4893try { 4894 if (store != undefined) { 4895 (store as relationalStore.RdbStore).on('dataChange', relationalStore.SubscribeType.SUBSCRIBE_TYPE_REMOTE, storeObserver); 4896 } 4897} catch (err) { 4898 let code = (err as BusinessError).code; 4899 let message = (err as BusinessError).message; 4900 console.error(`Register observer failed, code is ${code},message is ${message}`); 4901} 4902 4903try { 4904 if (store != undefined) { 4905 (store as relationalStore.RdbStore).off('dataChange', relationalStore.SubscribeType.SUBSCRIBE_TYPE_REMOTE, storeObserver); 4906 } 4907} catch (err) { 4908 let code = (err as BusinessError).code; 4909 let message = (err as BusinessError).message; 4910 console.error(`Unregister observer failed, code is ${code},message is ${message}`); 4911} 4912``` 4913 4914## off<sup>10+</sup> 4915 4916off(event: string, interProcess: boolean, observer?: Callback\<void>): void 4917 4918取消数据变更的事件监听。 4919 4920**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 4921 4922**参数：** 4923 4924| 参数名 | 类型 | 必填 | 说明 | 4925| ------------ | --------------- | ---- | ------------------------------------------------------------ | 4926| event | string | 是 | 取消订阅事件名称。事件名称与on接口调用时订阅事件的名称一致。 | 4927| interProcess | boolean | 是 | 指定是进程间还是本进程取消订阅。<br/> true：进程间。<br/> false：本进程。 | 4928| observer | Callback\<void> | 否 | 该参数存在，则取消指定Callback监听回调，否则取消该event事件的所有监听回调。 | 4929 4930**错误码：** 4931 4932以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。 4933 4934| **错误码ID** | **错误信息** | 4935| ------------ | -------------------------------------- | 4936| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 4937| 801 | Capability not supported. | 4938| 14800000 | Inner error. | 4939| 14800014 | The RdbStore or ResultSet is already closed. | 4940| 14800050 | Failed to obtain the subscription service. | 4941 4942**示例：** 4943 4944```ts 4945import { BusinessError } from '@kit.BasicServicesKit'; 4946 4947let storeObserver = () => { 4948 console.info(`storeObserver`); 4949}; 4950 4951try { 4952 if (store != undefined) { 4953 (store as relationalStore.RdbStore).on('storeObserver', false, storeObserver); 4954 } 4955} catch (err) { 4956 let code = (err as BusinessError).code; 4957 let message = (err as BusinessError).message; 4958 console.error(`Register observer failed, code is ${code},message is ${message}`); 4959} 4960 4961try { 4962 if (store != undefined) { 4963 (store as relationalStore.RdbStore).off('storeObserver', false, storeObserver); 4964 } 4965} catch (err) { 4966 let code = (err as BusinessError).code; 4967 let message = (err as BusinessError).message; 4968 console.error(`Unregister observer failed, code is ${code},message is ${message}`); 4969} 4970``` 4971 4972## off('autoSyncProgress')<sup>11+</sup> 4973 4974off(event: 'autoSyncProgress', progress?: Callback<ProgressDetails>): void 4975 4976取消订阅自动同步进度的通知。 4977 4978**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 4979 4980**参数：** 4981 4982| 参数名 | 类型 | 必填 | 说明 | 4983| ------------ |---------------------------------| ---- |------------------------------------------------------------------| 4984| event | string | 是 | 取值为'autoSyncProgress'，表示自动同步进度通知。 | 4985| progress | Callback<[ProgressDetails](arkts-apis-data-relationalStore-i.md#progressdetails10)> | 否 | 指已注册的自动同步进度观察者。该参数存在，则取消订阅指定回调，该参数为null或undefined或不存在，则取消订阅所有回调。 | 4986 4987**错误码：** 4988 4989以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。 4990 4991| **错误码ID** | **错误信息** | 4992| ------------ |--------------------| 4993| 401 | Parameter error. Possible causes: 1. Need 1 - 3 parameter(s)! 2. The RdbStore must be valid. 3. The event must be a not empty string. 4. The progress must be function. | 4994| 801 | Capability not supported. | 4995| 14800014 | The RdbStore or ResultSet is already closed. | 4996 4997**示例：** 4998 4999```ts 5000import { BusinessError } from '@kit.BasicServicesKit'; 5001 5002let progressDetail = (progressDetail: relationalStore.ProgressDetails) => { 5003 console.info(`progress: ${progressDetail}`); 5004}; 5005 5006try { 5007 if (store != undefined) { 5008 (store as relationalStore.RdbStore).on('autoSyncProgress', progressDetail); 5009 } 5010} catch (err) { 5011 let code = (err as BusinessError).code; 5012 let message = (err as BusinessError).message; 5013 console.error(`Register observer failed, code is ${code},message is ${message}`); 5014} 5015 5016try { 5017 if (store != undefined) { 5018 (store as relationalStore.RdbStore).off('autoSyncProgress', progressDetail); 5019 } 5020} catch (err) { 5021 let code = (err as BusinessError).code; 5022 let message = (err as BusinessError).message; 5023 console.error(`Unregister failed, code is ${code},message is ${message}`); 5024} 5025``` 5026 5027## off('statistics')<sup>12+</sup> 5028 5029off(event: 'statistics', observer?: Callback<SqlExecutionInfo>): void 5030 5031取消订阅SQL统计信息。 5032 5033**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 5034 5035**参数：** 5036 5037| 参数名 | 类型 | 必填 | 说明 | 5038| ------------ |---------------------------------| ---- |-----------------------------------| 5039| event | string | 是 | 取消订阅事件名称。取值为'statistics'，表示sql执行时间的统计。 | 5040| observer | Callback<[SqlExecutionInfo](arkts-apis-data-relationalStore-i.md#sqlexecutioninfo12)> | 否 | 回调函数。该参数存在，则取消指定Callback监听回调，否则取消该event事件的所有监听回调。 | 5041 5042 5043**错误码：** 5044 5045以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。 5046 5047| **错误码ID** | **错误信息** | 5048|-----------|--------| 5049| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 5050| 801 | Capability not supported. | 5051| 14800000 | Inner error. | 5052| 14800014 | The RdbStore or ResultSet is already closed. | 5053 5054```ts 5055import { BusinessError } from '@kit.BasicServicesKit'; 5056 5057try { 5058 if (store != undefined) { 5059 (store as relationalStore.RdbStore).off('statistics'); 5060 } 5061} catch (err) { 5062 let code = (err as BusinessError).code; 5063 let message = (err as BusinessError).message; 5064 console.error(`Unregister observer failed, code is ${code},message is ${message}`); 5065} 5066``` 5067 5068## off('sqliteErrorOccurred')<sup>20+</sup> 5069 5070off(event: 'sqliteErrorOccurred', observer?: Callback<ExceptionMessage>): void 5071 5072停止记录SQL执行过程中的异常日志。 5073 5074**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 5075 5076**参数：** 5077 5078| 参数名 | 类型 | 必填 | 说明 | 5079| ------------ |---------------------------------| ---- |-----------------------------------| 5080| event | string | 是 | 取消订阅事件名称，取值为'sqliteErrorOccurred'，记录SQL语句执行过程中的错误信息。 | 5081| observer | Callback<[ExceptionMessage](arkts-apis-data-relationalStore-i.md#exceptionmessage20)> | 否 | 回调函数。该参数存在，则取消指定Callback监听回调，否则取消该event事件的所有监听回调。 | 5082 5083**错误码：** 5084 5085以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。 5086 5087| **错误码ID** | **错误信息** | 5088|-----------|--------| 5089| 801 | Capability not supported. | 5090| 14800014 | The RdbStore or ResultSet is already closed. | 5091 5092**示例：** 5093 5094```ts 5095import { BusinessError } from '@kit.BasicServicesKit'; 5096 5097try { 5098 if (store != undefined) { 5099 (store as relationalStore.RdbStore).off('sqliteErrorOccurred'); 5100 } 5101} catch (err) { 5102 let code = (err as BusinessError).code; 5103 let message = (err as BusinessError).message; 5104 console.error(`Unregister observer failed, code is ${code},message is ${message}`); 5105} 5106``` 5107 5108## off('perfStat')<sup>20+</sup> 5109 5110off(event: 'perfStat', observer?: Callback<SqlExecutionInfo>): void 5111 5112取消订阅SQL统计信息。 5113 5114**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 5115 5116**参数：** 5117 5118| 参数名 | 类型 | 必填 | 说明 | 5119| ------------ |---------------------------------| ---- |-----------------------------------| 5120| event | string | 是 | 取消订阅事件名称。取值为'perfStat'，统计执行SQL的时间。 | 5121| observer | Callback<[SqlExecutionInfo](arkts-apis-data-relationalStore-i.md#sqlexecutioninfo12)> | 否 | 回调函数，表示订阅时的回调函数。该参数存在，则取消指定Callback监听回调，否则取消该event事件的所有监听回调。 | 5122 5123 5124**错误码：** 5125 5126以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。 5127 5128| **错误码ID** | **错误信息** | 5129|-----------|--------| 5130| 801 | Capability not supported. | 5131| 14800014 | The RdbStore or ResultSet is already closed. | 5132 5133```ts 5134import { BusinessError } from '@kit.BasicServicesKit'; 5135 5136try { 5137 if (store != undefined) { 5138 (store as relationalStore.RdbStore).off('perfStat'); 5139 } 5140} catch (err) { 5141 let code = (err as BusinessError).code; 5142 let message = (err as BusinessError).message; 5143 console.error(`Unregister observer failed, code is ${code},message is ${message}`); 5144} 5145``` 5146 5147## emit<sup>10+</sup> 5148 5149emit(event: string): void 5150 5151通知通过[on](#on10)注册的进程间或者进程内监听事件。 5152 5153**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 5154 5155**参数：** 5156 5157| 参数名 | 类型 | 必填 | 说明 | 5158| ------ | ------ | ---- | -------------------- | 5159| event | string | 是 | 通知订阅事件的名称，可自定义事件名称，不能与系统已有事件[dataChange](#ondatachange)，[autoSyncProgress](#onautosyncprogress11)，[statistics](#onstatistics12)名称重复。 | 5160 5161**错误码：** 5162 5163以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。 5164 5165| **错误码ID** | **错误信息** | 5166| --------- |---------------------------------------------------------------------------------------------------------------| 5167| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 5168| 801 | Capability not supported. | 5169| 14800000 | Inner error. | 5170| 14800014 | The RdbStore or ResultSet is already closed. | 5171| 14800050 | Failed to obtain the subscription service. | 5172 5173 5174**示例：** 5175 5176```ts 5177if (store != undefined) { 5178 (store as relationalStore.RdbStore).emit('storeObserver'); 5179} 5180``` 5181 5182## cleanDirtyData<sup>11+</sup> 5183 5184cleanDirtyData(table: string, cursor: number, callback: AsyncCallback<void>): void 5185 5186清理云端删除的数据同步到本地后，未自动清理的，且数据的游标（cursor）小于指定游标的数据。 5187 5188**系统能力：** SystemCapability.DistributedDataManager.CloudSync.Client 5189 5190**参数：** 5191 5192| 参数名 | 类型 | 必填 | 说明 | 5193| -------- | ----------------------------------------------------- | ---- | -------------------------------------------------- | 5194| table | string | 是 | 表示当前数据库的表的名称。 | 5195| cursor | number | 是 | 整数类型，表示数据游标，小于此游标的脏数据将被清理。 | 5196| callback | AsyncCallback<void> | 是 | 指定的callback回调函数。 | 5197 5198**错误码：** 5199 5200以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。其中，14800011错误码处理可参考[数据库备份与恢复](../../database/data-backup-and-restore.md)。 5201 5202| **错误码ID** | **错误信息** | 5203|-----------|---------------| 5204| 401 | Parameter error. Possible causes: 1. Need 1 - 3 parameter(s)! 2. The RdbStore must be not nullptr. 3. The tablesNames must be not empty string. 4. The cursor must be valid cursor. | 5205| 801 | Capability not supported. | 5206| 14800000 | Inner error. | 5207| 14800011 | Failed to open the database because it is corrupted. | 5208| 14800014 | The RdbStore or ResultSet is already closed. | 5209| 14800015 | The database does not respond. | 5210| 14800021 | SQLite: Generic error. Possible causes: Insert failed or the updated data does not exist. | 5211| 14800022 | SQLite: Callback routine requested an abort. | 5212| 14800023 | SQLite: Access permission denied. | 5213| 14800024 | SQLite: The database file is locked. | 5214| 14800025 | SQLite: A table in the database is locked. | 5215| 14800026 | SQLite: The database is out of memory. | 5216| 14800027 | SQLite: Attempt to write a readonly database. | 5217| 14800028 | SQLite: Some kind of disk I/O error occurred. | 5218| 14800029 | SQLite: The database is full. | 5219| 14800030 | SQLite: Unable to open the database file. | 5220| 14800031 | SQLite: TEXT or BLOB exceeds size limit. | 5221| 14800032 | SQLite: Abort due to constraint violation. | 5222| 14800033 | SQLite: Data type mismatch. | 5223| 14800034 | SQLite: Library used incorrectly. | 5224 5225**示例：** 5226 5227```ts 5228if (store != undefined) { 5229 (store as relationalStore.RdbStore).cleanDirtyData('test_table', 100, (err) => { 5230 if (err) { 5231 console.error(`clean dirty data failed, code is ${err.code},message is ${err.message}`); 5232 return; 5233 } 5234 console.info('clean dirty data succeeded'); 5235 }); 5236} 5237``` 5238 5239## cleanDirtyData<sup>11+</sup> 5240 5241cleanDirtyData(table: string, callback: AsyncCallback<void>): void 5242 5243清理云端删除的数据同步到本地后，未自动清理的所有数据。 5244 5245**系统能力：** SystemCapability.DistributedDataManager.CloudSync.Client 5246 5247**参数：** 5248 5249| 参数名 | 类型 | 必填 | 说明 | 5250| -------- | ----------------------------------------------------- | ---- | -------------------------------------------------- | 5251| table | string | 是 | 表示当前数据库的表的名称。 | 5252| callback | AsyncCallback<void> | 是 | 指定的callback回调函数。 | 5253 5254**错误码：** 5255 5256以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。其中，14800011错误码处理可参考[数据库备份与恢复](../../database/data-backup-and-restore.md)。 5257 5258| **错误码ID** | **错误信息** | 5259|-----------|---------| 5260| 401 | Parameter error. Possible causes: 1. Need 1 - 3 parameter(s). 2. The RdbStore must be not nullptr. 3. The tablesNames must be not empty string. | 5261| 801 | Capability not supported. | 5262| 14800000 | Inner error. | 5263| 14800011 | Failed to open the database because it is corrupted. | 5264| 14800014 | The RdbStore or ResultSet is already closed. | 5265| 14800015 | The database does not respond. | 5266| 14800021 | SQLite: Generic error. Possible causes: Insert failed or the updated data does not exist. | 5267| 14800022 | SQLite: Callback routine requested an abort. | 5268| 14800023 | SQLite: Access permission denied. | 5269| 14800024 | SQLite: The database file is locked. | 5270| 14800025 | SQLite: A table in the database is locked. | 5271| 14800026 | SQLite: The database is out of memory. | 5272| 14800027 | SQLite: Attempt to write a readonly database. | 5273| 14800028 | SQLite: Some kind of disk I/O error occurred. | 5274| 14800029 | SQLite: The database is full. | 5275| 14800030 | SQLite: Unable to open the database file. | 5276| 14800031 | SQLite: TEXT or BLOB exceeds size limit. | 5277| 14800032 | SQLite: Abort due to constraint violation. | 5278| 14800033 | SQLite: Data type mismatch. | 5279| 14800034 | SQLite: Library used incorrectly. | 5280 5281**示例：** 5282 5283```ts 5284if (store != undefined) { 5285 (store as relationalStore.RdbStore).cleanDirtyData('test_table', (err) => { 5286 if (err) { 5287 console.error(`clean dirty data failed, code is ${err.code},message is ${err.message}`); 5288 return; 5289 } 5290 console.info('clean dirty data succeeded'); 5291 }); 5292} 5293``` 5294 5295## cleanDirtyData<sup>11+</sup> 5296 5297cleanDirtyData(table: string, cursor?: number): Promise<void> 5298 5299清理云端删除的数据同步到本地后，未自动清理的，且数据的游标（cursor）小于指定游标的数据。若无cursor参数，将全部清理。 5300 5301**系统能力：** SystemCapability.DistributedDataManager.CloudSync.Client 5302 5303**参数：** 5304 5305| 参数名 | 类型 | 必填 | 说明 | 5306| -------- | ----------------------------------------------------- | ---- | -------------------------------------------------- | 5307| table | string | 是 | 表示当前数据库的表的名称。 | 5308| cursor | number | 否 | 整数类型，表示数据游标，小于此游标的脏数据将被清理。当此参数不填时，清理当前表的所有脏数据。 | 5309 5310**返回值：** 5311 5312| 类型 | 说明 | 5313| -------- | ------------------------------------------------- | 5314| Promise\<void> | 无返回结果的Promise对象。 | 5315 5316**错误码：** 5317 5318以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。其中，14800011错误码处理可参考[数据库备份与恢复](../../database/data-backup-and-restore.md)。 5319 5320| **错误码ID** | **错误信息** | 5321|-----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 5322| 401 | Parameter error. Possible causes: 1. Need 1 - 3 parameter(s)! 2. The RdbStore must be not nullptr. 3. The tablesNames must be not empty string. 4. The cursor must be valid cursor. | 5323| 801 | Capability not supported. | 5324| 14800000 | Inner error. | 5325| 14800011 | Failed to open the database because it is corrupted. | 5326| 14800014 | The RdbStore or ResultSet is already closed. | 5327| 14800015 | The database does not respond. | 5328| 14800021 | SQLite: Generic error. Possible causes: Insert failed or the updated data does not exist. | 5329| 14800022 | SQLite: Callback routine requested an abort. | 5330| 14800023 | SQLite: Access permission denied. | 5331| 14800024 | SQLite: The database file is locked. | 5332| 14800025 | SQLite: A table in the database is locked. | 5333| 14800026 | SQLite: The database is out of memory. | 5334| 14800027 | SQLite: Attempt to write a readonly database. | 5335| 14800028 | SQLite: Some kind of disk I/O error occurred. | 5336| 14800029 | SQLite: The database is full. | 5337| 14800030 | SQLite: Unable to open the database file. | 5338| 14800031 | SQLite: TEXT or BLOB exceeds size limit. | 5339| 14800032 | SQLite: Abort due to constraint violation. | 5340| 14800033 | SQLite: Data type mismatch. | 5341| 14800034 | SQLite: Library used incorrectly. | 5342 5343**示例：** 5344 5345```ts 5346import { BusinessError } from '@kit.BasicServicesKit'; 5347 5348if (store != undefined) { 5349 (store as relationalStore.RdbStore).cleanDirtyData('test_table', 100).then(() => { 5350 console.info('clean dirty data succeeded'); 5351 }).catch((err: BusinessError) => { 5352 console.error(`clean dirty data failed, code is ${err.code},message is ${err.message}`); 5353 }); 5354} 5355``` 5356 5357## attach<sup>12+</sup> 5358 5359attach(fullPath: string, attachName: string, waitTime?: number) : Promise<number> 5360 5361将一个数据库文件附加到当前数据库中，以便在SQL语句中可以直接访问附加数据库中的数据。 5362 5363数据库文件来自文件，且此API不支持附加加密数据库。调用attach接口后，数据库切换为非WAL模式，性能会存在一定的劣化。 5364 5365attach时，数据库会切换为非WAL模式，切换模式需要确保所有的ResultSet都已经Close，所有的写操作已经结束，否则会报错14800015。 5366 5367attach不能并发调用，否则可能出现未响应情况并报错14800015，需要重试。 5368 5369**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 5370 5371**参数：** 5372 5373| 参数名 | 类型 | 必填 | 说明 | 5374| ----------- | ------ | --- | ------------ | 5375| fullPath | string | 是 | 表示要附加的数据库的路径。 | 5376| attachName | string | 是 | 表示附加后的数据库的别名。 | 5377| waitTime | number | 否 | 表示附加数据库文件的等待时长。默认值2s，最小值1s，最大值300s。 | 5378 5379**返回值：** 5380 5381| 类型 | 说明 | 5382| ---------------- | ---------------------------- | 5383| Promise<number> | Promise对象。返回附加数据库的数量。 | 5384 5385**错误码：** 5386 5387以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。其中，14800011错误码处理可参考[数据库备份与恢复](../../database/data-backup-and-restore.md)。 5388 5389| **错误码ID** | **错误信息** | 5390|-----------| ------------------------------------------------------------ | 5391| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 5392| 801 | Capability not supported. | 5393| 14800000 | Inner error. | 5394| 14800010 | Failed to open or delete the database by an invalid database path. | 5395| 14800011 | Failed to open the database because it is corrupted. | 5396| 14800014 | The RdbStore or ResultSet is already closed. | 5397| 14800015 | The database does not respond. | 5398| 14800016 | The database alias already exists. | 5399| 14800021 | SQLite: Generic error. Possible causes: Insert failed or the updated data does not exist. | 5400| 14800022 | SQLite: Callback routine requested an abort. | 5401| 14800023 | SQLite: Access permission denied. | 5402| 14800024 | SQLite: The database file is locked. | 5403| 14800025 | SQLite: A table in the database is locked. | 5404| 14800026 | SQLite: The database is out of memory. | 5405| 14800027 | SQLite: Attempt to write a readonly database. | 5406| 14800028 | SQLite: Some kind of disk I/O error occurred. | 5407| 14800029 | SQLite: The database is full. | 5408| 14800030 | SQLite: Unable to open the database file. | 5409| 14800031 | SQLite: TEXT or BLOB exceeds size limit. | 5410| 14800032 | SQLite: Abort due to constraint violation. | 5411| 14800033 | SQLite: Data type mismatch. | 5412| 14800034 | SQLite: Library used incorrectly. | 5413 5414**示例：** 5415 5416```ts 5417// 非加密数据库附加非加密数据库。 5418import { BusinessError } from '@kit.BasicServicesKit'; 5419 5420if (store != undefined) { 5421 (store as relationalStore.RdbStore).attach("/path/rdbstore1.db", "attachDB").then((number: number) => { 5422 console.info('attach succeeded'); 5423 }).catch((err: BusinessError) => { 5424 console.error(`attach failed, code is ${err.code},message is ${err.message}`); 5425 }); 5426} 5427``` 5428 5429## attach<sup>12+</sup> 5430 5431attach(context: Context, config: StoreConfig, attachName: string, waitTime?: number) : Promise<number> 5432 5433将一个当前应用的数据库附加到当前数据库中，以便在SQL语句中可以直接访问附加数据库中的数据。 5434 5435此API不支持加密数据库附加非加密数据库。调用attach接口后，数据库切换为非WAL模式，性能会存在一定的劣化。 5436 5437attach时，数据库会切换为非WAL模式，切换模式需要确保所有的ResultSet都已经Close，所有的写操作已经结束，否则会报错14800015。 5438 5439attach不能并发调用，否则可能出现未响应情况并报错14800015，需要重试。除此之外，attach附加加密数据库时，可能受到并发的影响，出现解密失败的情况，报错14800011，需要显式指定加密参数并重试。 5440 5441**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 5442 5443**参数：** 5444 5445| 参数名 | 类型 | 必填 | 说明 | 5446| ----------- | ------ | --- | ------------ | 5447| context | Context | 是 | 应用的上下文。<br>FA模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-app-context.md)。<br>Stage模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-application-uiAbilityContext.md)。 | 5448| config | [StoreConfig](arkts-apis-data-relationalStore-i.md#storeconfig) | 是 | 与此RDB存储相关的数据库配置。 | 5449| attachName | string | 是 | 表示附加后的数据库的别名。 | 5450| waitTime | number | 否 | 表示附加数据库文件的等待时长。默认值2s，最小值1s，最大值300s。 | 5451 5452**返回值：** 5453 5454| 类型 | 说明 | 5455| ---------------- | ---------------------------- | 5456| Promise<number> | Promise对象。返回附加数据库的数量。 | 5457 5458**错误码：** 5459 5460以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。其中，14800011错误码处理可参考[数据库备份与恢复](../../database/data-backup-and-restore.md)。 5461 5462| **错误码ID** | **错误信息** | 5463|-----------| ------------------------------------------------------------ | 5464| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 5465| 801 | Capability not supported. | 5466| 14800000 | Inner error. | 5467| 14800010 | Failed to open or delete the database by an invalid database path. | 5468| 14800011 | Failed to open the database because it is corrupted. | 5469| 14800014 | The RdbStore or ResultSet is already closed. | 5470| 14800015 | The database does not respond. | 5471| 14800016 | The database alias already exists. | 5472| 14801001 | The operation is supported in the stage model only. | 5473| 14801002 | Invalid data group ID. | 5474| 14800021 | SQLite: Generic error. Possible causes: Insert failed or the updated data does not exist. | 5475| 14800022 | SQLite: Callback routine requested an abort. | 5476| 14800023 | SQLite: Access permission denied. | 5477| 14800024 | SQLite: The database file is locked. | 5478| 14800025 | SQLite: A table in the database is locked. | 5479| 14800026 | SQLite: The database is out of memory. | 5480| 14800027 | SQLite: Attempt to write a readonly database. | 5481| 14800028 | SQLite: Some kind of disk I/O error occurred. | 5482| 14800029 | SQLite: The database is full. | 5483| 14800030 | SQLite: Unable to open the database file. | 5484| 14800031 | SQLite: TEXT or BLOB exceeds size limit. | 5485| 14800032 | SQLite: Abort due to constraint violation. | 5486| 14800033 | SQLite: Data type mismatch. | 5487| 14800034 | SQLite: Library used incorrectly. | 5488 5489**示例1：非加密数据库附加非加密数据库** 5490 5491```ts 5492import { BusinessError } from '@kit.BasicServicesKit'; 5493 5494let attachStore: relationalStore.RdbStore | undefined = undefined; 5495 5496const STORE_CONFIG1: relationalStore.StoreConfig = { 5497 name: "rdbstore1.db", 5498 securityLevel: relationalStore.SecurityLevel.S3 5499}; 5500 5501relationalStore.getRdbStore(this.context, STORE_CONFIG1).then(async (rdbStore: relationalStore.RdbStore) => { 5502 attachStore = rdbStore; 5503 console.info('Get RdbStore successfully.'); 5504 if (store != undefined) { 5505 (store as relationalStore.RdbStore).attach(this.context, STORE_CONFIG1, "attachDB").then((number: number) => { 5506 console.info(`attach succeeded, number is ${number}`); 5507 }).catch((err: BusinessError) => { 5508 console.error(`attach failed, code is ${err.code},message is ${err.message}`); 5509 }); 5510 } 5511}).catch((err: BusinessError) => { 5512 console.error(`Get RdbStore failed, code is ${err.code},message is ${err.message}`); 5513}); 5514``` 5515 5516**示例2：非加密数据库附加加密数据库** 5517 5518```ts 5519import { BusinessError } from '@kit.BasicServicesKit'; 5520 5521let attachStore: relationalStore.RdbStore | undefined = undefined; 5522 5523const STORE_CONFIG2: relationalStore.StoreConfig = { 5524 name: "rdbstore2.db", 5525 encrypt: true, 5526 securityLevel: relationalStore.SecurityLevel.S3 5527}; 5528 5529relationalStore.getRdbStore(this.context, STORE_CONFIG2).then(async (rdbStore: relationalStore.RdbStore) => { 5530 attachStore = rdbStore; 5531 console.info('Get RdbStore successfully.'); 5532 if (store != undefined) { 5533 (store as relationalStore.RdbStore).attach(this.context, STORE_CONFIG2, "attachDB2", 10).then((number: number) => { 5534 console.info(`attach succeeded, number is ${number}`); 5535 }).catch((err: BusinessError) => { 5536 console.error(`attach failed, code is ${err.code},message is ${err.message}`); 5537 }); 5538 } 5539}).catch((err: BusinessError) => { 5540 console.error(`Get RdbStore failed, code is ${err.code},message is ${err.message}`); 5541}); 5542``` 5543 5544## detach<sup>12+</sup> 5545 5546detach(attachName: string, waitTime?: number) : Promise<number> 5547 5548将附加的数据库从当前数据库中分离。 5549 5550当所有的附加的数据库被分离后，数据库会重新切换为WAL模式。 5551 5552在detach之前，所有的数据库操作要确保已经结束，所有的ResultSet已经Close。并且不能并发调用，可能出现未响应情况，需要重试。 5553 5554**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 5555 5556**参数：** 5557 5558| 参数名 | 类型 | 必填 | 说明 | 5559| ----------- | ------ | --- | ------------ | 5560| attachName | string | 是 | 表示附加后的数据库的别名。 | 5561| waitTime | number | 否 | 表示分离数据库的等待时长。默认值2s，最小值1s，最大值300s。 | 5562 5563**返回值：** 5564 5565| 类型 | 说明 | 5566| ---------------- | ---------------------------- | 5567| Promise<number> | Promise对象。返回分离后剩余附加的数据库的数量。 | 5568 5569**错误码：** 5570 5571以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。其中，14800011错误码处理可参考[数据库备份与恢复](../../database/data-backup-and-restore.md)。 5572 5573| **错误码ID** | **错误信息** | 5574|-----------|------------------------| 5575| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 5576| 14800000 | Inner error. | 5577| 14800011 | Failed to open the database because it is corrupted. | 5578| 14800014 | The RdbStore or ResultSet is already closed. | 5579| 14800015 | The database does not respond. | 5580| 14800021 | SQLite: Generic error. Possible causes: Insert failed or the updated data does not exist. | 5581| 14800022 | SQLite: Callback routine requested an abort. | 5582| 14800023 | SQLite: Access permission denied. | 5583| 14800024 | SQLite: The database file is locked. | 5584| 14800025 | SQLite: A table in the database is locked. | 5585| 14800026 | SQLite: The database is out of memory. | 5586| 14800027 | SQLite: Attempt to write a readonly database. | 5587| 14800028 | SQLite: Some kind of disk I/O error occurred. | 5588| 14800029 | SQLite: The database is full. | 5589| 14800030 | SQLite: Unable to open the database file. | 5590| 14800031 | SQLite: TEXT or BLOB exceeds size limit. | 5591| 14800032 | SQLite: Abort due to constraint violation. | 5592| 14800033 | SQLite: Data type mismatch. | 5593| 14800034 | SQLite: Library used incorrectly. | 5594 5595**示例：** 5596 5597```ts 5598import { BusinessError } from '@kit.BasicServicesKit'; 5599 5600if (store != undefined) { 5601 (store as relationalStore.RdbStore).detach("attachDB").then((number: number) => { 5602 console.info(`detach succeeded, number is ${number}`); 5603 }).catch((err: BusinessError) => { 5604 console.error(`detach failed, code is ${err.code},message is ${err.message}`); 5605 }); 5606} 5607``` 5608 5609## lockRow<sup>12+</sup> 5610 5611lockRow(predicates: RdbPredicates):Promise<void> 5612 5613根据RdbPredicates的指定实例对象从数据库中锁定数据，锁定数据不执行端云同步，使用Promise异步回调。 5614 5615该接口只支持主键为基本类型的表、不支持共享表、无主键表和复合类型主键表。 5616该接口不支持依赖关系表之间的锁传递，如果表存在依赖关系，需要根据依赖关系手动调用该接口。 5617该接口不支持对已删除数据的操作。 5618 5619**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 5620 5621**参数：** 5622 5623| 参数名 | 类型 | 必填 | 说明 | 5624| ---------- | ------------------------------------ | ---- | ----------------------------------------- | 5625| predicates | [RdbPredicates](arkts-apis-data-relationalStore-RdbPredicates.md) | 是 | RdbPredicates的实例对象指定的锁定条件。 | 5626 5627**返回值**： 5628 5629| 类型 | 说明 | 5630| --------------------- | ------------------------------- | 5631| Promise<void> | 无返回结果的Promise对象。 | 5632 5633**错误码：** 5634 5635以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。其中，14800011错误码处理可参考[数据库备份与恢复](../../database/data-backup-and-restore.md)。 5636 5637| **错误码ID** | **错误信息** | 5638|-----------|----------------------------------------------------------------------------------------------| 5639| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 5640| 14800000 | Inner error. | 5641| 14800011 | Failed to open the database because it is corrupted. | 5642| 14800014 | The RdbStore or ResultSet is already closed. | 5643| 14800015 | The database does not respond. | 5644| 14800018 | No data meets the condition. | 5645| 14800021 | SQLite: Generic error. Possible causes: Insert failed or the updated data does not exist. | 5646| 14800022 | SQLite: Callback routine requested an abort. | 5647| 14800023 | SQLite: Access permission denied. | 5648| 14800024 | SQLite: The database file is locked. | 5649| 14800025 | SQLite: A table in the database is locked. | 5650| 14800026 | SQLite: The database is out of memory. | 5651| 14800027 | SQLite: Attempt to write a readonly database. | 5652| 14800028 | SQLite: Some kind of disk I/O error occurred. | 5653| 14800029 | SQLite: The database is full. | 5654| 14800030 | SQLite: Unable to open the database file. | 5655| 14800031 | SQLite: TEXT or BLOB exceeds size limit. | 5656| 14800032 | SQLite: Abort due to constraint violation. | 5657| 14800033 | SQLite: Data type mismatch. | 5658| 14800034 | SQLite: Library used incorrectly. | 5659 5660**示例：** 5661 5662```ts 5663import { BusinessError } from '@kit.BasicServicesKit'; 5664 5665let predicates = new relationalStore.RdbPredicates("EMPLOYEE"); 5666predicates.equalTo("NAME", "Lisa"); 5667if (store != undefined) { 5668 (store as relationalStore.RdbStore).lockRow(predicates).then(() => { 5669 console.info(`Lock success`); 5670 }).catch((err: BusinessError) => { 5671 console.error(`Lock failed, code is ${err.code},message is ${err.message}`); 5672 }); 5673} 5674``` 5675 5676## unlockRow<sup>12+</sup> 5677 5678unlockRow(predicates: RdbPredicates):Promise<void> 5679 5680根据RdbPredicates的指定实例对象从数据库中解锁数据，使用Promise异步回调。 5681 5682该接口只支持主键为基本类型的表、不支持共享表、无主键表和复合类型主键表。 5683该接口不支持依赖关系表之间的锁传递，如果表存在依赖关系，需要根据依赖关系手动调用该接口。 5684该接口不支持对已删除数据的操作。 5685 5686**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 5687 5688**参数：** 5689 5690| 参数名 | 类型 | 必填 | 说明 | 5691| ---------- | ------------------------------------ | ---- | ----------------------------------------- | 5692| predicates | [RdbPredicates](arkts-apis-data-relationalStore-RdbPredicates.md) | 是 | RdbPredicates的实例对象指定的锁定条件。 | 5693 5694**返回值**： 5695 5696| 类型 | 说明 | 5697| --------------------- | ------------------------------- | 5698| Promise<void> | 无返回结果的Promise对象。 | 5699 5700**错误码：** 5701 5702以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。其中，14800011错误码处理可参考[数据库备份与恢复](../../database/data-backup-and-restore.md)。 5703 5704| **错误码ID** | **错误信息** | 5705|-----------| ------------------------------------------------------------ | 5706| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 5707| 14800000 | Inner error. | 5708| 14800011 | Failed to open the database because it is corrupted. | 5709| 14800014 | The RdbStore or ResultSet is already closed. | 5710| 14800015 | The database does not respond. | 5711| 14800018 | No data meets the condition. | 5712| 14800021 | SQLite: Generic error. Possible causes: Insert failed or the updated data does not exist. | 5713| 14800022 | SQLite: Callback routine requested an abort. | 5714| 14800023 | SQLite: Access permission denied. | 5715| 14800024 | SQLite: The database file is locked. | 5716| 14800025 | SQLite: A table in the database is locked. | 5717| 14800026 | SQLite: The database is out of memory. | 5718| 14800027 | SQLite: Attempt to write a readonly database. | 5719| 14800028 | SQLite: Some kind of disk I/O error occurred. | 5720| 14800029 | SQLite: The database is full. | 5721| 14800030 | SQLite: Unable to open the database file. | 5722| 14800031 | SQLite: TEXT or BLOB exceeds size limit. | 5723| 14800032 | SQLite: Abort due to constraint violation. | 5724| 14800033 | SQLite: Data type mismatch. | 5725| 14800034 | SQLite: Library used incorrectly. | 5726 5727**示例：** 5728 5729```ts 5730import { BusinessError } from '@kit.BasicServicesKit'; 5731 5732let predicates = new relationalStore.RdbPredicates("EMPLOYEE"); 5733predicates.equalTo("NAME", "Lisa"); 5734if (store != undefined) { 5735 (store as relationalStore.RdbStore).unlockRow(predicates).then(() => { 5736 console.info(`Unlock success`); 5737 }).catch((err: BusinessError) => { 5738 console.error(`Unlock failed, code is ${err.code},message is ${err.message}`); 5739 }); 5740} 5741``` 5742 5743## queryLockedRow<sup>12+</sup> 5744 5745queryLockedRow(predicates: RdbPredicates, columns?: Array<string>):Promise<ResultSet> 5746 5747根据指定条件查询数据库中锁定的数据，使用Promise异步回调。 5748由于共享内存大小限制为2Mb，因此单条数据的大小需小于2Mb，否则会查询失败。 5749 5750**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 5751 5752**参数：** 5753 5754| 参数名 | 类型 | 必填 | 说明 | 5755| ---------- | ------------------------------------ | ---- | ------------------------------------------------ | 5756| predicates | [RdbPredicates](arkts-apis-data-relationalStore-RdbPredicates.md) | 是 | RdbPredicates的实例对象指定的查询条件。 | 5757| columns | Array<string> | 否 | 表示要查询的列。如果值为空，则查询应用于所有列。 | 5758 5759**返回值**： 5760 5761| 类型 | 说明 | 5762| ------------------------------------------------------- | -------------------------------------------------- | 5763| Promise<[ResultSet](arkts-apis-data-relationalStore-ResultSet.md)> | Promise对象。如果操作成功，则返回ResultSet对象。 | 5764 5765**错误码：** 5766 5767以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。其中，14800011错误码处理可参考[数据库备份与恢复](../../database/data-backup-and-restore.md)。 5768 5769| **错误码ID** | **错误信息** | 5770|-----------| ------------------------------------------------------------ | 5771| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 5772| 14800000 | Inner error. | 5773| 14800011 | Failed to open the database because it is corrupted. | 5774| 14800014 | The RdbStore or ResultSet is already closed. | 5775| 14800015 | The database does not respond. | 5776| 14800021 | SQLite: Generic error. Possible causes: Insert failed or the updated data does not exist. | 5777| 14800022 | SQLite: Callback routine requested an abort. | 5778| 14800023 | SQLite: Access permission denied. | 5779| 14800024 | SQLite: The database file is locked. | 5780| 14800025 | SQLite: A table in the database is locked. | 5781| 14800026 | SQLite: The database is out of memory. | 5782| 14800027 | SQLite: Attempt to write a readonly database. | 5783| 14800028 | SQLite: Some kind of disk I/O error occurred. | 5784| 14800029 | SQLite: The database is full. | 5785| 14800030 | SQLite: Unable to open the database file. | 5786| 14800031 | SQLite: TEXT or BLOB exceeds size limit. | 5787| 14800032 | SQLite: Abort due to constraint violation. | 5788| 14800033 | SQLite: Data type mismatch. | 5789| 14800034 | SQLite: Library used incorrectly. | 5790 5791**示例：** 5792 5793```ts 5794import { BusinessError } from '@kit.BasicServicesKit'; 5795 5796let predicates = new relationalStore.RdbPredicates("EMPLOYEE"); 5797predicates.equalTo("NAME", "Rose"); 5798if (store != undefined) { 5799 (store as relationalStore.RdbStore).queryLockedRow(predicates, ["ID", "NAME", "AGE", "SALARY", "CODES"]).then(async (resultSet: relationalStore.ResultSet) => { 5800 console.info(`ResultSet column names: ${resultSet.columnNames}, column count: ${resultSet.columnCount}`); 5801 // resultSet是一个数据集合的游标，默认指向第-1个记录，有效的数据从0开始。 5802 try { 5803 while (resultSet.goToNextRow()) { 5804 const id = resultSet.getLong(resultSet.getColumnIndex("ID")); 5805 const name = resultSet.getString(resultSet.getColumnIndex("NAME")); 5806 const age = resultSet.getLong(resultSet.getColumnIndex("AGE")); 5807 const salary = resultSet.getDouble(resultSet.getColumnIndex("SALARY")); 5808 console.info(`id=${id}, name=${name}, age=${age}, salary=${salary}`); 5809 } 5810 } catch (err) { 5811 console.error(`Query failed, code is ${err.code},message is ${err.message}`); 5812 } finally { 5813 // 释放数据集的内存，若不释放可能会引起fd泄露与内存泄露 5814 resultSet.close(); 5815 } 5816 }).catch((err: BusinessError) => { 5817 console.error(`Query failed, code is ${err.code},message is ${err.message}`); 5818 }); 5819} 5820``` 5821## close<sup>12+</sup> 5822 5823close(): Promise<void> 5824 5825关闭数据库，使用Promise异步回调。 5826 5827**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 5828 5829**返回值：** 5830 5831| 类型 | 说明 | 5832| ------------------- | ------------- | 5833| Promise<void> | Promise对象。 | 5834 5835**错误码：** 5836 5837以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。 5838 5839| **错误码ID** | **错误信息** | 5840| ------------ | ----------------------------------------------- | 5841| 401 | Parameter error. Possible causes: The RdbStore verification failed. | 5842| 14800000 | Inner error. | 5843 5844**示例：** 5845 5846```ts 5847import { BusinessError } from '@kit.BasicServicesKit'; 5848 5849if (store != undefined) { 5850 (store as relationalStore.RdbStore).close().then(() => { 5851 console.info(`close succeeded`); 5852 }).catch((err: BusinessError) => { 5853 console.error(`close failed, code is ${err.code},message is ${err.message}`); 5854 }); 5855} 5856``` 5857 5858## rekey<sup>20+</sup> 5859 5860rekey(cryptoParam?: CryptoParam): Promise\<void> 5861 5862手动更新加密数据库的密钥。使用Promise异步回调。 5863 5864不支持对非WAL模式的数据库进行密钥更新。 5865 5866手动更新密钥时需要独占访问数据库，此时若存在任何未释放的结果集（ResultSet）、事务（Transaction）或其他进程打开的数据库均会引发失败。 5867 5868仅支持加密数据库进行密钥更新，不支持非加密数据库变加密数据库及加密数据库变非加密数据库，且需要保持加密参数和密钥生成方式与建库时一致。 5869 5870数据库越大，密钥更新所需的时间越长。 5871 5872**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 5873 5874**参数：** 5875 5876| 参数名 | 类型 | 必填 | 说明 | 5877| ------------ | ----------------------------------------------------------------- | ---- | ----------------------------------------- | 5878| cryptoParam | [CryptoParam](arkts-apis-data-relationalStore-i.md#cryptoparam14) | 否 | 指定用户自定义的加密参数。<br/>当此参数不填时，使用默认的加密参数，见CryptoParam。| 5879 5880**返回值：** 5881 5882| 类型 | 说明 | 5883| -------------- | ------------------------ | 5884| Promise\<void> | 无返回结果的Promise对象。 | 5885 5886**错误码：** 5887 5888以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。 5889 5890| **错误码ID** | **错误信息** | 5891| ------------ | ---------------------------------------------------------------------- | 5892| 801 | Capability not supported. | 5893| 14800001 | Invalid arguments. Possible causes: 1.Parameter is out of valid range. | 5894| 14800011 | Failed to open the database because it is corrupted. | 5895| 14800014 | The RdbStore or ResultSet is already closed. | 5896| 14800015 | The database does not respond. | 5897| 14800021 | SQLite: Generic error. | 5898| 14800023 | SQLite: Access permission denied. | 5899| 14800024 | SQLite: The database file is locked. | 5900| 14800026 | SQLite: The database is out of memory. | 5901| 14800027 | SQLite: Attempt to write a readonly database. | 5902| 14800028 | SQLite: Some kind of disk I/O error occurred. | 5903| 14800029 | SQLite: The database is full. | 5904 5905**示例：** 5906 5907```ts 5908import { UIAbility } from '@kit.AbilityKit'; 5909import { BusinessError } from '@kit.BasicServicesKit'; 5910// 示例1：使用默认的加密参数 5911export default class EntryAbility extends UIAbility { 5912 onCreate() { 5913 let store: relationalStore.RdbStore | undefined = undefined; 5914 const STORE_CONFIG1: relationalStore.StoreConfig = { 5915 name: 'rdbstore1.db', 5916 securityLevel: relationalStore.SecurityLevel.S3, 5917 encrypt: true 5918 }; 5919 5920 relationalStore.getRdbStore(this.context, STORE_CONFIG1).then(async (rdbStore: relationalStore.RdbStore) => { 5921 store = rdbStore; 5922 console.info('Get RdbStore successfully.'); 5923 5924 let cryptoParam1: relationalStore.CryptoParam = { 5925 encryptionKey: new Uint8Array() 5926 }; 5927 5928 if (store != undefined) { 5929 try { 5930 (store as relationalStore.RdbStore).rekey(cryptoParam1); 5931 console.info('rekey is successful'); 5932 } catch (err) { 5933 console.error(`rekey is failed, code is ${err.code},message is ${err.message}`); 5934 } 5935 } 5936 }).catch((err: BusinessError) => { 5937 console.error(`Get RdbStore failed, code is ${err.code},message is ${err.message}`); 5938 }); 5939 } 5940} 5941``` 5942 5943```ts 5944import { UIAbility } from '@kit.AbilityKit'; 5945import { BusinessError } from '@kit.BasicServicesKit'; 5946// 示例2：使用自定义的加密参数 5947export default class EntryAbility extends UIAbility { 5948 onCreate() { 5949 let store: relationalStore.RdbStore | undefined = undefined; 5950 let cryptoParam: relationalStore.CryptoParam = { 5951 encryptionKey: new Uint8Array([1, 2, 3, 4, 5, 6]), 5952 iterationCount: 1000, 5953 encryptionAlgo: relationalStore.EncryptionAlgo.AES_256_GCM, 5954 hmacAlgo: relationalStore.HmacAlgo.SHA256, 5955 kdfAlgo: relationalStore.KdfAlgo.KDF_SHA256, 5956 cryptoPageSize: 1024 5957 }; 5958 5959 const STORE_CONFIG2: relationalStore.StoreConfig = { 5960 name: 'rdbstore2.db', 5961 securityLevel: relationalStore.SecurityLevel.S3, 5962 encrypt: true, 5963 cryptoParam: cryptoParam 5964 }; 5965 5966 relationalStore.getRdbStore(this.context, STORE_CONFIG2).then(async (rdbStore: relationalStore.RdbStore) => { 5967 store = rdbStore; 5968 console.info('Get RdbStore successfully.'); 5969 let cryptoParam2: relationalStore.CryptoParam = { 5970 encryptionKey: new Uint8Array([6, 5, 4, 3, 2, 1]), 5971 iterationCount: 1000, 5972 encryptionAlgo: relationalStore.EncryptionAlgo.AES_256_GCM, 5973 hmacAlgo: relationalStore.HmacAlgo.SHA256, 5974 kdfAlgo: relationalStore.KdfAlgo.KDF_SHA256, 5975 cryptoPageSize: 1024 5976 }; 5977 5978 if (store != undefined) { 5979 try { 5980 (store as relationalStore.RdbStore).rekey(cryptoParam2); 5981 console.info('rekey is successful'); 5982 } catch (err) { 5983 console.error(`rekey is failed, code is ${err.code},message is ${err.message}`); 5984 } 5985 } 5986 }).catch((err: BusinessError) => { 5987 console.error(`Get RdbStore failed, code is ${err.code},message is ${err.message}`); 5988 }); 5989 } 5990} 5991``` 5992 5993## setLocale<sup>20+</sup> 5994 5995setLocale(locale: string) : Promise\<void> 5996 5997设置自定义排序的语言。使用Promise异步回调。 5998 5999该值符合ISO 639标准，但是仅支持ICU中的部分语言，对于不支持的语言，设置自定义排序的语言时会报错14800001。 6000 6001**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 6002 6003**参数：** 6004 6005| 参数名 | 类型 | 必填 | 说明 | 6006| ------ | ------- | ---- | ----------------------------------------- | 6007| locale | string | 是 | 设置自定义排序的语言。该值符合ISO 639标准，如："zh"。| 6008 6009**返回值：** 6010 6011| 类型 | 说明 | 6012| -------------- | ------------------------ | 6013| Promise\<void> | 无返回结果的Promise对象。 | 6014 6015**错误码：** 6016 6017以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。 6018 6019| **错误码ID** | **错误信息** | 6020| ------------ | ---------------------------------------------------------------------- | 6021| 801 | Capability not supported. | 6022| 14800001 | Invalid arguments. Possible causes: 1.Parameter is out of valid range. | 6023| 14800014 | The RdbStore or ResultSet is already closed. | 6024| 14800024 | SQLite: The database file is locked. | 6025| 14800026 | SQLite: The database is out of memory. | 6026| 14800034 | SQLite: Library used incorrectly. | 6027 6028**示例：** 6029 6030```ts 6031try { 6032 if (store != undefined) { 6033 await store.setLocale("zh"); 6034 store.querySql("SELECT * FROM EMPLOYEE ORDER BY NAME COLLATE LOCALES", async (err, resultSet) => { 6035 if (err) { 6036 console.error(`Query failed, code: ${err.code}, message: ${err.message}`); 6037 return; 6038 } 6039 console.info(`ResultSet rowCount ${resultSet.rowCount}`); 6040 }); 6041 } 6042} catch (err) { 6043 console.error(`SetLocale failed, code: ${err.code}, message: ${err.message}`); 6044} 6045```