R: Copy data frames from database tables

dbReadTable {DBI} | R Documentation

## Copy data frames from database tables

### Description

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

- `DBI::dbReadTable("DBIConnection", "Id")`

- `DBI::dbReadTable("DBIConnection", "character")`

### Usage

    dbReadTable(conn, name, ...)

### 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()`.
`...` | 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`, otherwise non-syntactic column names can be returned unquoted.

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.

### Additional arguments

The following arguments are not part of the `dbReadTable()` generic (to improve compatibility across backends) but are part of the DBI specification:

- `row.names`

- `check.names`

They must be provided as named arguments. See the "Value" section for details on their usage.

### Specification

The `name` argument is processed as follows, to support databases that allow non-syntactic names for their objects:

- If an unquoted table name as string: `dbReadTable()` will do the quoting, perhaps by calling `dbQuoteIdentifier(conn, x = name)`

- If the result of a call to `dbQuoteIdentifier()`: no more quoting is done

### See Also

Other DBIConnection generics: `DBIConnection-class`, `dbDataType`, `dbDisconnect`, `dbExecute`, `dbExistsTable`, `dbGetException`, `dbGetInfo`, `dbGetQuery`, `dbIsValid`, `dbListFields`, `dbListObjects`, `dbListResults`, `dbListTables`, `dbRemoveTable`, `dbSendQuery`, `dbSendStatement`, `dbWriteTable`

### Examples

    con <- dbConnect(RSQLite::SQLite(), ":memory:")

    dbWriteTable(con, "mtcars", mtcars[1:10, ])
    dbReadTable(con, "mtcars")

    dbDisconnect(con)

[Package DBI version 0.8 Index]