Importing Geospatial Data

Importing Geospatial Data Using MapD Immerse

You can use MapD Immerse to import geospatial data into the MapD Core Database. Supported formats include:

  • Keyhole Markup Language (.kml)
  • GeoJSON (.geojson)
  • Shapefiles (.shp)
Shapefiles include four mandatory files: .shp, .shx, .dbf, and .prj. If you do not import the .prj file, the coordinate system will be incorrect and you cannot render the shapes on a map.

To import geospatial definition data:

  1. Open MapD Immerse.

  2. Click Data Manager.

  3. Click Import Data.

  4. Click the large + icon to select files for upload, or drag and drop the files to the Data Importer screen.

    When importing shapefiles, upload all required file types at the same time. If you upload them separately, Immerse issues an error message.

  5. Wait for the uploads to complete (indicated by green checkmarks on the file icons), then click Import Files.

  6. On the Table Preview screen, edit column headers (if needed), enter a name for the table in the field at the bottom of the screen, and click Save Table.

  7. On the Table Metadata screen, verify the rows and columns that compose your data table.

Well-known Text import

You can import spatial representations in Well-known Text (WKT) format. WKT is a text markup language for representing vector geometry objects on a map, spatial reference systems of spatial objects and transformations between spatial reference systems.

Creating WKT tables using mapdql

You can use mapdql to define tables with columns that store WKT geospatial objects.

mapdql> \d geo
CREATE TABLE geo (
p POINT,
l LINESTRING,
poly POLYGON)

Insert

You can use mapdql to insert data as WKT string values.

mapdql> INSERT INTO geo values('POINT(20 20)', 'LINESTRING(40 0, 40 40)', 'POLYGON(( 0 0, 40 0, 40 40, 0 40, 0 0 ))');

Importing Delimited Files

You can insert data from CSV/TSV files containing WKT strings.

> cat geo.csv
"p", "l", "poly"
"POINT(1 1)", "LINESTRING( 2 0,  2  2)", "POLYGON(( 1 0,  0 1, 1 1 ))"
"POINT(2 2)", "LINESTRING( 4 0,  4  4)", "POLYGON(( 2 0,  0 2, 2 2 ))"
"POINT(3 3)", "LINESTRING( 6 0,  6  6)", "POLYGON(( 3 0,  0 3, 3 3 ))"
"POINT(4 4)", "LINESTRING( 8 0,  8  8)", "POLYGON(( 4 0,  0 4, 4 4 ))"
mapdql> COPY geo FROM 'geo.csv';
Result
Loaded: 4 recs, Rejected: 0 recs in 0.356000 secs

You can use your own custom delimiter in your data files.

> cat geo1.csv
"p", "l", "poly"
POINT(5 5); LINESTRING(10 0, 10 10); POLYGON(( 5 0, 0 5, 5 5 ))
mapdql> COPY geo FROM 'geo1.csv' WITH (delimiter=';', quoted=’false’);
Result
Loaded: 1 recs, Rejected: 0 recs in 0.148000 secs

Importing Legacy CSV/TSV

You can import CSV/TSV files intended for tables that store longitude and latitude as separate consecutive scalar columns. Create a new table with longitude and latitude columns each stored in a separate POINT column. You can then import the data into a new table without modifications. When the importer finds scalar values in the CSV/TSV row for a POINT column, it consumes two consecutive columns. 
mapdql> \d legacy_geo
CREATE TABLE legacy_geo (
lon double,
lat double)

> cat legacy_geo.csv
"lon", "lat"
-71.160281, 42.258729
-71.160837, 42.259113
mapdql> COPY legacy_geo FROM 'legacy_geo.csv';
Result
Loaded: 2 recs, Rejected: 0 recs in 0.152000 secs
mapdql> \d new_geo
CREATE TABLE legacy_geo (
p POINT)
mapdql> COPY new_geo FROM 'legacy_geo.csv';
Result
Loaded: 2 recs, Rejected: 0 recs in 0.152000 secs

The default behavior is to consume the two columns as longitude (x) and then latitude (y). If the order of the coordinates in the CSV file is the opposite, you can load the data using the WITH option lonlat='false':

mapdql> COPY new_geo FROM 'legacy_geo.csv' with (lonlat='false');

Importing Geo Files

You can create geo tables by importing specific geo file formats. MapD supports the following types:

  • ESRI Shapefile (.shp and associated files)
  • GeoJSON (.geojson or .json)
  • KML (.kml or .kmz)

The geo file import process automatically creates the table by detecting the column names and types explicitly described in the geo file header. It then creates a single geo column (always called mapd_geo) which is of one of the supported types (POINT, LINESTRING, POLYGON or MULTIPOLYGON).

