R: Write simple features object to file or database

st_write {sf} | R Documentation

## Write simple features object to file or database

### Description

Write simple features object to file or database

### Usage

    st_write(obj, dsn, layer, ...)

    ## S3 method for class 'sfc'
    st_write(obj, dsn, layer, ...)

    ## S3 method for class 'sf'
    st_write(
      obj,
      dsn,
      layer = NULL,
      ...,
      driver = guess_driver_can_write(dsn),
      dataset_options = NULL,
      layer_options = NULL,
      quiet = FALSE,
      factorsAsCharacter = TRUE,
      append = NA,
      delete_dsn = FALSE,
      delete_layer = !is.na(append) && !append,
      fid_column_name = NULL
    )

    ## S3 method for class 'data.frame'
    st_write(obj, dsn, layer = NULL, ...)

    write_sf(..., quiet = TRUE, append = FALSE, delete_layer = TRUE)

    ## S4 method for signature 'PostgreSQLConnection,character,sf'
    dbWriteTable(
      conn,
      name,
      value,
      ...,
      row.names = FALSE,
      overwrite = FALSE,
      append = FALSE,
      field.types = NULL,
      factorsAsCharacter = TRUE,
      binary = TRUE
    )

    ## S4 method for signature 'DBIObject,character,sf'
    dbWriteTable(
      conn,
      name,
      value,
      ...,
      row.names = FALSE,
      overwrite = FALSE,
      append = FALSE,
      field.types = NULL,
      factorsAsCharacter = TRUE,
      binary = TRUE
    )

### Arguments

`obj` | object of class `sf` or `sfc`
`dsn` | data source name (interpretation varies by driver - for some drivers, dsn is a file name, but may also be a folder or contain a database name) or a Database Connection (currently official support is for RPostgreSQL connections)
`layer` | layer name (varies by driver, may be a file name without extension); if layer is missing, the basename of `dsn` is taken.
`...` | other arguments passed to dbWriteTable when `dsn` is a Database Connection
`driver` | character; name of driver to be used; if missing and `dsn` is not a Database Connection, a driver name is guessed from `dsn`; `st_drivers()` returns the drivers that are available with their properties; links to full driver documentation are found at https://gdal.org/ogr_formats.html.
`dataset_options` | character; driver dependent dataset creation options; multiple options supported.
`layer_options` | character; driver dependent layer creation options; multiple options supported.
`quiet` | logical; suppress info on name, driver, size and spatial reference
`factorsAsCharacter` | logical; convert `factor` objects into character strings (default), else into numbers by `as.numeric`.
`append` | Append rows to existing table; default `FALSE`.
`delete_dsn` | logical; delete data source `dsn` before attempting to write?
`delete_layer` | logical; delete layer `layer` before attempting to write?
`fid_column_name` | character, name of column with feature IDs; if specified, this column is no longer written as feature attribute.
`conn` | DBIObject
`name` | character vector of names (table names, fields, keywords).
`value` | a data.frame.
`row.names` | Add a `row.name` column, or a vector of length `nrow(obj)` containing row.names; default `FALSE`.
`overwrite` | Will try to `drop` table before writing; default `FALSE`.
`field.types` | default `NULL`. Allows to override type conversion from R to PostgreSQL. See `dbDataType()` for details.
`binary` | Send geometries serialized as Well-Known Binary (WKB); if `FALSE`, uses Well-Known Text (WKT). Defaults to `TRUE` (WKB).

### Details

Columns (variables) of a class not supported are dropped with a warning.

When updating an existing layer, records are appended to it if the updating object has the right variable names and types. If names don't match an error is raised. If types don't match, behaviour is undefined: GDAL may raise warnings or errors or fail silently.

When deleting layers or data sources is not successful, no error is emitted. `delete_dsn` and `delete_layer` should be handled with care; the former may erase complete directories or databases.

### Value

`obj`, invisibly; in case `obj` is of class `sfc`, it is returned as an `sf` object.

### See Also

st_drivers

### Examples

    nc = st_read(system.file("shape/nc.shp", package="sf"))
    st_write(nc, paste0(tempdir(), "/", "nc.shp"))
    st_write(nc, paste0(tempdir(), "/", "nc.shp"), delete_layer = TRUE) # overwrites
    data(meuse, package = "sp") # loads data.frame from sp
    meuse_sf = st_as_sf(meuse, coords = c("x", "y"), crs = 28992)
    # writes X and Y as columns:
    st_write(meuse_sf, paste0(tempdir(), "/", "meuse.csv"), layer_options = "GEOMETRY=AS_XY")
    st_write(meuse_sf, paste0(tempdir(), "/", "meuse.csv"), layer_options = "GEOMETRY=AS_WKT",
      delete_dsn=TRUE) # overwrites
    ## Not run:
     library(sp)
     example(meuse, ask = FALSE, echo = FALSE)
     try(st_write(st_as_sf(meuse), "PG:dbname=postgis", "meuse_sf",
         layer_options = c("OVERWRITE=yes", "LAUNDER=true")))
     demo(nc, ask = FALSE)
     try(st_write(nc, "PG:dbname=postgis", "sids", layer_options = "OVERWRITE=true"))

    ## End(Not run)

[Package sf version 0.9-7 Index]