diff --git a/DESCRIPTION b/DESCRIPTION index d04910fa2..f83433653 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -112,6 +112,7 @@ Collate: 'spec-transaction-with-transaction.R' 'spec-arrow-send-query-arrow.R' 'spec-arrow-fetch-arrow.R' + 'spec-arrow-fetch-arrow-chunk.R' 'spec-arrow-get-query-arrow.R' 'spec-arrow-read-table-arrow.R' 'spec-arrow-write-table-arrow.R' diff --git a/R/spec-.R b/R/spec-.R index ba941e711..23dcf585c 100644 --- a/R/spec-.R +++ b/R/spec-.R @@ -37,6 +37,7 @@ #' @include spec-arrow-write-table-arrow.R #' @include spec-arrow-read-table-arrow.R #' @include spec-arrow-get-query-arrow.R +#' @include spec-arrow-fetch-arrow-chunk.R #' @include spec-arrow-fetch-arrow.R #' @include spec-arrow-send-query-arrow.R ##### Method specs diff --git a/R/spec-arrow-fetch-arrow-chunk.R b/R/spec-arrow-fetch-arrow-chunk.R new file mode 100644 index 000000000..64418d101 --- /dev/null +++ b/R/spec-arrow-fetch-arrow-chunk.R @@ -0,0 +1,97 @@ +#' spec_arrow_fetch_arrow_chunk +#' @family Arrow specifications +#' @usage NULL +#' @format NULL +#' @keywords NULL +spec_arrow_fetch_arrow_chunk <- list( + arrow_fetch_arrow_chunk_formals = function() { + # + expect_equal(names(formals(dbFetchArrowChunk)), c("res", "...")) + }, + + arrow_fetch_arrow_chunk_atomic = function(con) { + #' @return + #' `dbFetchArrowChunk()` always returns an object coercible to a [data.frame] + #' with as many rows as records were fetched and as many + #' columns as fields in the result set, + #' even if the result is a single value + query <- trivial_query() + res <- local_result(dbSendQueryArrow(con, query)) + rows <- check_arrow(dbFetchArrowChunk(res)) + expect_equal(rows, data.frame(a = 1.5)) + }, + + arrow_fetch_arrow_chunk_one_row = function(con) { + #' or has one + query <- trivial_query(3, letters[1:3]) + result <- trivial_df(3, letters[1:3]) + res <- local_result(dbSendQueryArrow(con, query)) + rows <- check_arrow(dbFetchArrowChunk(res)) + expect_identical(rows, result) + }, + + arrow_fetch_arrow_chunk_zero_rows = function(con) { + #' or zero rows. + query <- + "SELECT * FROM (SELECT 1 as a, 2 as b, 3 as c) AS x WHERE (1 = 0)" + res <- local_result(dbSendQueryArrow(con, query)) + rows <- check_arrow(dbFetchArrowChunk(res)) + expect_identical(class(rows), "data.frame") + }, + + #' + arrow_fetch_arrow_chunk_closed = function(con) { + skip("Fails in adbc") + + #' @section Failure modes: + #' An attempt to fetch from a closed result set raises an error. + query <- trivial_query() + + res <- dbSendQueryArrow(con, query) + dbClearResult(res) + + expect_error(dbFetchArrowChunk(res)) + }, + + arrow_fetch_arrow_chunk_multi_row_single_column = function(ctx, con) { + #' @section Specification: + #' Fetching multi-row queries with one + query <- trivial_query(3, .ctx = ctx, .order_by = "a") + result <- trivial_df(3) + + res <- local_result(dbSendQueryArrow(con, query)) + rows <- check_arrow(dbFetchArrowChunk(res)) + expect_identical(rows, result) + }, + + arrow_fetch_arrow_chunk_multi_row_multi_column = function(ctx, con) { + #' or more columns returns the next chunk. + #' The size of the chunk is implementation-specific. + query <- sql_union( + .ctx = ctx, paste("SELECT", 1:5 + 0.5, "AS a,", 4:0 + 0.5, "AS b"), .order_by = "a" + ) + + res <- local_result(dbSendQueryArrow(con, query)) + rows <- check_arrow(dbFetchArrowChunk(res)) + expect_identical(rows, data.frame(a = 1:5 + 0.5, b = 4:0 + 0.5)) + }, + + arrow_fetch_arrow_chunk_array = function(ctx, con) { + #' The object returned by `dbFetchArrowChunk()` can also be passed to + #' [nanoarrow::as_nanoarrow_array()] to create a nanoarrow array object. + query <- trivial_query(25, .ctx = ctx, .order_by = "a") + result <- trivial_df(25) + + res <- local_result(dbSendQueryArrow(con, query)) + chunk <- dbFetchArrowChunk(res) + + rbr <- nanoarrow::as_nanoarrow_array(chunk) + + #' The chunk size is implementation-specific. + out <- as.data.frame(rbr) + expect_equal(out, head(result, nrow(out))) + }, + + # + NULL +) diff --git a/R/spec-arrow.R b/R/spec-arrow.R index 69aab47dd..8af3af403 100644 --- a/R/spec-arrow.R +++ b/R/spec-arrow.R @@ -2,6 +2,7 @@ spec_arrow <- c( spec_arrow_send_query_arrow, spec_arrow_fetch_arrow, + spec_arrow_fetch_arrow_chunk, spec_arrow_get_query_arrow, spec_arrow_read_table_arrow, spec_arrow_write_table_arrow, diff --git a/man/spec_arrow_append_table_arrow.Rd b/man/spec_arrow_append_table_arrow.Rd index 785bba167..f4b156185 100644 --- a/man/spec_arrow_append_table_arrow.Rd +++ b/man/spec_arrow_append_table_arrow.Rd @@ -97,6 +97,7 @@ The order of the columns does not matter. \seealso{ Other Arrow specifications: \code{\link{spec_arrow_create_table_arrow}}, +\code{\link{spec_arrow_fetch_arrow_chunk}}, \code{\link{spec_arrow_fetch_arrow}}, \code{\link{spec_arrow_get_query_arrow}}, \code{\link{spec_arrow_read_table_arrow}}, diff --git a/man/spec_arrow_create_table_arrow.Rd b/man/spec_arrow_create_table_arrow.Rd index 8ee35ee1e..7c97845de 100644 --- a/man/spec_arrow_create_table_arrow.Rd +++ b/man/spec_arrow_create_table_arrow.Rd @@ -66,6 +66,7 @@ if the database supports non-syntactic identifiers. \seealso{ Other Arrow specifications: \code{\link{spec_arrow_append_table_arrow}}, +\code{\link{spec_arrow_fetch_arrow_chunk}}, \code{\link{spec_arrow_fetch_arrow}}, \code{\link{spec_arrow_get_query_arrow}}, \code{\link{spec_arrow_read_table_arrow}}, diff --git a/man/spec_arrow_fetch_arrow.Rd b/man/spec_arrow_fetch_arrow.Rd index 223e775e1..e770fc2da 100644 --- a/man/spec_arrow_fetch_arrow.Rd +++ b/man/spec_arrow_fetch_arrow.Rd @@ -35,6 +35,7 @@ The chunk size is implementation-specific. Other Arrow specifications: \code{\link{spec_arrow_append_table_arrow}}, \code{\link{spec_arrow_create_table_arrow}}, +\code{\link{spec_arrow_fetch_arrow_chunk}}, \code{\link{spec_arrow_get_query_arrow}}, \code{\link{spec_arrow_read_table_arrow}}, \code{\link{spec_arrow_send_query_arrow}}, diff --git a/man/spec_arrow_fetch_arrow_chunk.Rd b/man/spec_arrow_fetch_arrow_chunk.Rd new file mode 100644 index 000000000..c91c31637 --- /dev/null +++ b/man/spec_arrow_fetch_arrow_chunk.Rd @@ -0,0 +1,44 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/spec-arrow-fetch-arrow-chunk.R +\docType{data} +\name{spec_arrow_fetch_arrow_chunk} +\alias{spec_arrow_fetch_arrow_chunk} +\title{spec_arrow_fetch_arrow_chunk} +\value{ +\code{dbFetchArrowChunk()} always returns an object coercible to a \link{data.frame} +with as many rows as records were fetched and as many +columns as fields in the result set, +even if the result is a single value +or has one +or zero rows. +} +\description{ +spec_arrow_fetch_arrow_chunk +} +\section{Failure modes}{ + +An attempt to fetch from a closed result set raises an error. +} + +\section{Specification}{ + +Fetching multi-row queries with one +or more columns returns the next chunk. +The size of the chunk is implementation-specific. +The object returned by \code{dbFetchArrowChunk()} can also be passed to +\code{\link[nanoarrow:as_nanoarrow_array]{nanoarrow::as_nanoarrow_array()}} to create a nanoarrow array object. +The chunk size is implementation-specific. +} + +\seealso{ +Other Arrow specifications: +\code{\link{spec_arrow_append_table_arrow}}, +\code{\link{spec_arrow_create_table_arrow}}, +\code{\link{spec_arrow_fetch_arrow}}, +\code{\link{spec_arrow_get_query_arrow}}, +\code{\link{spec_arrow_read_table_arrow}}, +\code{\link{spec_arrow_send_query_arrow}}, +\code{\link{spec_arrow_write_table_arrow}}, +\code{\link{spec_result_clear_result}} +} +\concept{Arrow specifications} diff --git a/man/spec_arrow_get_query_arrow.Rd b/man/spec_arrow_get_query_arrow.Rd index 2cb05ec65..a23ec155c 100644 --- a/man/spec_arrow_get_query_arrow.Rd +++ b/man/spec_arrow_get_query_arrow.Rd @@ -32,6 +32,7 @@ The chunk size is implementation-specific. Other Arrow specifications: \code{\link{spec_arrow_append_table_arrow}}, \code{\link{spec_arrow_create_table_arrow}}, +\code{\link{spec_arrow_fetch_arrow_chunk}}, \code{\link{spec_arrow_fetch_arrow}}, \code{\link{spec_arrow_read_table_arrow}}, \code{\link{spec_arrow_send_query_arrow}}, diff --git a/man/spec_arrow_read_table_arrow.Rd b/man/spec_arrow_read_table_arrow.Rd index fb522d6a0..9f185d457 100644 --- a/man/spec_arrow_read_table_arrow.Rd +++ b/man/spec_arrow_read_table_arrow.Rd @@ -42,6 +42,7 @@ perhaps by calling \code{dbQuoteIdentifier(conn, x = name)} Other Arrow specifications: \code{\link{spec_arrow_append_table_arrow}}, \code{\link{spec_arrow_create_table_arrow}}, +\code{\link{spec_arrow_fetch_arrow_chunk}}, \code{\link{spec_arrow_fetch_arrow}}, \code{\link{spec_arrow_get_query_arrow}}, \code{\link{spec_arrow_send_query_arrow}}, diff --git a/man/spec_arrow_send_query_arrow.Rd b/man/spec_arrow_send_query_arrow.Rd index 21ba4c909..26b90f4c2 100644 --- a/man/spec_arrow_send_query_arrow.Rd +++ b/man/spec_arrow_send_query_arrow.Rd @@ -103,6 +103,7 @@ the backend tries \code{immediate = TRUE} (and gives a message) Other Arrow specifications: \code{\link{spec_arrow_append_table_arrow}}, \code{\link{spec_arrow_create_table_arrow}}, +\code{\link{spec_arrow_fetch_arrow_chunk}}, \code{\link{spec_arrow_fetch_arrow}}, \code{\link{spec_arrow_get_query_arrow}}, \code{\link{spec_arrow_read_table_arrow}}, diff --git a/man/spec_arrow_write_table_arrow.Rd b/man/spec_arrow_write_table_arrow.Rd index 6429e2817..97c757295 100644 --- a/man/spec_arrow_write_table_arrow.Rd +++ b/man/spec_arrow_write_table_arrow.Rd @@ -133,6 +133,7 @@ Mixing column types in the same table is supported. Other Arrow specifications: \code{\link{spec_arrow_append_table_arrow}}, \code{\link{spec_arrow_create_table_arrow}}, +\code{\link{spec_arrow_fetch_arrow_chunk}}, \code{\link{spec_arrow_fetch_arrow}}, \code{\link{spec_arrow_get_query_arrow}}, \code{\link{spec_arrow_read_table_arrow}}, diff --git a/man/spec_result_clear_result.Rd b/man/spec_result_clear_result.Rd index a17dd8012..89e8b50ed 100644 --- a/man/spec_result_clear_result.Rd +++ b/man/spec_result_clear_result.Rd @@ -42,6 +42,7 @@ Other result specifications: Other Arrow specifications: \code{\link{spec_arrow_append_table_arrow}}, \code{\link{spec_arrow_create_table_arrow}}, +\code{\link{spec_arrow_fetch_arrow_chunk}}, \code{\link{spec_arrow_fetch_arrow}}, \code{\link{spec_arrow_get_query_arrow}}, \code{\link{spec_arrow_read_table_arrow}},