From 209db54fda9c8cc735e3046453fac805145fd6db Mon Sep 17 00:00:00 2001 From: zaleslaw Date: Tue, 30 Apr 2024 10:45:30 +0200 Subject: [PATCH] Update comments and doc to provide more details about ResultSet --- .../kotlinx/dataframe/io/readJdbc.kt | 41 +++++++++++++++---- docs/StardustDocs/topics/readSqlDatabases.md | 9 +++- 2 files changed, 40 insertions(+), 10 deletions(-) diff --git a/dataframe-jdbc/src/main/kotlin/org/jetbrains/kotlinx/dataframe/io/readJdbc.kt b/dataframe-jdbc/src/main/kotlin/org/jetbrains/kotlinx/dataframe/io/readJdbc.kt index 2b6d0e1b6..97852e069 100644 --- a/dataframe-jdbc/src/main/kotlin/org/jetbrains/kotlinx/dataframe/io/readJdbc.kt +++ b/dataframe-jdbc/src/main/kotlin/org/jetbrains/kotlinx/dataframe/io/readJdbc.kt @@ -228,13 +228,24 @@ private fun isValid(sqlQuery: String): Boolean { } /** - * Reads the data from a [ResultSet] and converts it into a DataFrame. + * Reads the data from a [ResultSet][java.sql.ResultSet] and converts it into a DataFrame. * - * @param [resultSet] the [ResultSet] containing the data to read. + * A [ResultSet][java.sql.ResultSet] object maintains a cursor pointing to its current row of data. + * By default, a ResultSet object is not updatable and has a cursor that can only move forward. + * Therefore, you can iterate through it only once, from the first row to the last row. + * + * For more details, refer to the official Java documentation on [ResultSet][java.sql.ResultSet]. + * + * NOTE: Reading from the [ResultSet][java.sql.ResultSet] could potentially change its state. + * + * @param [resultSet] the [ResultSet][java.sql.ResultSet] containing the data to read. + * Its state may be altered after the read operation. * @param [dbType] the type of database that the [ResultSet] belongs to. - * @param [limit] the maximum number of rows to read from the [ResultSet]. + * @param [limit] the maximum number of rows to read from the [ResultSet][java.sql.ResultSet]. * @param [inferNullability] indicates how the column nullability should be inferred. - * @return the DataFrame generated from the [ResultSet] data. + * @return the DataFrame generated from the [ResultSet][java.sql.ResultSet] data. + * + * [java.sql.ResultSet]: https://docs.oracle.com/javase/8/docs/api/java/sql/ResultSet.html */ public fun DataFrame.Companion.readResultSet( resultSet: ResultSet, @@ -247,13 +258,25 @@ public fun DataFrame.Companion.readResultSet( } /** - * Reads the data from a [ResultSet] and converts it into a DataFrame. + * Reads the data from a [ResultSet][java.sql.ResultSet] and converts it into a DataFrame. * - * @param [resultSet] the [ResultSet] containing the data to read. - * @param [connection] the connection to the database (it's required to extract the database type). - * @param [limit] the maximum number of rows to read from the [ResultSet]. + * A [ResultSet][java.sql.ResultSet] object maintains a cursor pointing to its current row of data. + * By default, a ResultSet object is not updatable and has a cursor that can only move forward. + * Therefore, you can iterate through it only once, from the first row to the last row. + * + * For more details, refer to the official Java documentation on [ResultSet][java.sql.ResultSet]. + * + * NOTE: Reading from the [ResultSet][java.sql.ResultSet] could potentially change its state. + * + * @param [resultSet] the [ResultSet][java.sql.ResultSet] containing the data to read. + * Its state may be altered after the read operation. + * @param [connection] the connection to the database (it's required to extract the database type) + * that the [ResultSet] belongs to. + * @param [limit] the maximum number of rows to read from the [ResultSet][java.sql.ResultSet]. * @param [inferNullability] indicates how the column nullability should be inferred. - * @return the DataFrame generated from the [ResultSet] data. + * @return the DataFrame generated from the [ResultSet][java.sql.ResultSet] data. + * + * [java.sql.ResultSet]: https://docs.oracle.com/javase/8/docs/api/java/sql/ResultSet.html */ public fun DataFrame.Companion.readResultSet( resultSet: ResultSet, diff --git a/docs/StardustDocs/topics/readSqlDatabases.md b/docs/StardustDocs/topics/readSqlDatabases.md index 9a436b463..dcb890ba1 100644 --- a/docs/StardustDocs/topics/readSqlDatabases.md +++ b/docs/StardustDocs/topics/readSqlDatabases.md @@ -246,11 +246,18 @@ The versions with a limit parameter will only read up to the specified number of This function allows reading a ResultSet object from your SQL database and transforms it into an AnyFrame object. +A ResultSet object maintains a cursor pointing to its current row of data. +By default, a ResultSet object is not updatable and has a cursor that moves forward only. +Therefore, you can iterate it only once and only from the first row to the last row. + +More details about ResultSet can be found in the [official Java documentation](https://docs.oracle.com/javase/8/docs/api/java/sql/ResultSet.html). + +Note that reading from the ResultSet could potentially change its state. + The `dbType: DbType` parameter specifies the type of our database (e.g., PostgreSQL, MySQL, etc.), supported by a library. Currently, the following classes are available: `H2, MariaDb, MySql, PostgreSql, Sqlite`. - ```kotlin import org.jetbrains.kotlinx.dataframe.io.db.PostgreSql import java.sql.ResultSet