From 4b76ba992fd2db9d9148ee3c1a863098ce062c42 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kirill=20M=C3=BCller?= Date: Mon, 9 Oct 2023 17:04:10 +0200 Subject: [PATCH] Tweak docs --- R/db-interface.R | 53 ++++++++++++++++++++++++++++++++++++----------- man/copy_dm_to.Rd | 48 +++++++++++++++++++++++++++++++++++------- 2 files changed, 81 insertions(+), 20 deletions(-) diff --git a/R/db-interface.R b/R/db-interface.R index 2162eb78e4..3e82ecc67c 100644 --- a/R/db-interface.R +++ b/R/db-interface.R @@ -6,15 +6,19 @@ #' The latter is copied to the former. #' The default is to create temporary tables, set `temporary = FALSE` to create permanent tables. #' Unless `set_key_constraints` is `FALSE`, primary key, foreign key, and unique constraints -#' are set on all databases. +#' are set, and indexes for foreign keys are created, on all databases. #' #' @inheritParams dm_examine_constraints #' #' @param dest An object of class `"src"` or `"DBIConnection"`. #' @param dm A `dm` object. -#' @param set_key_constraints If `TRUE` will mirror `dm` primary and foreign key constraints on a database -#' and create indexes for foreign key constraints. -#' Set to `FALSE` if your data model currently does not satisfy primary or foreign key constraints. +#' @inheritParams rlang::args_dots_empty +#' @param set_key_constraints If `TRUE` will mirror +#' the primary, foreign, and unique key constraints +#' and create indexes for foreign key constraints +#' for the primary and foreign keys in the `dm` object. +#' Set to `FALSE` if your data model currently does not satisfy +#' primary or foreign key constraints. #' @param temporary If `TRUE`, only temporary tables will be created. #' These tables will vanish when disconnecting from the database. #' @param schema Name of schema to copy the `dm` to. @@ -22,9 +26,38 @@ #' `table_names` is not `NULL`. #' #' Not all DBMS are supported. -#' @inheritParams dm_sql -#' @inheritParams rlang::args_dots_empty -#' @param unique_table_names,copy_to Deprecated. +#' @param table_names Desired names for the tables on `dest`; the names within the `dm` remain unchanged. +#' Can be `NULL`, a named character vector, or a vector of [DBI::Id] objects. +#' +#' If left `NULL` (default), the names will be determined automatically depending on the `temporary` argument: +#' +#' 1. `temporary = TRUE` (default): unique table names based on the names of the tables in the `dm` are created. +#' 1. `temporary = FALSE`: the table names in the `dm` are used as names for the tables on `dest`. +#' +#' If a function or one-sided formula, `table_names` is converted to a function +#' using [rlang::as_function()]. +#' This function is called with the unquoted table names of the `dm` object +#' as the only argument. +#' The output of this function is processed by [DBI::dbQuoteIdentifier()], +#' that result should be a vector of identifiers of the same length +#' as the original table names. +#' +#' Use a variant of +#' `table_names = ~ DBI::SQL(paste0("schema_name", ".", .x))` +#' to specify the same schema for all tables. +#' Use `table_names = identity` with `temporary = TRUE` +#' to avoid giving temporary tables unique names. +#' +#' If a named character vector, +#' the names of this vector need to correspond to the table names in the `dm`, +#' and its values are the desired names on `dest`. +#' The value is processed by [DBI::dbQuoteIdentifier()], +#' that result should be a vector of identifiers of the same length +#' as the original table names. +#' +#' Use qualified names corresponding to your database's syntax +#' to specify e.g. database and schema for your tables. +#' @param unique_table_names,copy_to Must be `NULL`. #' #' @family DB interaction functions #' @@ -63,11 +96,7 @@ copy_dm_to <- function( progress = NA, unique_table_names = NULL, copy_to = NULL) { - # for the time being, we will be focusing on MSSQL - # we want to - # 1. change `dm_get_src_impl(dm)` to `dest` - # 2. copy the tables to `dest` - # 3. implement the key situation within our `dm` on the DB + # if (!is.null(unique_table_names)) { deprecate_stop( diff --git a/man/copy_dm_to.Rd b/man/copy_dm_to.Rd index 6b1ab02cea..5f57acdab4 100644 --- a/man/copy_dm_to.Rd +++ b/man/copy_dm_to.Rd @@ -24,15 +24,45 @@ copy_dm_to( \item{...}{These dots are for future extensions and must be empty.} -\item{set_key_constraints}{If \code{TRUE} will mirror \code{dm} primary and foreign key constraints on a database -and create indexes for foreign key constraints. -Set to \code{FALSE} if your data model currently does not satisfy primary or foreign key constraints.} +\item{set_key_constraints}{If \code{TRUE} will mirror +the primary, foreign, and unique key constraints +and create indexes for foreign key constraints +for the primary and foreign keys in the \code{dm} object. +Set to \code{FALSE} if your data model currently does not satisfy +primary or foreign key constraints.} -\item{unique_table_names, copy_to}{Deprecated.} +\item{table_names}{Desired names for the tables on \code{dest}; the names within the \code{dm} remain unchanged. +Can be \code{NULL}, a named character vector, or a vector of \link[DBI:Id]{DBI::Id} objects. -\item{table_names}{A named character vector or vector of \link[DBI:Id]{DBI::Id} objects, -with one unique element for each table in \code{dm}. -The default, \code{NULL}, means to use the original table names.} +If left \code{NULL} (default), the names will be determined automatically depending on the \code{temporary} argument: +\enumerate{ +\item \code{temporary = TRUE} (default): unique table names based on the names of the tables in the \code{dm} are created. +\item \code{temporary = FALSE}: the table names in the \code{dm} are used as names for the tables on \code{dest}. +} + +If a function or one-sided formula, \code{table_names} is converted to a function +using \code{\link[rlang:as_function]{rlang::as_function()}}. +This function is called with the unquoted table names of the \code{dm} object +as the only argument. +The output of this function is processed by \code{\link[DBI:dbQuoteIdentifier]{DBI::dbQuoteIdentifier()}}, +that result should be a vector of identifiers of the same length +as the original table names. + +Use a variant of +\code{table_names = ~ DBI::SQL(paste0("schema_name", ".", .x))} +to specify the same schema for all tables. +Use \code{table_names = identity} with \code{temporary = TRUE} +to avoid giving temporary tables unique names. + +If a named character vector, +the names of this vector need to correspond to the table names in the \code{dm}, +and its values are the desired names on \code{dest}. +The value is processed by \code{\link[DBI:dbQuoteIdentifier]{DBI::dbQuoteIdentifier()}}, +that result should be a vector of identifiers of the same length +as the original table names. + +Use qualified names corresponding to your database's syntax +to specify e.g. database and schema for your tables.} \item{temporary}{If \code{TRUE}, only temporary tables will be created. These tables will vanish when disconnecting from the database.} @@ -46,6 +76,8 @@ Not all DBMS are supported.} \item{progress}{Whether to display a progress bar, if \code{NA} (the default) hide in non-interactive mode, show in interactive mode. Requires the 'progress' package.} + +\item{unique_table_names, copy_to}{Must be \code{NULL}.} } \value{ A \code{dm} object on the given \code{src} with the same table names @@ -57,7 +89,7 @@ and a \code{\link{dm}} object as its second argument. The latter is copied to the former. The default is to create temporary tables, set \code{temporary = FALSE} to create permanent tables. Unless \code{set_key_constraints} is \code{FALSE}, primary key, foreign key, and unique constraints -are set on all databases. +are set, and indexes for foreign keys are created, on all databases. } \examples{ \dontshow{if (rlang::is_installed(c("RSQLite", "nycflights13", "dbplyr"))) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf}