1# @ohos.data.sendableRelationalStore (Shared RDB Store) 2 3The **sendableRelationalStore** module provides APIs for obtaining **ValuesBucket** of the sendable type from the query result set and transferring it between concurrent instances. 4 5> **NOTE** 6> 7> The initial APIs of this module are supported since API version 12. Newly added APIs will be marked with a superscript to indicate their earliest API version. 8 9## When to Use 10 11When [taskpool](../../arkts-utils/taskpool-introduction.md) is used for multi-thread computing, data storage containers such as **ValuesBucket**, **Asset**, and **Assets** of the RDB store cannot be used for cross-thread transfer due to the restriction on data types. 12 13This module provides conversion functions for converting the types between common data storage containers and data storage containers that can be passed across threads. 14 15## Modules to Import 16 17```ts 18import { sendableRelationalStore } from '@kit.ArkData'; 19``` 20 21## sendableRelationalStore.toSendableValuesBucket 22 23toSendableValuesBucket(valuesBucket: NonSendableBucket): ValuesBucket 24 25Converts a key-value (KV) pair that cannot be passed across threads into the data that can be passed across threads. 26 27**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 28 29**Parameters** 30 31| Name | Type | Mandatory| Description | 32| ------------ | --------------------------------------- | ---- | :--------------------------------- | 33| valuesBucket | [NonSendableBucket](#nonsendablebucket) | Yes | Data that cannot be passed across threads.| 34 35**Return value** 36 37| Type | Description | 38| ----------------------------- | ------------------------------------ | 39| [ValuesBucket](#valuesbucket) | Data that can be passed across threads.| 40 41**Error codes** 42 43For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [RDB Store Error Codes](errorcode-data-rdb.md). 44 45| **ID**| **Error Message** | 46| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | 47| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 48| 14800000 | Inner error. | 49 50**Example** 51 52```ts 53const asset1: sendableRelationalStore.NonSendableAsset = { 54 name: 'hangman', 55 uri: '//path/example', 56 path: '//path/example', 57 createTime: 'createTime1', 58 modifyTime: 'modifyTime1', 59 size: 'size1' 60}; 61const asset2: sendableRelationalStore.NonSendableAsset = { 62 name: 'hangman', 63 uri: '//path/example', 64 path: '//path/example', 65 createTime: 'createTime1', 66 modifyTime: 'modifyTime1', 67 size: 'size1' 68}; 69const u8 = new Uint8Array([1, 2, 3]); 70const valuesBucket: sendableRelationalStore.NonSendableBucket = { 71 age: 18, 72 name: "hangman", 73 salary: 100.5, 74 passed: true, 75 data1: asset1, 76 blobType: u8, 77 bigValue: BigInt("15822401018187971961171"), 78 data2: [asset1, asset2] 79}; 80 81const sendableValuesBucket = sendableRelationalStore.toSendableValuesBucket(valuesBucket); 82``` 83 84## sendableRelationalStore.fromSendableValuesBucket 85 86fromSendableValuesBucket(valuesBucket: ValuesBucket): NonSendableBucket 87 88Converts a KV pair that can be passed across threads into the data that cannot be passed across threads. 89 90**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 91 92**Parameters** 93 94| Name | Type | Mandatory| Description | 95| ------------ | ----------------------------- | ---- | :----------------------------------- | 96| valuesBucket | [ValuesBucket](#valuesbucket) | Yes | Data that can be passed across threads.| 97 98**Return value** 99 100| Type | Description | 101| --------------------------------------- | ---------------------------------- | 102| [NonSendableBucket](#nonsendablebucket) | Data that cannot be passed across threads.| 103 104**Error codes** 105 106For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [RDB Store Error Codes](errorcode-data-rdb.md). 107 108| **ID**| **Error Message** | 109| ------------ | ------------------------------------------------------------------------------------------------------------- | 110| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 111| 14800000 | Inner error. | 112 113**Example** 114 115```ts 116const asset1: sendableRelationalStore.NonSendableAsset = { 117 name: 'hangman', 118 uri: '//path/example', 119 path: '//path/example', 120 createTime: 'createTime1', 121 modifyTime: 'modifyTime1', 122 size: 'size1' 123}; 124const asset2: sendableRelationalStore.NonSendableAsset = { 125 name: 'hangman', 126 uri: '//path/example', 127 path: '//path/example', 128 createTime: 'createTime1', 129 modifyTime: 'modifyTime1', 130 size: 'size1' 131}; 132const u8 = new Uint8Array([1, 2, 3]); 133 134const sendableValuesBucket = sendableRelationalStore.toSendableValuesBucket({ 135 age: 18, 136 name: "hangman", 137 salary: 100.5, 138 passed: true, 139 data1: asset1, 140 blobType: u8, 141 bigValue: BigInt("15822401018187971961171"), 142 data2: [asset1, asset2] 143}); 144const nonSendableBucket = sendableRelationalStore.fromSendableValuesBucket(sendableValuesBucket); 145``` 146 147## sendableRelationalStore.toSendableAsset 148 149function toSendableAsset(asset: NonSendableAsset): Asset 150 151Converts the asset data that cannot be passed across threads into the data that can be passed across threads. 152 153**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 154 155**Parameters** 156 157| Name| Type | Mandatory| Description | 158| ------ | -------------------------------------- | ---- | :-------------------------- | 159| asset | [NonSendableAsset](#nonsendablebucket) | Yes | Asset data that cannot be passed across threads.| 160 161**Return value** 162 163| Type | Description | 164| --------------- | ------------------------- | 165| [Asset](#asset) | Asset data that can be passed across threads.| 166 167**Error codes** 168 169For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [RDB Store Error Codes](errorcode-data-rdb.md). 170 171| **ID**| **Error Message** | 172| ------------ | ------------------------------------------------------------------------------------------------------------- | 173| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 174| 14800000 | Inner error. | 175 176**Example** 177 178```ts 179const asset1: sendableRelationalStore.NonSendableAsset = { 180 name: 'hangman', 181 uri: '//path/example', 182 path: '//path/example', 183 createTime: 'createTime1', 184 modifyTime: 'modifyTime1', 185 size: 'size1' 186}; 187const sendableAsset = sendableRelationalStore.toSendableAsset(asset1); 188``` 189 190## sendableRelationalStore.fromSendableAsset 191 192function fromSendableAsset(asset: Asset): NonSendableAsset 193 194Converts the asset data that can be passed across threads into the data that cannot be passed across threads. 195 196**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 197 198**Parameters** 199 200| Name| Type | Mandatory| Description | 201| ------ | --------------- | ---- | :------------------------ | 202| asset | [Asset](#asset) | Yes | Asset data that can be passed across threads.| 203 204**Return value** 205 206| Type | Description | 207| -------------------------------------- | --------------------------- | 208| [NonSendableAsset](#nonsendablebucket) | Asset data that cannot be passed across threads.| 209 210**Error codes** 211 212For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [RDB Store Error Codes](errorcode-data-rdb.md). 213 214| **ID**| **Error Message** | 215| ------------ | ------------------------------------------------------------------------------------------------------------- | 216| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 217| 14800000 | Inner error. | 218 219**Example** 220 221```ts 222const asset1: sendableRelationalStore.NonSendableAsset = { 223 name: 'hangman', 224 uri: '//path/example', 225 path: '//path/example', 226 createTime: 'createTime1', 227 modifyTime: 'modifyTime1', 228 size: 'size1' 229}; 230const sendableAsset = sendableRelationalStore.toSendableAsset(asset1); 231const normalAsset = sendableRelationalStore.fromSendableAsset(sendableAsset); 232``` 233 234## sendableRelationalStore.fromSendableValues<sup>20+</sup> 235 236fromSendableValues(values: collections.Array\<ValueType>): NonSendableValues 237 238Converts the array data that can be passed across threads into the data that cannot be passed across threads. 239 240**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 241 242**Parameters** 243 244| Name| Type | Mandatory| Description | 245| ------ | --------------- | ---- | :------------------------ | 246| values | collections.Array\<[ValueType](arkts-apis-data-relationalStore-t.md#valuetype)> | Yes | Array data that can be passed across threads.| 247 248**Return value** 249 250| Type | Description | 251| -------------------------------------- | --------------------------- | 252| [NonSendableValues](#nonsendablevalues20) | Array data that cannot be passed across threads.| 253 254**Error codes** 255 256For details about the error codes, see [RDB Error Codes](errorcode-data-rdb.md). 257 258| **ID**| **Error Message** | 259| ------------ | ------------------------------------------------------------------------------------------------------------- | 260| 14800000 | Inner error. | 261 262**Example** 263 264```ts 265import { sendableRelationalStore } from '@kit.ArkData'; 266import { collections } from '@kit.ArkTS'; 267const array = new collections.Array<sendableRelationalStore.ValueType>(); 268array.push("a"); 269array.push("b"); 270array.push(1); 271array.push(2); 272const values = sendableRelationalStore.fromSendableValues(array); 273``` 274 275## sendableRelationalStore.toSendableValues<sup>20+</sup> 276 277toSendableValues(values: NonSendableValues): collections.Array\<ValueType> 278 279Converts the array data that cannot be passed across threads into the data that can be passed across threads. 280 281**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 282 283**Parameters** 284 285| Name| Type | Mandatory| Description | 286| ------ | --------------- | ---- | :------------------------ | 287| values | [NonSendableValues](#nonsendablevalues20) | Yes | Array data that cannot be passed across threads.| 288 289**Return value** 290 291| Type | Description | 292| -------------------------------------- | --------------------------- | 293| collections.Array\<[ValueType](arkts-apis-data-relationalStore-t.md#valuetype)> | Array data that can be passed across threads.| 294 295**Error codes** 296 297For details about the error codes, see [RDB Error Codes](errorcode-data-rdb.md). 298 299| **ID**| **Error Message** | 300| ------------ | ------------------------------------------------------------------------------------------------------------- | 301| 14800000 | Inner error. | 302 303**Example** 304 305```ts 306import { relationalStore, sendableRelationalStore } from '@kit.ArkData'; 307const array: relationalStore.ValueType[] = []; 308array.push(1); 309array.push(2); 310array.push("aaaaaa") 311const values = sendableRelationalStore.toSendableValues(array); 312``` 313 314## Asset 315 316Represent the asset (such as a document, image, or video). **Asset** inherits from [lang.ISendable](../apis-arkts/js-apis-arkts-lang.md#langisendable) and is used to implement cross-thread transfer of asset data. The asset data does not support **Datashare** APIs. Use [sendableRelationalStore.toSendableAsset](#sendablerelationalstoretosendableasset) to create an **Asset** instance. 317 318**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 319 320| Name | Type | Read-Only| Optional| Description | 321| ---------- | ------ | --- | ---- | ---------------------------------- | 322| name | string | No | No | Asset name. | 323| uri | string | No | No | Asset URI, which is an absolute path in the system. | 324| path | string | No | No | Application sandbox path of the asset. | 325| createTime | string | No | No | Time when the asset was created. | 326| modifyTime | string | No | No | Time when the asset was last modified. | 327| size | string | No | No | Size of the asset. | 328| status | number | No | Yes | Asset status. For details, see [relationalStore.AssetStatus](arkts-apis-data-relationalStore-e.md#assetstatus10). The default value is **relationalStore.AssetStatus.ASSET_NORMAL**.| 329 330 331## Assets 332 333type Assets = collections.Array\<Asset> 334 335Represent an array of [Assets](#asset), which allows assets to be passed across threads. 336 337**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 338 339| Type | Description | 340| -------------------------------------------------------------------------------------------------- | --------------------------------- | 341| [collections.Array](../apis-arkts/js-apis-arkts-collections.md#collectionsarray)\<[Asset](#asset)> | Array of assets.| 342 343## ValueType 344 345type ValueType = null | number | string | boolean | collection.Uint8Array | Asset | Assets | collection.Float32Array | bigint 346 347Defines the types of the value in a KV pair. The type varies with the parameter function. 348 349**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 350 351| Type | Description | 352| ------- | -------------------- | 353| null | The value is null. | 354| number | The value is a number. | 355| string | The value is a string.| 356| boolean | The value is **true** or **false**.| 357| [collection.Uint8Array](../apis-arkts/js-apis-arkts-collections.md#collectionstypedarray) | The value is a Uint8 array.| 358| [Asset](#asset) | The value is an asset.<br>If the value type is **Asset**, the type in the SQL statement for creating a table must be **ASSET**. | 359| [Assets](#assets) | The value is an array of assets.<br>If the value type is **Assets**, the type in the SQL statement for creating a table must be **ASSETS**.| 360| [collection.Float32Array](../apis-arkts/js-apis-arkts-collections.md#collectionstypedarray) | The value is an array of 32-bit floating-point numbers.<br>If the value type is **collection.Float32Array**, the type in the SQL statement for creating a table must be **floatvector(128)**.| 361| bigint | The value is an integer of any length.<br>If the value type is bigint, the type in the SQL statement for creating a table must be **UNLIMITED INT**. For details, see [Persisting RDB Store Data](../../database/data-persistence-by-rdb-store.md).<br>**NOTE**<br>The bigint type does not support value comparison and cannot be used with the following predicates: **between**, **notBetween**, **greaterThan**, **lessThan**, **greaterThanOrEqualTo**, **lessThanOrEqualTo**, **orderByAsc**, and **orderByDesc**<br>To write a value of bigint type, use **BigInt()** or add **n** to the end of the value, for example,'let data = BigInt(1234)' or 'let data = 1234n'.<br>If data of the number type is written to a bigint field, the type of the return value obtained (queried) is number but not bigint. | 362 363## ValuesBucket 364 365type ValuesBucket = collections.Map<string, ValueType> 366 367Represents the KV pair of the [ValueType](#valuetype) data that can be passed across threads. 368 369**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 370 371| Type | Description | 372| ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | 373| [collections.Map](../apis-arkts/js-apis-arkts-collections.md#collectionsmap)<string, [ValueType](#valuetype)> | KV pair that can be passed across threads. The key must be a string, and the value is of the **ValueType** type.| 374 375## NonSendableBucket 376 377type NonSendableBucket = relationalStore.ValuesBucket 378 379Represents the KV pair that cannot be passed across threads. 380 381**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 382 383| Type | Description | 384| ------------------------------------------------------------------------------ | ---------------------------- | 385| [relationalStore.ValuesBucket](arkts-apis-data-relationalStore-t.md#valuesbucket) | KV pair that cannot be passed across threads.| 386 387## NonSendableValues<sup>20+</sup> 388 389type NonSendableValues = Array\<relationalStore.ValueType> 390 391Represents the [ValueType](arkts-apis-data-relationalStore-t.md#valuetype) array that cannot be passed across threads. 392 393**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 394 395| Type | Description | 396| ------------------------------------------------------------------ | ------------------------------ | 397| Array\<[relationalStore.ValueType](arkts-apis-data-relationalStore-t.md#valuetype)> | Array that cannot be passed across threads. The value type is **ValueType**.| 398 399## NonSendableAsset 400 401type NonSendableAsset = relationalStore.Asset 402 403Represents the asset (such as a document, image, or video) that cannot be passed across threads. 404 405**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 406 407| Type | Description | 408| ------------------------------------------------------------------ | ------------------------------ | 409| [relationalStore.Asset](arkts-apis-data-relationalStore-i.md#asset10) | Asset that cannot be passed across threads.| 410 411## Example of Cross-Thread Data Passing 412 413When invoking TaskPool for data insertion, the main thread calls the **toSendableValuesBucket** method to convert data into a cross-thread transferable type, which is then passed to TaskPool for processing. 414 415When invoking TaskPool for data query operations, call the **getSendableRow** method of **ResultSet** to obtain cross-thread transferable data rows, which are then returned to the main thread. In the main thread, invoke the **fromSendableValuesBucket** method to convert these rows into the standard **ValuesBucket** format for subsequent processing. 416 417```ts 418// Index.ets 419import { relationalStore, sendableRelationalStore } from '@kit.ArkData'; 420import { taskpool } from '@kit.ArkTS'; 421 422@Concurrent 423async function insert(context: Context, dataItem: sendableRelationalStore.ValuesBucket) { 424 const CONFIG: relationalStore.StoreConfig = { 425 name: "Store.db", 426 securityLevel: relationalStore.SecurityLevel.S3, 427 }; 428 429 let store = await relationalStore.getRdbStore(context, CONFIG); 430 console.info(`Get store successfully!`); 431 432 const CREATE_TABLE_SQL = "CREATE TABLE IF NOT EXISTS test (" + 433 "id INTEGER PRIMARY KEY AUTOINCREMENT, " + 434 "name TEXT NOT NULL, " + 435 "age INTEGER, " + 436 "salary REAL, " + 437 "blobType BLOB)"; 438 await store.executeSql(CREATE_TABLE_SQL); 439 console.info(`Create table test successfully!`); 440 441 // Insert data. 442 const rowId = await store.insertSync("test", dataItem); 443 await store.close(); 444 return rowId; 445} 446 447@Concurrent 448async function queryByName(context: Context, name: string) { 449 const CONFIG: relationalStore.StoreConfig = { 450 name: "Store.db", 451 securityLevel: relationalStore.SecurityLevel.S3, 452 }; 453 454 let store = await relationalStore.getRdbStore(context, CONFIG); 455 console.info(`Get store successfully!`); 456 457 const predicates = new relationalStore.RdbPredicates("test"); 458 predicates.equalTo("name", name); 459 460 const resultSet = await store.query(predicates); 461 if (resultSet.rowCount > 0 && resultSet.goToFirstRow()) { 462 // Obtain the cross-thread transferable ValuesBucket to return the query result. 463 return resultSet.getSendableRow(); 464 } 465 return null; 466} 467 468 469@Entry 470@Component 471struct Index { 472 @State message: string = 'Hello World'; 473 474 build() { 475 RelativeContainer() { 476 Text(this.message) 477 .id('HelloWorld') 478 .fontSize(50) 479 .fontWeight(FontWeight.Bold) 480 .alignRules({ 481 center: { anchor: '__container__', align: VerticalAlign.Center }, 482 middle: { anchor: '__container__', align: HorizontalAlign.Center } 483 }) 484 .onClick(async () => { 485 let context: Context = this.getUIContext().getHostContext() as Context; 486 487 const item: relationalStore.ValuesBucket = { 488 name: "zhangsan", 489 age: 20, 490 salary: 5000 491 } 492 // Call toSendableValuesBucket to convert the data type for cross-thread passing. 493 const sendableItem = sendableRelationalStore.toSendableValuesBucket(item); 494 const insertRowId = await taskpool.execute(insert, context, sendableItem) as number; 495 console.info(`Insert data success, row id is: ${insertRowId}`); 496 497 const rowData = await taskpool.execute(queryByName, context, "zhangsan"); 498 if (rowData) { 499 const row = 500 sendableRelationalStore.fromSendableValuesBucket(rowData as sendableRelationalStore.ValuesBucket); 501 console.info(`Query success, name is ${row['name']}, age is ${row['age']}.`); 502 } else { 503 console.error(`Query failed.`) 504 } 505 }) 506 } 507 .height('100%') 508 .width('100%') 509 } 510} 511``` 512