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 { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit'; 27import { DataShareResultSet, dataShare, dataSharePredicates } from '@kit.ArkData'; 28import { BusinessError } from '@kit.BasicServicesKit'; 29 30export default class EntryAbility extends UIAbility { 31 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { 32 let dataShareHelper: dataShare.DataShareHelper | undefined = undefined; 33 let uri = ("datashare:///com.samples.datasharetest.DataShare"); 34 let context = this.context; 35 dataShare.createDataShareHelper(context, uri, (err:BusinessError, data:dataShare.DataShareHelper) => { 36 if (err != undefined) { 37 console.error("createDataShareHelper fail, error message : " + err); 38 } else { 39 console.info("createDataShareHelper end, data : " + data); 40 dataShareHelper = data; 41 } 42 }); 43 44 let columns = ["*"]; 45 let da = new dataSharePredicates.DataSharePredicates(); 46 let resultSet: DataShareResultSet | undefined = undefined; 47 da.equalTo("name", "ZhangSan"); 48 if (dataShareHelper != undefined) { 49 (dataShareHelper as dataShare.DataShareHelper).query(uri, da, columns).then((data: DataShareResultSet) => { 50 console.info("query end, data : " + data); 51 resultSet = data; 52 }).catch((err: BusinessError) => { 53 console.error("query fail, error message : " + err); 54 }); 55 } 56 }; 57}; 58``` 59 60## DataShareResultSet 61Provides APIs for accessing the result sets returned. 62 63The 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. 64 65### Properties 66 67**System capability**: SystemCapability.DistributedDataManager.DataShare.Core 68 69| Name | Type | Mandatory| Description | 70| ----------- | ------------- | ---- | ------------------------ | 71| columnNames | Array<string> | Yes | Names of all columns in the result set. | 72| columnCount | number | Yes | Number of columns in the result set. | 73| rowCount | number | Yes | Number of rows in the result set. | 74| isClosed | boolean | Yes | Whether the result set is closed. The value **true** means the result set is closed; the value **false** means the opposite.| 75 76### goToFirstRow 77 78goToFirstRow(): boolean 79 80Moves to the first row of the result set. 81 82**System capability**: SystemCapability.DistributedDataManager.DataShare.Core 83 84**Return value** 85 86| Type | Description | 87| :------ | --------------------------------------------- | 88| boolean | Returns **true** if the operation is successful; returns **false** otherwise.| 89 90**Example** 91 92```ts 93// Create a resultSet object. For details, see Usage in this topic. 94if (resultSet != undefined) { 95 let isGoToFirstRow = (resultSet as DataShareResultSet).goToFirstRow(); 96 console.info('resultSet.goToFirstRow: ' + isGoToFirstRow); 97} 98``` 99 100### goToLastRow 101 102goToLastRow(): boolean 103 104Moves to the last row of the result set. 105 106**System capability**: SystemCapability.DistributedDataManager.DataShare.Core 107 108**Return value** 109 110| Type| Description| 111| -------- | -------- | 112| boolean | Returns **true** if the operation is successful; returns **false** otherwise.| 113 114**Example** 115 116```ts 117if (resultSet != undefined) { 118 let isGoToLastRow = (resultSet as DataShareResultSet).goToLastRow(); 119 console.info('resultSet.goToLastRow: ' + isGoToLastRow); 120} 121``` 122 123### goToNextRow 124 125goToNextRow(): boolean 126 127Moves to the next row in the result set. 128 129**System capability**: SystemCapability.DistributedDataManager.DataShare.Core 130 131**Return value** 132 133| Type | Description | 134| ------- | --------------------------------------------- | 135| boolean | Returns **true** if the operation is successful; returns **false** otherwise.| 136 137**Example** 138 139```ts 140if (resultSet != undefined) { 141 let isGoToNextRow = (resultSet as DataShareResultSet).goToNextRow(); 142 console.info('resultSet.goToNextRow: ' + isGoToNextRow); 143} 144``` 145 146### goToPreviousRow 147 148goToPreviousRow(): boolean 149 150Moves to the previous row in the result set. 151 152**System capability**: SystemCapability.DistributedDataManager.DataShare.Core 153 154**Return value** 155 156| Type | Description | 157| ------- | --------------------------------------------- | 158| boolean | Returns **true** if the operation is successful; returns **false** otherwise.| 159 160**Example** 161 162```ts 163if (resultSet != undefined) { 164 let isGoToPreviousRow = (resultSet as DataShareResultSet).goToPreviousRow(); 165 console.info('resultSet.goToPreviousRow: ' + isGoToPreviousRow); 166} 167``` 168 169### goTo 170 171goTo(offset: number): boolean 172 173Moves based on the specified offset. 174 175**System capability**: SystemCapability.DistributedDataManager.DataShare.Core 176 177**Parameters** 178 179| **Name**| **Type**| **Mandatory**| Description | 180| ---------- | -------- | -------- | ------------------------------------------------------------ | 181| offset | number | Yes | Offset relative to the current position. A negative value means to move backward, and a positive value means to move forward.| 182 183**Return value** 184 185| Type | Description | 186| ------- | --------------------------------------------- | 187| boolean | Returns **true** if the operation is successful; returns **false** otherwise.| 188 189**Example** 190 191```ts 192let goToNum = 1; 193if (resultSet != undefined) { 194 let isGoTo = (resultSet as DataShareResultSet).goTo(goToNum); 195 console.info('resultSet.goTo: ' + isGoTo); 196} 197``` 198 199### goToRow 200 201goToRow(position: number): boolean 202 203Moves to the specified row in the result set. 204 205**System capability**: SystemCapability.DistributedDataManager.DataShare.Core 206 207**Parameters** 208 209| **Name**| **Type**| **Mandatory**| Description | 210| ---------- | -------- | -------- | --------------------------------------- | 211| position | number | Yes | Position to move to, starting from 0.| 212 213**Return value** 214 215| Type | Description | 216| ------- | --------------------------------------------- | 217| boolean | Returns **true** if the operation is successful; returns **false** otherwise.| 218 219**Example** 220 221```ts 222let goToRowNum = 2; 223if (resultSet != undefined) { 224 let isGoToRow = (resultSet as DataShareResultSet).goToRow(goToRowNum); 225 console.info('resultSet.goToRow: ' + isGoToRow); 226} 227``` 228 229### getBlob 230 231getBlob(columnIndex: number): Uint8Array 232 233Obtains the value in the form of a byte array based on the specified column and the current row. 234 235If 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. 236 237**System capability**: SystemCapability.DistributedDataManager.DataShare.Core 238 239**Parameters** 240 241| **Name** | **Type**| **Mandatory**| Description | 242| ----------- | -------- | -------- | ----------------------- | 243| columnIndex | number | Yes | Index of the target column, starting from 0.| 244 245**Return value** 246 247| Type | Description | 248| ---------- | -------------------------------- | 249| Uint8Array | Value obtained.| 250 251**Example** 252 253```ts 254let columnIndex = 1; 255if (resultSet != undefined) { 256 let goToFirstRow = (resultSet as DataShareResultSet).goToFirstRow(); 257 let getBlob = (resultSet as DataShareResultSet).getBlob(columnIndex); 258 console.info('resultSet.getBlob: ' + getBlob); 259} 260``` 261 262### getString 263 264getString(columnIndex: number): string 265 266Obtains the value in the form of a string based on the specified column and the current row. 267 268If 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. 269 270**System capability**: SystemCapability.DistributedDataManager.DataShare.Core 271 272**Parameters** 273 274| **Name** | **Type**| **Mandatory**| Description | 275| ----------- | -------- | -------- | ----------------------- | 276| columnIndex | number | Yes | Index of the target column, starting from 0.| 277 278**Return value** 279 280| Type | Description | 281| ------ | ---------------------------- | 282| string | Value obtained.| 283 284**Example** 285 286```ts 287let columnIndex = 1; 288if (resultSet != undefined) { 289 let goToFirstRow = (resultSet as DataShareResultSet).goToFirstRow(); 290 let getString = (resultSet as DataShareResultSet).getString(columnIndex); 291 console.info('resultSet.getString: ' + getString); 292} 293``` 294 295### getLong 296 297getLong(columnIndex: number): number 298 299Obtains the value in the form of a long integer based on the specified column and the current row. 300 301If 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. 302 303**System capability**: SystemCapability.DistributedDataManager.DataShare.Core 304 305**Parameters** 306 307| **Name** | **Type**| **Mandatory**| Description | 308| ----------- | -------- | -------- | ----------------------- | 309| columnIndex | number | Yes | Index of the target column, starting from 0.| 310 311**Return value** 312 313| Type | Description | 314| ------ | -------------------------- | 315| number | Value obtained.| 316 317**Example** 318 319```ts 320let columnIndex = 1; 321if (resultSet != undefined) { 322 let goToFirstRow = (resultSet as DataShareResultSet).goToFirstRow(); 323 let getLong = (resultSet as DataShareResultSet).getLong(columnIndex); 324 console.info('resultSet.getLong: ' + getLong); 325} 326``` 327 328### getDouble 329 330getDouble(columnIndex: number): number 331 332Obtains the value in the form of a double-precision floating-point number based on the specified column and the current row. 333 334If 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. 335 336**System capability**: SystemCapability.DistributedDataManager.DataShare.Core 337 338**Parameters** 339 340| **Name** | **Type**| **Mandatory**| Description | 341| ----------- | -------- | -------- | ----------------------- | 342| columnIndex | number | Yes | Index of the target column, starting from 0.| 343 344**Return value** 345 346| Type | Description | 347| ------ | ---------------------------- | 348| number | Value obtained.| 349 350**Example** 351 352```ts 353let columnIndex = 1; 354if (resultSet != undefined) { 355 let goToFirstRow = (resultSet as DataShareResultSet).goToFirstRow(); 356 let getDouble = (resultSet as DataShareResultSet).getDouble(columnIndex); 357 console.info('resultSet.getDouble: ' + getDouble); 358} 359``` 360 361### close 362 363close(): void 364 365Closes this result set. 366 367Calling this API will invalidate the result set and release all its resources. 368 369**System capability**: SystemCapability.DistributedDataManager.DataShare.Core 370 371**Example** 372 373```ts 374if (resultSet != undefined) { 375 (resultSet as DataShareResultSet).close(); 376} 377``` 378 379### getColumnIndex 380 381getColumnIndex(columnName: string): number 382 383Obtains the column index based on a column name. 384 385The column name is passed in as an input parameter. 386 387**System capability**: SystemCapability.DistributedDataManager.DataShare.Core 388 389**Parameters** 390 391| **Name**| **Type**| **Mandatory**| Description | 392| ---------- | -------- | -------- | -------------------------- | 393| columnName | string | Yes | Column name.| 394 395**Return value** 396 397| Type | Description | 398| ------ | ------------------ | 399| number | Column index obtained.| 400 401**Example** 402 403```ts 404let ColumnName = "name"; 405if (resultSet != undefined) { 406 let getColumnIndex = (resultSet as DataShareResultSet).getColumnIndex(ColumnName); 407 console.info('resultSet.getColumnIndex: ' + getColumnIndex); 408} 409``` 410 411### getColumnName 412 413getColumnName(columnIndex: number): string 414 415Obtains the column name based on a column index. 416 417The column index is passed in as an input parameter. 418 419**System capability**: SystemCapability.DistributedDataManager.DataShare.Core 420 421**Parameters** 422 423| **Name** | **Type**| **Mandatory**| Description | 424| ----------- | -------- | -------- | -------------------------- | 425| columnIndex | number | Yes | Column index.| 426 427**Return value** 428 429| Type | Description | 430| ------ | ------------------ | 431| string | Column name obtained.| 432 433**Example** 434 435```ts 436let columnIndex = 1; 437if (resultSet != undefined) { 438 let getColumnName = (resultSet as DataShareResultSet).getColumnName(columnIndex); 439 console.info('resultSet.getColumnName: ' + getColumnName); 440} 441``` 442 443### getDataType 444 445getDataType(columnIndex: number): DataType 446 447Obtains the data type based on the specified column index. 448 449If 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. 450 451**System capability**: SystemCapability.DistributedDataManager.DataShare.Core 452 453**Parameters** 454 455| **Name** | **Type**| **Mandatory**| Description | 456| ----------- | -------- | -------- | -------------------------- | 457| columnIndex | number | Yes | Column index.| 458 459**Return value** 460 461| Type | Description | 462| --------------------- | ------------------ | 463| [DataType](#datatype) | Data type obtained.| 464 465**Example** 466 467```ts 468let columnIndex = 1; 469if (resultSet != undefined) { 470 let getDataType = (resultSet as DataShareResultSet).getDataType(columnIndex); 471 console.info('resultSet.getDataType: ' + getDataType); 472} 473``` 474 475## DataType 476 477Enumerates the data types. 478 479**System capability**: SystemCapability.DistributedDataManager.DataShare.Core 480 481| Name | Value| Description | 482| ----------- | ------ | -------------------- | 483| TYPE_NULL | 0 | Null. | 484| TYPE_LONG | 1 | Long integer. | 485| TYPE_DOUBLE | 2 | Double-precision floating-point number.| 486| TYPE_STRING | 3 | String.| 487| TYPE_BLOB | 4 | Byte array.| 488