EVOLUTION-MANAGER
Edit File: st_read.html
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><title>R: Read simple features or layers from file or database</title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <link rel="stylesheet" type="text/css" href="R.css" /> </head><body> <table width="100%" summary="page for st_read {sf}"><tr><td>st_read {sf}</td><td style="text-align: right;">R Documentation</td></tr></table> <h2>Read simple features or layers from file or database</h2> <h3>Description</h3> <p>Read simple features from file or database, or retrieve layer names and their geometry type(s) </p> <p>Read PostGIS table directly through DBI and RPostgreSQL interface, converting Well-Know Binary geometries to sfc </p> <h3>Usage</h3> <pre> st_read(dsn, layer, ...) ## S3 method for class 'character' st_read( dsn, layer, ..., query = NA, options = NULL, quiet = FALSE, geometry_column = 1L, type = 0, promote_to_multi = TRUE, stringsAsFactors = sf_stringsAsFactors(), int64_as_string = FALSE, check_ring_dir = FALSE, fid_column_name = character(0), drivers = character(0), wkt_filter = character(0) ) read_sf(..., quiet = TRUE, stringsAsFactors = FALSE, as_tibble = TRUE) ## S3 method for class 'DBIObject' st_read( dsn = NULL, layer = NULL, query = NULL, EWKB = TRUE, quiet = TRUE, as_tibble = FALSE, geometry_column = NULL, ... ) </pre> <h3>Arguments</h3> <table summary="R argblock"> <tr valign="top"><td><code>dsn</code></td> <td> <p>data source name (interpretation varies by driver - for some drivers, <code>dsn</code> is a file name, but may also be a folder, or contain the name and access credentials of a database); in case of GeoJSON, <code>dsn</code> may be the character string holding the geojson data. It can also be an open database connection.</p> </td></tr> <tr valign="top"><td><code>layer</code></td> <td> <p>layer name (varies by driver, may be a file name without extension); in case <code>layer</code> is missing, <code>st_read</code> will read the first layer of <code>dsn</code>, give a warning and (unless <code>quiet = TRUE</code>) print a message when there are multiple layers, or give an error if there are no layers in <code>dsn</code>. If <code>dsn</code> is a database connection, then <code>layer</code> can be a table name or a database identifier (see <code><a href="../../DBI/html/Id.html">Id</a></code>). It is also possible to omit <code>layer</code> and rather use the <code>query</code> argument.</p> </td></tr> <tr valign="top"><td><code>...</code></td> <td> <p>parameter(s) passed on to <a href="st_as_sf.html">st_as_sf</a></p> </td></tr> <tr valign="top"><td><code>query</code></td> <td> <p>SQL query to select records; see details</p> </td></tr> <tr valign="top"><td><code>options</code></td> <td> <p>character; driver dependent dataset open options, multiple options supported. For possible values, see the "Open options" section of the GDAL documentation of the corresponding driver, and https://github.com/r-spatial/sf/issues/1157 for an example.</p> </td></tr> <tr valign="top"><td><code>quiet</code></td> <td> <p>logical; suppress info on name, driver, size and spatial reference, or signaling no or multiple layers</p> </td></tr> <tr valign="top"><td><code>geometry_column</code></td> <td> <p>integer or character; in case of multiple geometry fields, which one to take?</p> </td></tr> <tr valign="top"><td><code>type</code></td> <td> <p>integer; ISO number of desired simple feature type; see details. If left zero, and <code>promote_to_multi</code> is <code>TRUE</code>, in case of mixed feature geometry types, conversion to the highest numeric type value found will be attempted. A vector with different values for each geometry column can be given.</p> </td></tr> <tr valign="top"><td><code>promote_to_multi</code></td> <td> <p>logical; in case of a mix of Point and MultiPoint, or of LineString and MultiLineString, or of Polygon and MultiPolygon, convert all to the Multi variety; defaults to <code>TRUE</code></p> </td></tr> <tr valign="top"><td><code>stringsAsFactors</code></td> <td> <p>logical; logical: should character vectors be converted to factors? Default for <code>read_sf</code> or R version >= 4.1.0 is <code>FALSE</code>, for <code>st_read</code> and R version < 4.1.0 equal to <code>default.stringsAsFactors()</code></p> </td></tr> <tr valign="top"><td><code>int64_as_string</code></td> <td> <p>logical; if TRUE, Int64 attributes are returned as string; if FALSE, they are returned as double and a warning is given when precision is lost (i.e., values are larger than 2^53).</p> </td></tr> <tr valign="top"><td><code>check_ring_dir</code></td> <td> <p>logical; if TRUE, polygon ring directions are checked and if necessary corrected (when seen from above: exterior ring counter clockwise, holes clockwise)</p> </td></tr> <tr valign="top"><td><code>fid_column_name</code></td> <td> <p>character; name of column to write feature IDs to; defaults to not doing this</p> </td></tr> <tr valign="top"><td><code>drivers</code></td> <td> <p>character; limited set of driver short names to be tried (default: try all)</p> </td></tr> <tr valign="top"><td><code>wkt_filter</code></td> <td> <p>character; WKT representation of a spatial filter (may be used as bounding box, selecting overlapping geometries); see examples</p> </td></tr> <tr valign="top"><td><code>as_tibble</code></td> <td> <p>logical; should the returned table be of class tibble or data.frame?</p> </td></tr> <tr valign="top"><td><code>EWKB</code></td> <td> <p>logical; is the WKB of type EWKB? if missing, defaults to <code>TRUE</code></p> </td></tr> </table> <h3>Details</h3> <p>for <code>geometry_column</code>, see also <a href="https://trac.osgeo.org/gdal/wiki/rfc41_multiple_geometry_fields">https://trac.osgeo.org/gdal/wiki/rfc41_multiple_geometry_fields</a> </p> <p>for values for <code>type</code> see <a href="https://en.wikipedia.org/wiki/Well-known_text#Well-known_binary">https://en.wikipedia.org/wiki/Well-known_text#Well-known_binary</a>, but note that not every target value may lead to successful conversion. The typical conversion from POLYGON (3) to MULTIPOLYGON (6) should work; the other way around (type=3), secondary rings from MULTIPOLYGONS may be dropped without warnings. <code>promote_to_multi</code> is handled on a per-geometry column basis; <code>type</code> may be specified for each geometry column. </p> <p>Note that stray files in data source directories (such as <code>*.dbf</code>) may lead to spurious errors that accompanying <code>*.shp</code> are missing. </p> <p>In case of problems reading shapefiles from USB drives on OSX, please see <a href="https://github.com/r-spatial/sf/issues/252">https://github.com/r-spatial/sf/issues/252</a>. </p> <p>For <code>query</code> with a character <code>dsn</code> the query text is handed to 'ExecuteSQL' on the GDAL/OGR data set and will result in the creation of a new layer (and <code>layer</code> is ignored). See 'OGRSQL' <a href="https://gdal.org/user/ogr_sql_dialect.html">https://gdal.org/user/ogr_sql_dialect.html</a> for details. Please note that the 'FID' special field is driver-dependent, and may be either 0-based (e.g. ESRI Shapefile), 1-based (e.g. MapInfo) or arbitrary (e.g. OSM). Other features of OGRSQL are also likely to be driver dependent. The available layer names may be obtained with <a href="st_layers.html">st_layers</a>. Care will be required to properly escape the use of some layer names. </p> <p><code>read_sf</code> and <code>write_sf</code> are aliases for <code>st_read</code> and <code>st_write</code>, respectively, with some modified default arguments. <code>read_sf</code> and <code>write_sf</code> are quiet by default: they do not print information about the data source. <code>read_sf</code> returns an sf-tibble rather than an sf-data.frame. <code>write_sf</code> delete layers by default: it overwrites existing files without asking or warning. </p> <p>if <code>table</code> is not given but <code>query</code> is, the spatial reference system (crs) of the table queried is only available in case it has been stored into each geometry record (e.g., by PostGIS, when using EWKB) </p> <p>The function will automatically find the 'geometry' type columns for drivers that support it. For the other drivers, it will try to cast all the character columns, which can be slow for very wide tables. </p> <h3>Value</h3> <p>object of class <a href="sf.html">sf</a> when a layer was successfully read; in case argument <code>layer</code> is missing and data source <code>dsn</code> does not contain a single layer, an object of class <code>sf_layers</code> is returned with the layer names, each with their geometry type(s). Note that the number of layers may also be zero. </p> <h3>Note</h3> <p>The use of <code>system.file</code> in examples make sure that examples run regardless where R is installed: typical users will not use <code>system.file</code> but give the file name directly, either with full path or relative to the current working directory (see <a href="../../base/html/getwd.html">getwd</a>). "Shapefiles" consist of several files with the same basename that reside in the same directory, only one of them having extension <code>.shp</code>. </p> <h3>See Also</h3> <p><a href="st_layers.html">st_layers</a>, <a href="st_drivers.html">st_drivers</a> </p> <h3>Examples</h3> <pre> nc = st_read(system.file("shape/nc.shp", package="sf")) summary(nc) # note that AREA was computed using Euclidian area on lon/lat degrees ## only three fields by select clause ## only two features by where clause nc_sql = st_read(system.file("shape/nc.shp", package="sf"), query = "SELECT NAME, SID74, FIPS FROM \"nc\" WHERE BIR74 > 20000") ## Not run: library(sp) example(meuse, ask = FALSE, echo = FALSE) try(st_write(st_as_sf(meuse), "PG:dbname=postgis", "meuse", layer_options = "OVERWRITE=true")) try(st_meuse <- st_read("PG:dbname=postgis", "meuse")) if (exists("st_meuse")) summary(st_meuse) ## End(Not run) ## Not run: ## note that we need special escaping of layer within single quotes (nc.gpkg) ## and that geom needs to be included in the select, otherwise we don't detect it layer <- st_layers(system.file("gpkg/nc.gpkg", package = "sf"))$name[1] nc_gpkg_sql = st_read(system.file("gpkg/nc.gpkg", package = "sf"), query = sprintf("SELECT NAME, SID74, FIPS, geom FROM \"%s\" WHERE BIR74 > 20000", layer)) ## End(Not run) # spatial filter, as wkt: wkt = st_as_text(st_geometry(nc[1,])) # filter by (bbox overlaps of) first feature geometry: read_sf(system.file("gpkg/nc.gpkg", package="sf"), wkt_filter = wkt) # read geojson from string: geojson_txt <- paste("{\"type\":\"MultiPoint\",\"coordinates\":", "[[3.2,4],[3,4.6],[3.8,4.4],[3.5,3.8],[3.4,3.6],[3.9,4.5]]}") x = read_sf(geojson_txt) x ## Not run: library(RPostgreSQL) try(conn <- dbConnect(PostgreSQL(), dbname = "postgis")) if (exists("conn") && !inherits(conn, "try-error")) { x = st_read(conn, "meuse", query = "select * from meuse limit 3;") x = st_read(conn, table = "public.meuse") print(st_crs(x)) # SRID resolved by the database, not by GDAL! dbDisconnect(conn) } ## End(Not run) </pre> <hr /><div style="text-align: center;">[Package <em>sf</em> version 0.9-5 <a href="00Index.html">Index</a>]</div> </body></html>