dbGetQueryArrow

r-dbi · Dec 24, 2023 · f18dd76 · f18dd76
1 parent 4caa19c
commit f18dd76
Show file tree

Hide file tree

Showing 33 changed files with 295 additions and 49 deletions.
diff --git a/R/dbGetQuery.R b/R/dbGetQuery.R
@@ -4,13 +4,14 @@
 #' `dbGetQuery()` comes with a default implementation
 #' (which should work with most backends) that calls
 #' [dbSendQuery()], then [dbFetch()], ensuring that
-#' the result is always free-d by [dbClearResult()].
+#' the result is always freed by [dbClearResult()].
 #' For retrieving chunked/paged results or for passing query parameters,
 #' see [dbSendQuery()], in particular the "The data retrieval flow" section.
+#' For retrieving results as an Arrow object, see [dbGetQueryArrow()].
 #'
 #' This method is for `SELECT` queries only
 #' (incl. other SQL statements that return a `SELECT`-alike result,
-#'  e. g. execution of a stored procedure or data manipulation queries
+#' e.g., execution of a stored procedure or data manipulation queries
 #' like `INSERT INTO ... RETURNING ...`).
 #' To execute a stored procedure that does not return a result set,
 #' use [dbExecute()].
@@ -23,11 +24,10 @@
 #' @template methods
 #' @templateVar method_name dbGetQuery
 #'
-#' @inherit DBItest::spec_result_get_query return
-#' @inheritSection DBItest::spec_result_get_query Failure modes
-#' @inheritSection DBItest::spec_result_get_query Additional arguments
-#' @inheritSection DBItest::spec_result_get_query Specification
-#' @inheritSection DBItest::spec_result_get_query Specification for the `immediate` argument
+#' @inherit DBItest::spec_arrow_get_query_arrow return
+#' @inheritSection DBItest::spec_arrow_get_query_arrow Failure modes
+#' @inheritSection DBItest::spec_arrow_get_query_arrow Additional arguments
+#' @inheritSection DBItest::spec_arrow_get_query_arrow Specification for the `immediate` argument
 #'
 #' @section Implementation notes:
 #' Subclasses should override this method only if they provide some sort of

diff --git a/R/dbGetQueryArrow.R b/R/dbGetQueryArrow.R
@@ -1,3 +1,46 @@
+#' Send query, retrieve results as an Arrow object and then clear result set
+#'
+#' Returns the result of a query as a data frame.
+#' `dbGetQuery()` comes with a default implementation
+#' (which should work with most backends) that calls
+#' [dbSendQueryArrow()], then [dbFetchArrow()], ensuring that
+#' the result is always freed by [dbClearResult()].
+#' For passing query parameters,
+#' see [dbSendQueryArrow()], in particular the "The data retrieval flow" section.
+#' For retrieving results as a data frame, see [dbGetQuery()].
+#'
+#' This method is for `SELECT` queries only
+#' (incl. other SQL statements that return a `SELECT`-alike result,
+#' e.g., execution of a stored procedure or data manipulation queries
+#' like `INSERT INTO ... RETURNING ...`).
+#' To execute a stored procedure that does not return a result set,
+#' use [dbExecute()].
+#'
+#' Some backends may
+#' support data manipulation statements through this method.
+#' However, callers are strongly advised to use
+#' [dbExecute()] for data manipulation statements.
+#'
+#' @template methods
+#' @templateVar method_name dbGetQueryArrow
+#'
+#' @inherit DBItest::spec_result_get_query return
+#' @inheritSection DBItest::spec_result_get_query Failure modes
+#' @inheritSection DBItest::spec_result_get_query Additional arguments
+#' @inheritSection DBItest::spec_result_get_query Specification
+#' @inheritSection DBItest::spec_result_get_query Specification for the `immediate` argument
+#'
+#' @section Implementation notes:
+#' Subclasses should override this method only if they provide some sort of
+#' performance optimization.
+#'
+#' @param conn A [DBIConnection-class] object, as returned by
+#'   [dbConnect()].
+#' @param statement a character string containing SQL.
+#' @param ... Other parameters passed on to methods.
+#' @family DBIConnection generics
+#' @family data retrieval generics
+#' @seealso For updates: [dbSendStatementArrow()] and [dbExecute()].
 #' @export
 #' @examplesIf requireNamespace("RSQLite", quietly = TRUE) && requireNamespace("nanoarrow", quietly = TRUE)
 #' # Retrieve data as arrow table
@@ -7,7 +50,6 @@
 #' dbGetQueryArrow(con, "SELECT * FROM mtcars")
 #'
 #' dbDisconnect(con)
-#' @rdname dbGetQuery
 setGeneric("dbGetQueryArrow",
   def = function(conn, statement, ...) standardGeneric("dbGetQueryArrow")
 )
diff --git a/_pkgdown.yml b/_pkgdown.yml
@@ -84,6 +84,7 @@ reference:
   - dbWriteTableArrow
   - dbCreateTableArrow
   - dbAppendTableArrow
+  - dbGetQueryArrow
 
 - title: Classes
   desc: S4 classes defined by DBI.

diff --git a/man/DBIConnection-class.Rd b/man/DBIConnection-class.Rd
diff --git a/man/dbAppendTable.Rd b/man/dbAppendTable.Rd
diff --git a/man/dbAppendTableArrow.Rd b/man/dbAppendTableArrow.Rd
diff --git a/man/dbBind.Rd b/man/dbBind.Rd
diff --git a/man/dbClearResult.Rd b/man/dbClearResult.Rd
diff --git a/man/dbCreateTable.Rd b/man/dbCreateTable.Rd
diff --git a/man/dbCreateTableArrow.Rd b/man/dbCreateTableArrow.Rd
diff --git a/man/dbDataType.Rd b/man/dbDataType.Rd
diff --git a/man/dbDisconnect.Rd b/man/dbDisconnect.Rd
diff --git a/man/dbExecute.Rd b/man/dbExecute.Rd
diff --git a/man/dbExistsTable.Rd b/man/dbExistsTable.Rd
diff --git a/man/dbFetch.Rd b/man/dbFetch.Rd
diff --git a/man/dbGetException.Rd b/man/dbGetException.Rd
diff --git a/man/dbGetInfo.Rd b/man/dbGetInfo.Rd
diff --git a/man/dbGetQuery.Rd b/man/dbGetQuery.Rd