Reads a database table to a data frame, optionally converting a column to row names and converting the column names to valid R identifiers.

Methods in other packages

  • DatabaseConnector::dbReadTable("DatabaseConnectorConnection", "character")

# S4 method for DatabaseConnectorConnection,character
dbReadTable(
  conn,
  name,
  database = NULL,
  schema = NULL,
  oracleTempSchema = NULL,
  tempEmulationSchema = getOption("sqlRenderTempEmulationSchema"),
  ...
)

Arguments

conn

A DBIConnection object, as returned by dbConnect().

name

A character string specifying the unquoted DBMS table name, or the result of a call to dbQuoteIdentifier().

database

Name of the database.

schema

Name of the schema.

oracleTempSchema

DEPRECATED: use tempEmulationSchema instead.

tempEmulationSchema

Some database platforms like Oracle and Impala do not truly support temp tables. To emulate temp tables, provide a schema with write privileges where temp tables can be created.

...

Other parameters passed on to methods.

Value

dbReadTable() returns a data frame that contains the complete data from the remote table, effectively the result of calling dbGetQuery()

with SELECT * FROM <name>. An error is raised if the table does not exist. An empty table is returned as a data frame with zero rows.

The presence of rownames depends on the row.names argument, see sqlColumnToRownames() for details:

  • If FALSE or NULL, the returned data frame doesn't have row names.

  • If TRUE, a column named "row_names" is converted to row names, an error is raised if no such column exists.

  • If NA, a column named "row_names" is converted to row names if it exists, otherwise no translation occurs.

  • If a string, this specifies the name of the column in the remote table that contains the row names, an error is raised if no such column exists.

The default is row.names = FALSE.

If the database supports identifiers with special characters, the columns in the returned data frame are converted to valid R identifiers if the check.names argument is TRUE, If check.names = FALSE, the returned table has non-syntactic column names without quotes.

An error is raised when calling this method for a closed or invalid connection. An error is raised if name cannot be processed with dbQuoteIdentifier()

or if this results in a non-scalar. Unsupported values for row.names and check.names

(non-scalars, unsupported data types, NA for check.names) also raise an error.