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