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