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## Modules to Import
10
11```ts
12import { sendableRelationalStore } from '@kit.ArkData';
13```
14
15## sendableRelationalStore.toSendableValuesBucket
16
17toSendableValuesBucket(valuesBucket: NonSendableBucket): ValuesBucket
18
19Converts a key-value (KV) pair that cannot be transferred across threads into the data that can be transferred across threads.
20
21**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core
22
23**Parameters**
24
25| Name      | Type                                   | Mandatory | Description                              |
26| ------------ | --------------------------------------- | ---- | :--------------------------------- |
27| valuesBucket | [NonSendableBucket](#nonsendablebucket) | Yes  | Data that cannot be transferred across threads. |
28
29**Return value**
30
31| Type                         | Description                                |
32| ----------------------------- | ------------------------------------ |
33| [ValuesBucket](#valuesbucket) | Data that can be transferred across threads. |
34
35**Error codes**
36
37For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [RDB Store Error Codes](errorcode-data-rdb.md).
38
39| **Error Code** | **Error Message**                                                                                                                                   |
40| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
41| 401          | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
42| 14800000     | Inner error.                                                                                                                                    |
43
44**Example**
45
46```ts
47const asset1: sendableRelationalStore.NonSendableAsset = {
48  name: 'hangman',
49  uri: '//path/example',
50  path: '//path/example',
51  createTime: 'createTime1',
52  modifyTime: 'modifyTime1',
53  size: 'size1',
54};
55const asset2: sendableRelationalStore.NonSendableAsset = {
56  name: 'hangman',
57  uri: '//path/example',
58  path: '//path/example',
59  createTime: 'createTime1',
60  modifyTime: 'modifyTime1',
61  size: 'size1',
62}
63const u8 = new Uint8Array([1, 2, 3]);
64const valuesBucket: sendableRelationalStore.NonSendableBucket = {
65  age: 18,
66  name: "hangman",
67  salary: 100.5,
68  passed: true,
69  data1: asset1,
70  blobType: u8,
71  bigValue: BigInt("15822401018187971961171"),
72  data2: [asset1, asset2],
73};
74
75const sendableValuesBucket = sendableRelationalStore.toSendableValuesBucket(valuesBucket);
76```
77
78## sendableRelationalStore.fromSendableValuesBucket
79
80fromSendableValuesBucket(valuesBucket: ValuesBucket): NonSendableBucket
81
82Converts a KV pair that can be transferred across threads into the data that cannot be transferred across threads.
83
84**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core
85
86**Parameters**
87
88| Name      | Type                         | Mandatory | Description                                |
89| ------------ | ----------------------------- | ---- | :----------------------------------- |
90| valuesBucket | [ValuesBucket](#valuesbucket) | Yes  | Data that can be transferred across threads. |
91
92**Return value**
93
94| Type                                   | Description                              |
95| --------------------------------------- | ---------------------------------- |
96| [NonSendableBucket](#nonsendablebucket) | Data that cannot be transferred across threads. |
97
98**Error codes**
99
100For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [RDB Store Error Codes](errorcode-data-rdb.md).
101
102| **Error Code** | **Error Message**                                                                                                 |
103| ------------ | ------------------------------------------------------------------------------------------------------------- |
104| 401          | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
105| 14800000     | Inner error.                                                                                                  |
106
107**Example**
108
109```ts
110const asset1: sendableRelationalStore.NonSendableAsset = {
111  name: 'hangman',
112  uri: '//path/example',
113  path: '//path/example',
114  createTime: 'createTime1',
115  modifyTime: 'modifyTime1',
116  size: 'size1',
117};
118const asset2: sendableRelationalStore.NonSendableAsset = {
119  name: 'hangman',
120  uri: '//path/example',
121  path: '//path/example',
122  createTime: 'createTime1',
123  modifyTime: 'modifyTime1',
124  size: 'size1',
125}
126const u8 = new Uint8Array([1, 2, 3]);
127
128const sendableValuesBucket = sendableRelationalStore.toSendableValuesBucket({
129  age: 18,
130  name: "hangman",
131  salary: 100.5,
132  passed: true,
133  data1: asset1,
134  blobType: u8,
135  bigValue: BigInt("15822401018187971961171"),
136  data2: [asset1, asset2],
137});
138const nonSendableBucket = sendableRelationalStore.fromSendableValuesBucket(sendableValuesBucket);
139```
140
141## sendableRelationalStore.toSendableAsset
142
143function toSendableAsset(asset: NonSendableAsset): Asset
144
145Converts the asset data that cannot be transferred across threads into the data that can be transferred across threads.
146
147**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core
148
149**Parameters**
150
151| Name | Type                                  | Mandatory | Description                       |
152| ------ | -------------------------------------- | ---- | :-------------------------- |
153| asset  | [NonSendableAsset](#nonsendablebucket) | Yes  | Asset data that cannot be transferred across threads. |
154
155**Return value**
156
157| Type           | Description                     |
158| --------------- | ------------------------- |
159| [Asset](#asset) | Asset data that can be transferred across threads. |
160
161For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [RDB Store Error Codes](errorcode-data-rdb.md).
162
163| **Error Code** | **Error Message**                                                                                                 |
164| ------------ | ------------------------------------------------------------------------------------------------------------- |
165| 401          | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
166| 14800000     | Inner error.                                                                                                  |
167
168**Example**
169
170```ts
171const asset1: sendableRelationalStore.NonSendableAsset = {
172  name: 'hangman',
173  uri: '//path/example',
174  path: '//path/example',
175  createTime: 'createTime1',
176  modifyTime: 'modifyTime1',
177  size: 'size1',
178};
179const sendableAsset = sendableRelationalStore.toSendableAsset(asset1);
180```
181
182## sendableRelationalStore.fromSendableAsset
183
184function fromSendableAsset(asset: Asset): NonSendableAsset
185
186Converts the asset data that can be transferred across threads into the data that cannot be transferred across threads.
187
188**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core
189
190**Parameters**
191
192| Name | Type           | Mandatory | Description                     |
193| ------ | --------------- | ---- | :------------------------ |
194| asset  | [Asset](#asset) | Yes  | Asset data that can be transferred across threads. |
195
196**Return value**
197
198| Type                                  | Description                       |
199| -------------------------------------- | --------------------------- |
200| [NonSendableAsset](#nonsendablebucket) | Asset data that cannot be transferred across threads. |
201
202
203For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [RDB Store Error Codes](errorcode-data-rdb.md).
204
205| **Error Code** | **Error Message**                                                                                                 |
206| ------------ | ------------------------------------------------------------------------------------------------------------- |
207| 401          | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
208| 14800000     | Inner error.                                                                                                  |
209
210**Example**
211
212```ts
213const asset1: sendableRelationalStore.NonSendableAsset = {
214  name: 'hangman',
215  uri: '//path/example',
216  path: '//path/example',
217  createTime: 'createTime1',
218  modifyTime: 'modifyTime1',
219  size: 'size1',
220};
221const sendableAsset = sendableRelationalStore.toSendableAsset(asset1);
222const normalAsset = sendableRelationalStore.fromSendableAsset(sendableAsset);
223```
224
225## Asset
226
227Represent information about an asset (such as a document, image, and 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.
228
229**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core
230
231| Name      | Type  | Read-Only | Optional | Description                              |
232| ---------- | ------ | ---  | ---- | ---------------------------------- |
233| name       | string | No  | No  | Asset name.                      |
234| uri        | string | No  | No  | Asset URI, which is an absolute path in the system.   |
235| path       | string | No  | No  | Application sandbox path of the asset.          |
236| createTime | string | No  | No  | Time when the asset was created.            |
237| modifyTime | string | No  | No  | Time when the asset was last modified.        |
238| size       | string | No  | No  | Size of the asset.              |
239| status     | number | No  | Yes  | Asset status. For details, see [relationalStore.AssetStatus](./js-apis-data-relationalStore.md#assetstatus10). The default value is **relationalStore.AssetStatus.ASSET_NORMAL**.|
240
241
242## Assets
243
244type Assets = collections.Array\<Asset>
245
246Represent an array of [Assets](#asset), which allows assets to be transferred across threads.
247
248**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core
249
250| Type                                                                                              | Description                             |
251| -------------------------------------------------------------------------------------------------- | --------------------------------- |
252| [collections.Array](../apis-arkts/js-apis-arkts-collections.md#collectionsarray)\<[Asset](#asset)> | Array of assets. |
253
254## ValueType
255
256type ValueType = null | number | string | boolean | collection.Uint8Array | Asset | Assets | collection.Float32Array | bigint
257
258Enumerates the types of the value in a KV pair. The type varies with the parameter function.
259
260**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core
261
262| Type   | Description                |
263| ------- | -------------------- |
264| null    | The value is null.    |
265| number  | The value is a number.  |
266| string  | The value is a string. |
267| boolean | The value is **true** or **false**. |
268| [collection.Uint8Array](../apis-arkts/js-apis-arkts-collections.md#collectionstypedarray) | The value is a Uint8 array.|
269| [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**.            |
270| [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**. |
271| [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)**. |
272| 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**, **greaterThanlessThan**, **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. |
273
274## ValuesBucket
275
276type ValuesBucket = collections.Map<string, ValueType>
277
278Represents the KV pair that can be transferred across threads.
279
280**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core
281
282| Type                                                                                                         | Description                                                                   |
283| ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
284| [collections.Map](../apis-arkts/js-apis-arkts-collections.md#collectionsmap)<string, [ValueType](#valuetype)> | KV pair that can be transferred across threads. The key must be a string, and the value is of the **ValueType** type. |
285
286## NonSendableBucket
287
288type NonSendableBucket = relationalStore.ValuesBucket
289
290Represents the KV pair that cannot be transferred across threads
291
292**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core
293
294| Type                                                                          | Description                        |
295| ------------------------------------------------------------------------------ | ---------------------------- |
296| [relationalStore.ValuesBucket](./js-apis-data-relationalStore.md#valuesbucket) | KV pair that cannot be transferred across threads. |
297
298## NonSendableAsset
299
300type NonSendableAsset = relationalStore.Asset
301
302Represent the asset (such as a document, image, and video) that cannot be transferred across threads
303
304**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core
305
306| Type                                                              | Description                          |
307| ------------------------------------------------------------------ | ------------------------------ |
308| [relationalStore.Asset](./js-apis-data-relationalStore.md#asset10) | Asset that cannot be transferred across threads. |
309