diff --git a/R/db-sql.R b/R/db-sql.R index b8f934d46..63235d7b0 100644 --- a/R/db-sql.R +++ b/R/db-sql.R @@ -688,8 +688,9 @@ sql_query_union.DBIConnection <- function(con, x, unions, ..., lvl = 0) { #' These functions generate the SQL used in `rows_*(in_place = TRUE)`. #' #' @param con Database connection. -#' @param table Table to update. Must be a table identifier, e.g. single string -#' or created via `in_schema()`. +#' @param table Table to update. Must be a table identifier. +#' Use a string to refer to tables in the current schema/catalog or +#' `I()` to refer to tables in other schemas/catalogs. #' @param from Table or query that contains the new data. Either a table #' identifier or SQL. #' @inheritParams dplyr::rows_upsert diff --git a/R/ident.R b/R/ident.R index ab456ce19..835a21799 100644 --- a/R/ident.R +++ b/R/ident.R @@ -1,12 +1,18 @@ #' Flag a character vector as SQL identifiers #' -#' `ident()` takes unquoted strings and flags them as identifiers. -#' `ident_q()` assumes its input has already been quoted, and ensures -#' it does not get quoted again. This is currently used only for -#' `schema.table`. +#' @description +#' `ident()` takes strings and turns them as database identifiers (e.g. table +#' or column names) quoting them using the identifer rules for your database. +#' `ident_q()` does the same, but assumes the names have already been +#' quoted, preventing them from being quoted again. #' -#' @param ... A character vector, or name-value pairs -#' @param x An object +#' These are generally for internal use only; if you need to supply an +#' table name that is qualified with schema or catalog, or has already been +#' quoted for some other reason, use `I()`. +#' +#' @param ... A character vector, or name-value pairs. +#' @param x An object. +#' @keywords internal #' @export #' @examples #' # SQL92 quotes strings with ' diff --git a/R/schema.R b/R/schema.R index 8b75dd3eb..e4f382e28 100644 --- a/R/schema.R +++ b/R/schema.R @@ -1,19 +1,26 @@ -#' Refer to a table in a schema or a database catalog +#' Refer to a table in another schema/catalog #' -#' `in_schema()` can be used in [tbl()] to indicate a table in a specific -#' schema. -#' `in_catalog()` additionally allows specifying the database catalog. +#' @description +#' `in_schema()` and `in_catalog()` can be used to refer to tables outside of +#' the current catalog/schema. However, we now recommend using `I()` as it's +#' typically less typing. #' #' @param catalog,schema,table Names of catalog, schema, and table. #' These will be automatically quoted; use [sql()] to pass a raw name #' that won't get quoted. #' @export +#' @keywords internal #' @examples +#' # Previously: #' in_schema("my_schema", "my_table") #' in_catalog("my_catalog", "my_schema", "my_table") -#' # eliminate quotes #' in_schema(sql("my_schema"), sql("my_table")) #' +#' # Now +#' I("my_schema.my_table") +#' I("my_catalog.my_schema.my_table") +#' I("my_schema.my_table") +#' #' # Example using schemas with SQLite #' con <- DBI::dbConnect(RSQLite::SQLite(), ":memory:") #' @@ -23,10 +30,10 @@ #' #' library(dplyr, warn.conflicts = FALSE) #' copy_to(con, iris, "df", temporary = FALSE) -#' copy_to(con, mtcars, in_schema("aux", "df"), temporary = FALSE) +#' copy_to(con, mtcars, I("aux.df"), temporary = FALSE) #' #' con %>% tbl("df") -#' con %>% tbl(in_schema("aux", "df")) +#' con %>% tbl(I("aux.df")) in_schema <- function(schema, table) { structure( list( diff --git a/R/src_dbi.R b/R/src_dbi.R index 978be8439..5c62b7e56 100644 --- a/R/src_dbi.R +++ b/R/src_dbi.R @@ -15,9 +15,12 @@ #' the data into R. #' #' @param src A `DBIConnection` object produced by `DBI::dbConnect()`. -#' @param from Either a string (giving a table name), -#' a fully qualified table name created by [in_schema()] -#' or a literal [sql()] string. +#' @param from Either a table identifier or a literal [sql()] string. +#' +#' Use a string to identify a table in the current schema/catalog. We +#' recommend using `I()` to identify a table outside the default catalog or +#' schema, e.g. `I("schema.table")` or `I("catalog.schema.table")`. You can +#' also use [in_schema()]/[in_catalog()] or [DBI::Id()]. #' @param ... Passed on to [tbl_sql()] #' @export #' @examples @@ -33,8 +36,8 @@ #' # To retrieve a single table from a source, use `tbl()` #' con %>% tbl("mtcars") #' -#' # Use `in_schema()` for fully qualified table names -#' con %>% tbl(in_schema("temp", "mtcars")) %>% head(1) +#' # Use `I()` for qualified table names +#' con %>% tbl(I("temp.mtcars")) %>% head(1) #' #' # You can also use pass raw SQL if you want a more sophisticated query #' con %>% tbl(sql("SELECT * FROM mtcars WHERE cyl = 8")) diff --git a/R/verb-copy-to.R b/R/verb-copy-to.R index 03489113a..cd0a2bc50 100644 --- a/R/verb-copy-to.R +++ b/R/verb-copy-to.R @@ -13,6 +13,9 @@ #' from another source. If from another source, all data must transition #' through R in one pass, so it is only suitable for transferring small #' amounts of data. +#' @param name Name of new remote table. Use a string to create the table +#' in the current catalog/schema. Use `I()` if you want to create it +#' in a specific catalog/schema, e.g. `I("schema.table")`. #' @param types a character vector giving variable types to use for the columns. #' See for available types. #' @param temporary if `TRUE`, will create a temporary table that is diff --git a/_pkgdown.yml b/_pkgdown.yml index 23957f2df..4acd672b2 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -71,7 +71,6 @@ reference: - title: Database connection contents: - - in_schema - memdb_frame - remote_name @@ -79,7 +78,6 @@ reference: contents: - build_sql - escape - - ident - partial_eval - sql - sql_expr diff --git a/man/copy_to.src_sql.Rd b/man/copy_to.src_sql.Rd index 590bbc612..c7d8f4a1a 100644 --- a/man/copy_to.src_sql.Rd +++ b/man/copy_to.src_sql.Rd @@ -26,7 +26,9 @@ from another source. If from another source, all data must transition through R in one pass, so it is only suitable for transferring small amounts of data.} -\item{name}{name for new remote table.} +\item{name}{Name of new remote table. Use a string to create the table +in the current catalog/schema. Use \code{I()} if you want to create it +in a specific catalog/schema, e.g. \code{I("schema.table")}.} \item{overwrite}{If \code{TRUE}, will overwrite an existing table with name \code{name}. If \code{FALSE}, will throw an error if \code{name} already diff --git a/man/ident.Rd b/man/ident.Rd index 3406d8878..4b728f30f 100644 --- a/man/ident.Rd +++ b/man/ident.Rd @@ -10,15 +10,19 @@ ident(...) is.ident(x) } \arguments{ -\item{...}{A character vector, or name-value pairs} +\item{...}{A character vector, or name-value pairs.} -\item{x}{An object} +\item{x}{An object.} } \description{ -\code{ident()} takes unquoted strings and flags them as identifiers. -\code{ident_q()} assumes its input has already been quoted, and ensures -it does not get quoted again. This is currently used only for -\code{schema.table}. +\code{ident()} takes strings and turns them as database identifiers (e.g. table +or column names) quoting them using the identifer rules for your database. +\code{ident_q()} does the same, but assumes the names have already been +quoted, preventing them from being quoted again. + +These are generally for internal use only; if you need to supply an +table name that is qualified with schema or catalog, or has already been +quoted for some other reason, use \code{I()}. } \examples{ # SQL92 quotes strings with ' @@ -32,3 +36,4 @@ escape_ansi(ident("x")) ident(a = "x", b = "y") ident_q(a = "x", b = "y") } +\keyword{internal} diff --git a/man/in_schema.Rd b/man/in_schema.Rd index a51df1fb4..968a39415 100644 --- a/man/in_schema.Rd +++ b/man/in_schema.Rd @@ -3,7 +3,7 @@ \name{in_schema} \alias{in_schema} \alias{in_catalog} -\title{Refer to a table in a schema or a database catalog} +\title{Refer to a table in another schema/catalog} \usage{ in_schema(schema, table) @@ -15,16 +15,21 @@ These will be automatically quoted; use \code{\link[=sql]{sql()}} to pass a raw that won't get quoted.} } \description{ -\code{in_schema()} can be used in \code{\link[=tbl]{tbl()}} to indicate a table in a specific -schema. -\code{in_catalog()} additionally allows specifying the database catalog. +\code{in_schema()} and \code{in_catalog()} can be used to refer to tables outside of +the current catalog/schema. However, we now recommend using \code{I()} as it's +typically less typing. } \examples{ +# Previously: in_schema("my_schema", "my_table") in_catalog("my_catalog", "my_schema", "my_table") -# eliminate quotes in_schema(sql("my_schema"), sql("my_table")) +# Now +I("my_schema.my_table") +I("my_catalog.my_schema.my_table") +I("my_schema.my_table") + # Example using schemas with SQLite con <- DBI::dbConnect(RSQLite::SQLite(), ":memory:") @@ -34,8 +39,9 @@ DBI::dbExecute(con, paste0("ATTACH '", tmp, "' AS aux")) library(dplyr, warn.conflicts = FALSE) copy_to(con, iris, "df", temporary = FALSE) -copy_to(con, mtcars, in_schema("aux", "df"), temporary = FALSE) +copy_to(con, mtcars, I("aux.df"), temporary = FALSE) con \%>\% tbl("df") -con \%>\% tbl(in_schema("aux", "df")) +con \%>\% tbl(I("aux.df")) } +\keyword{internal} diff --git a/man/sql_query_insert.Rd b/man/sql_query_insert.Rd index 03abc5f5e..ac320e97b 100644 --- a/man/sql_query_insert.Rd +++ b/man/sql_query_insert.Rd @@ -48,8 +48,9 @@ sql_query_delete(con, table, from, by, ..., returning_cols = NULL) \arguments{ \item{con}{Database connection.} -\item{table}{Table to update. Must be a table identifier, e.g. single string -or created via \code{in_schema()}.} +\item{table}{Table to update. Must be a table identifier. +Use a string to refer to tables in the current schema/catalog or +\code{I()} to refer to tables in other schemas/catalogs.} \item{from}{Table or query that contains the new data. Either a table identifier or SQL.} diff --git a/man/tbl.src_dbi.Rd b/man/tbl.src_dbi.Rd index 9ea1bfd23..c2c4ad005 100644 --- a/man/tbl.src_dbi.Rd +++ b/man/tbl.src_dbi.Rd @@ -10,9 +10,12 @@ \arguments{ \item{src}{A \code{DBIConnection} object produced by \code{DBI::dbConnect()}.} -\item{from}{Either a string (giving a table name), -a fully qualified table name created by \code{\link[=in_schema]{in_schema()}} -or a literal \code{\link[=sql]{sql()}} string.} +\item{from}{Either a table identifier or a literal \code{\link[=sql]{sql()}} string. + +Use a string to identify a table in the current schema/catalog. We +recommend using \code{I()} to identify a table outside the default catalog or +schema, e.g. \code{I("schema.table")} or \code{I("catalog.schema.table")}. You can +also use \code{\link[=in_schema]{in_schema()}}/\code{\link[=in_catalog]{in_catalog()}} or \code{\link[DBI:Id]{DBI::Id()}}.} \item{...}{Passed on to \code{\link[=tbl_sql]{tbl_sql()}}} } @@ -44,8 +47,8 @@ DBI::dbListTables(con) # To retrieve a single table from a source, use `tbl()` con \%>\% tbl("mtcars") -# Use `in_schema()` for fully qualified table names -con \%>\% tbl(in_schema("temp", "mtcars")) \%>\% head(1) +# Use `I()` for qualified table names +con \%>\% tbl(I("temp.mtcars")) \%>\% head(1) # You can also use pass raw SQL if you want a more sophisticated query con \%>\% tbl(sql("SELECT * FROM mtcars WHERE cyl = 8"))