dbFetchArrowChunk

r-dbi · Dec 25, 2023 · 2fc961d · 2fc961d
1 parent f335521
commit 2fc961d
Show file tree

Hide file tree

Showing 25 changed files with 200 additions and 5 deletions.
diff --git a/R/dbFetchArrow.R b/R/dbFetchArrow.R
@@ -4,6 +4,7 @@
 #' `r lifecycle::badge('experimental')`
 #'
 #' Fetch the result set and return it as an Arrow object.
+#' Use [dbFetchArrowChunk()] to fetch results in chunks.
 #'
 #' @inheritSection dbBind The data retrieval flow for Arrow streams
 #'

diff --git a/R/dbFetchArrowChunk.R b/R/dbFetchArrowChunk.R
@@ -1,5 +1,43 @@
-#' @rdname dbFetch
+#' Fetch the next batch of records from a previously executed query as an Arrow object
+#'
+#' @description
+#' `r lifecycle::badge('experimental')`
+#'
+#' Fetch the next chunk of the result set and return it as an Arrow object.
+#' The chunk size is implementation-specific.
+#' Use [dbFetchArrow()] to fetch all results.
+#'
+#' @inheritSection dbBind The data retrieval flow for Arrow streams
+#'
+#' @template methods
+#' @templateVar method_name dbFetchArrowChunk
+#'
+#' @inherit DBItest::spec_arrow_fetch_arrow_chunk return
+#' @inheritSection DBItest::spec_arrow_fetch_arrow_chunk Failure modes
+#' @inheritSection DBItest::spec_arrow_fetch_arrow_chunk Specification
+#'
+#' @param res An object inheriting from [DBIResultArrow-class], created by
+#'   [dbSendQueryArrow()].
+#' @param ... Other arguments passed on to methods.
+#' @seealso Close the result set with [dbClearResult()] as soon as you
+#'   finish retrieving the records you want.
+#' @family DBIResult generics
+#' @family data retrieval generics
 #' @export
+#' @examplesIf requireNamespace("RSQLite", quietly = TRUE) && requireNamespace("nanoarrow", quietly = TRUE)
+#' con <- dbConnect(RSQLite::SQLite(), ":memory:")
+#'
+#' dbWriteTable(con, "mtcars", mtcars)
+#'
+#' # Fetch all results
+#' rs <- dbSendQueryArrow(con, "SELECT * FROM mtcars WHERE cyl = 4")
+#' dbHasCompleted(rs)
+#' as.data.frame(dbFetchArrowChunk(rs))
+#' dbHasCompleted(rs)
+#' as.data.frame(dbFetchArrowChunk(rs))
+#' dbClearResult(rs)
+#'
+#' dbDisconnect(con)
 setGeneric("dbFetchArrowChunk",
   def = function(res, ...) standardGeneric("dbFetchArrowChunk")
 )
diff --git a/_pkgdown.yml b/_pkgdown.yml
@@ -88,6 +88,7 @@ reference:
   - dbSendQueryArrow
   - dbBindArrow
   - dbFetchArrow
+  - dbFetchArrowChunk
 
 - title: Classes
   desc: S4 classes defined by DBI.

diff --git a/man/DBIResult-class.Rd b/man/DBIResult-class.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/dbColumnInfo.Rd b/man/dbColumnInfo.Rd
diff --git a/man/dbFetch.Rd b/man/dbFetch.Rd
diff --git a/man/dbFetchArrow.Rd b/man/dbFetchArrow.Rd
diff --git a/man/dbFetchArrowChunk.Rd b/man/dbFetchArrowChunk.Rd
diff --git a/man/dbGetInfo.Rd b/man/dbGetInfo.Rd
diff --git a/man/dbGetQuery.Rd b/man/dbGetQuery.Rd
diff --git a/man/dbGetQueryArrow.Rd b/man/dbGetQueryArrow.Rd
diff --git a/man/dbGetRowCount.Rd b/man/dbGetRowCount.Rd
diff --git a/man/dbGetRowsAffected.Rd b/man/dbGetRowsAffected.Rd
diff --git a/man/dbGetStatement.Rd b/man/dbGetStatement.Rd
diff --git a/man/dbHasCompleted.Rd b/man/dbHasCompleted.Rd
diff --git a/man/dbIsReadOnly.Rd b/man/dbIsReadOnly.Rd
diff --git a/man/dbIsValid.Rd b/man/dbIsValid.Rd
diff --git a/man/dbQuoteIdentifier.Rd b/man/dbQuoteIdentifier.Rd
diff --git a/man/dbQuoteLiteral.Rd b/man/dbQuoteLiteral.Rd