% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/ddbs_as_spatial.R
\name{ddbs_as_points}
\alias{ddbs_as_points}
\title{Generate point geometries from coordinates}
\usage{
ddbs_as_points(
  x,
  coords = c("lon", "lat"),
  crs = "EPSG:4326",
  remove = TRUE,
  na.fail = TRUE,
  conn = NULL,
  name = NULL,
  mode = NULL,
  overwrite = FALSE,
  quiet = FALSE,
  ...
)
}
\arguments{
\item{x}{Input spatial data. Can be:
\itemize{
\item A \code{duckspatial_df} object (lazy spatial data frame via dbplyr)
\item An \code{sf} object
\item A \code{tbl_lazy} from dbplyr
\item A character string naming a table/view in \code{conn}
}
Data is returned from this object.}

\item{coords}{Character vector of length 2 specifying the names of the
longitude and latitude columns (or X and Y coordinates). Defaults to
\code{c("lon", "lat")}.}

\item{crs}{Character or numeric. The Coordinate Reference System (CRS) of the
input coordinates. Can be specified as an EPSG code (e.g., \code{"EPSG:4326"}
or \code{4326}) or a WKT string. Defaults to \code{"EPSG:4326"} (WGS84
longitude/latitude).}

\item{remove}{Logical. If \code{TRUE} (default), the coordinate columns
specified in \code{coords} are removed from the output.}

\item{na.fail}{Logical. If \code{TRUE} (default), the function errors if
any missing values (NAs) are found in the coordinate columns.}

\item{conn}{A connection object to a DuckDB database. If \code{NULL}, the function
runs on a temporary DuckDB database.}

\item{name}{A character string of length one specifying the name of the table,
or a character string of length two specifying the schema and table
names. If \code{NULL} (the default), the function returns the result as an
\code{sf} object}

\item{mode}{Character. Controls the return type. Options:
\itemize{
\item \code{"duckspatial"} (default): Lazy spatial data frame backed by dbplyr/DuckDB
\item \code{"sf"}: Eagerly collected sf object (uses memory)
}
Can be set globally via \code{\link{ddbs_options}(mode = "...")} or
per-function via this argument. Per-function overrides global setting.}

\item{overwrite}{Boolean. whether to overwrite the existing table if it exists. Defaults
to \code{FALSE}. This argument is ignored when \code{name} is \code{NULL}.}

\item{quiet}{A logical value. If \code{TRUE}, suppresses any informational messages.
Defaults to \code{FALSE}.}

\item{...}{Additional arguments. Currently supports \code{geom_col} to
specify the name of the geometry column in the output.}
}
\value{
Depends on the \code{mode} argument (or global preference set by \code{\link{ddbs_options}}):
\itemize{
\item \code{duckspatial} (default): A \code{duckspatial_df} (lazy spatial data frame) backed by dbplyr/DuckDB.
\item \code{sf}: An eagerly collected object in R memory, that will return the same data type as the
\code{sf} equivalent (e.g. \code{sf} or \code{units} vector).
}
When \code{name} is provided, the result is also written as a table or view in DuckDB and the function returns \code{TRUE} (invisibly).
}
\description{
Converts a data frame with coordinate columns into spatial point geometries.
}
\examples{
\dontrun{
## load packages
library(duckspatial)

## create sample data with coordinates
cities_df <- data.frame(
  city = c("Buenos Aires", "Córdoba", "Rosario"),
  lon = c(-58.3816, -64.1811, -60.6393),
  lat = c(-34.6037, -31.4201, -32.9468),
  population = c(3075000, 1391000, 1193605)
)

# option 1: convert data frame to sf object
cities_ddbs <- ddbs_as_points(cities_df)

# specify custom coordinate column names and keep them in output
cities_df2 <- data.frame(
  city = c("Mendoza", "Tucumán"),
  longitude = c(-68.8272, -65.2226),
  latitude = c(-32.8895, -26.8241)
)

ddbs_as_points(cities_df2, coords = c("longitude", "latitude"), remove = FALSE)


## option 2: convert table in duckdb to spatial table

# create a duckdb connection and write data
conn <- duckspatial::ddbs_create_conn()
DBI::dbWriteTable(conn, "cities_tbl", cities_df, overwrite = TRUE)

# convert to spatial table in database
ddbs_as_points(
    x = "cities_tbl",
    conn = conn,
    name = "cities_spatial",
    overwrite = TRUE
)

# read the spatial table
ddbs_read_table(conn, "cities_spatial")
}
}
