1# @ohos.data.dataShareResultSet (DataShare Result Set) (System API)
2
3The **DataShareResultSet** module provides APIs for accessing the result set obtained from the database. You can access the values in the specified rows or the value of the specified data type.
4
5> **NOTE**
6>
7> - The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.
8>
9> - The APIs provided by this module are system APIs.
10>
11> - The APIs of this module can be used only in the stage model.
12
13
14## Modules to Import
15
16```ts
17import { DataShareResultSet } from '@kit.ArkData';
18```
19
20## Usage
21
22You can use [query](js-apis-data-dataShare-sys.md#query) to obtain a **DataShareResultSet** object.
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
56Provides APIs for accessing the result sets returned.
57
58The column or key names are returned as a string array, in which the strings are in the same order as the columns or keys in the result set.
59
60### Properties
61
62**System capability**: SystemCapability.DistributedDataManager.DataShare.Core
63
64| Name       | Type     | Mandatory| Description                    |
65| ----------- | ------------- | ---- | ------------------------ |
66| columnNames | Array<string> | Yes  | Names of all columns in the result set.  |
67| columnCount | number        | Yes  | Number of columns in the result set.        |
68| rowCount    | number        | Yes  | Number of rows in the result set.        |
69| isClosed    | boolean       | Yes  | Whether the result set is closed.|
70
71### goToFirstRow
72
73goToFirstRow(): boolean
74
75Moves to the first row of the result set.
76
77**System capability**: SystemCapability.DistributedDataManager.DataShare.Core
78
79**Return value**
80
81| Type   | Description                                         |
82| :------ | --------------------------------------------- |
83| boolean | Returns **true** if the operation is successful; returns **false** otherwise.|
84
85**Example**
86
87```ts
88// Create a resultSet object. For details, see Usage in this topic.
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
99Moves to the last row of the result set.
100
101**System capability**: SystemCapability.DistributedDataManager.DataShare.Core
102
103**Return value**
104
105| Type| Description|
106| -------- | -------- |
107| boolean | Returns **true** if the operation is successful; returns **false** otherwise.|
108
109**Example**
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
122Moves to the next row in the result set.
123
124**System capability**: SystemCapability.DistributedDataManager.DataShare.Core
125
126**Return value**
127
128| Type   | Description                                         |
129| ------- | --------------------------------------------- |
130| boolean | Returns **true** if the operation is successful; returns **false** otherwise.|
131
132**Example**
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
145Moves to the previous row in the result set.
146
147**System capability**: SystemCapability.DistributedDataManager.DataShare.Core
148
149**Return value**
150
151| Type   | Description                                         |
152| ------- | --------------------------------------------- |
153| boolean | Returns **true** if the operation is successful; returns **false** otherwise.|
154
155**Example**
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
168Moves based on the specified offset.
169
170**System capability**: SystemCapability.DistributedDataManager.DataShare.Core
171
172**Parameters**
173
174| **Name**| **Type**| **Mandatory**| Description                                                        |
175| ---------- | -------- | -------- | ------------------------------------------------------------ |
176| offset     | number   | Yes      | Offset relative to the current position. A negative value means to move backward, and a positive value means to move forward.|
177
178**Return value**
179
180| Type   | Description                                         |
181| ------- | --------------------------------------------- |
182| boolean | Returns **true** if the operation is successful; returns **false** otherwise.|
183
184**Example**
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
198Moves to the specified row in the result set.
199
200**System capability**: SystemCapability.DistributedDataManager.DataShare.Core
201
202**Parameters**
203
204| **Name**| **Type**| **Mandatory**| Description                                   |
205| ---------- | -------- | -------- | --------------------------------------- |
206| position   | number   | Yes      | Position to move to, starting from 0.|
207
208**Return value**
209
210| Type   | Description                                         |
211| ------- | --------------------------------------------- |
212| boolean | Returns **true** if the operation is successful; returns **false** otherwise.|
213
214**Example**
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
228Obtains the value in the form of a byte array based on the specified column and the current row.
229
230If the specified column or key is empty or the value is not of the Blob type, you need to determine whether to throw an exception.
231
232**System capability**: SystemCapability.DistributedDataManager.DataShare.Core
233
234**Parameters**
235
236| **Name** | **Type**| **Mandatory**| Description                   |
237| ----------- | -------- | -------- | ----------------------- |
238| columnIndex | number   | Yes      | Index of the target column, starting from 0.|
239
240**Return value**
241
242| Type      | Description                            |
243| ---------- | -------------------------------- |
244| Uint8Array | Value obtained.|
245
246**Example**
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
261Obtains the value in the form of a string based on the specified column and the current row.
262
263If the specified column or key is empty or the value is not of the string type, you need to determine whether to throw an exception.
264
265**System capability**: SystemCapability.DistributedDataManager.DataShare.Core
266
267**Parameters**
268
269| **Name** | **Type**| **Mandatory**| Description                   |
270| ----------- | -------- | -------- | ----------------------- |
271| columnIndex | number   | Yes      | Index of the target column, starting from 0.|
272
273**Return value**
274
275| Type  | Description                        |
276| ------ | ---------------------------- |
277| string | Value obtained.|
278
279**Example**
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
294Obtains the value in the form of a long integer based on the specified column and the current row.
295
296If the specified column or key is empty or the value is not of the long type, you need to determine whether to throw an exception.
297
298**System capability**: SystemCapability.DistributedDataManager.DataShare.Core
299
300**Parameters**
301
302| **Name** | **Type**| **Mandatory**| Description                   |
303| ----------- | -------- | -------- | ----------------------- |
304| columnIndex | number   | Yes      | Index of the target column, starting from 0.|
305
306**Return value**
307
308| Type  | Description                      |
309| ------ | -------------------------- |
310| number | Value obtained.|
311
312**Example**
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
327Obtains the value in the form of a double-precision floating-point number based on the specified column and the current row.
328
329If the specified column or key is empty or the value is not of the double type, you need to determine whether to throw an exception.
330
331**System capability**: SystemCapability.DistributedDataManager.DataShare.Core
332
333**Parameters**
334
335| **Name** | **Type**| **Mandatory**| Description                   |
336| ----------- | -------- | -------- | ----------------------- |
337| columnIndex | number   | Yes      | Index of the target column, starting from 0.|
338
339**Return value**
340
341| Type  | Description                        |
342| ------ | ---------------------------- |
343| number | Value obtained.|
344
345**Example**
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
360Closes this result set.
361
362Calling this API will invalidate the result set and release all its resources.
363
364**System capability**: SystemCapability.DistributedDataManager.DataShare.Core
365
366**Example**
367
368```ts
369if (resultSet != undefined) {
370  (resultSet as DataShareResultSet).close();
371}
372```
373
374### getColumnIndex
375
376getColumnIndex(columnName: string): number
377
378Obtains the column index based on a column name.
379
380The column name is passed in as an input parameter.
381
382**System capability**: SystemCapability.DistributedDataManager.DataShare.Core
383
384**Parameters**
385
386| **Name**| **Type**| **Mandatory**| Description                      |
387| ---------- | -------- | -------- | -------------------------- |
388| columnName | string   | Yes      | Column name.|
389
390**Return value**
391
392| Type  | Description              |
393| ------ | ------------------ |
394| number | Column index obtained.|
395
396**Example**
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
410Obtains the column name based on a column index.
411
412The column index is passed in as an input parameter.
413
414**System capability**: SystemCapability.DistributedDataManager.DataShare.Core
415
416**Parameters**
417
418| **Name** | **Type**| **Mandatory**| Description                      |
419| ----------- | -------- | -------- | -------------------------- |
420| columnIndex | number   | Yes      | Column index.|
421
422**Return value**
423
424| Type  | Description              |
425| ------ | ------------------ |
426| string | Column name obtained.|
427
428**Example**
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
442Obtains the data type based on the specified column index.
443
444If the specified column or key is empty or the value is not of the DataType type, you need to determine whether to throw an exception.
445
446**System capability**: SystemCapability.DistributedDataManager.DataShare.Core
447
448**Parameters**
449
450| **Name** | **Type**| **Mandatory**| Description                      |
451| ----------- | -------- | -------- | -------------------------- |
452| columnIndex | number   | Yes      | Column index.|
453
454**Return value**
455
456| Type                 | Description              |
457| --------------------- | ------------------ |
458| [DataType](#datatype) | Data type obtained.|
459
460**Example**
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
472Enumerates the data types.
473
474**System capability**: SystemCapability.DistributedDataManager.DataShare.Core
475
476| Name       | Value| Description                |
477| ----------- | ------ | -------------------- |
478| TYPE_NULL   | 0      | Null.    |
479| TYPE_LONG   | 1      | Long integer.  |
480| TYPE_DOUBLE | 2      | Double-precision floating-point number.|
481| TYPE_STRING | 3      | String.|
482| TYPE_BLOB   | 4      | Byte array.|
483