1# @ohos.data.dataShareResultSet (数据共享结果集)(系统接口)
2
3**结果集(DataShareResultSet)** 可提供访问由查询数据库生成的结果集的相关方法，根据提供的行数，查询相应的值，也可查询指定数据类型的值。
4
5> **说明：**
6>
7> - 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
8>
9> - 本模块接口为系统接口。
10>
11> - 本模块接口仅可在Stage模型下使用。
12>
13> - 数据共享结果集在全系统最多同时存在32个，使用完及时释放。
14
15## 导入模块
16
17```ts
18import { DataShareResultSet } from '@kit.ArkData';
19```
20
21## 使用说明
22
23需要通过调用[query](js-apis-data-dataShare-sys.md#query)接口获取DataShareResultSet对象。
24
25```ts
26import { DataShareResultSet, dataShare, dataSharePredicates } from '@kit.ArkData';
27import { BusinessError } from '@kit.BasicServicesKit'
28import { UIAbility } from '@kit.AbilityKit';
29
30let dataShareHelper: dataShare.DataShareHelper | undefined = undefined;
31let uri = ("datashare:///com.samples.datasharetest.DataShare");
32let context = getContext(UIAbility);
33dataShare.createDataShareHelper(context, uri, (err:BusinessError, data:dataShare.DataShareHelper) => {
34  if (err != undefined) {
35    console.error("createDataShareHelper fail, error message : " + err);
36  } else {
37    console.info("createDataShareHelper end, data : " + data);
38    dataShareHelper = data;
39  }
40});
41
42let columns = ["*"];
43let da = new dataSharePredicates.DataSharePredicates();
44let resultSet: DataShareResultSet | undefined = undefined;
45da.equalTo("name", "ZhangSan");
46if (dataShareHelper != undefined) {
47  (dataShareHelper as dataShare.DataShareHelper).query(uri, da, columns).then((data: DataShareResultSet) => {
48    console.info("query end, data : " + data);
49    resultSet = data;
50  }).catch((err: BusinessError) => {
51    console.error("query fail, error message : " + err);
52  });
53}
54```
55
56## DataShareResultSet
57提供通过查询数据库生成的结果集的相关访问方法。
58
59列或键名称作为字符串数组返回，其中字符串的顺序与结果集中的列或键的顺序相同。
60
61### 属性
62
63**系统能力：**  SystemCapability.DistributedDataManager.DataShare.Core
64
65| 名称        | 类型      | 必填 | 说明                     |
66| ----------- | ------------- | ---- | ------------------------ |
67| columnNames | Array<string> | 是   | 结果集中所有列的名称。   |
68| columnCount | number        | 是   | 结果集中的列数。         |
69| rowCount    | number        | 是   | 结果集中的行数。         |
70| isClosed    | boolean       | 是   | 标识当前结果集是否关闭。 |
71
72### goToFirstRow
73
74goToFirstRow(): boolean
75
76转到结果集的第一行。
77
78**系统能力：** SystemCapability.DistributedDataManager.DataShare.Core
79
80**返回值：**
81
82| 类型    | 说明                                          |
83| :------ | --------------------------------------------- |
84| boolean | 如果成功移动结果集，则为true；否则返回false。 |
85
86**示例：**
87
88```ts
89// resultSet需依照本页的使用说明进行创建。
90if (resultSet != undefined) {
91  let isGoToFirstRow = (resultSet as DataShareResultSet).goToFirstRow();
92  console.info('resultSet.goToFirstRow: ' + isGoToFirstRow);
93}
94```
95
96### goToLastRow
97
98goToLastRow(): boolean
99
100转到结果集的最后一行。
101
102**系统能力：**  SystemCapability.DistributedDataManager.DataShare.Core
103
104**返回值：**
105
106| 类型 | 说明 |
107| -------- | -------- |
108| boolean | 如果成功移动结果集，则为true；否则返回false。 |
109
110**示例：**
111
112```ts
113if (resultSet != undefined) {
114  let isGoToLastRow = (resultSet as DataShareResultSet).goToLastRow();
115  console.info('resultSet.goToLastRow: ' + isGoToLastRow);
116}
117```
118
119### goToNextRow
120
121goToNextRow(): boolean
122
123转到结果集的下一行。
124
125**系统能力：**  SystemCapability.DistributedDataManager.DataShare.Core
126
127**返回值：**
128
129| 类型    | 说明                                          |
130| ------- | --------------------------------------------- |
131| boolean | 如果成功移动结果集，则为true；否则返回false。 |
132
133**示例：**
134
135```ts
136if (resultSet != undefined) {
137  let isGoToNextRow = (resultSet as DataShareResultSet).goToNextRow();
138  console.info('resultSet.goToNextRow: ' + isGoToNextRow);
139}
140```
141
142### goToPreviousRow
143
144goToPreviousRow(): boolean
145
146转到结果集的上一行。
147
148**系统能力：**  SystemCapability.DistributedDataManager.DataShare.Core
149
150**返回值：**
151
152| 类型    | 说明                                          |
153| ------- | --------------------------------------------- |
154| boolean | 如果成功移动结果集，则为true；否则返回false。 |
155
156**示例：**
157
158```ts
159if (resultSet != undefined) {
160  let isGoToPreviousRow = (resultSet as DataShareResultSet).goToPreviousRow();
161  console.info('resultSet.goToPreviousRow: ' + isGoToPreviousRow);
162}
163```
164
165### goTo
166
167goTo(offset: number): boolean
168
169相对于当前位置向前或向后移动指定行数。
170
171**系统能力：**  SystemCapability.DistributedDataManager.DataShare.Core
172
173**参数：**
174
175| **参数名** | **类型** | **必填** | 说明                                                         |
176| ---------- | -------- | -------- | ------------------------------------------------------------ |
177| offset     | number   | 是       | 表示相对于当前位置的偏移量。offset为负值表示向前偏移，正值则表示向后偏移。 |
178
179**返回值：**
180
181| 类型    | 说明                                          |
182| ------- | --------------------------------------------- |
183| boolean | 如果成功移动结果集，则为true；否则返回false。 |
184
185**示例：**
186
187```ts
188let goToNum = 1;
189if (resultSet != undefined) {
190  let isGoTo = (resultSet as DataShareResultSet).goTo(goToNum);
191  console.info('resultSet.goTo: ' + isGoTo);
192}
193```
194
195### goToRow
196
197goToRow(position: number): boolean
198
199转到结果集的指定行。
200
201**系统能力：**  SystemCapability.DistributedDataManager.DataShare.Core
202
203**参数：**
204
205| **参数名** | **类型** | **必填** | 说明                                    |
206| ---------- | -------- | -------- | --------------------------------------- |
207| position   | number   | 是       | 表示要移动到的指定位置，从 0 开始。 |
208
209**返回值：**
210
211| 类型    | 说明                                          |
212| ------- | --------------------------------------------- |
213| boolean | 如果成功移动结果集，则为true；否则返回false。 |
214
215**示例：**
216
217```ts
218let goToRowNum = 2;
219if (resultSet != undefined) {
220  let isGoToRow = (resultSet as DataShareResultSet).goToRow(goToRowNum);
221  console.info('resultSet.goToRow: ' + isGoToRow);
222}
223```
224
225### getBlob
226
227getBlob(columnIndex: number): Uint8Array
228
229以字节数组的形式获取当前行中指定列的值。
230
231如果当前行中指定的列或键的值为空，或者指定的列或键不是Blob类型，则使用方需要确定是否抛出此异常。
232
233**系统能力：**  SystemCapability.DistributedDataManager.DataShare.Core
234
235**参数：**
236
237| **参数名**  | **类型** | **必填** | 说明                    |
238| ----------- | -------- | -------- | ----------------------- |
239| columnIndex | number   | 是       | 指定的列索引，从0开始。 |
240
241**返回值：**
242
243| 类型       | 说明                             |
244| ---------- | -------------------------------- |
245| Uint8Array | 以字节数组的形式返回指定列的值。 |
246
247**示例：**
248
249```ts
250let columnIndex = 1;
251if (resultSet != undefined) {
252  let goToFirstRow = (resultSet as DataShareResultSet).goToFirstRow();
253  let getBlob = (resultSet as DataShareResultSet).getBlob(columnIndex);
254  console.info('resultSet.getBlob: ' + getBlob);
255}
256```
257
258### getString
259
260getString(columnIndex: number): string
261
262以字符串形式获取当前行中指定列的值。
263
264如果当前行中指定的列或键的值为空，或者指定的列或键不是string类型，则使用方需要确定是否抛出此异常。
265
266**系统能力：**  SystemCapability.DistributedDataManager.DataShare.Core
267
268**参数：**
269
270| **参数名**  | **类型** | **必填** | 说明                    |
271| ----------- | -------- | -------- | ----------------------- |
272| columnIndex | number   | 是       | 指定的列索引，从0开始。 |
273
274**返回值：**
275
276| 类型   | 说明                         |
277| ------ | ---------------------------- |
278| string | 以字符串形式返回指定列的值。 |
279
280**示例：**
281
282```ts
283let columnIndex = 1;
284if (resultSet != undefined) {
285  let goToFirstRow = (resultSet as DataShareResultSet).goToFirstRow();
286  let getString = (resultSet as DataShareResultSet).getString(columnIndex);
287  console.info('resultSet.getString: ' + getString);
288}
289```
290
291### getLong
292
293getLong(columnIndex: number): number
294
295以长整数值形式获取当前行中指定列的值。
296
297如果当前行中指定的列或键的值为空，或者指定的列或键不是long类型，则使用方需要确定是否抛出此异常。
298
299**系统能力：**  SystemCapability.DistributedDataManager.DataShare.Core
300
301**参数：**
302
303| **参数名**  | **类型** | **必填** | 说明                    |
304| ----------- | -------- | -------- | ----------------------- |
305| columnIndex | number   | 是       | 指定的列索引，从0开始。 |
306
307**返回值：**
308
309| 类型   | 说明                       |
310| ------ | -------------------------- |
311| number | 以长整数值形式返回指定列的值。 |
312
313**示例：**
314
315```ts
316let columnIndex = 1;
317if (resultSet != undefined) {
318  let goToFirstRow = (resultSet as DataShareResultSet).goToFirstRow();
319  let getLong = (resultSet as DataShareResultSet).getLong(columnIndex);
320  console.info('resultSet.getLong: ' + getLong);
321}
322```
323
324### getDouble
325
326getDouble(columnIndex: number): number
327
328以值类型为双浮点数形式获取当前行中指定列的值。
329
330如果当前行中指定的列或键的值为空，或者指定的列或键不是double类型，则使用方需要确定是否抛出此异常。
331
332**系统能力：**  SystemCapability.DistributedDataManager.DataShare.Core
333
334**参数：**
335
336| **参数名**  | **类型** | **必填** | 说明                    |
337| ----------- | -------- | -------- | ----------------------- |
338| columnIndex | number   | 是       | 指定的列索引，从0开始。 |
339
340**返回值：**
341
342| 类型   | 说明                         |
343| ------ | ---------------------------- |
344| number | 值类型为双浮点数形式返回指定列的值。 |
345
346**示例：**
347
348```ts
349let columnIndex = 1;
350if (resultSet != undefined) {
351  let goToFirstRow = (resultSet as DataShareResultSet).goToFirstRow();
352  let getDouble = (resultSet as DataShareResultSet).getDouble(columnIndex);
353  console.info('resultSet.getDouble: ' + getDouble);
354}
355```
356
357### close
358
359close(): void
360
361关闭结果集。
362
363对结果集调用此方法将释放其所有资源并使其无效。
364
365**系统能力：**  SystemCapability.DistributedDataManager.DataShare.Core
366
367**示例：**
368
369```ts
370if (resultSet != undefined) {
371  (resultSet as DataShareResultSet).close();
372}
373```
374
375### getColumnIndex
376
377getColumnIndex(columnName: string): number
378
379根据指定的列名获取列索引。
380
381列名作为输入参数传递。
382
383**系统能力：**  SystemCapability.DistributedDataManager.DataShare.Core
384
385**参数：**
386
387| **参数名** | **类型** | **必填** | 说明                       |
388| ---------- | -------- | -------- | -------------------------- |
389| columnName | string   | 是       | 表示结果集中指定列的名称。 |
390
391**返回值：**
392
393| 类型   | 说明               |
394| ------ | ------------------ |
395| number | 返回指定列的索引。 |
396
397**示例：**
398
399```ts
400let ColumnName = "name";
401if (resultSet != undefined) {
402  let getColumnIndex = (resultSet as DataShareResultSet).getColumnIndex(ColumnName);
403  console.info('resultSet.getColumnIndex: ' + getColumnIndex);
404}
405```
406
407### getColumnName
408
409getColumnName(columnIndex: number): string
410
411根据指定的列索引获取列名。
412
413列索引作为输入参数传递。
414
415**系统能力：**  SystemCapability.DistributedDataManager.DataShare.Core
416
417**参数：**
418
419| **参数名**  | **类型** | **必填** | 说明                       |
420| ----------- | -------- | -------- | -------------------------- |
421| columnIndex | number   | 是       | 表示结果集中指定列的索引。 |
422
423**返回值：**
424
425| 类型   | 说明               |
426| ------ | ------------------ |
427| string | 返回指定列的名称。 |
428
429**示例：**
430
431```ts
432let columnIndex = 1;
433if (resultSet != undefined) {
434  let getColumnName = (resultSet as DataShareResultSet).getColumnName(columnIndex);
435  console.info('resultSet.getColumnName: ' + getColumnName);
436}
437```
438
439### getDataType
440
441getDataType(columnIndex: number): DataType
442
443指定列索引获取该列的数据类型。
444
445如果当前行中指定的列或键的值为空，或者指定的列或键不是DataType类型，则使用方需要确定是否抛出此异常。
446
447**系统能力：**  SystemCapability.DistributedDataManager.DataShare.Core
448
449**参数：**
450
451| **参数名**  | **类型** | **必填** | 说明                       |
452| ----------- | -------- | -------- | -------------------------- |
453| columnIndex | number   | 是       | 表示结果集中指定列的索引。 |
454
455**返回值：**
456
457| 类型                  | 说明               |
458| --------------------- | ------------------ |
459| [DataType](#datatype) | 返回指定列的类型。 |
460
461**示例：**
462
463```ts
464let columnIndex = 1;
465if (resultSet != undefined) {
466  let getDataType = (resultSet as DataShareResultSet).getDataType(columnIndex);
467  console.info('resultSet.getDataType: ' + getDataType);
468}
469```
470
471## DataType
472
473数据类型枚举。
474
475**系统能力：**  SystemCapability.DistributedDataManager.DataShare.Core
476
477| 名称        | 值 | 说明                 |
478| ----------- | ------ | -------------------- |
479| TYPE_NULL   | 0      | 表示值类型为空。     |
480| TYPE_LONG   | 1      | 表示值类型为长整数值。   |
481| TYPE_DOUBLE | 2      | 表示值类型为双浮点数。 |
482| TYPE_STRING | 3      | 表示值类型为字符串。 |
483| TYPE_BLOB   | 4      | 表示值类型为字节数组。 |