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