1# @ohos.data.sendableRelationalStore (共享关系型数据库)
2
3该模块针对关系型数据库（Relational Database，RDB）提供了sendable支持。支持从查询结果集中获取sendable类型ValuesBucket用于并发实例间传递。
4
5> **说明：**
6>
7> 本模块首批接口从API version 12开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
8
9## 导入模块
10
11```ts
12import { sendableRelationalStore } from '@kit.ArkData';
13```
14
15## sendableRelationalStore.toSendableValuesBucket
16
17toSendableValuesBucket(valuesBucket: NonSendableBucket): ValuesBucket
18
19将不能用于跨线程传递的键值对数据，转换为可用于跨线程传递的键值对数据。
20
21**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core
22
23**参数：**
24
25| 参数名       | 类型                                    | 必填 | 说明                               |
26| ------------ | --------------------------------------- | ---- | :--------------------------------- |
27| valuesBucket | [NonSendableBucket](#nonsendablebucket) | 是   | 不可跨线程传递的ValuesBucket数据。 |
28
29**返回值**：
30
31| 类型                          | 说明                                 |
32| ----------------------------- | ------------------------------------ |
33| [ValuesBucket](#valuesbucket) | 可用于跨线程传递的ValuesBucket数据。 |
34
35**错误码：**
36
37以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。
38
39| **错误码ID** | **错误信息**                                                                                                                                    |
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**示例：**
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
82将可用于跨线程传递的键值对数据，转换为不能用于跨线程传递的键值对数据。
83
84**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core
85
86**参数：**
87
88| 参数名       | 类型                          | 必填 | 说明                                 |
89| ------------ | ----------------------------- | ---- | :----------------------------------- |
90| valuesBucket | [ValuesBucket](#valuesbucket) | 是   | 可用于跨线程传递的ValuesBucket数据。 |
91
92**返回值**：
93
94| 类型                                    | 说明                               |
95| --------------------------------------- | ---------------------------------- |
96| [NonSendableBucket](#nonsendablebucket) | 不可跨线程传递的ValuesBucket数据。 |
97
98**错误码：**
99
100以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。
101
102| **错误码ID** | **错误信息**                                                                                                  |
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**示例：**
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
145将不可跨线程传递的附件数据，转换为可跨线程传递的附件数据。
146
147**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core
148
149**参数：**
150
151| 参数名 | 类型                                   | 必填 | 说明                        |
152| ------ | -------------------------------------- | ---- | :-------------------------- |
153| asset  | [NonSendableAsset](#nonsendablebucket) | 是   | 不可跨线程传递的Asset数据。 |
154
155**返回值**：
156
157| 类型            | 说明                      |
158| --------------- | ------------------------- |
159| [Asset](#asset) | 可跨线程传递的Asset数据。 |
160
161以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。
162
163| **错误码ID** | **错误信息**                                                                                                  |
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**示例：**
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
186将可跨线程传递的附件数据，转换为不可跨线程传递的附件数据。
187
188**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core
189
190**参数：**
191
192| 参数名 | 类型            | 必填 | 说明                      |
193| ------ | --------------- | ---- | :------------------------ |
194| asset  | [Asset](#asset) | 是   | 可跨线程传递的Asset数据。 |
195
196**返回值**：
197
198| 类型                                   | 说明                        |
199| -------------------------------------- | --------------------------- |
200| [NonSendableAsset](#nonsendablebucket) | 不可跨线程传递的Asset数据。 |
201
202
203以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[关系型数据库错误码](errorcode-data-rdb.md)。
204
205| **错误码ID** | **错误信息**                                                                                                  |
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**示例：**
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
227记录资产附件（文件、图片、视频等类型文件）的相关信息。用于支持资产数据跨线程传递，继承自[lang.ISendable](../apis-arkts/js-apis-arkts-lang.md#langisendable)。资产类型的相关接口暂不支持Datashare。使用[sendableRelationalStore.toSendableAsset](#sendablerelationalstoretosendableasset)方法创建。
228
229**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core
230
231| 名称       | 类型   | 只读 | 可选 | 说明                               |
232| ---------- | ------ | ---  | ---- | ---------------------------------- |
233| name       | string | 否   | 否   | 资产的名称。                       |
234| uri        | string | 否   | 否   | 资产的uri，在系统里的绝对路径。    |
235| path       | string | 否   | 否   | 资产在应用沙箱里的路径。           |
236| createTime | string | 否   | 否   | 资产被创建出来的时间。             |
237| modifyTime | string | 否   | 否   | 资产最后一次被修改的时间。         |
238| size       | string | 否   | 否   | 资产占用空间的大小。               |
239| status     | number | 否   | 是   | 资产的状态, 取值与[relationalStore.AssetStatus](./js-apis-data-relationalStore.md#assetstatus10)枚举值保持一致，默认值为relationalStore.AssetStatus.ASSET_NORMAL。|
240
241
242## Assets
243
244type Assets = collections.Array\<Asset>
245
246表示[Asset](#asset)类型数据的集合。用于支持Asset数据集合跨线程传递。
247
248**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core
249
250| 类型                                                                                               | 说明                              |
251| -------------------------------------------------------------------------------------------------- | --------------------------------- |
252| [collections.Array](../apis-arkts/js-apis-arkts-collections.md#collectionsarray)\<[Asset](#asset)> | 用于并发场景的Asset附件数据集合。 |
253
254## ValueType
255
256type ValueType = null | number | string | boolean | collection.Uint8Array | Asset | Assets | collection.Float32Array | bigint
257
258用于表示允许的数据字段类型，接口参数具体类型根据其功能而定。
259
260**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core
261
262| 类型    | 说明                 |
263| ------- | -------------------- |
264| null    | 表示值类型为空。     |
265| number  | 表示值类型为数字。   |
266| string  | 表示值类型为字符串。 |
267| boolean | 表示值类型为布尔值。 |
268| [collection.Uint8Array](../apis-arkts/js-apis-arkts-collections.md#collectionstypedarray) | 表示值类型为Uint8类型的数组。|
269| [Asset](#asset)  | 表示值类型为附件Asset。<br/>当字段类型是Asset时，在创建表的sql语句中，类型应当为：ASSET。             |
270| [Assets](#assets) | 表示值类型为附件数据集合Assets。<br/>当字段类型是Assets时，在创建表的sql语句中，类型应当为：ASSETS。 |
271| [collection.Float32Array](../apis-arkts/js-apis-arkts-collections.md#collectionstypedarray) | 表示值类型为浮点数组。<br/>当字段类型是collection.Float32Array时，在创建表的sql语句中，类型应当为：floatvector(128)。 |
272| bigint | 表示值类型为任意长度的整数。<br/>当字段类型是bigint时，在创建表的sql语句中，类型应当为：UNLIMITED INT, 详见[通过关系型数据库实现数据持久化](../../database/data-persistence-by-rdb-store.md)。<br/>**说明：** bigint类型当前不支持比较大小，不支持如下谓词：between、notBetween、greaterThanlessThan、greaterThanOrEqualTo、lessThanOrEqualTo、orderByAsc、orderByDesc。<br/>bigint类型字段的数据写入时，需通过BigInt()方法或在数据尾部添加'n'的方式明确为bigint类型，如'let data = BigInt(1234)'或'let data = 1234n'。<br/>bigint字段如果写入number类型的数据，则查询该数据的返回类型为number，而非bigint。 |
273
274## ValuesBucket
275
276type ValuesBucket = collections.Map<string, ValueType>
277
278表示[ValueType](#valuetype)数据的键值对存储，用于支持ValueType数据跨线程传递。
279
280**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core
281
282| 类型                                                                                                          | 说明                                                                    |
283| ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
284| [collections.Map](../apis-arkts/js-apis-arkts-collections.md#collectionsmap)<string, [ValueType](#valuetype)> | 并发场景的键值对数据存储，其中，键的类型为string，值的类型为ValueType。 |
285
286## NonSendableBucket
287
288type NonSendableBucket = relationalStore.ValuesBucket
289
290用于存储键值对的类型。不支持跨线程传递。
291
292**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core
293
294| 类型                                                                           | 说明                         |
295| ------------------------------------------------------------------------------ | ---------------------------- |
296| [relationalStore.ValuesBucket](./js-apis-data-relationalStore.md#valuesbucket) | 非并发场景的键值对数据存储。 |
297
298## NonSendableAsset
299
300type NonSendableAsset = relationalStore.Asset
301
302记录资产附件（文件、图片、视频等类型文件）的相关信息。不支持跨线程传递。
303
304**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core
305
306| 类型                                                               | 说明                           |
307| ------------------------------------------------------------------ | ------------------------------ |
308| [relationalStore.Asset](./js-apis-data-relationalStore.md#asset10) | 非并发场景的资产附件数据存储。 |