From f8466935cfbc6efd5923c688ddd9143b351f7f63 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kirill=20M=C3=BCller?= Date: Sat, 23 Dec 2023 12:53:52 +0100 Subject: [PATCH] dbCreateTableArrow --- R/12-dbCreateTable.R | 2 + R/22-dbCreateTableArrow.R | 33 ++++++++- _pkgdown.yml | 1 + man/DBIConnection-class.Rd | 1 + man/dbAppendTable.Rd | 1 + man/dbCreateTable.Rd | 16 ++--- man/dbCreateTableArrow.Rd | 136 +++++++++++++++++++++++++++++++++++++ man/dbDataType.Rd | 1 + man/dbDisconnect.Rd | 1 + man/dbExecute.Rd | 1 + man/dbExistsTable.Rd | 1 + man/dbGetException.Rd | 1 + man/dbGetInfo.Rd | 1 + man/dbGetQuery.Rd | 1 + man/dbIsReadOnly.Rd | 1 + man/dbIsValid.Rd | 1 + man/dbListFields.Rd | 1 + man/dbListObjects.Rd | 1 + man/dbListResults.Rd | 1 + man/dbListTables.Rd | 1 + man/dbReadTable.Rd | 1 + man/dbReadTableArrow.Rd | 1 + man/dbRemoveTable.Rd | 1 + man/dbSendQuery.Rd | 1 + man/dbSendStatement.Rd | 1 + man/dbWriteTable.Rd | 1 + man/dbWriteTableArrow.Rd | 1 + 27 files changed, 198 insertions(+), 12 deletions(-) create mode 100644 man/dbCreateTableArrow.Rd diff --git a/R/12-dbCreateTable.R b/R/12-dbCreateTable.R index 15e669971..a18bf0237 100644 --- a/R/12-dbCreateTable.R +++ b/R/12-dbCreateTable.R @@ -2,6 +2,8 @@ #' #' The default `dbCreateTable()` method calls [sqlCreateTable()] and #' [dbExecute()]. +#' Use [dbCreateTableArrow()] to create a table from an Arrow schema. +#' #' Backends compliant to ANSI SQL 99 don't need to override it. #' Backends with a different SQL syntax can override `sqlCreateTable()`, #' backends with entirely different ways to create tables need to diff --git a/R/22-dbCreateTableArrow.R b/R/22-dbCreateTableArrow.R index 3b9555050..7dcc51fb2 100644 --- a/R/22-dbCreateTableArrow.R +++ b/R/22-dbCreateTableArrow.R @@ -1,7 +1,34 @@ -#' @name dbCreateTable -#' @aliases dbCreateTableArrow -#' @param value An object coercible to an Arrow RecordBatchReader. +#' Create a table in the database based on an Arrow object +#' +#' The default `dbCreateTableArrow()` method determines the R data types +#' of the Arrow schema associated with the Arrow object, +#' and calls [dbCreateTable()]. +#' Backends who implement [dbAppendTableArrow()] should typically +#' also implement this generic. +#' Use [dbCreateTable()] to create a table from the column types +#' as defined in a data frame. +#' +#' @param value An object for which a schema can be determined via +#' [nanoarrow::infer_nanoarrow_schema()]. +#' @inheritParams dbReadTable +#' @inheritParams sqlCreateTable +#' +#' @inherit DBItest::spec_arrow_create_table_arrow return +#' @inheritSection DBItest::spec_arrow_create_table_arrow Failure modes +#' @inheritSection DBItest::spec_arrow_create_table_arrow Additional arguments +#' @inheritSection DBItest::spec_arrow_create_table_arrow Specification +#' +#' @template methods +#' @templateVar method_name dbCreateTableArrow +#' +#' @family DBIConnection generics #' @export +#' @examplesIf requireNamespace("RSQLite", quietly = TRUE) && requireNamespace("nanoarrow", quietly = TRUE) +#' con <- dbConnect(RSQLite::SQLite(), ":memory:") +#' ptype <- data.frame(a = numeric()) +#' dbCreateTableArrow(con, "df", nanoarrow::infer_nanoarrow_schema(ptype)) +#' dbReadTable(con, "df") +#' dbDisconnect(con) setGeneric("dbCreateTableArrow", def = function(conn, name, value, ...) standardGeneric("dbCreateTableArrow") ) diff --git a/_pkgdown.yml b/_pkgdown.yml index 7468568b8..1c689e3ae 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -82,6 +82,7 @@ reference: contents: - dbReadTableArrow - dbWriteTableArrow + - dbCreateTableArrow - title: Classes desc: S4 classes defined by DBI. diff --git a/man/DBIConnection-class.Rd b/man/DBIConnection-class.Rd index 5df202328..242c4a16a 100644 --- a/man/DBIConnection-class.Rd +++ b/man/DBIConnection-class.Rd @@ -37,6 +37,7 @@ Other DBI classes: Other DBIConnection generics: \code{\link{dbAppendTable}()}, \code{\link{dbCreateTable}()}, +\code{\link{dbCreateTableArrow}()}, \code{\link{dbDataType}()}, \code{\link{dbDisconnect}()}, \code{\link{dbExecute}()}, diff --git a/man/dbAppendTable.Rd b/man/dbAppendTable.Rd index 2f70710af..81a1b7167 100644 --- a/man/dbAppendTable.Rd +++ b/man/dbAppendTable.Rd @@ -166,6 +166,7 @@ dbDisconnect(con) Other DBIConnection generics: \code{\link{DBIConnection-class}}, \code{\link{dbCreateTable}()}, +\code{\link{dbCreateTableArrow}()}, \code{\link{dbDataType}()}, \code{\link{dbDisconnect}()}, \code{\link{dbExecute}()}, diff --git a/man/dbCreateTable.Rd b/man/dbCreateTable.Rd index d0fbcef1a..666ed9da8 100644 --- a/man/dbCreateTable.Rd +++ b/man/dbCreateTable.Rd @@ -1,13 +1,10 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/12-dbCreateTable.R, R/22-dbCreateTableArrow.R +% Please edit documentation in R/12-dbCreateTable.R \name{dbCreateTable} \alias{dbCreateTable} -\alias{dbCreateTableArrow} \title{Create a table in the database} \usage{ dbCreateTable(conn, name, fields, ..., row.names = NULL, temporary = FALSE) - -dbCreateTableArrow(conn, name, value, ...) } \arguments{ \item{conn}{A \linkS4class{DBIConnection} object, as returned by @@ -37,8 +34,6 @@ 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. @@ -46,14 +41,16 @@ A data frame: field types are generated using \description{ The default \code{dbCreateTable()} method calls \code{\link[=sqlCreateTable]{sqlCreateTable()}} and \code{\link[=dbExecute]{dbExecute()}}. +Use \code{\link[=dbCreateTableArrow]{dbCreateTableArrow()}} to create a table from an Arrow schema. + +\Sexpr[results=rd,stage=render]{DBI:::methods_as_rd("dbCreateTable")} +} +\details{ Backends compliant to ANSI SQL 99 don't need to override it. Backends with a different SQL syntax can override \code{sqlCreateTable()}, backends with entirely different ways to create tables need to override this method. -\Sexpr[results=rd,stage=render]{DBI:::methods_as_rd("dbCreateTable")} -} -\details{ The \code{row.names} argument is not supported by this method. Process the values with \code{\link[=sqlRownamesToColumn]{sqlRownamesToColumn()}} before calling this method. @@ -139,6 +136,7 @@ dbDisconnect(con) Other DBIConnection generics: \code{\link{DBIConnection-class}}, \code{\link{dbAppendTable}()}, +\code{\link{dbCreateTableArrow}()}, \code{\link{dbDataType}()}, \code{\link{dbDisconnect}()}, \code{\link{dbExecute}()}, diff --git a/man/dbCreateTableArrow.Rd b/man/dbCreateTableArrow.Rd new file mode 100644 index 000000000..37fb1a4e0 --- /dev/null +++ b/man/dbCreateTableArrow.Rd @@ -0,0 +1,136 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/22-dbCreateTableArrow.R +\name{dbCreateTableArrow} +\alias{dbCreateTableArrow} +\title{Create a table in the database based on an Arrow object} +\usage{ +dbCreateTableArrow(conn, name, value, ...) +} +\arguments{ +\item{conn}{A \linkS4class{DBIConnection} object, as returned by +\code{\link[=dbConnect]{dbConnect()}}.} + +\item{name}{The table name, passed on to \code{\link[=dbQuoteIdentifier]{dbQuoteIdentifier()}}. Options are: +\itemize{ +\item a character string with the unquoted DBMS table name, +e.g. \code{"table_name"}, +\item a call to \code{\link[=Id]{Id()}} with components to the fully qualified table name, +e.g. \code{Id(schema = "my_schema", table = "table_name")} +\item a call to \code{\link[=SQL]{SQL()}} with the quoted and fully qualified table name +given verbatim, e.g. \code{SQL('"my_schema"."table_name"')} +}} + +\item{value}{An object for which a schema can be determined via +\code{\link[nanoarrow:as_nanoarrow_schema]{nanoarrow::infer_nanoarrow_schema()}}.} + +\item{...}{Other parameters passed on to methods.} +} +\value{ +\code{dbCreateTableArrow()} returns \code{TRUE}, invisibly. +} +\description{ +The default \code{dbCreateTableArrow()} method determines the R data types +of the Arrow schema associated with the Arrow object, +and calls \code{\link[=dbCreateTable]{dbCreateTable()}}. +Backends who implement \code{\link[=dbAppendTableArrow]{dbAppendTableArrow()}} should typically +also implement this generic. +Use \code{\link[=dbCreateTable]{dbCreateTable()}} to create a table from the column types +as defined in a data frame. + +\Sexpr[results=rd,stage=render]{DBI:::methods_as_rd("dbCreateTableArrow")} +} +\section{Failure modes}{ + + +If the table exists, an error is raised; the remote table remains unchanged. + +An error is raised when calling this method for a closed +or invalid connection. +An error is also raised +if \code{name} cannot be processed with \code{\link[=dbQuoteIdentifier]{dbQuoteIdentifier()}} +or if this results in a non-scalar. +Invalid values for the \code{temporary} argument +(non-scalars, +unsupported data types, +\code{NA}, +incompatible values, +duplicate names) +also raise an error. + +} + +\section{Additional arguments}{ + + +The following arguments are not part of the \code{dbCreateTableArrow()} generic +(to improve compatibility across backends) +but are part of the DBI specification: +\itemize{ +\item \code{temporary} (default: \code{FALSE}) +} + +They must be provided as named arguments. +See the "Specification" and "Value" sections for details on their usage. + +} + +\section{Specification}{ + + +The \code{name} argument is processed as follows, +to support databases that allow non-syntactic names for their objects: +\itemize{ +\item If an unquoted table name as string: \code{dbCreateTableArrow()} will do the quoting, +perhaps by calling \code{dbQuoteIdentifier(conn, x = name)} +\item If the result of a call to \code{\link[=dbQuoteIdentifier]{dbQuoteIdentifier()}}: no more quoting is done +} + +If the \code{temporary} argument is \code{TRUE}, the table is not available in a +second connection and is gone after reconnecting. +Not all backends support this argument. +A regular, non-temporary table is visible in a second connection, +in a pre-existing connection, +and after reconnecting to the database. + +SQL keywords can be used freely in table names, column names, and data. +Quotes, commas, and spaces can also be used for table names and column names, +if the database supports non-syntactic identifiers. + +} + +\examples{ +\dontshow{if (requireNamespace("RSQLite", quietly = TRUE) && requireNamespace("nanoarrow", quietly = TRUE)) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf} +con <- dbConnect(RSQLite::SQLite(), ":memory:") +ptype <- data.frame(a = numeric()) +dbCreateTableArrow(con, "df", nanoarrow::infer_nanoarrow_schema(ptype)) +dbReadTable(con, "df") +dbDisconnect(con) +\dontshow{\}) # examplesIf} +} +\seealso{ +Other DBIConnection generics: +\code{\link{DBIConnection-class}}, +\code{\link{dbAppendTable}()}, +\code{\link{dbCreateTable}()}, +\code{\link{dbDataType}()}, +\code{\link{dbDisconnect}()}, +\code{\link{dbExecute}()}, +\code{\link{dbExistsTable}()}, +\code{\link{dbGetException}()}, +\code{\link{dbGetInfo}()}, +\code{\link{dbGetQuery}()}, +\code{\link{dbIsReadOnly}()}, +\code{\link{dbIsValid}()}, +\code{\link{dbListFields}()}, +\code{\link{dbListObjects}()}, +\code{\link{dbListResults}()}, +\code{\link{dbListTables}()}, +\code{\link{dbReadTable}()}, +\code{\link{dbReadTableArrow}()}, +\code{\link{dbRemoveTable}()}, +\code{\link{dbSendQuery}()}, +\code{\link{dbSendStatement}()}, +\code{\link{dbWriteTable}()}, +\code{\link{dbWriteTableArrow}()} +} +\concept{DBIConnection generics} diff --git a/man/dbDataType.Rd b/man/dbDataType.Rd index 561e1b2aa..9bacec552 100644 --- a/man/dbDataType.Rd +++ b/man/dbDataType.Rd @@ -135,6 +135,7 @@ Other DBIConnection generics: \code{\link{DBIConnection-class}}, \code{\link{dbAppendTable}()}, \code{\link{dbCreateTable}()}, +\code{\link{dbCreateTableArrow}()}, \code{\link{dbDisconnect}()}, \code{\link{dbExecute}()}, \code{\link{dbExistsTable}()}, diff --git a/man/dbDisconnect.Rd b/man/dbDisconnect.Rd index c98be77c4..f356bf61e 100644 --- a/man/dbDisconnect.Rd +++ b/man/dbDisconnect.Rd @@ -44,6 +44,7 @@ Other DBIConnection generics: \code{\link{DBIConnection-class}}, \code{\link{dbAppendTable}()}, \code{\link{dbCreateTable}()}, +\code{\link{dbCreateTableArrow}()}, \code{\link{dbDataType}()}, \code{\link{dbExecute}()}, \code{\link{dbExistsTable}()}, diff --git a/man/dbExecute.Rd b/man/dbExecute.Rd index 1803318b5..0b414e1bc 100644 --- a/man/dbExecute.Rd +++ b/man/dbExecute.Rd @@ -153,6 +153,7 @@ Other DBIConnection generics: \code{\link{DBIConnection-class}}, \code{\link{dbAppendTable}()}, \code{\link{dbCreateTable}()}, +\code{\link{dbCreateTableArrow}()}, \code{\link{dbDataType}()}, \code{\link{dbDisconnect}()}, \code{\link{dbExistsTable}()}, diff --git a/man/dbExistsTable.Rd b/man/dbExistsTable.Rd index 7b7c5fcf5..6d3e5b723 100644 --- a/man/dbExistsTable.Rd +++ b/man/dbExistsTable.Rd @@ -76,6 +76,7 @@ Other DBIConnection generics: \code{\link{DBIConnection-class}}, \code{\link{dbAppendTable}()}, \code{\link{dbCreateTable}()}, +\code{\link{dbCreateTableArrow}()}, \code{\link{dbDataType}()}, \code{\link{dbDisconnect}()}, \code{\link{dbExecute}()}, diff --git a/man/dbGetException.Rd b/man/dbGetException.Rd index 3c76907d7..aef69f7c6 100644 --- a/man/dbGetException.Rd +++ b/man/dbGetException.Rd @@ -26,6 +26,7 @@ Other DBIConnection generics: \code{\link{DBIConnection-class}}, \code{\link{dbAppendTable}()}, \code{\link{dbCreateTable}()}, +\code{\link{dbCreateTableArrow}()}, \code{\link{dbDataType}()}, \code{\link{dbDisconnect}()}, \code{\link{dbExecute}()}, diff --git a/man/dbGetInfo.Rd b/man/dbGetInfo.Rd index be9a2e61f..81f2e5869 100644 --- a/man/dbGetInfo.Rd +++ b/man/dbGetInfo.Rd @@ -79,6 +79,7 @@ Other DBIConnection generics: \code{\link{DBIConnection-class}}, \code{\link{dbAppendTable}()}, \code{\link{dbCreateTable}()}, +\code{\link{dbCreateTableArrow}()}, \code{\link{dbDataType}()}, \code{\link{dbDisconnect}()}, \code{\link{dbExecute}()}, diff --git a/man/dbGetQuery.Rd b/man/dbGetQuery.Rd index ac3191fa3..502377d36 100644 --- a/man/dbGetQuery.Rd +++ b/man/dbGetQuery.Rd @@ -188,6 +188,7 @@ Other DBIConnection generics: \code{\link{DBIConnection-class}}, \code{\link{dbAppendTable}()}, \code{\link{dbCreateTable}()}, +\code{\link{dbCreateTableArrow}()}, \code{\link{dbDataType}()}, \code{\link{dbDisconnect}()}, \code{\link{dbExecute}()}, diff --git a/man/dbIsReadOnly.Rd b/man/dbIsReadOnly.Rd index 523ad7fbe..31b26641d 100644 --- a/man/dbIsReadOnly.Rd +++ b/man/dbIsReadOnly.Rd @@ -36,6 +36,7 @@ Other DBIConnection generics: \code{\link{DBIConnection-class}}, \code{\link{dbAppendTable}()}, \code{\link{dbCreateTable}()}, +\code{\link{dbCreateTableArrow}()}, \code{\link{dbDataType}()}, \code{\link{dbDisconnect}()}, \code{\link{dbExecute}()}, diff --git a/man/dbIsValid.Rd b/man/dbIsValid.Rd index f840315c2..bfe7c84c0 100644 --- a/man/dbIsValid.Rd +++ b/man/dbIsValid.Rd @@ -69,6 +69,7 @@ Other DBIConnection generics: \code{\link{DBIConnection-class}}, \code{\link{dbAppendTable}()}, \code{\link{dbCreateTable}()}, +\code{\link{dbCreateTableArrow}()}, \code{\link{dbDataType}()}, \code{\link{dbDisconnect}()}, \code{\link{dbExecute}()}, diff --git a/man/dbListFields.Rd b/man/dbListFields.Rd index f9a3c6ddd..ef1eec203 100644 --- a/man/dbListFields.Rd +++ b/man/dbListFields.Rd @@ -81,6 +81,7 @@ Other DBIConnection generics: \code{\link{DBIConnection-class}}, \code{\link{dbAppendTable}()}, \code{\link{dbCreateTable}()}, +\code{\link{dbCreateTableArrow}()}, \code{\link{dbDataType}()}, \code{\link{dbDisconnect}()}, \code{\link{dbExecute}()}, diff --git a/man/dbListObjects.Rd b/man/dbListObjects.Rd index 3a2296a6b..d81f1c611 100644 --- a/man/dbListObjects.Rd +++ b/man/dbListObjects.Rd @@ -104,6 +104,7 @@ Other DBIConnection generics: \code{\link{DBIConnection-class}}, \code{\link{dbAppendTable}()}, \code{\link{dbCreateTable}()}, +\code{\link{dbCreateTableArrow}()}, \code{\link{dbDataType}()}, \code{\link{dbDisconnect}()}, \code{\link{dbExecute}()}, diff --git a/man/dbListResults.Rd b/man/dbListResults.Rd index c859983e0..d3df2807a 100644 --- a/man/dbListResults.Rd +++ b/man/dbListResults.Rd @@ -26,6 +26,7 @@ Other DBIConnection generics: \code{\link{DBIConnection-class}}, \code{\link{dbAppendTable}()}, \code{\link{dbCreateTable}()}, +\code{\link{dbCreateTableArrow}()}, \code{\link{dbDataType}()}, \code{\link{dbDisconnect}()}, \code{\link{dbExecute}()}, diff --git a/man/dbListTables.Rd b/man/dbListTables.Rd index 56bf96f58..7cb32676c 100644 --- a/man/dbListTables.Rd +++ b/man/dbListTables.Rd @@ -59,6 +59,7 @@ Other DBIConnection generics: \code{\link{DBIConnection-class}}, \code{\link{dbAppendTable}()}, \code{\link{dbCreateTable}()}, +\code{\link{dbCreateTableArrow}()}, \code{\link{dbDataType}()}, \code{\link{dbDisconnect}()}, \code{\link{dbExecute}()}, diff --git a/man/dbReadTable.Rd b/man/dbReadTable.Rd index d9c782b8f..0a156cfde 100644 --- a/man/dbReadTable.Rd +++ b/man/dbReadTable.Rd @@ -132,6 +132,7 @@ Other DBIConnection generics: \code{\link{DBIConnection-class}}, \code{\link{dbAppendTable}()}, \code{\link{dbCreateTable}()}, +\code{\link{dbCreateTableArrow}()}, \code{\link{dbDataType}()}, \code{\link{dbDisconnect}()}, \code{\link{dbExecute}()}, diff --git a/man/dbReadTableArrow.Rd b/man/dbReadTableArrow.Rd index f019a4504..8c0d922b8 100644 --- a/man/dbReadTableArrow.Rd +++ b/man/dbReadTableArrow.Rd @@ -83,6 +83,7 @@ Other DBIConnection generics: \code{\link{DBIConnection-class}}, \code{\link{dbAppendTable}()}, \code{\link{dbCreateTable}()}, +\code{\link{dbCreateTableArrow}()}, \code{\link{dbDataType}()}, \code{\link{dbDisconnect}()}, \code{\link{dbExecute}()}, diff --git a/man/dbRemoveTable.Rd b/man/dbRemoveTable.Rd index 18020a340..8a6164e1c 100644 --- a/man/dbRemoveTable.Rd +++ b/man/dbRemoveTable.Rd @@ -106,6 +106,7 @@ Other DBIConnection generics: \code{\link{DBIConnection-class}}, \code{\link{dbAppendTable}()}, \code{\link{dbCreateTable}()}, +\code{\link{dbCreateTableArrow}()}, \code{\link{dbDataType}()}, \code{\link{dbDisconnect}()}, \code{\link{dbExecute}()}, diff --git a/man/dbSendQuery.Rd b/man/dbSendQuery.Rd index a14465c78..98cf1bc82 100644 --- a/man/dbSendQuery.Rd +++ b/man/dbSendQuery.Rd @@ -225,6 +225,7 @@ Other DBIConnection generics: \code{\link{DBIConnection-class}}, \code{\link{dbAppendTable}()}, \code{\link{dbCreateTable}()}, +\code{\link{dbCreateTableArrow}()}, \code{\link{dbDataType}()}, \code{\link{dbDisconnect}()}, \code{\link{dbExecute}()}, diff --git a/man/dbSendStatement.Rd b/man/dbSendStatement.Rd index 7cdda30c0..54d352339 100644 --- a/man/dbSendStatement.Rd +++ b/man/dbSendStatement.Rd @@ -205,6 +205,7 @@ Other DBIConnection generics: \code{\link{DBIConnection-class}}, \code{\link{dbAppendTable}()}, \code{\link{dbCreateTable}()}, +\code{\link{dbCreateTableArrow}()}, \code{\link{dbDataType}()}, \code{\link{dbDisconnect}()}, \code{\link{dbExecute}()}, diff --git a/man/dbWriteTable.Rd b/man/dbWriteTable.Rd index 78a0cc0e5..56f3c8b37 100644 --- a/man/dbWriteTable.Rd +++ b/man/dbWriteTable.Rd @@ -218,6 +218,7 @@ Other DBIConnection generics: \code{\link{DBIConnection-class}}, \code{\link{dbAppendTable}()}, \code{\link{dbCreateTable}()}, +\code{\link{dbCreateTableArrow}()}, \code{\link{dbDataType}()}, \code{\link{dbDisconnect}()}, \code{\link{dbExecute}()}, diff --git a/man/dbWriteTableArrow.Rd b/man/dbWriteTableArrow.Rd index 596fd7e71..6fa87627c 100644 --- a/man/dbWriteTableArrow.Rd +++ b/man/dbWriteTableArrow.Rd @@ -181,6 +181,7 @@ Other DBIConnection generics: \code{\link{DBIConnection-class}}, \code{\link{dbAppendTable}()}, \code{\link{dbCreateTable}()}, +\code{\link{dbCreateTableArrow}()}, \code{\link{dbDataType}()}, \code{\link{dbDisconnect}()}, \code{\link{dbExecute}()},