Steer people towards I()

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

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 '

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(

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

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 <https://www.sqlite.org/datatype3.html> for available types.
 #' @param temporary if `TRUE`, will create a temporary table that is

_pkgdown.yml

@@ -71,15 +71,13 @@ reference:
 
 - title: Database connection
   contents:
-  - in_schema
   - memdb_frame
   - remote_name
 
 - title: SQL generation
   contents:
   - build_sql
   - escape
-  - ident
   - partial_eval
   - sql
   - sql_expr