From 658cefad60f92d509573bccb672c0115dde84d40 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kirill=20M=C3=BCller?= Date: Sun, 13 Nov 2022 07:55:54 +0100 Subject: [PATCH 1/4] Document --- man/dbClearResult.Rd | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/man/dbClearResult.Rd b/man/dbClearResult.Rd index c2712601..b049ae3e 100644 --- a/man/dbClearResult.Rd +++ b/man/dbClearResult.Rd @@ -13,8 +13,9 @@ dbClearResult(res, ...) } \value{ \code{dbClearResult()} returns \code{TRUE}, invisibly, for result sets obtained from -both \code{dbSendQuery()} -and \code{dbSendStatement()}. +\code{dbSendQuery()}, +\code{dbSendStatement()}, +or \code{dbSendQueryStream()}, } \description{ Frees all resources (local and remote) associated with a result set. @@ -92,7 +93,9 @@ to ensure that this step is always executed. An attempt to close an already closed result set issues a warning -in both cases. +for \code{dbSendQuery()}, +\code{dbSendStatement()}, +and \code{dbSendQueryStream()}, } From 16d62c989324e1d8fd9dbcdeead3e0b32b6f5a49 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kirill=20M=C3=BCller?= Date: Sun, 13 Nov 2022 08:03:10 +0100 Subject: [PATCH 2/4] Harmonize table documentation --- DESCRIPTION | 6 +++--- R/dbAppendStream.R | 3 ++- R/dbAppendTable.R | 4 ++-- R/dbCreateFromStream.R | 4 +++- R/dbWriteStream.R | 1 + R/dbWriteTable.R | 9 +++++---- man/dbAppendTable.Rd | 9 ++++++--- man/dbCreateTable.Rd | 7 ++++++- man/dbWriteTable.Rd | 20 +++++++------------- 9 files changed, 35 insertions(+), 28 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index f30b8720..745c2302 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -86,9 +86,9 @@ Collate: 'SQLKeywords_missing.R' 'data-types.R' 'data.R' + 'dbAppendTable.R' 'dbAppendStream.R' 'dbAppendStream_DBIConnection.R' - 'dbAppendTable.R' 'dbAppendTable_DBIConnection.R' 'dbBegin.R' 'dbBind.R' @@ -102,9 +102,9 @@ Collate: 'dbCommit.R' 'dbConnect.R' 'dbConnect_DBIConnector.R' + 'dbCreateTable.R' 'dbCreateFromStream.R' 'dbCreateFromStream_DBIConnection.R' - 'dbCreateTable.R' 'dbCreateTable_DBIConnection.R' 'dbDataType.R' 'dbDataType_DBIConnector.R' @@ -176,9 +176,9 @@ Collate: 'dbUnquoteIdentifier_DBIConnection.R' 'dbWithTransaction.R' 'dbWithTransaction_DBIConnection.R' + 'dbWriteTable.R' 'dbWriteStream.R' 'dbWriteStream_DBIConnection.R' - 'dbWriteTable.R' 'dbWriteTable_DBIConnection_Id_ANY.R' 'dbiDataType.R' 'dbiDataType_ANY.R' diff --git a/R/dbAppendStream.R b/R/dbAppendStream.R index fd01e0e2..4977e37a 100644 --- a/R/dbAppendStream.R +++ b/R/dbAppendStream.R @@ -1,4 +1,5 @@ -#' @name dbWriteTable +#' @include dbAppendTable.R +#' @name dbAppendTable #' @aliases dbAppendStream #' @export setGeneric("dbAppendStream", diff --git a/R/dbAppendTable.R b/R/dbAppendTable.R index 09ab1909..15753461 100644 --- a/R/dbAppendTable.R +++ b/R/dbAppendTable.R @@ -14,8 +14,8 @@ #' Process the values with [sqlRownamesToColumn()] before calling this method. #' #' @inheritParams dbReadTable -#' @param value A data frame of values. The column names must be consistent -#' with those in the target table in the database. +#' @param value For `dbAppendTable()`, a [data.frame] (or coercible to data.frame). +#' For `dbAppendStream()`, an object coercible to an Arrow RecordBatchReader. #' @param row.names Must be `NULL`. #' @inheritParams sqlAppendTableTemplate #' diff --git a/R/dbCreateFromStream.R b/R/dbCreateFromStream.R index dce2324c..17ccae37 100644 --- a/R/dbCreateFromStream.R +++ b/R/dbCreateFromStream.R @@ -1,5 +1,7 @@ -#' @name dbWriteTable +#' @include dbCreateTable.R +#' @name dbCreateTable #' @aliases dbCreateFromStream +#' @param value An object coercible to an Arrow RecordBatchReader. #' @export setGeneric("dbCreateFromStream", def = function(conn, name, value, ...) standardGeneric("dbCreateFromStream") diff --git a/R/dbWriteStream.R b/R/dbWriteStream.R index bbe534f4..00a98b0a 100644 --- a/R/dbWriteStream.R +++ b/R/dbWriteStream.R @@ -1,3 +1,4 @@ +#' @include dbWriteTable.R #' @name dbWriteTable #' @aliases dbWriteStream #' @export diff --git a/R/dbWriteTable.R b/R/dbWriteTable.R index d359136c..5eca7d30 100644 --- a/R/dbWriteTable.R +++ b/R/dbWriteTable.R @@ -5,9 +5,9 @@ #' #' @details #' This function is useful if you want to create and load a table at the same time. -#' Use [dbAppendTable()] for appending data to a table, -#' and [dbCreateTable()], [dbExistsTable()] and [dbRemoveTable()] -#' for more control over the individual operations. +#' Use [dbAppendTable()] or [dbAppendStream()] for appending data to an existing +#' table, [dbCreateTable()] or [dbCreateFromStream()] for creating a table, +#' and [dbExistsTable()] and [dbRemoveTable()] for overwriting tables. #' #' DBI only standardizes writing data frames and `ArrowTabular` objects. #' Some backends might implement methods that can consume CSV files @@ -24,7 +24,8 @@ #' #' @inheritParams dbGetQuery #' @inheritParams dbReadTable -#' @param value a [data.frame] (or coercible to data.frame). +#' @param value For `dbWriteTable()`, a [data.frame] (or coercible to data.frame). +#' For `dbWriteStream()`, an object coercible to an Arrow RecordBatchReader. #' @family DBIConnection generics #' @export #' @examples diff --git a/man/dbAppendTable.Rd b/man/dbAppendTable.Rd index a3fc1fb0..7b722690 100644 --- a/man/dbAppendTable.Rd +++ b/man/dbAppendTable.Rd @@ -1,10 +1,13 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/dbAppendTable.R +% Please edit documentation in R/dbAppendTable.R, R/dbAppendStream.R \name{dbAppendTable} \alias{dbAppendTable} +\alias{dbAppendStream} \title{Insert rows into a table} \usage{ dbAppendTable(conn, name, value, ..., row.names = NULL) + +dbAppendStream(conn, name, value, ...) } \arguments{ \item{conn}{A \linkS4class{DBIConnection} object, as returned by @@ -20,8 +23,8 @@ e.g. \code{Id(schema = "my_schema", table = "table_name")} given verbatim, e.g. \code{SQL('"my_schema"."table_name"')} }} -\item{value}{A data frame of values. The column names must be consistent -with those in the target table in the database.} +\item{value}{For \code{dbAppendTable()}, a \link{data.frame} (or coercible to data.frame). +For \code{dbAppendStream()}, an object coercible to an Arrow RecordBatchReader.} \item{...}{Other parameters passed on to methods.} diff --git a/man/dbCreateTable.Rd b/man/dbCreateTable.Rd index d6fb3d0f..02683d8a 100644 --- a/man/dbCreateTable.Rd +++ b/man/dbCreateTable.Rd @@ -1,10 +1,13 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/dbCreateTable.R +% Please edit documentation in R/dbCreateTable.R, R/dbCreateFromStream.R \name{dbCreateTable} \alias{dbCreateTable} +\alias{dbCreateFromStream} \title{Create a table in the database} \usage{ dbCreateTable(conn, name, fields, ..., row.names = NULL, temporary = FALSE) + +dbCreateFromStream(conn, name, value, ...) } \arguments{ \item{conn}{A \linkS4class{DBIConnection} object, as returned by @@ -34,6 +37,8 @@ A data frame: field types are generated using \item{row.names}{Must be \code{NULL}.} \item{temporary}{If \code{TRUE}, will generate a temporary table statement.} + +\item{value}{An object coercible to an Arrow RecordBatchReader.} } \value{ \code{dbCreateTable()} returns \code{TRUE}, invisibly. diff --git a/man/dbWriteTable.Rd b/man/dbWriteTable.Rd index c5476c17..0a85f8c4 100644 --- a/man/dbWriteTable.Rd +++ b/man/dbWriteTable.Rd @@ -1,20 +1,13 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/dbAppendStream.R, R/dbCreateFromStream.R, -% R/dbWriteStream.R, R/dbWriteTable.R +% Please edit documentation in R/dbWriteTable.R, R/dbWriteStream.R \name{dbWriteTable} \alias{dbWriteTable} -\alias{dbAppendStream} -\alias{dbCreateFromStream} \alias{dbWriteStream} \title{Copy data frames to database tables} \usage{ -dbAppendStream(conn, name, value, ...) - -dbCreateFromStream(conn, name, value, ...) +dbWriteTable(conn, name, value, ...) dbWriteStream(conn, name, value, ...) - -dbWriteTable(conn, name, value, ...) } \arguments{ \item{conn}{A \linkS4class{DBIConnection} object, as returned by @@ -30,7 +23,8 @@ e.g. \code{Id(schema = "my_schema", table = "table_name")} given verbatim, e.g. \code{SQL('"my_schema"."table_name"')} }} -\item{value}{a \link{data.frame} (or coercible to data.frame).} +\item{value}{For \code{dbWriteTable()}, a \link{data.frame} (or coercible to data.frame). +For \code{dbWriteStream()}, an object coercible to an Arrow RecordBatchReader.} \item{...}{Other parameters passed on to methods.} } @@ -45,9 +39,9 @@ converting row names to a column and specifying SQL data types for fields. } \details{ This function is useful if you want to create and load a table at the same time. -Use \code{\link[=dbAppendTable]{dbAppendTable()}} for appending data to a table, -and \code{\link[=dbCreateTable]{dbCreateTable()}}, \code{\link[=dbExistsTable]{dbExistsTable()}} and \code{\link[=dbRemoveTable]{dbRemoveTable()}} -for more control over the individual operations. +Use \code{\link[=dbAppendTable]{dbAppendTable()}} or \code{\link[=dbAppendStream]{dbAppendStream()}} for appending data to an existing +table, \code{\link[=dbCreateTable]{dbCreateTable()}} or \code{\link[=dbCreateFromStream]{dbCreateFromStream()}} for creating a table, +and \code{\link[=dbExistsTable]{dbExistsTable()}} and \code{\link[=dbRemoveTable]{dbRemoveTable()}} for overwriting tables. DBI only standardizes writing data frames and \code{ArrowTabular} objects. Some backends might implement methods that can consume CSV files From 46b2fa50fc9af0442be0e4b2627f83d6f3ebb9a0 Mon Sep 17 00:00:00 2001 From: krlmlr Date: Sun, 13 Nov 2022 07:08:31 +0000 Subject: [PATCH 3/4] Auto-update from GitHub Actions Run: https://github.com/r-dbi/DBI/actions/runs/3454253218 --- man/dbClearResult.Rd | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/man/dbClearResult.Rd b/man/dbClearResult.Rd index b049ae3e..c2712601 100644 --- a/man/dbClearResult.Rd +++ b/man/dbClearResult.Rd @@ -13,9 +13,8 @@ dbClearResult(res, ...) } \value{ \code{dbClearResult()} returns \code{TRUE}, invisibly, for result sets obtained from -\code{dbSendQuery()}, -\code{dbSendStatement()}, -or \code{dbSendQueryStream()}, +both \code{dbSendQuery()} +and \code{dbSendStatement()}. } \description{ Frees all resources (local and remote) associated with a result set. @@ -93,9 +92,7 @@ to ensure that this step is always executed. An attempt to close an already closed result set issues a warning -for \code{dbSendQuery()}, -\code{dbSendStatement()}, -and \code{dbSendQueryStream()}, +in both cases. } From dfc9701196015d34c3ea905e4db445e6eb2f95ea Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kirill=20M=C3=BCller?= Date: Sun, 13 Nov 2022 08:17:07 +0100 Subject: [PATCH 4/4] Tweak vignette --- vignettes/DBI-arrow.Rmd | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/vignettes/DBI-arrow.Rmd b/vignettes/DBI-arrow.Rmd index 80b31ef1..7ea9c32e 100644 --- a/vignettes/DBI-arrow.Rmd +++ b/vignettes/DBI-arrow.Rmd @@ -39,7 +39,9 @@ Apache Arrow is - suitable for large and huge data, also out-of-memory - data exchange format, good support for data types used in SQL databases - new extension points to allow backends (currently DuckDB and adbc) to make use of the data exchange format -- faster data retrieval and loading +- faster data retrieval and loading, by avoiding serialization in some cases +- better support for reading and summarizing data from a database that is larger than memory +- better type fidelity with workflows centered around Arrow - fundamental data structure: `arrow::RecordBatchReader` ## New classes and generics @@ -50,6 +52,8 @@ Apache Arrow is - New generics: - `dbStreamTable()` + - `dbCreateFromStream()` + - `dbAppendStream()` - `dbGetStream()` - `dbSendQueryStream()` - `dbStream()`