Note Due to the prevalence of mixed POLYGON/MULTIPOLYGON geo files (and CSVs) if MapD detects a POLYGON type geo file, MapD creates a MULTIPOLYGON column and imports the data as single polygons.

You import geo files using the COPY FROM commmand using the ‘geo’ option.

mapdql> COPY states FROM 'states.shp' with (geo=’true’);
mapdql> COPY zipcodes FROM 'zipcodes.geojson' with (geo=’true’);
mapdql> COPY cell_towers FROM 'cell_towers.kml' with (geo=’true’);

The table must not already exist, and cannot be appended once you create it. Once created from a geo file, however, you can append more rows from a CSV with the same column structure.

By default, geo data is stored as GEOMETRY, converted to Earth coordinates in lon/lat (WGS84 SRID 4326), compressing the data size by 50% (giving a worst-case real-world resolution of ~4 inches at the equator).

To store in other formats, use the following WITH options in addition to geo=’true’: 

geo_coords_encoding=’NONE|COMPRESSED(32)’ // default is COMPRESSED(32)’
geo_coords_srid=4326|3857|900913 // default is 4326
Note Rendering of geo LINESTRING, POLYGON and MULTIPOLYGON might only be possible with data stored in the default lon/lat (WGS84 SRID 4326) format (although the type and encoding are flexible).

Importing Geo Files from Archives or Non-Local Storage

You can import geo files directly from archive files (for example, .zip .tar .tgz .tar.gz) without unpacking the archive. You can directly import individual geo files compressed with Zip or GZip (GeoJSON and KML only). The server opens the archive header and loads the first candidate file it finds (.shp .geojson .json .kml), along with any associated files (in the case of an ESRI Shapefile, the associated files must be siblings of the first). 

$ unzip -l states.zip
Archive:  states.zip
  Length      Date    Time    Name
---------  ---------- -----   ----
        0  2018-02-13 11:09   states/
   446116  2017-11-06 12:15   states/cb_2014_us_state_20m.shp
     8434  2017-11-06 12:15   states/cb_2014_us_state_20m.dbf
        9  2017-11-06 12:15   states/cb_2014_us_state_20m.cpg
      165  2017-11-06 12:15   states/cb_2014_us_state_20m.prj
      516  2017-11-06 12:15   states/cb_2014_us_state_20m.shx
---------                     -------
   491525                     6 files

mapdql> COPY states FROM 'states.zip' with (geo=’true’);
mapdql> COPY zipcodes FROM 'zipcodes.geojson.gz' with (geo=’true’);
mapdql> COPY zipcodes FROM 'zipcodes.geojson.zip' with (geo=’true’);
mapdql> COPY cell_towers FROM 'cell_towers.kml.gz' with (geo=’true’);

You can import geo files or archives directly from an Amazon S3 bucket.

mapdql> COPY states FROM 's3://mybucket/myfolder/states.shp' with (geo=’true’);
mapdql> COPY states FROM 's3://mybucket/myfolder/states.zip' with (geo=’true’);
mapdql> COPY zipcodes FROM 's3://mybucket/myfolder/zipcodes.geojson.gz' with (geo=’true’);
mapdql> COPY zipcodes FROM 's3://mybucket/myfolder/zipcodes.geojson.zip' with (geo=’true’);

You can provide Amazon S3 credentials, if required, by setting variables in the environment of the mapdql process…

AWS_REGION=us-west-1
AWS_ACCESS_KEY_ID=********************
AWS_SECRET_ACCESS_KEY=****************************************

You can also provide your credentials explicitly in the COPY FROM command.

mapdql> COPY states FROM 's3://mybucket/myfolder/states.zip' WITH (geo=’true’, s3_region=’us-west-1’, s3_access_key=’********************’, s3_secret_key=’****************************************’);

You can import geo files or archives directly from an HTTP/HTTPS website.

mapdql> COPY states FROM 'http://www.mysite.com/myfolder/states.zip' with (geo=’true’);

WGS84 Coordinate Compression

You can extend a column type specification to include spatial reference (SRID) and compression mode information.

Geospatial objects declared with SRID 4326 are compressed 50% by default with ENCODING COMPRESSED(32). In the following definition of table geo2, the columns poly2 and mpoly2 are compressed.

CREATE TABLE geo2 (
p2 GEOMETRY(POINT, 4326) ENCODING NONE,
l2 GEOMETRY(LINESTRING, 900913),
poly2 GEOMETRY(POLYGON, 4326),
mpoly2 GEOMETRY(MULTIPOLYGON, 4326) ENCODING COMPRESSED(32));

COMPRESSED(32) compression provides a smaller memory footprint and faster query execution at the cost of lower resolution (about 4 inches at the equator).

You can disable compression by explicitly choosing ENCODING NONE.