docs: Harmonize table documentation

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'

R/dbAppendStream.R

@@ -1,4 +1,5 @@
-#' @name dbWriteTable
+#' @include dbAppendTable.R
+#' @name dbAppendTable
 #' @aliases dbAppendStream
 #' @export
 setGeneric("dbAppendStream",

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
 #'

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")

R/dbWriteStream.R

@@ -1,3 +1,4 @@
+#' @include dbWriteTable.R
 #' @name dbWriteTable
 #' @aliases dbWriteStream
 #' @export

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

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()`