Vous êtes sur la page 1sur 181

Place

HP Vertica Analytic Database


Software Version: 7.1.x

Document Release Date: 7/21/2016

Legal Notices
Warranty
The only warranties for HP products and services are set forth in the express warranty statements accompanying such products and services. Nothing herein should be
construed as constituting an additional warranty. HP shall not be liable for technical or editorial errors or omissions contained herein.
The information contained herein is subject to change without notice.

Restricted Rights Legend


Confidential computer software. Valid license from HP required for possession, use or copying. Consistent with FAR 12.211 and 12.212, Commercial Computer
Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor's standard commercial
license.

Copyright Notice
Copyright 2006 - 2015 Hewlett-Packard Development Company, L.P.

Trademark Notices
Adobe is a trademark of Adobe Systems Incorporated.
Microsoft and Windows are U.S. registered trademarks of Microsoft Corporation.
UNIX is a registered trademark of The Open Group.

HP Vertica Analytic Database

Page 2 of 181

Contents
Contents

HP Vertica Place: An Overview

Mapping Geospatial Package Functions to HP Vertica Place Functions


Migrating from BB_WITHIN to Determine a Bounding Box

9
11

HP Vertica Place Installation Overview

12

Downloading the HP Vertica Place Package

12

Installing or Upgrading HP Vertica Place

12

Uninstalling HP Vertica Place

14

OGC Spatial Definitions


Spatial Classes

16
17

Point

17

Multipoint

18

Linestring

18

Multilinestring

20

Polygon

21

Multipolygon

22

Spatial Object Representations

23

WellKnown Text (WKT)

23

Well-Known Binary (WKB)

25

Spatial Definitions

25

Boundary

25

Buffer

26

Contains

26

Convex Hull

26

Crosses

27

HP Vertica Analytic Database

Page 3 of 181

Place
Contents

Disjoint

27

Envelope

27

Equals

28

Exterior

28

GeometryCollection

28

Interior

28

Intersection

28

Overlaps

29

Relates

29

Simple

30

Symmetric Difference

30

Union

31

Validity

31

Within

32

HP Vertica Place Spatial Objects

34

Supported Spatial Objects

34

Spatial Reference Identifiers (SRIDs)

34

Supported SRIDs

HP Vertica Place Functions: An Overview

35

36

Function-Naming Conventions

36

Verifying Spatial Objects Validity

36

Spatial Functions Categories

36

HP Vertica Place Functions

40

ST_Area

40

ST_AsBinary

42

ST_AsText

44

ST_Boundary

46

HP Vertica Analytic Database (7.1.x)

Page 4 of 181

Place
Contents

ST_Buffer

48

ST_Centroid

50

ST_Contains

51

ST_ConvexHull

55

ST_Crosses

57

ST_Difference

59

ST_Disjoint

61

ST_Distance

63

ST_Envelope

65

ST_Equals

66

ST_GeographyFromText

68

ST_GeographyFromWKB

70

ST_GeometryType

71

ST_GeomFromText

72

ST_GeomFromWKB

74

ST_Intersection

76

ST_Intersects

79

ST_IsEmpty

81

ST_IsSimple

82

ST_IsValid

85

ST_Length

89

ST_NumPoints

91

ST_Overlaps

93

ST_PointN

94

ST_Relate

96

ST_SRID

97

ST_SymDifference

99

HP Vertica Analytic Database (7.1.x)

Page 5 of 181

Place
Contents

ST_Touches

101

ST_Union

103

ST_Within

104

ST_X

106

ST_XMax

108

ST_XMin

109

ST_Y

111

ST_YMax

112

ST_YMin

114

STV_Create_Index

115

STV_Describe_Index

121

STV_Drop_Index

123

STV_DWithin

124

STV_Geography

126

STV_Geometry

127

STV_Intersect Scalar Function

129

STV_Intersect Transform Function

131

STV_IsValidReason

133

STV_LineStringPoint

135

STV_NN

136

STV_PolygonPoint

138

STV_Refresh_Index

140

STV_Rename_Index

144

STV_ShpCreateTable

146

STV_ShpSource and STV_ShpParser

148

Spatial Joins with ST_Intersects and STV_Intersect


STV_Intersect: Scalar Function vs. Transform Function

HP Vertica Analytic Database (7.1.x)

150
150

Page 6 of 181

Place
Contents

When to Use ST_Intersects vs. STV_Intersect

151

Performing Spatial Joins with ST_Intersects

152

Example
Performing Spatial Joins with STV_Intersect Functions
Spatial Indexes and STV_Intersect
Best Practices for Spatial Joins
Optimizations in Example Query
Loading Spatial Data from Shapefiles

152
153
153
153
155
156

Working with Spatial Objects in Tables

158

Defining Table Columns for Spatial Data

158

Loading Spatial Data into Tables Using COPY

158

Loading Spatial Data into Tables Using INSERT

159

Retrieving Spatial Data from a Table

160

Identifying Null Spatial Objects

160

Working with Spatial Objects from Client Applications

162

Using LONG VARCHAR and LONG VARBINARY Data Types with ODBC

162

Using LONG VARCHAR and LONG VARBINARY Data Types with JDBC

163

Using GEOMETRY and GEOGRAPHY Data Types in ODBC

165

Using GEOMETRY and GEOGRAPHY Data Types in JDBC

170

Using GEOMETRY and GEOGRAPHY Data Types in ADO.NET

172

BestPractices for HPVerticaPlace

175

Performance Optimization

175

Spatial Joins with Points and Polygons

175

Spatial Indexes

176

Checking Polygon Validity

178

HP Vertica Place Limitations

179

We appreciate your feedback!

181

HP Vertica Analytic Database (7.1.x)

Page 7 of 181

Place
HP Vertica Place: An Overview

HP Vertica Place: An Overview


HP Vertica Place provides functions that allows you to manipulate complex two-dimensional
spatial objects.These functions follow the Open Geospatial Consortium (OGC) standards.
HP Vertica Place also provides data types and SQL functions that allow you to specify and store
spatial objects in a database according to OGC standards. Using this functionality, you can:
l

Store objects in and retrieve them from an HP Vertica database


Determine if:
n

An object contains self-intersection or self-tangency points

One object is entirely within another object, such as a point within a polygon

Test the relationships between objects, for example, if they intersect or touch
Identify:
n

Boundary of an object

Vertices of an object

Calculate:
n

Shortest distance between two objects

Size of an object (length, area)

Centroid for one or more objects

Buffer around one or more objects

Convert to and from well-known text (WKT) and well-known binary (WKB) representations of
spatial objects

Perform spatial joins with points and polygons

Load spatial data from shapefiles into an HP Vertica database

HP Vertica Analytic Database (7.1.x)

Page 8 of 181

Place
HP Vertica Place: An Overview

Mapping Geospatial Package Functions to HP


Vertica Place Functions
If you have been using the deprecated Geospatial Package SQL Functions, you can migrate
functions to HP Vertica Place.
The following examples show how you can use HP Vertica Place functions to replicate functions
from the Geospatial Package.

Migrating from LAT_WITHIN to Determine Latitude


The following examples show how you determine that latitude 12 is between 220230 kilometers of
latitude 14.
Geospatial Package SQL Function
=> SELECT LAT_WITHIN(12,14,223);
LAT_WITHIN
-------------t
(1 row)

HP Vertica Place SQL Function


=> SELECT ST_Distance(ST_GeographyFromText('POINT(0 12)'), ST_GeographyFromText('POINT(0
14)'))/1000 <= 223;
?column?
---------t
(1 row)

Migrating from LON_WITHIN to Determine Longitude


The following examples show how you determine that the longitude 15 is between 16001700
kilometers from the point with latitude 16 and longitude 0.
Note: The order of coordinates in HP Vertica Place and the Geospatial Package differ. HP
Vertica Place requires that coordinates be listed as (longitude latitude).
Geospatial Package SQL Function
=> SELECT LON_WITHIN(15,16,0,1600);

HP Vertica Analytic Database (7.1.x)

Page 9 of 181

Place
HP Vertica Place: An Overview

LON_WITHIN
-----------f
(1 row)
=> SELECT LON_WITHIN(15,16,0,1700);
LON_WITHIN
-----------t
(1 row)

HP Vertica Place SQL Function


=> SELECT ST_Distance(ST_GeographyFromText('POINT(0 16)'), ST_GeographyFromText
('LINESTRING(15 -90, 15 90)'))/1000 <= 1600;
?column?
---------f
(1 row)
=> SELECT ST_Distance(ST_GeographyFromText('POINT(0 16)'), ST_GeographyFromText
('LINESTRING(15 -90, 15 90)'))/1000 <= 1700;
?column?
---------t
(1 row)

Migrating from LL_WITHIN to Determine if a Point is


Within a Bounding Box
The following examples show how you determine that the point (16,15) is within a bounding box.
This bounding box is centered at (12,13), and its sides are between 880890 kilometers long.
Geospatial Package SQL Function
=> SELECT LL_WITHIN(16,15,12,13,445);
LL_WITHIN
----------t
(1 row)

HP Vertica Place SQL Function


First, determine the distance on a meridian:
=> SELECT ST_Distance(ST_GeographyFromText('POINT(15 16)'), ST_GeographyFromText('POINT
(15 12)'))/1000 <= 440;
?column?
----------

HP Vertica Analytic Database (7.1.x)

Page 10 of 181

Place
HP Vertica Place: An Overview

f
(1 row)
=> SELECT ST_Distance(ST_GeographyFromText('POINT(15 16)'), ST_GeographyFromText('POINT
(15 12)'))/1000 <= 445;
?column?
---------t
(1 row)

Next, calculate the distance on the great circle arc from (longitude center, lat) to (longitude,
latitude):
=> SELECT ST_DISTANCE(ST_GeographyFromText('POINT(15 16)'), ST_GeographyFromText('POINT
(13 16)'))/1000 <= 440;
?column?
---------t
(1 row)
=> SELECT ST_DISTANCE(ST_GeographyFromText('POINT(15 16)'), ST_GeographyFromText('POINT
(13 16)'))/1000 <= 445;
?column?
---------t
(1 row)

Migrating from BB_WITHIN to Determine a Bounding


Box
The following examples show how you determine that the point (14,30) is not contained in the
bounding box. This bounding box is defined by (23.0,45) and (13,37):
Geospatial Package SQL Function
=> SELECT BB_WITHIN(14,30,23.0,45,13,37);
BB_WITHIN
----------f
(1 row)

HP Vertica Place SQL Function


=> SELECT ST_YMax(ST_GeographyFromText('POLYGON((-71.50 42.35, -71.00 42.35, -71.00
42.38, -71.50 42.38, -71.50 42.35))'));

TKTKTK

HP Vertica Analytic Database (7.1.x)

Page 11 of 181

Place
HP Vertica Place Installation Overview

HP Vertica Place Installation Overview


Before you install HP Vertica Place, follow the instructions in the Installation Guide to install the
latest HP Vertica server software on all nodes in your cluster. The HP Vertica Place version must
be the same as the version of the HP Vertica server.
Important: Be sure that you download the RPM for the correct operating system and
architecture.
The following topics explain the HP Vertica Place installation process:
l

Downloading the HP Vertica Place Package

Installing or Upgrading HP Vertica Place

Run Examples of HPVertica Place

Uninstalling HP Vertica Place

Downloading the HP Vertica Place Package


To download HP Vertica Place:
1. Use a Web browser to log in to the myVertica portal. If you do not have a myVertica account
you must create one.
2. Click the Download tab, and select the HP Vertica Place package.
Verify that the package you download matches both the operating system and the machine
architecture on which you intend to install it.

Tip: Sometimes, you cannot locate a test system or want to bypass the installation. You can
download a virtual machine to install HP Vertica Place on laptop or desktop computers,
although performance differs from a standard installation.

Installing or Upgrading HP Vertica Place


To install or upgrade HP Vertica Place:

HP Vertica Analytic Database (7.1.x)

Page 12 of 181

Place
HP Vertica Place Installation Overview

1. Copy the package to all nodes in the cluster.


2. Log in as root.
3. Use one of the following commands to run the package installer on each node in the cluster:
For rpm packages:
# rpm -Uvh <place_file_name>.rpm

For deb packages:


#dpkg -i <place_file_name>.deb

4. Log out as root.


5. Log back in as the dbadmin. From any node in the cluster, verify that you have started the
database.
6. After verifying that the database is running, change to the HP Vertica Place directory:
$cd /opt/vertica/packages/place

7. Using only one node in the cluster, run the installation script to install the functions and types
required for HP Vertica Place.
$/opt/vertica/bin/vsql -a -f ./install.sql

If the functions and types already exist from a previous installation of HP Vertica Place, the
script replaces them with the latest version.

Note: Do not use the -t option when running the install.sql script.

Completing the installation script creates the HP Vertica Place functions in the Public schema. All
users have EXECUTE privileges for the HP Vertica Place functions.

HP Vertica Analytic Database (7.1.x)

Page 13 of 181

Place
HP Vertica Place Installation Overview

Troubleshooting:
l

You must install HP Vertica Place on all nodes before you run the HP Vertica Place installation
script.

Before you install HP Vertica Place, verify that the HP Vertica server is installed on all nodes in
your cluster. HP Vertica Place must run on the matching version of the HP Vertica Analytics
Platform.

Upgrading is not supported for Innovations versions of HP Vertica Place. You must uninstall the
Innovations .rpm or .deb package before installing the official version.

An error message that reads libgeos_c.so.1: cannot open shared object file indicates
that theHP Vertica Place .rpm or .deb was not installed on every node.

Uninstalling HP Vertica Place


To uninstall HP Vertica Place:
1. Verify that you are logged in as the dbadmin user and that a database is running.
2. Change to the directory where the HP Vertica Place files are installed:
$cd /opt/vertica/packages/place

3. Run the uninstall script to uninstall the HP Vertica Place functions:


$/opt/vertica/bin/vsql -a -f ./uninstall.sql

4. Log in as root.
5. Find the HP Vertica Place package that is installed:
For rpm packages:
# rpm -qa | grep vertica-place

For deb packages:

HP Vertica Analytic Database (7.1.x)

Page 14 of 181

Place
HP Vertica Place Installation Overview

# dpkg -l | grep vertica-place

6. Uninstall the HP Vertica Place package from each node in your cluster:
For rpm packages:
# rpm -e <place_rpm_file_name>

For deb packages:


# dpkg --remove <place_deb_file_name>.deb

HP Vertica Analytic Database (7.1.x)

Page 15 of 181

Place
OGC Spatial Definitions

OGC Spatial Definitions


Using HP Vertica Place requires an understanding of the Open Geospatial Consortium (OGC)
concepts and capabilities. For more information, see the OGC Simple Feature Access Part 1 Common Architecture specification.

HP Vertica Analytic Database (7.1.x)

Page 16 of 181

Place
OGC Spatial Definitions

Spatial Classes
HP Vertica Place supports several classes of objects, as defined in the OGC standards.

Point
A location in two-dimensional space that is identified by one of the following:
l

X and Y coordinates

Longitude and latitude values

A point has dimension 0 and no boundary.

Examples
The following example uses a GEOMETRY point:
=> CREATE TABLE point_geo (gid int, geom GEOMETRY(100));
CREATETABLE
=> COPY point_geo(gid, gx filler LONG VARCHAR, geom AS ST_GeomFromText(gx)) FROM stdin
delimiter ',';
Enter data to be copied followed by a newline.
End with a backslash and a period on a line by itself.
>>1, POINT(3 5)
>>\.
=> SELECT gid, ST_AsText(geom) FROM point_geo;
gid | ST_AsText
-----+------------1 | POINT (3 5)
(1 row)

The following example uses a GEOGRAPHY point:


=> CREATE TABLE point_geog (gid int, geog geography(100));
CREATETABLE
=> COPY point_geog(gid, gx filler LONG VARCHAR, geom AS ST_GeographyFromText(gx)) FROM
stdin delimiter ',';
Enter data to be copied followed by a newline.
End with a backslash and a period on a line by itself.
>>1, POINT(42 71)
>>\.
=> SELECT gid, ST_AsText(geog) FROM point_geog;
gid |
ST_AsText
-----+--------------1 | POINT (42 71)
(1 row)

HP Vertica Analytic Database (7.1.x)

Page 17 of 181

Place
OGC Spatial Definitions

Multipoint
A set of one or more points. A multipoint object has dimension 0 and no boundary.

Examples
The following example uses a GEOMETRY multipoint:
=> CREATE TABLE mpoint_geo (gid int, geom GEOMETRY(1000));
CREATETABLE
=> COPY mpoint_geo(gid, gx filler LONGVARCHAR, geom AS ST_GeomFromText(gx)) FROM stdin
delimiter '|';
Enter data to be copied followed by a newline.
End with a backslash and a period on a line by itself.
>>1|MULTIPOINT(4 7, 8 10)
>>\.
=> SELECT gid, ST_AsText(geom) FROM mpoint_geo;
gid |
st_astext
-----+----------------------1 | MULTIPOINT (7 8, 6 9)
(1 row)

The following example uses a GEOGRAPHY multipoint:


=> CREATE TABLE mpoint_geog (gid int, geog GEOGRAPHY(1000));
CREATETABLE
=> COPY mpoint_geog(gid, gx filler LONGVARCHAR, geog AS ST_GeographyFromText(gx)) FROM
stdin delimiter '|';
Enter data to be copied followed by a newline.
End with a backslash and a period on a line by itself.
>>1|MULTIPOINT(42 71, 41.4 70)
>>\.
=> SELECT gid, ST_AsText(geom) FROM mpoint_geo;
gid |
st_astext
-----+----------------------1 | MULTIPOINT (42 71, 41.4 70)
(1 row)

Linestring
One or more connected lines, identified by pairs of consecutive points. A linestring has dimension
1. The boundary of a linestring is a multipoint object containing its start and end points.
The following are examples of linestrings:

HP Vertica Analytic Database (7.1.x)

Page 18 of 181

Place
OGC Spatial Definitions

Examples
The following example uses the GEOMETRY type to create a table, use copy to load a linestring to
the table, and then queries the table to view the linestring:
=> CREATE TABLE linestring_geom (gid int, geom GEOMETRY(1000));
CREATETABLE
=> COPY linestring_geom(gid, gx filler LONG VARCHAR, geom AS ST_GeomFromText(gx)) FROM
stdin delimiter '|';
Enter data to be copied followed by a newline.
End with a backslash and a period on a line by itself.
>>1|LINESTRING(0 0, 1 1, 2 2, 3 4, 2 4, 1 5)
>>\.
=> SELECT gid, ST_AsText(geom) FROM linestring_geom;
gid |
ST_AsText
-----+------------------------------------------1 | LINESTRING (0 0, 1 1, 2 2, 3 4, 2 4, 1 5)
(1 row)

The following example uses the GEOGRAPHY type to create a table, use copy to load a linestring
to the table, and then queries the table to view the linestring:
=> CREATE TABLE linestring_geog (gid int, geog GEOGRAPHY(1000));
CREATETABLE
=> COPY linestring_geog(gid, gx filler LONGVARCHAR, geog AS ST_GeographyFromText(gx))
FROM stdin delimiter '|';
Enter data to be copied followed by a newline.
End with a backslash and a period on a line by itself.
>>1|LINESTRING(42.1 71, 41.4 70, 41.3 72.9, 42.99 71.46, 44.47 73.21)
>>\.

HP Vertica Analytic Database (7.1.x)

Page 19 of 181

Place
OGC Spatial Definitions

=> SELECT gid, ST_AsText(geog) FROM linestring_geog;


gid |
ST_AsText
-----+-------------------------------------------------------------------1 | LINESTRING (42.1 71, 41.4 70, 41.3 72.9, 42.99 71.46, 44.47 73.21)
(1 row)

Multilinestring
A collection of zero or more linestrings. A multilinestring has no dimension. The boundary of a
multilinestring is a multipoint object containing the start and end points of all the linestrings.
The following are examples of multilinestrings:

Examples
The following example uses the GEOMETRY type to create a table, use copy to load a
multilinestring to the table, and then queries the table to view the multilinestring:
=> CREATE TABLE multilinestring_geom (gid int, geom GEOMETRY(1000));
CREATETABLE
=> COPY multilinestring_geom(gid, gx filler LONGVARCHAR, geom AS ST_GeomFromText(gx))
FROM stdin delimiter '|';
Enter data to be copied followed by a newline.
End with a backslash and a period on a line by itself.
>>1|MULTILINESTRING((1 5, 2 4, 5 3, 6 6),(3 5, 3 7))
>>\.
=> SELECT gid, ST_AsText(geom) FROM multilinestring_geom;

HP Vertica Analytic Database (7.1.x)

Page 20 of 181

Place
OGC Spatial Definitions

gid |
ST_AsText
-----+---------------------------------------------------1 | MULTILINESTRING ((1 5, 2 4, 5 3, 6 6), (3 5, 3 7))
(1 row)

The following example uses the GEOGRAPHY type to create a table, use copy to load a
multilinestring to the table, and then queries the table to view the multilinestring:
=> CREATE TABLE multilinestring_geog (gid int, geog GEOGRAPHY(1000));
CREATETABLE
=> COPY multilinestring_geog(gid, gx filler LONGVARCHAR, geog AS ST_GeographyFromText
(gx)) FROM stdin delimiter '|';
Enter data to be copied followed by a newline.
End with a backslash and a period on a line by itself.
>>1|MULTILINESTRING((42.1 71, 41.4 70, 41.3 72.9), (42.99 71.46, 44.47 73.21))
>>\.
=> SELECT gid, ST_AsText(geog) FROM multilinestring_geog;
gid |
ST_AsText
-----+---------------------------------------------------------------------------1 | MULTILINESTRING((42.1 71, 41.4 70, 41.3 72.9), (42.99 71.46, 44.47 73.21))
(1 row)

Polygon
An object identified by a set of closed linestrings. A polygon can have one or more holes, as defined
by interior boundaries, but all points must be connected. Two examples of polygons are:

Examples
The following example uses the GEOMETRY type to create a table, use copy to load a polygon into
the table, and then queries the table to view the polygon:
=> CREATE TABLE polygon_geom (gid int, geom GEOMETRY(1000));
CREATETABLE
=> COPY polygon_geom(gid, gx filler LONG VARCHAR, geom AS ST_GeomFromText(gx)) FROM stdin
delimiter '|';
Enter data to be copied followed by a newline.

HP Vertica Analytic Database (7.1.x)

Page 21 of 181

Place
OGC Spatial Definitions

End with a backslash and a period on a line by itself.


>>1|POLYGON((2 6, 2 9, 6 9, 7 7, 4 6, 2 6))
>>\.
=> SELECT gid, ST_AsText(geom) FROM polygon_geom;
gid |
ST_AsText
-----+-----------------------------------------1 | POLYGON((2 6, 2 9, 6 9, 7 7, 4 6, 2 6))
(1 row)

The following example uses the GEOGRAPHY type to create a table, use copy to load a polygon
into the table, and then queries the table to view the polygon:
=> CREATE TABLE polygon_geog (gid int, geog GEOGRAPHY(1000));
CREATETABLE
=> COPY polygon_geog(gid, gx filler LONG VARCHAR, geog AS ST_GeographyFromText(gx)) FROM
stdin delimiter '|';
Enter data to be copied followed by a newline.
End with a backslash and a period on a line by itself.
>>1|POLYGON((42.1 71, 41.4 70, 41.3 72.9, 44.47 73.21, 42.99 71.46, 42.1 71))
>>\.
=> SELECT gid, ST_AsText(geog) FROM polygon_geog;
gid |
ST_AsText
-----+--------------------------------------------------------------------------1 | POLYGON((42.1 71, 41.4 70, 41.3 72.9, 44.47 73.21, 42.99 71.46, 42.1 71))
(1 row)

Multipolygon
A collection of zero or more polygons that do not overlap.

Examples
The following example uses the GEOMETRY type to create a table, use copy to load a
multipolygon into the table, and then queries the table to view the polygon:
=> CREATE TABLE multipolygon_geom (gid int, geom GEOMETRY(1000));
CREATETABLE
=> COPY multipolygon_geom(gid, gx filler LONG VARCHAR, geom AS ST_GeomFromText(gx)) FROM

HP Vertica Analytic Database (7.1.x)

Page 22 of 181

Place
OGC Spatial Definitions

stdin delimiter '|';


Enter data to be copied followed by a newline.
End with a backslash and a period on a line by itself.
>>9|MULTIPOLYGON(((2 6, 2 9, 6 9, 7 7, 4 6, 2 6)),((0 0, 0 5, 1 0, 0 0)),((0 2, 2 5, 4 5,
0 2)))
>>\.
=> SELECT gid, ST_AsText(geom) FROM polygon_geom;
gid |
ST_AsText
-----+--------------------------------------------------------------------------------------------9 | MULTIPOLYGON(((2 6, 2 9, 6 9, 7 7, 4 6, 2 6)),((0 0, 0 5, 1 0, 0 0)),((0 2, 2 5, 4
5, 0 2)))
(1 row)

The following example uses the GEOGRAPHY type to create a table, use copy to load a
multipolygon into the table, and then queries the table to view the polygon:
=> CREATE TABLE multipolygon_geog (gid int, geog GEOGRAPHY(1000));
CREATETABLE
=> COPY polygon_geog(gid, gx filler LONG VARCHAR, geog AS ST_GeographyFromText(gx)) FROM
stdin delimiter '|';
Enter data to be copied followed by a newline.
End with a backslash and a period on a line by itself.
>>1|POLYGON((42.1 71, 41.4 70, 41.3 72.9, 44.47 73.21, 42.99 71.46, 42.1 71))
>>\.
=> SELECT gid, ST_AsText(geog) FROM polygon_geog;
gid |
ST_AsText
-----+--------------------------------------------------------------------------1 | POLYGON(((42.1 71, 41.4 70, 41.3 72.9, 42.1 71)),((44.47 73.21, 42.99 71.46, 42.1
71, 44.47 73.21)))
(1 row)

Spatial Object Representations


The OGC defines two ways to represent spatial objects:
l

Well-known text (WKT)

Well-known binary (WKB)

WellKnown Text (WKT)


Wellknown text (WKT) is an ASCII representation of a spatial object.
WKTs are not case sensitive; HP Vertica recognizes any combination of lowercase and uppercase
letters.
Some examples of valid WKTs are:

HP Vertica Analytic Database (7.1.x)

Page 23 of 181

Place
OGC Spatial Definitions

WKT Example

Description

POINT(1 2)

The point (1,2)

MULTIPOINT(0 0,1 1)

A set made up of the points (0,0) and (1,1)

LINESTRING(1.5 2.45,3.21 4)

The line from the point (1.5,2.45) to the point (3.21,4)

MULTILINESTRING((0 0,1 2, Two linestrings, one that passes through (0,0), (1,2), and
3 4),(2 3,3 4,6 7))

(3,4), and one that passes through (2,3), (3,4), and (6,7).

POLYGON((1 2,1 4,3 4,3 2,1 2))

The rectangle whose four corners are indicated by (1,2),


(1,4), (3,4), and (3,2). A polygon must be closed, so the first
and last points in the WKT must match.

POLYGON((0.5 0.5,5 0,5 5,0

A polygon (0.5 0.5,5 0,5 5,0 5,0.5 0.5) with a hole in it (1.5 1,4

5,0.5 0.5), (1.5 1,4 3,4 1,1.5 1))

3,4 1,1.5 1).

MULTIPOLYGON(((0 1,3 0,4 3,0

A set of three polygons

4,0 1)), ((3 4,6 3,5 5,3 4)), ((0 0,1


2,3 2,2 1,0 0)))
GEOMETRYCOLLECTION

A set containing the point (5,8) and the line from (1,3) to

(POINT(5 8), LINESTRING(1

(1,4)

3,1 4))
POINT EMPTY

Empty spatial objects; empty objects have no points.

MULTIPOINT EMPTY
LINESTRING EMPTY
MULTILINESTRING EMPTY
MULTILINESTRING(EMPTY)
POLYGON EMPTY
POLYGON(EMPTY)
MULTIPOLYGON EMPTY
MULTIPOLYGON(EMPTY)
Invalid WKTs are:

HP Vertica Analytic Database (7.1.x)

Page 24 of 181

Place
OGC Spatial Definitions

POINT(1 NAN), POINT(1 INF)Coordinates must be numbers.

POLYGON((1 2, 1 4, 3 4, 3 2))A polygon must be closed.

POLYGON((1 4, 2 4))A linestring is not a valid polygon.

Well-Known Binary (WKB)


Well-known binary (WKB) is a binary representation of a spatial object. This format is primarily used
to port spatial data between applications.

Spatial Definitions
The OGC defines properties that describe
l

Characteristics of spatial objects

Spatial relationships that can exist among objects

HP Vertica Place provides functions that test for and analyze the following properties and
relationships.

Boundary
The set of points that define the limit of a spatial object:
l

Points, multipoints, and geometrycollections do not have boundaries.

The boundary of a linestring is a multipoint object. This object contains its start and end points.

The boundary of a multilinestring is a multipoint object. This object contains the start and end
points of all the linestrings that make up the multilinestring.

The boundary of a polygon is a linestring that begins and ends at the same point. If the polygon
has one or more holes, the boundary is a multilinestring that contains the boundaries of the
exterior polygon and any interior polygons.

The boundary of a multipolygon is a multilinestring that contains the boundaries of all the
polygons that make up the multipolygon.

HP Vertica Analytic Database (7.1.x)

Page 25 of 181

Place
OGC Spatial Definitions

Buffer
The set of all points that are within or equal to a specified distance from the boundary of a spatial
object. The distance can be positive or negative.
Positive buffer:

Negative buffer:

Contains
One spatial object contains another spatial object if its interior includes all points of the other object.
If an object such as a point or linestring only exists along a polygon's boundary, the polygon does
not contain it. If a point is on a linestring, the linestring contains it; the interior of a linestring is all the
points on the linestring except the start and end points.
Contains(a, b) is spatially equivalent to within(b, a).

Convex Hull
The smallest convex polygon that contains one or more spatial objects.
In the following figure, the dotted lines represent the convex hull for a linestring and a triangle.

HP Vertica Analytic Database (7.1.x)

Page 26 of 181

Place
OGC Spatial Definitions

Crosses
Two spatial objects cross if both of the following are true:
l

The two objects have some but not all interior points in common.

The dimension of the result of their intersection is less than the maximum dimension of the two
objects.

Disjoint
Two spatial objects have no points in common; they do not intersect or touch.

Envelope
The minimum bounding rectangle that contains a spatial object.
The envelope for the following polygon is represented by the dotted lines in the following figure.

HP Vertica Analytic Database (7.1.x)

Page 27 of 181

Place
OGC Spatial Definitions

Equals
Two spatial objects are equal when their coordinates match exactly. Synonymous with spatially
equivalent.
The order of the points do not matter in determining spatial equivalence:
l

LINESTRING(1 2, 4 3) equals LINESTRING(4 3, 1 2).

POLYGON ((0 0, 1 1, 1 2, 2 2, 2 1, 3 0, 1.5 1.5, 0 0)) equals POLYGON((1 1 , 1 2, 2 2, 2 1, 3 0,


1.5 1.5, 0 0, 1 1)).

MULTILINESTRING((1 2, 4 3),(0 0, 1 4)) equals MULTILINESTRING((0 0, 1 4),(1 2, 4 3)).

Exterior
The set of points not contained within a spatial object nor on its boundary.

GeometryCollection
A set of zero or more objects from any of the supported classes of spatial objects.

Interior
The set of points contained in a spatial object, excluding its boundary.

Intersection
The set of points that two or more spatial objects have in common.

HP Vertica Analytic Database (7.1.x)

Page 28 of 181

Place
OGC Spatial Definitions

Overlaps
If a spatial object shares space with another object, but is not contained within that object, the
objects overlap. The objects must overlap at their interiors; if two objects touch at a single point or
intersect only along a boundary, they do not overlap.

Relates
When a spatial object is spatially related to another object as defined by a DE-9IM pattern matrix
string.
A DE-9IM pattern matrix string identifies how two spatial objects are spatially related to each other.
For more information about the DE-9IM standard, see Understanding Spatial Relations.

HP Vertica Analytic Database (7.1.x)

Page 29 of 181

Place
OGC Spatial Definitions

Simple
For points, multipoints, linestrings, or multilinestrings, a spatial object is simple if it does not
intersect itself or has no self-tangency points.
Polygons, multipolygons, and geometrycollections are always simple.

Symmetric Difference
The set of all points of a pair of spatial objects where the objects do not intersect. This difference is
spatially equivalent to the union of the two objects less their intersection. The symmetric difference
contains the boundaries of the intersections.
In the following figure, the shaded areas represent the symmetric difference of the two rectangles.

The following figure shows the symmetric difference of two overlapping linestrings.

HP Vertica Analytic Database (7.1.x)

Page 30 of 181

Place
OGC Spatial Definitions

Union
For two or more spatial objects, the set of all points in all the objects.

Validity
For a polygon or multipolygon, when all of the following are true:
l

It is closed; its start point is the same as its end point.

Its boundary is a set of linestrings.

HP Vertica Analytic Database (7.1.x)

Page 31 of 181

Place
OGC Spatial Definitions

No two linestrings in the boundary cross. The linestrings in the boundary may touch at a point
but they cannot cross.

Any polygons in the interior must be completely contained; they cannot touch the boundary of
the exterior polygon except at a vertex.

Valid polygons:

Invalid polygon:

Within
A spatial object is considered within another spatial object when all its points are inside the other
object's interior. Thus, if a point or linestring only exists along a polygon's boundary, it is not
considered within the polygon. The polygon boundary is not part of its interior.
If a point is on a linestring, it is considered within the linestring. The interior of a linestring is all the
points along the linestring, except the start and end points.
Within(a, b) is spatially equivalent to contains(b, a).

HP Vertica Analytic Database (7.1.x)

Page 32 of 181

Place
OGC Spatial Definitions

HP Vertica Analytic Database (7.1.x)

Page 33 of 181

Place
HP Vertica Place Spatial Objects

HP Vertica Place Spatial Objects


HP Vertica Place implements several new data types for storing spatial objects, well-known text
(WKT) strings, and well-known binary (WKB) representations. These data types include:
l

Supported Spatial Objects

Spatial Reference Identifiers (SRIDs)

Supported Spatial Objects


HP Vertica Place introduces two new data types. These data types store two-dimensional spatial
objects in a table column:
l

A GEOMETRY object is a spatial object with coordinates expressed as (x,y) pairs, defined in
the Cartesian plane. All calculations use Cartesian coordinates.

A GEOGRAPHY object is a spatial object defined on the surface of a perfect sphere. This
sphere has a radius of 6371 kilometers, which approximates the shape of the earth. Coordinates
are expressed in longitude/latitude angular values, measured in degrees. All calculations are in
meters.

Note: Other spatial programs may use an ellipsoid to model the earth, resulting in slightly
different data.
The maximum size of a GEOMETRY or GEOGRAPHY data type is 10,000,000 bytes (10 MB). You
cannot use a GEOMETRY or GEOGRAPHY type as the primary key for a table in an HP Vertica
database.

Spatial Reference Identifiers (SRIDs)


A spatial reference identifier (SRID) is an integer value that represents a method for projecting
coordinates on the plane. A SRID is metadata that indicates the coordinate system in which a
spatial object is defined.
Place functions using Geometry arguments must contain the same SRID. If the functions do not
contain the same SRID, then the query returns an error.
For example, in this query the two points have different SRIDs. As a result the query returns an
error:

HP Vertica Analytic Database (7.1.x)

Page 34 of 181

Place
HP Vertica Place Spatial Objects

=> SELECT ST_Distance(ST_GeomFromText('POINT(34 9)',2749), ST_GeomFromText('POINT(70 12)


', 3359));
ERROR 5861: Error calling processBlock() in User Function ST_Distance at
[src/Distance.cpp:65],
error code: 0, message: Geometries with different SRIDs found: 2749, 3359

Supported SRIDs
HP Vertica Place supports SRIDs derived from the EPSG standards. HP Vertica Place functions
using Geometry arguments must use supported SRIDs when performing calculations. SRID values
of 0 to 232-1 are valid. Queries with SRID values outside of this range will return an error.

HP Vertica Analytic Database (7.1.x)

Page 35 of 181

Place
HP Vertica Place Functions: An Overview

HP Vertica Place Functions: An Overview


HP Vertica Place includes functions that allow you to measure and manipulate two-dimensional
spatial objects on a plane and on the surface of the earth.
You create HP Vertica Place functions in the Public schema. All users have EXECUTE privileges
for the HP Vertica Place functions.

Function-Naming Conventions
The functions in HP Vertica Place use the following naming conventions:
l

The ST_<function_name> functions are compliant with the latest Open Geospatial Consortium
standard OGC SFA-SQL version 1.2.1 (reference. number is OGC 06-104r4, date: 2010-08-04).
Currently, some ST_<function_name> functions may not support all data types. Each function
page contains details about the supported data types.

Note: Some functions, such as ST_GeomFromText, are based on previous versions of the
standard.

The STV_<function_name> functions are unique to HP Vertica and not compliant with OGC
standards. Each function page explains its functionality in detail.

Verifying Spatial Objects Validity


Many spatial functions do not verify the validity of the parameters. If you pass an invalid spatial
object to an ST_ or STV_ function, the function may return an error or produce incorrect results.
To avoid this issue, Hewlett-Packard recommends that you first run ST_IsValid on all spatial
objects to verify their validity. If your object is not valid, run STV_IsValidReason to get information
about the location of the invalidity.
Note: If you pass a valid polygon to STV_IsValidReason, it returns NULL.

Spatial Functions Categories


HP Vertica Place includes the following functions:

HP Vertica Analytic Database (7.1.x)

Page 36 of 181

Place
HP Vertica Place Functions: An Overview

Function Category

Description

Predicate functions

Test spatial parameters and return a

Function Names
l

ST_Contains

ST_Crosses

ST_Disjoint

STV_DWithin

ST_Equals

ST_Intersects

ST_IsEmpty

ST_IsSimple

ST_IsValid

ST_Overlaps

ST_Relate

ST_Touches

ST_Within

ST_Area

ST_Distance

ST_Length

BOOLEAN value.

Measurement

Calculate measurements on the spatial

functions

parameters and return a FLOAT value.

HP Vertica Analytic Database (7.1.x)

Page 37 of 181

Place
HP Vertica Place Functions: An Overview

Function Category

Description

Operator functions

Calculate spatial relationships, based on

Function Names
l

ST_Boundary

ST_Buffer

ST_Centroid

ST_ConvexHull

ST_Difference

ST_Envelope

ST_Intersection

STV_NN

ST_SymDifference

ST_Union

parameters. Return either:


l

A spatial object or
Rows from a table that contain spatial
objects

HP Vertica Analytic Database (7.1.x)

Page 38 of 181

Place
HP Vertica Place Functions: An Overview

Function Category

Description

Attribute functions

Calculate and return information about

Function Names
l

ST_GeometryType

STV_IsValidReason

STV_LineStringPoint

ST_NumPoints

ST_PointN

STV_PolygonPoint

ST_SRID

ST_X

ST_XMax

ST_XMin

ST_Y

ST_YMax

ST_YMin

ST_AsText

ST_AsBinary

ST_

spatial parameters.

I/O functions

Operate on GEOMETRY or GEOGRAPHY


data types or WKT or WKB data. Convert
spatial objects from one format to another.

GeographyFromText
l

ST_
GeographyFromWKB

HP Vertica Analytic Database (7.1.x)

STV_Geography

STV_Geometry

ST_GeomFromText

ST_GeomFromWKB

Page 39 of 181

Place
HP Vertica Place Functions: An Overview

Function Category

Description

Spatial index functions

Perform tasks related to spatial indexes.

Functions for spatial

Perform spatial joins on point-polygon pairs.

Function Names
l

STV_Create_Index

STV_Describe_Index

STV_Drop_Index

STV_Refresh_Index

STV_Rename_Index

STV_Intersect Scalar

joins with large sets of

Function

points and polygons


l

STV_Intersect
Transform Function

Functions for loading

Create a table, based on a shapefile

shapefile data into

content. Parse the data, and load it into a

your database

HP Vertica database.

STV_
ShpCreateTable

STV_ShpSource and
STV_ShpParser

HP Vertica Place Functions


The following topics describe the HP Vertica Place functions.

ST_Area
Calculates the area of a spatial object.
The units are:
l

GEOMETRY objects: spatial reference system identifier (SRID) units

GEOGRAPHY objects: square meters

Behavior Type
Immutable

Syntax
ST_Area(g )

HP Vertica Analytic Database (7.1.x)

Page 40 of 181

Place
HP Vertica Place Functions: An Overview

Arguments
g

Spatial object for which you want to calculate the area, type GEOMETRY or GEOGRAPHY

Returns
FLOAT

Supported Data Types


Data Type

GEOMETRY GEOGRAPHY

Point

Yes

Yes

Multipoint

Yes

Yes

Linestring

Yes

Yes

Multilinestring

Yes

Yes

Polygon

Yes

Yes

Multipolygon

Yes

Yes

GeometryCollection Yes

No

Examples
The following examples show how to use ST_Area.
Calculate the area of a polygon:
=> SELECT ST_Area(ST_GeomFromText('POLYGON((0 0,1 0,1 1,0 1,0 0))'));
ST_Area
--------1
(1 row)

Calculate the area of a multipolygon:


=> SELECT ST_Area(ST_GeomFromText('MultiPolygon(((0 0,1 0,1 1,0 1,0 0)),
((2 2,2 3,4 6,3 3,2 2)))'));
ST_Area
--------3

HP Vertica Analytic Database (7.1.x)

Page 41 of 181

Place
HP Vertica Place Functions: An Overview

(1 row)

Suppose the polygon has a hole, as in the following figure.

Calculate the area, excluding the area of the hole:


=> SELECT ST_Area(ST_GeomFromText('POLYGON((2 2,5 5,8 2,2 2),
(4 3,5 4,6 3,4 3))'));
ST_Area
--------8
(1 row)

Calculate the area of a geometry collection:


=> SELECT ST_Area(ST_GeomFromText('GEOMETRYCOLLECTION(POLYGON((20.5 20.45,
20.51 20.52,20.69 20.32,20.5 20.45)),POLYGON((10 20,30 40,25 50,10 20)))'));
ST_Area
---------150.0073
(1 row)

Calculate the area of a geography object:


=> SELECT ST_Area(ST_GeographyFromText('POLYGON((20.5 20.45,20.51 20.52,
20.69 20.32,20.5 20.45))'));
ST_Area
-----------------84627437.116037
(1 row)

ST_AsBinary
Creates the well-known binary (WKB) representation of a spatial object. Use this function when you
need to convert an object to binary form for porting spatial data to or from other applications.

HP Vertica Analytic Database (7.1.x)

Page 42 of 181

Place
HP Vertica Place Functions: An Overview

The Open Geospatial Consortium (OGC) defines the format of a WKB representation in the Simple
Feature Access Part 1 - Common Architecture specification.

Behavior Type
Immutable

Syntax
ST_AsBinary(g )

Arguments
g

Spatial object for which you want the WKB, type GEOMETRY or GEOGRAPHY

Returns
LONG VARBINARY

Supported Data Types


Data Type

GEOMETRY GEOGRAPHY

Point

Yes

Yes

Multipoint

Yes

Yes

Linestring

Yes

Yes

Multilinestring

Yes

Yes

Polygon

Yes

Yes

Multipolygon

Yes

Yes

GeometryCollection Yes

No

Example
The following example shows how to use ST_AsBinary.
Retrieve WKB and WKT representations:
=> CREATE TABLE locations (id INTEGER, name VARCHAR(100), geom1 GEOMETRY(800), geom2

HP Vertica Analytic Database (7.1.x)

Page 43 of 181

Place
HP Vertica Place Functions: An Overview

GEOGRAPHY);
CREATE TABLE
=> COPY locations
(id, geom1x FILLER LONG VARCHAR(800), geom1 AS ST_GeomFromText(geom1x), geom2x FILLER
LONG VARCHAR (800),
geom2 AS ST_GeographyFromText(geom2x))
FROM stdin;
Enter data to be copied followed by a newline.
End with a backslash and a period on a line by itself.
>> 1|POINT(2 3)|
>> 2|LINESTRING(2 4,1 5)|
>> 3||POLYGON((-70.96 43.27,-70.67 42.95,-66.90 44.74,-67.81 46.08,-67.81 47.20,-69.22
47.43,-71.09 45.25,-70.96 43.27))
>> \.
=> SELECT id, ST_AsText(geom1),ST_AsText(geom2) FROM locations ORDER BY id ASC;
id |
ST_AsText
|
ST_AsText
----+-----------------------+--------------------------------------------1 | POINT (2 3)
|
2 | LINESTRING (2 4, 1 5) |
3 |
| POLYGON ((-70.96 43.27, -70.67 42.95, -66.9 44.74, -67.81
46.08, -67.81 47.2, -69.22 47.43, -71.09 45.25, -70.96 43.27))
=> SELECT id, ST_AsBinary(geom1),ST_AsBinary(geom2) FROM locations ORDER BY id ASC;
.
.
.
(3 rows)

Calculate the length of a WKB using the HP Vertica SQL function LENGTH:
=> SELECT LENGTH(ST_AsBinary(St_GeomFromText('POLYGON ((-1 2, 0 3, 1 2,
0 1, -1 2))')));
LENGTH
-------93
(1 row)

See Also
l

ST_AsText

ST_AsText
Creates the well-known text (WKT) representation of a spatial object. Use this function when you
need to specify a spatial object in ASCII form.
The Open Geospatial Consortium (OGC) defines the format of a WKT string in the Simple Feature
Access Part 1 - Common Architecture specification.

Behavior Type
Immutable

HP Vertica Analytic Database (7.1.x)

Page 44 of 181

Place
HP Vertica Place Functions: An Overview

Syntax
ST_AsText(g )

Arguments
g

Spatial object for which you want the WKT string, type GEOMETRY or GEOGRAPHY

Returns
LONG VARCHAR

Supported Data Types


Data Type

GEOMETRY GEOGRAPHY

Point

Yes

Yes

Multipoint

Yes

Yes

Linestring

Yes

Yes

Multilinestring

Yes

Yes

Polygon

Yes

Yes

Multipolygon

Yes

Yes

GeometryCollection Yes

No

Example
The following example shows how to use ST_AsText.
Retrieve WKB and WKT representations:
=> CREATE TABLE locations (id INTEGER, name VARCHAR(100), geom1 GEOMETRY(800),
geom2 GEOGRAPHY);
CREATE TABLE
=> COPY locations
(id, geom1x FILLER LONG VARCHAR(800), geom1 AS ST_GeomFromText(geom1x), geom2x FILLER
LONG VARCHAR (800),
geom2 AS ST_GeographyFromText(geom2x))
FROM stdin;
Enter data to be copied followed by a newline.

HP Vertica Analytic Database (7.1.x)

Page 45 of 181

Place
HP Vertica Place Functions: An Overview

End with a backslash and a period on a line by itself.


>> 1|POINT(2 3)|
>> 2|LINESTRING(2 4,1 5)|
>> 3||POLYGON((-70.96 43.27,-70.67 42.95,-66.90 44.74,-67.81 46.08,-67.81 47.20,-69.22
47.43,-71.09 45.25,-70.96 43.27))
>> \.
=> SELECT id, ST_AsText(geom1),ST_AsText(geom2) FROM locations ORDER BY id ASC;
id |
ST_AsText
|
ST_AsText
----+-----------------------+--------------------------------------------1 | POINT (2 3)
|
2 | LINESTRING (2 4, 1 5) |
3 |
| POLYGON ((-70.96 43.27, -70.67 42.95, -66.9 44.74, -67.81
46.08, -67.81 47.2, -69.22 47.43, -71.09 45.25, -70.96 43.27))
(3 rows)

Calculate the length of a WKT using the HP Vertica SQL function LENGTH:
=> SELECT LENGTH(ST_AsText(St_GeomFromText('POLYGON ((-1 2, 0 3, 1 2,
0 1, -1 2))')));
LENGTH
-------37
(1 row)

See Also
l

ST_AsBinary

ST_Boundary
Calculates the boundary of the specified GEOMETRY object. An object's boundary is the set of
points that define the limit of the object.
For a linestring, the boundary is the start and end points. For a polygon, the boundary is a linestring
that begins and ends at the same point.

Behavior Type
Immutable

Syntax
ST_Boundary(g )

HP Vertica Analytic Database (7.1.x)

Page 46 of 181

Place
HP Vertica Place Functions: An Overview

Arguments
g

Spatial object for which you want the boundary, type GEOMETRY

Returns
GEOMETRY

Supported Data Types


Data Type

GEOMETRY

Point

Yes

Multipoint

Yes

Linestring

Yes

Multilinestring

Yes

Polygon

Yes

Multipolygon

Yes

GeometryCollection No

Examples
The following examples show how to use ST_Boundary.
Returns a linestring that represents the boundary:
=> SELECT ST_AsText(ST_Boundary(ST_GeomFromText('POLYGON((-1 -1,2 2,
0 1,-1 -1))')));
ST_AsText
-------------LINESTRING(-1 -1, 2 2, 0 1, -1 -1)
(1 row)

Returns a multilinestring that contains the boundaries of both polygons:


=> SELECT ST_AsText(ST_Boundary(ST_GeomFromText('POLYGON((2 2,5 5,8 2,2 2),
(4 3,5 4,6 3,4 3))')));
ST_AsText
------------------------------------------------------------------

HP Vertica Analytic Database (7.1.x)

Page 47 of 181

Place
HP Vertica Place Functions: An Overview

MULTILINESTRING ((2 2, 5 5, 8 2, 2 2), (4 3, 5 4, 6 3, 4 3))


(1 row)

The boundary of a linestring is its start and end points:


=> SELECT ST_AsText(ST_Boundary(ST_GeomFromText(
'LINESTRING(1 1,2 2,3 3,4 4)')));
ST_AsText
----------------------MULTIPOINT (1 1, 4 4)
(1 row)

A closed linestring has no boundary because it has no start and end points:
=> SELECT ST_AsText(ST_Boundary(ST_GeomFromText(
'LINESTRING(1 1,2 2,3 3,4 4,1 1)')));
ST_AsText
-----------------MULTIPOINT EMPTY
(1 row)

ST_Buffer
Creates a GEOMETRY object greater than or equal to a specified distance from the boundary of a
spatial object. The distance is measured in Cartesian coordinate units. ST_Buffer does not accept
a distance size greater than +1e15 or less than 1e15.

Behavior Type
Immutable

Syntax
ST_Buffer(g, d )

Arguments
g

Spatial object for which you want to calculate the buffer, type GEOMETRY

Distance from the object in Cartesian coordinate units, type FLOAT

Returns
GEOMETRY

HP Vertica Analytic Database (7.1.x)

Page 48 of 181

Place
HP Vertica Place Functions: An Overview

Supported Data Types


Data Type

GEOMETRY

Point

Yes

Multipoint

Yes

Linestring

Yes

Multilinestring

Yes

Polygon

Yes

Multipolygon

Yes

GeometryCollection Yes

Usage Tips
l

If you specify a positive distance, ST_Buffer returns a polygon that represents the points within
or equal to the distance outside the object. If you specify a negative distance, ST_Buffer returns
a polygon that represents the points within or equal to the distance inside the object.

For points, multipoints, linestrings, and multilinestrings, if you specify a negative distance, ST_
Buffer returns an empty polygon.

The HP Vertica Place version of ST_Buffer returns the buffer as a polygon, so the buffer object
has corners at its vertices. It does not contain rounded corners.

Example
The following example shows how to use ST_Buffer.
Returns a GEOMETRY object:
=> SELECT ST_AsText(ST_Buffer(ST_GeomFromText('POLYGON((0 1,1 4,4 3,0 1))'),1));
ST_AsText
-----------------------------------------------------------------------------POLYGON ((-0.188847498856 -0.159920845081, -1.12155598386 0.649012935089, 0.290814745534
4.76344136152,
0.814758063466 5.02541302048, 4.95372324225 3.68665254814, 5.04124517538 2.45512549204,
-0.188847498856 -0.159920845081))
(1 row)

HP Vertica Analytic Database (7.1.x)

Page 49 of 181

Place
HP Vertica Place Functions: An Overview

ST_Centroid
Calculates the geometric centerthe centroidof a spatial object. If points or linestrings or both
are present in a geometry with polygons, only the polygons contribute to the calculation of the
centroid. Similarly, if points are present with linestrings, the points do not contribute to the
calculation of the centroid.
To calculate the centroid of a GEOGRAPHY object, see the examples for STV_Geometry and
STV_Geography.

Behavior Type
Immutable

Syntax
ST_Centroid(g )

Arguments
g

Spatial object for which you want to calculate the centroid, type GEOMETRY

Returns
GEOMETRY (POINT only)

Supported Data Types


Data Type

GEOMETRY

Point

Yes

Multipoint

Yes

Linestring

Yes

Multilinestring

Yes

Polygon

Yes

Multipolygon

Yes

GeometryCollection Yes

HP Vertica Analytic Database (7.1.x)

Page 50 of 181

Place
HP Vertica Place Functions: An Overview

Examples
The following examples show how to use ST_Centroid.
Calculate the centroid for a polygon:
=> SELECT ST_AsText(ST_Centroid(ST_GeomFromText('POLYGON((-1 -1,2 2,-1 2,
-1 -1))')));
ST_AsText
-----------POINT (-0 1)
(1 row)

Calculate the centroid for a multipolygon:


=> SELECT ST_AsText(ST_Centroid(ST_GeomFromText('MULTIPOLYGON(((1 0,2 1,2 0,
1 0)),((-1 -1,2 2,-1 2,-1 -1)))')));
ST_AsText
-------------------------------------POINT (0.166666666667 0.933333333333)
(1 row)

This figure shows the centroid for the multipolygon.

ST_Contains
Determines if a spatial object is entirely inside another spatial object without existing only on its
boundary. Both arguments must be the same spatial data type. Either specify two GEOMETRY
objects or two GEOGRAPHY objects.

HP Vertica Analytic Database (7.1.x)

Page 51 of 181

Place
HP Vertica Place Functions: An Overview

If an object such as a point or linestring only exists along a spatial object's boundary, then ST_
Contains returns false. The interior of a linestring is all the points on the linestring except the start
and end points.
ST_Contains(g1, g2) is functionally equivalent to ST_Within(g2, g1).

Behavior Type
Immutable

Syntax
ST_Contains(g1, g2 )

Arguments
g1

Spatial object, type GEOMETRY or GEOGRAPHY

g2

Spatial object, type GEOMETRY or GEOGRAPHY

Returns
BOOLEAN

Supported Data Types


Data Type

GEOMETRY GEOGRAPHY

Point

Yes

Yes

Multipoint

Yes

No

Linestring

Yes

Yes

Multilinestring

Yes

No

Polygon

Yes

Yes

Multipolygon

Yes

Yes

GeometryCollection Yes

No

Compatible GEOGRAPHY pairs:

HP Vertica Analytic Database (7.1.x)

Page 52 of 181

Place
HP Vertica Place Functions: An Overview

Data Type

GEOGRAPHY

Point-Point

Yes

Linestring-Point

Yes

Polygon-Point

Yes

Multipolygon-Point Yes

Examples
The following examples show how to use ST_Contains.
The first polygon does not completely contain the second polygon:
=> SELECT ST_Contains(ST_GeomFromText('POLYGON((0 2,1 1,0 -1,0 2))'),
ST_GeomFromText('POLYGON((-1 3,2 1,0 -3,-1 3))'));
ST_Contains
------------f
(1 row)

If a point is on a linestring, but not on an end point:


=> SELECT ST_Contains(ST_GeomFromText('LINESTRING(20 20,30 30)'),
ST_GeomFromText('POINT(25 25)'));
ST_Contains
-------------t
(1 row)

HP Vertica Analytic Database (7.1.x)

Page 53 of 181

Place
HP Vertica Place Functions: An Overview

If a point is on the boundary of a polygon:


=> SELECT ST_Contains(ST_GeographyFromText('POLYGON((20 20,30 30,30 25,20 20))'),
ST_GeographyFromText('POINT(20 20)'));
ST_Contains
-------------f
(1 row)

Two spatially equivalent polygons:


=> SELECT ST_Contains (ST_GeomFromText('POLYGON((-1 2, 0 3, 0 1, -1 2))'),
ST_GeomFromText('POLYGON((0 3, -1 2, 0 1, 0 3))'));
ST_Contains
-------------t
(1 row)

HP Vertica Analytic Database (7.1.x)

Page 54 of 181

Place
HP Vertica Place Functions: An Overview

See Also
l

ST_Overlaps

ST_Within

ST_ConvexHull
Calculates the smallest convex GEOMETRY object that contains a GEOMETRY object.

Behavior Type
Immutable

Syntax
ST_ConvexHull(g )

Arguments
g

Spatial object for which you want the convex hull, type GEOMETRY

Returns
GEOMETRY

Supported Data Types


Data Type

GEOMETRY

HP Vertica Analytic Database (7.1.x)

Page 55 of 181

Place
HP Vertica Place Functions: An Overview

Point

Yes

Multipoint

Yes

Linestring

Yes

Multilinestring

Yes

Polygon

Yes

Multipolygon

Yes

GeometryCollection Yes

Examples
The following examples show how to use ST_ConvexHull.
For a pair of points in a geometry collection:
=> SELECT ST_AsText(ST_ConvexHull(ST_GeomFromText('GEOMETRYCOLLECTION(
POINT(1 1),POINT(0 0))')));
ST_AsText
----------------------LINESTRING (1 1, 0 0)
(1 row)

For a geometry collection:


=> SELECT ST_AsText(ST_ConvexHull(ST_GeomFromText('GEOMETRYCOLLECTION(
LINESTRING(2.5 3,-2 1.5), POLYGON((0 1,1 3,1 -2,0 1)))')));
ST_AsText
--------------------------------------------POLYGON ((1 -2, -2 1.5, 1 3, 2.5 3, 1 -2))
(1 row)

The solid lines represent the original geometry collection and the dashed lines represent the convex
hull.

HP Vertica Analytic Database (7.1.x)

Page 56 of 181

Place
HP Vertica Place Functions: An Overview

ST_Crosses
Determines if one GEOMETRY object spatially crosses another GEOMETRY object. If two objects
touch only at a border, ST_Crosses returns FALSE.
Two objects spatially cross when both of the following are true:
l

The two objects have some, but not all, interior points in common.

The dimension of the result of their intersection is less than the maximum dimension of the two
objects.

Behavior Type
Immutable

Syntax
ST_Crosses(g1, g2 )

Arguments
g1

Spatial object, type GEOMETRY

g2

Spatial object, type GEOMETRY

Returns
BOOLEAN

HP Vertica Analytic Database (7.1.x)

Page 57 of 181

Place
HP Vertica Place Functions: An Overview

Supported Data Types


Data Type

GEOMETRY

Point

Yes

Multipoint

Yes

Linestring

Yes

Multilinestring

Yes

Polygon

Yes

Multipolygon

Yes

GeometryCollection Yes

Examples
The following examples show how to use ST_Crosses.

=> SELECT ST_Crosses(ST_GeomFromText('LINESTRING(-1 3,1 4)'),


ST_GeomFromText('LINESTRING(-1 4,1 3)'));
ST_Crosses
-----------t
(1 row)

HP Vertica Analytic Database (7.1.x)

Page 58 of 181

Place
HP Vertica Place Functions: An Overview

=> SELECT ST_Crosses(ST_GeomFromText('LINESTRING(-1 1,1 2)'),


ST_GeomFromText('POLYGON((1 1,0 -1,3 -1,2 1,1 1))'));
ST_Crosses
-----------f
(1 row)

=> SELECT ST_Crosses(ST_GeomFromText('POINT(-1 4)'),


ST_GeomFromText('LINESTRING(-1 4,1 3)'));
ST_ Crosses
-----------f
(1 row)

ST_Difference
Calculates the part of a spatial object that does not intersect with another spatial object.

Behavior Type
Immutable

Syntax
ST_Difference(g1, g2 )

HP Vertica Analytic Database (7.1.x)

Page 59 of 181

Place
HP Vertica Place Functions: An Overview

Arguments
g1

Spatial object, type GEOMETRY

g2

Spatial object, type GEOMETRY

Returns
GEOMETRY

Supported Data Types


Data Type

GEOMETRY

Point

Yes

Multipoint

Yes

Linestring

Yes

Multilinestring

Yes

Polygon

Yes

Multipolygon

Yes

GeometryCollection Yes

Examples
The following examples show how to use ST_Difference.
Two overlapping linestrings:
=> SELECT ST_AsText(ST_Difference(ST_GeomFromText('LINESTRING(0 0,0 2)'),
ST_GeomFromText('LINESTRING(0 1,0 2)')));
ST_AsText
----------------------LINESTRING (0 0, 0 1)
(1 row)
=> SELECT ST_AsText(ST_Difference(ST_GeomFromText('LINESTRING(0 0,0 3)'),
ST_GeomFromText('LINESTRING(0 1,0 2)')));
ST_AsText
-----------------------------------------MULTILINESTRING ((0 0, 0 1), (0 2, 0 3))
(1 row)

HP Vertica Analytic Database (7.1.x)

Page 60 of 181

Place
HP Vertica Place Functions: An Overview

Two overlapping polygons:

=> SELECT ST_AsText(ST_Difference(ST_GeomFromText('POLYGON((0 1,0 3,2 3,2 1,0 1))'),


ST_GeomFromText('POLYGON((0 0,0 2,2 2,2 0,0 0))')));
ST_AsText
------------------------------------POLYGON ((0 2, 0 3, 2 3, 2 2, 0 2))
(1 row)

Two non-intersecting polygons:


=> SELECT ST_AsText(ST_Difference(ST_GeomFromText('POLYGON((1 1,1 3,3 3,3 1,
1 1))'),ST_GeomFromText('POLYGON((1 5,1 7,-1 7,-1 5,1 5))')));
ST_AsText
------------------------------------POLYGON ((1 1, 1 3, 3 3, 3 1, 1 1))
(1 row)

ST_Disjoint
Determines if two GEOMETRY objects do not intersect or touch.
If ST_Disjoint returns TRUE for a pair of GEOMETRY objects, ST_Intersects returns FALSE for
the same two objects.

HP Vertica Analytic Database (7.1.x)

Page 61 of 181

Place
HP Vertica Place Functions: An Overview

Behavior Type
Immutable

Syntax
ST_Disjoint(g1, g2 )

Arguments
g1

Spatial object, type GEOMETRY

g2

Spatial object, type GEOMETRY

Returns
BOOLEAN

Supported Data Types


Data Type

GEOMETRY

Point

Yes

Multipoint

Yes

Linestring

Yes

Multilinestring

Yes

Polygon

Yes

Multipolygon

Yes

GeometryCollection Yes

Examples
The following examples show how to use ST_Disjoint.
Two non-intersecting or touching polygons:
=> SELECT ST_Disjoint (ST_GeomFromText('POLYGON((-1 2,0 3,0 1,-1 2))'),

HP Vertica Analytic Database (7.1.x)

Page 62 of 181

Place
HP Vertica Place Functions: An Overview

ST_GeomFromText('POLYGON((1 0, 1 1, 2 2, 1 0))'));
ST_Disjoint
------------t
(1 row)

Two intersecting linestrings:


=> SELECT ST_Disjoint(ST_GeomFromText('LINESTRING(-1 2,0 3)'),
ST_GeomFromText('LINESTRING(0 2,-1 3)'));
ST_Disjoint
------------f
(1 row)

Two polygons touching at a single point:


=> SELECT ST_Disjoint (ST_GeomFromText('POLYGON((-1 2, 0 3, 0 1, -1 2))'),
ST_GeomFromText('POLYGON((0 2, 1 1, 1 2, 0 2))'));
ST_Disjoint
-------------f
(1 row)

SeeAlso
l

ST_Intersects

ST_Distance
Calculates the shortest distance between two spatial objects. For GEOMETRY objects, the
distance is measured in Cartesian coordinate units. For GEOGRAPHY objects, the distance is
measured in meters.
Parameters g1 and g2 must be both GEOMETRY objects or both GEOGRAPHY objects.

Behavior Type
Immutable

Syntax
ST_Distance(g1, g2 )

HP Vertica Analytic Database (7.1.x)

Page 63 of 181

Place
HP Vertica Place Functions: An Overview

Arguments
g1

Spatial object, type GEOMETRY or GEOGRAPHY

g2

Spatial object, type GEOMETRY or GEOGRAPHY

Returns
FLOAT

Supported Data Types


Data Type

GEOMETRY GEOGRAPHY

Point

Yes

Yes

Multipoint

Yes

Yes

Linestring

Yes

Yes

Multilinestring

Yes

Yes

Polygon

Yes

Yes

Multipolygon

Yes

Yes

GeometryCollection Yes

No

Examples
The following examples show how to use ST_Distance.
Distance between two polygons:
=> SELECT ST_Distance(ST_GeomFromText('POLYGON((-1 -1,2 2,0 1,-1 -1))'),
ST_GeomFromText('POLYGON((3 3,1 5,-1 3,0 4,2 6,3 3))'));
ST_Distance
----------------1.4142135623731
(1 row)

Distance between a point and a linestring in meters:


=> SELECT ST_Distance(ST_GeographyFromText('POINT(31.75 31.25)'),

HP Vertica Analytic Database (7.1.x)

Page 64 of 181

Place
HP Vertica Place Functions: An Overview

ST_GeographyFromText('LINESTRING(32 32,32 35,40.5 35,32 35,32 32)'));


ST_Distance
-----------------86690.3950562969
(1 row)

ST_Envelope
Calculates the minimum bounding rectangle that contains the specified GEOMETRY object.

Behavior Type
Immutable

Syntax
ST_Envelope(g )

Arguments
g

Spatial object for which you want to find the minimum bounding rectangle, type GEOMETRY

Returns
GEOMETRY

Supported Data Types


Data Type

GEOMETRY

Point

Yes

Multipoint

Yes

Linestring

Yes

Multilinestring

Yes

Polygon

Yes

Multipolygon

Yes

GeometryCollection Yes

HP Vertica Analytic Database (7.1.x)

Page 65 of 181

Place
HP Vertica Place Functions: An Overview

Example
The following example shows how to use ST_Envelope.
Returns the minimum bounding rectangle:
=> SELECT ST_AsText(ST_Envelope(ST_GeomFromText('POLYGON((0 0,1 1,1 2,2 2,
2 1,3 0,1.5 -1.5,0 0))')));
ST_AsText
------------------------------------------POLYGON ((0 -1.5, 3 -1.5, 3 2, 0 2, 0 -1.5))
(1 row)

ST_Equals
Determines if two spatial objects are spatially equivalent. The coordinates of the two objects and
their WKT/WKB representations must match exactly for ST_Equals to return TRUE.
The order of the points do not matter in determining spatial equivalence:
l

LINESTRING(1 2, 4 3) equals LINESTRING(4 3, 1 2).

POLYGON ((0 0, 1 1, 1 2, 2 2, 2 1, 3 0, 1.5 -1.5, 0 0)) equals POLYGON((1 1 , 1 2, 2 2, 2 1, 3 0,


1.5 -1.5, 0 0, 1 1)).

MULTILINESTRING((1 2, 4 3),(0 0, -1 -4)) equals MULTILINESTRING((0 0, -1 -4),(1 2, 4 3)).

Coordinates are stored as FLOAT types. Thus, rounding errors are expected when importing wellknown text (WKT) values because the limitations of floating-point number representation.
g1 and g2 must both be GEOMETRY objects or both be GEOGRAPHY objects.

HP Vertica Analytic Database (7.1.x)

Page 66 of 181

Place
HP Vertica Place Functions: An Overview

Behavior Type
Immutable

Syntax
ST_Equals(g1, g2 )

Arguments
g1

Spatial object to compare to g2, type GEOMETRY or GEOGRAPHY

g2

Spatial object to compare to g1, type GEOMETRY or GEOGRAPHY

Returns
BOOLEAN

Supported Data Types


Data Type

GEOMETRY GEOGRAPHY

Point

Yes

Yes

Multipoint

Yes

Yes

Linestring

Yes

Yes

Multilinestring

Yes

Yes

Polygon

Yes

Yes

Multipolygon

Yes

Yes

GeometryCollection Yes

No

Examples
The following examples show how to use ST_Equals.
Two linestrings:
=> SELECT ST_Equals (ST_GeomFromText('LINESTRING(-1 2, 0 3)'),

HP Vertica Analytic Database (7.1.x)

Page 67 of 181

Place
HP Vertica Place Functions: An Overview

ST_GeomFromText('LINESTRING(0 3, -1 2)'));
ST_Equals
-------------t
(1 row)

Two polygons:
=> SELECT ST_Equals (ST_GeographyFromText('POLYGON((43.22 42.21,40.3 39.88,
42.1 50.03,43.22 42.21))'),ST_GeographyFromText('POLYGON((43.22 42.21,
40.3 39.88,42.1 50.31,43.22 42.21))'));
ST_Equals
-------------f
(1 row)

ST_GeographyFromText
Converts a well-known text (WKT) string into its corresponding GEOGRAPHY object. Use this
function to convert a WKT string into the format expected by the HP Vertica Place functions.
A GEOGRAPHY object is a spatial object with coordinates (longitude, latitude) defined on the
surface of the earth. Coordinates are expressed in degrees (longitude, latitude) from reference
planes dividing the earth.
The maximum size of a GEOGRAPHY object is 10 MB. If you pass a WKT to ST_
GeographyFromText, the result is a spatial object whose size is greater than 10 MB, ST_
GeographyFromText returns an error.
The Open Geospatial Consortium (OGC) defines the format of a WKT string in Section 7 in the
Simple Feature Access Part 1 - Common Architecture specification.

Behavior Type
Immutable

Syntax
ST_GeographyFromText(wkt [USING PARAMETERS ignore_errors={'y'|'n'} ] )

Arguments
wkt

Well-known text (WKT) string of a GEOGRAPHY object, type LONG


VARCHAR

HP Vertica Analytic Database (7.1.x)

Page 68 of 181

Place
HP Vertica Place Functions: An Overview

ignore_errors

(Optional) ST_GeographyFromText returns the following, based on the


parameters supplied:
l

NULLIf wkt is invalid and ignore_errors='y'.

ErrorIf wkt is invalid and ignore_errors='n' or is unspecified.

Returns
GEOGRAPHY

Supported Data Types


Data Type

GEOGRAPHY

Point

Yes

Multipoint

Yes

Linestring

Yes

Multilinestring

Yes

Polygon

Yes

Multipolygon

Yes

GeometryCollection No

Example
The following example shows how to use ST_GeographyFromText.
Convert WKT into a GEOGRAPHY object:
=> CREATE TABLE wkt_ex (g GEOGRAPHY);
CREATE TABLE
=> INSERT INTO wkt_ex VALUES(ST_GeographyFromText('POLYGON((1 2,3 4,2 3,1 2))'));
OUTPUT
-------1
(1 row)

HP Vertica Analytic Database (7.1.x)

Page 69 of 181

Place
HP Vertica Place Functions: An Overview

ST_GeographyFromWKB
Converts a well-known binary (WKB) value into its corresponding GEOGRAPHY object. Use this
function to convert a WKB into the format expected by HP Vertica Place functions.
A GEOGRAPHY object is a spatial object defined on the surface of the earth. Coordinates are
expressed in degrees (longitude, latitude) from reference planes dividing the earth. All calculations
are in meters.
The maximum size of a GEOGRAPHY object is 10 MB. If you pass a WKB to ST_
GeographyFromWKB that results in a spatial object whose size is greater than 10 MB, ST_
GeographyFromWKB returns an error.
The Open Geospatial Consortium (OGC) defines the format of a WKB representation in Section 8 in
the Simple Feature Access Part 1 - Common Architecture specification.

Behavior Type
Immutable

Syntax
ST_GeographyFromWKB(wkb [USING PARAMETERS ignore_errors={'y'|'n'} ] )

Arguments
wkb

Well-known binary (WKB) value of a GEOGRAPHY object, type LONG


VARBINARY

ignore_errors

(Optional) ST_GeographyFromWKB returns the following, based on the


parameters supplied:
l

NULLIf wkb is invalid and ignore_errors='y'.

ErrorIf wkb is invalid and ignore_errors='n' or is unspecified.

Returns
GEOGRAPHY

HP Vertica Analytic Database (7.1.x)

Page 70 of 181

Place
HP Vertica Place Functions: An Overview

Supported Data Types


Data Type

GEOGRAPHY

Point

Yes

Multipoint

Yes

Linestring

Yes

Multilinestring

Yes

Polygon

Yes

Multipolygon

Yes

GeometryCollection No

Example
The following example shows how to use ST_GeographyFromWKB.
Convert WKB into a GEOGRAPHY object:
=> CREATE TABLE wkb_ex (g GEOGRAPHY);
CREATE TABLE
=> INSERT INTO wkb_ex VALUES(ST_GeographyFromWKB(X'0103000000010000000 ... );
OUTPUT
-------1
(1 row)

ST_GeometryType
Determines the class of a spatial object.

Behavior Type
Immutable

Syntax
ST_GeometryType(g )

HP Vertica Analytic Database (7.1.x)

Page 71 of 181

Place
HP Vertica Place Functions: An Overview

Arguments
g

Spatial object for which you want the class, type GEOMETRY or GEOGRAPHY

Returns
VARCHAR

Supported Data Types


Data Type

GEOMETRY GEOGRAPHY

Point

Yes

Yes

Multipoint

Yes

Yes

Linestring

Yes

Yes

Multilinestring

Yes

Yes

Polygon

Yes

Yes

Multipolygon

Yes

Yes

GeometryCollection Yes

No

Example
The following example shows how to use ST_GeometryType.
Returns spatial class:
=> SELECT ST_GeometryType(ST_GeomFromText('GEOMETRYCOLLECTION(LINESTRING(1 1,
2 2), POLYGON((1 3,4 5,2 2,1 3)))'));
ST_GeometryType
----------------------ST_GeometryCollection
(1 row)

ST_GeomFromText
Converts a well-known text (WKT) string into its corresponding GEOMETRY object. Use this
function to convert a WKT string into the format expected by the HP Vertica Place functions.

HP Vertica Analytic Database (7.1.x)

Page 72 of 181

Place
HP Vertica Place Functions: An Overview

A GEOMETRY object is a spatial object defined by the coordinates of a plane. Coordinates are
expressed as points on a Cartesian plane (x,y). SRID values of 0 to 232-1 are valid. SRID values
outside of this range will generate an error.
The maximum size of a GEOMETRY object is 10 MB. If you pass a WKT to ST_GeomFromText
and the result is a spatial object whose size is greater than 10 MB, ST_GeomFromText returns an
error.
The Open Geospatial Consortium (OGC) defines the format of a WKT representation. See section 7
in the Simple Feature Access Part 1 - Common Architecture specification.

Behavior Type
Immutable

Syntax
ST_GeomFromText(wkt [, srid] [USING PARAMETERS ignore_errors={'y'|'n'} ])

Arguments
wkt

Well-known text (WKT) string of a GEOMETRY object, type LONG VARCHAR.

srid

(Optional when not performing operations) Spatial reference system identifier


(SRID) of the GEOMETRY object, type INTEGER.
The SRID is stored in the GEOMETRY object, but does not influence the results
of spatial computations.

ignore_errors

(Optional) ST_GeomFromText returns the following, based on parameters


supplied:
l

NULLIf wkt is invalid and ignore_errors='y'.

ErrorIf wkt is invalid and ignore_errors='n' or is unspecified.

Returns
GEOMETRY

Supported Data Types


Data Type

GEOMETRY

HP Vertica Analytic Database (7.1.x)

Page 73 of 181

Place
HP Vertica Place Functions: An Overview

Point

Yes

Multipoint

Yes

Linestring

Yes

Multilinestring

Yes

Polygon

Yes

Multipolygon

Yes

GeometryCollection No

Example
The following example shows how to use ST_GeomFromText.
Convert WKT into a GEOMETRY object:
=> SELECT ST_Area(ST_GeomFromText('POLYGON((1 1,2 3,3 5,0 5,1 -2,0 0,1 1))'));
ST_Area
--------6
(1 row)

ST_GeomFromWKB
Converts the well-known binary (WKB) value to its corresponding GEOMETRY object. Use this
function to convert a WKB into the format expected by many of the HP Vertica Place functions.
A GEOMETRY object is a spatial object with coordinates (x,y) defined in the Cartesian plane.
The maximum size of a GEOMETRY object is 10 MB. If you pass a WKB to ST_GeomFromWKB and
the result is a spatial object whose size is greater than 10 MB, ST_GeomFromWKB returns an error.
The Open Geospatial Consortium (OGC) defines the format of a WKB representation in section 8 in
the Simple Feature Access Part 1 - Common Architecture specification.

Behavior Type
Immutable

Syntax
ST_GeomFromWKB(wkb[, srid]
[USING PARAMETERS ignore_errors={'y'|'n'} ])

HP Vertica Analytic Database (7.1.x)

Page 74 of 181

Place
HP Vertica Place Functions: An Overview

Arguments
wkb

Well-known binary (WKB) value of a GEOMETRY object, type LONG


VARBINARY

srid

(Optional) Spatial reference system identifier (SRID) of the GEOMETRY object,


type INTEGER.
The SRID is stored in the GEOMETRY object, but does not influence the results
of spatial computations.

ignore_errors

(Optional) ST_GeomFromWKB returns the following, based on the parameters


supplied:
l

NULLIf wkb is invalid and ignore_errors='y'.

ErrorIf wkb is invalid and ignore_errors='n' or is unspecified.

Returns
GEOMETRY

Supported Data Types


Data Type

GEOMETRY

Point

Yes

Multipoint

Yes

Linestring

Yes

Multilinestring

Yes

Polygon

Yes

Multipolygon

Yes

GeometryCollection Yes

Example
The following example shows how to use ST_GeomFromWKB.
Convert GEOMETRY into WKT:

HP Vertica Analytic Database (7.1.x)

Page 75 of 181

Place
HP Vertica Place Functions: An Overview

=> CREATE TABLE t(g GEOMETRY);


CREATE TABLE
=> INSERT INTO t VALUES(
ST_GeomFromWKB(X'0103000000010000000400000000000000000000000000000000000000000000000000f
03f0000000000000000f64ae1c7022db544000000000000f03f00000000000000000000000000000000'));
OUTPUT
-------1
(1 row)
=> SELECT ST_AsText(g) from t;
ST_AsText
-----------------------------------POLYGON ((0 0, 1 0, 1e+23 1, 0 0))
(1 row)

ST_Intersection
Calculates the set of points shared by two GEOMETRY objects.

Behavior Type
Immutable

Syntax
ST_Intersection(g1, g2 )

Arguments
g1

Spatial object, type GEOMETRY

g2

Spatial object, type GEOMETRY

Returns
GEOMETRY

Supported Data Types


Data Type

GEOMETRY

Point

Yes

Multipoint

Yes

HP Vertica Analytic Database (7.1.x)

Page 76 of 181

Place
HP Vertica Place Functions: An Overview

Linestring

Yes

Multilinestring

Yes

Polygon

Yes

Multipolygon

Yes

GeometryCollection Yes

Examples
The following examples show how to use ST_Intersection.
Two polygons intersect at a single point:

=> SELECT ST_AsText(ST_Intersection(ST_GeomFromText('POLYGON((0 2,1 1,0 -1,


0 2))'),ST_GeomFromText('POLYGON((-1 2,0 0,-2 0,-1 2))')));
ST_AsText
----------------POINT(0 0)
(1 row)

Two polygons:

HP Vertica Analytic Database (7.1.x)

Page 77 of 181

Place
HP Vertica Place Functions: An Overview

=> SELECT ST_AsText(ST_Intersection(ST_GeomFromText('POLYGON((1 2,1 5,4 5,


4 2,1 2))'), ST_GeomFromText('POLYGON((3 1,3 3,5 3,5 1,3 1))')));
ST_AsText
-----------------POLYGON ((4 3, 4 2, 3 2, 3 3, 4 3))
(1 row)

Two non-intersecting linestrings:

=> SELECT ST_AsText(ST_Intersection(ST_GeomFromText('LINESTRING(1 1,1 3,3 3)'),


ST_GeomFromText('LINESTRING(1 5,1 7,-1 7)')));
ST_AsText
-------------------------GEOMETRYCOLLECTION EMPTY
(1 row)

HP Vertica Analytic Database (7.1.x)

Page 78 of 181

Place
HP Vertica Place Functions: An Overview

ST_Intersects
Determines if two GEOMETRY objects intersect or touch at a single point. If ST_Disjoint returns
TRUE, ST_Intersects returns FALSE for the same GEOMETRY objects.

Behavior Type
Immutable

Syntax
ST_Intersects(g1, g2 )

Arguments
g1

Spatial object, type GEOMETRY

g2

Spatial object, type GEOMETRY

Returns
BOOLEAN

Supported Data Types


Data Type

GEOMETRY

Point

Yes

Multipoint

Yes

Linestring

Yes

Multilinestring

Yes

Polygon

Yes

Multipolygon

Yes

GeometryCollection Yes

Examples
The following examples show how to use ST_Intersects.

HP Vertica Analytic Database (7.1.x)

Page 79 of 181

Place
HP Vertica Place Functions: An Overview

Two polygons do not intersect or touch:

=> SELECT ST_Intersects (ST_GeomFromText('POLYGON((-1 2,0 3,0 1,-1 2))'),


ST_GeomFromText('POLYGON((1 0,1 1,2 2,1 0))'));
ST_Intersects
-------------f
(1 row)

Two polygons touch at a single point:

=> SELECT ST_Intersects (ST_GeomFromText('POLYGON((-1 2,0 3,0 1,-1 2))'),


ST_GeomFromText('POLYGON((1 0,1 1,0 1,1 0))'));
ST_Intersects
-------------t

HP Vertica Analytic Database (7.1.x)

Page 80 of 181

Place
HP Vertica Place Functions: An Overview

(1 row)

Two polygons intersect:

=> SELECT ST_Intersects (ST_GeomFromText('POLYGON((-1 2, 0 3, 0 1, -1 2))'),


ST_GeomFromText('POLYGON((0 2, -1 3, -2 0, 0 2))'));
ST_Intersects
-------------t
(1 row)

See Also
l

ST_Disjoint

ST_IsEmpty
Determines if a spatial object represents the empty set. An empty object has no dimension.

Behavior Type
Immutable

Syntax
ST_IsEmpty(g )

HP Vertica Analytic Database (7.1.x)

Page 81 of 181

Place
HP Vertica Place Functions: An Overview

Arguments
g

Spatial object, type GEOMETRY or GEOGRAPHY

Returns
BOOLEAN

Supported Data Types


Data Type

GEOMETRY GEOGRAPHY

Point

Yes

Yes

Multipoint

Yes

Yes

Linestring

Yes

Yes

Multilinestring

Yes

Yes

Polygon

Yes

Yes

Multipolygon

Yes

Yes

GeometryCollection Yes

No

Example
The following example shows how to use ST_IsEmpty.
An empty polygon:
=> SELECT ST_IsEmpty(ST_GeomFromText('GeometryCollection EMPTY'));
ST_IsEmpty
-----------t
(1 row)

ST_IsSimple
Determines if a spatial object does not intersect itself or touch its own boundary at any point.

HP Vertica Analytic Database (7.1.x)

Page 82 of 181

Place
HP Vertica Place Functions: An Overview

Behavior Type
Immutable

Syntax
ST_IsSimple(g )

Arguments
g

Spatial object, type GEOMETRY or GEOGRAPHY

Returns
BOOLEAN

Supported Data Types


Data Type

GEOMETRY GEOGRAPHY

Point

Yes

Yes

Multipoint

Yes

No

Linestring

Yes

Yes

Multilinestring

Yes

No

Polygon

Yes

Yes

Multipolygon

Yes

No

GeometryCollection No

No

Examples
The following examples show how to use ST_IsSimple.
Polygon does not intersect itself:

HP Vertica Analytic Database (7.1.x)

Page 83 of 181

Place
HP Vertica Place Functions: An Overview

=> SELECT ST_IsSimple(ST_GeomFromText('POLYGON((-1 2,0 3,1 2,1 -2,-1 2))'));


ST_IsSimple
-------------t
(1 row)

Linestring intersects itself.:

=> SELECT ST_IsSimple(ST_GeographyFromText('LINESTRING(10 10,25 25,26 34.5,


10 30,10 20,20 10)'));
St_IsSimple
------------f
(1 row)

Linestring touches its interior at one or more locations:

HP Vertica Analytic Database (7.1.x)

Page 84 of 181

Place
HP Vertica Place Functions: An Overview

=> SELECT ST_IsSimple(ST_GeomFromText('LINESTRING(0 0,0 1,1 0,2 1,2 0,0 0)'));


ST_IsSimple
------------f
(1 row)

ST_IsValid
Determines if a spatial object is well formed or valid. If the object is valid, ST_IsValid returns
TRUE; otherwise, it returns FALSE. Use STV_IsValidReason to identify the location of the
invalidity.
Spatial validity applies only to polygons and multipolygons. A polygon or multipolygon is valid if all
of the following are true:
l

The polygon is closed; its start point is the same as its end point.

Its boundary is a set of linestrings.

The boundary does not touch or cross itself.

Any polygons in the interior do not touch the boundary of the exterior polygon except at a vertex.

The Open Geospatial Consortium (OGC) defines the validity of a polygon in section 6.1.11.1 of the
Simple Feature Access Part 1 - Common Architecture specification.
If you are not sure if a polygon is valid, run ST_IsValid first. If you pass an invalid spatial object to
an HP Vertica Place function, the function fails or returns incorrect results.

Behavior Type
Immutable

HP Vertica Analytic Database (7.1.x)

Page 85 of 181

Place
HP Vertica Place Functions: An Overview

Syntax
ST_IsValid(g )

Arguments
g

Polygon or multipolygon to test for validity, value of type GEOMETRY

Returns
BOOLEAN

Supported Data Types


Data Type

GEOMETRY

Point

No

Multipoint

No

Linestring

No

Multilinestring

No

Polygon

Yes

Multipolygon

Yes

GeometryCollection No

Examples
The following examples show how to use ST_IsValid.
Valid polygon:

HP Vertica Analytic Database (7.1.x)

Page 86 of 181

Place
HP Vertica Place Functions: An Overview

=> SELECT ST_IsValid(ST_GeomFromText('POLYGON((1 1,1 3,3 3,3 1,1 1))'));


ST_IsValid
-----------t
(1 row)

Invalid polygon:

=> SELECT ST_IsValid(ST_GeomFromText('POLYGON((1 3,3 2,1 1,3 0,1 0,1 3))'));


ST_IsValid
-----------f
(1 row)

Invalid polygon:

HP Vertica Analytic Database (7.1.x)

Page 87 of 181

Place
HP Vertica Place Functions: An Overview

=> SELECT ST_IsValid(ST_GeomFromText('POLYGON((0 0,2 2,0 2,2 0,0 0))'));


ST_IsValid
-----------f
(1 row)

Invalid multipolygon:.

=> SELECT ST_IsValid(ST_GeomFromText('MULTIPOLYGON(((0 0, 0 1, 1 1, 0 0)),


((0.5 0.5, 0.7 0.5, 0.7 0.7, 0.5 0.7, 0.5 0.5)))'));
ST_IsValid
-----------f
(1 row)

Valid polygon with hole:

HP Vertica Analytic Database (7.1.x)

Page 88 of 181

Place
HP Vertica Place Functions: An Overview

=> SELECT ST_IsValid(ST_GeomFromText('POLYGON((1 1,3 3,6 -1,0.5 -1,1 1),


(1 1,3 1,2 0,1 1))'));
ST_IsValid
-----------t
(1 row)

Invalid polygon with hole:

=> SELECT ST_IsValid(ST_GeomFromText('POLYGON((1 1,3 3,6 -1,0.5 -1,1 1),


(1 1,4.5 1,2 0,1 1))'));
ST_IsValid
-----------f
(1 row)

ST_Length
Calculates the length of a spatial object. For GEOMETRY objects, the length is measured in
Cartesian coordinate units. For GEOGRAPHY objects, the length is measured in meters.
Calculates the length as follows:

HP Vertica Analytic Database (7.1.x)

Page 89 of 181

Place
HP Vertica Place Functions: An Overview

The length of a point or multipoint object is 0.

The length of a linestring is the sum of the lengths of each line segment The length of a line
segment is the distance from the start point to the end point.
The length of a polygon is the sum of the lengths of the exterior boundary and any interior

boundaries.
The length of a multilinestring, multipolygon, or geometrycollection is the sum of the lengths of

all the objects it contains.

Note: ST_Length does not calculate the length of WKTs or WKBs. To calculate the lengths of
those objects, use the HP Vertica LENGTH SQL function with ST_AsBinary or ST_AsText.

Behavior Type
Immutable

Syntax
ST_Length(g )

Arguments
g

Spatial object for which you want to calculate the length, type GEOMETRY or GEOGRAPHY

Returns
FLOAT

Supported Data Types


Data Type

GEOMETRY GEOGRAPHY

Point

Yes

Yes

Multipoint

Yes

Yes

Linestring

Yes

Yes

Multilinestring

Yes

Yes

HP Vertica Analytic Database (7.1.x)

Page 90 of 181

Place
HP Vertica Place Functions: An Overview

Polygon

Yes

Yes

Multipolygon

Yes

Yes

GeometryCollection Yes

No

Examples
The following examples show how to use ST_Length.
Returns length in Cartesian coordinate units:
=> SELECT ST_Length(ST_GeomFromText('LINESTRING(-1 -1,2 2,4 5,6 7)'));
ST_Length
-----------------10.6766190873295
(1 row)

Returns length in meters:


=> SELECT ST_Length(ST_GeographyFromText('LINESTRING(-56.12 38.26,-57.51 39.78,
-56.37 45.24)'));
ST_Length
-----------------821580.025733461
(1 row)

ST_NumPoints
Calculates the number of vertices on a linestring.

Behavior Type
Immutable

Syntax
ST_NumPoints(g )

Arguments
g

Linestring for which you want to count the vertices, type GEOMETRY or GEOGRAPHY

HP Vertica Analytic Database (7.1.x)

Page 91 of 181

Place
HP Vertica Place Functions: An Overview

Returns
INTEGER

Supported Data Types


Data Type

GEOMETRY GEOGRAPHY

Point

No

No

Multipoint

No

No

Linestring

Yes

Yes

Multilinestring

No

No

Polygon

No

No

Multipolygon

No

No

GeometryCollection No

No

Examples
The following examples show how to use ST_NumPoints.
Returns the number of vertices in a linestring:
=> SELECT ST_NumPoints(ST_GeomFromText('LINESTRING(1.33 1.56,2.31 3.4,2.78 5.82,
3.76 3.9,4.11 3.27,5.85 4.34,6.9 4.231,7.61 5.77)'));
ST_NumPoints
-------------8
(1 row)

Use ST_Boundary and ST_NumPoints to return the number of vertices of a polygon:


=> SELECT ST_NumPoints(ST_Boundary(ST_GeomFromText('POLYGON((1 2,1 4,
2 5,3 6,4 6,5 5,4 4,3 3,1 2))')));
ST_NumPoints
-------------9
(1 row)

HP Vertica Analytic Database (7.1.x)

Page 92 of 181

Place
HP Vertica Place Functions: An Overview

ST_Overlaps
Determines if a GEOMETRY object shares space with another GEOMETRY object, but is not
completely contained within that object. They must overlap at their interiors. If two objects touch at
a single point or intersect only along a boundary, they do not overlap. Both parameters must have
the same dimension; otherwise, ST_Overlaps returns FALSE.

Behavior Type
Immutable

Syntax
ST_Overlaps (g1, g2 )

Arguments
g1

Spatial object, type GEOMETRY

g2

Spatial object, type GEOMETRY

Returns
BOOLEAN

Supported Data Types


Data Type

GEOMETRY

Point

Yes

Multipoint

Yes

Linestring

Yes

Multilinestring

Yes

Polygon

Yes

Multipolygon

Yes

GeometryCollection Yes

HP Vertica Analytic Database (7.1.x)

Page 93 of 181

Place
HP Vertica Place Functions: An Overview

Examples
The following examples show how to use ST_Overlaps.
Polygon_1 overlaps but does not completely contain Polygon_2:

=> SELECT ST_Overlaps(ST_GeomFromText('POLYGON((0 0, 0 1, 1 1, 0 0))'),


ST_GeomFromText('POLYGON((0.5 0.5, 0.7 0.5, 0.7 0.7, 0.5 0.7, 0.5 0.5))'));
ST_Overlaps
------------t
(1 row)

Two objects with different dimensions:


=> SELECT ST_Overlaps(ST_GeomFromText('LINESTRING(2 2,4 4)'),
ST_GeomFromText('POINT(3 3)'));
ST_Overlaps
------------f
(1 row)

ST_PointN
Finds the nth point of a linestring. If you pass a negative number, zero, or a number larger than the
total number of points on the linestring, ST_PointN returns NULL

Behavior Type
Immutable

Syntax
ST_PointN(g, n )

HP Vertica Analytic Database (7.1.x)

Page 94 of 181

Place
HP Vertica Place Functions: An Overview

Arguments
g

Linestring to search, type GEOMETRY or GEOGRAPHY

Point in the linestring to be returned, type INTEGER

Returns
GEOMETRY or GEOGRAPHY (POINT only)

Supported Data Types


Data Type

GEOMETRY GEOGRAPHY

Point

No

No

Multipoint

No

No

Linestring

Yes

Yes

Multilinestring

No

No

Polygon

No

No

Multipolygon

No

No

GeometryCollection No

No

Examples
The following examples show how to use STV_Create_Index.
Returns the fifth point:
=> SELECT ST_AsText(ST_PointN(ST_GeomFromText('
LINESTRING(1 1,1 3,2 5,3 3,4 3,5 4,6 4,7 5)'),5));
ST_AsText
-----------POINT(4 3)
(1 row)

Returns the second point:


=> SELECT ST_AsText(ST_PointN(ST_GeographyFromText('

HP Vertica Analytic Database (7.1.x)

Page 95 of 181

Place
HP Vertica Place Functions: An Overview

LINESTRING(23.41 24.93,34.2 32.98,40.7 41.19)'),2));


ST_AsText
------------------POINT(34.2 32.98)
(1 row)

ST_Relate
Determines if a given GEOMETRY object is spatially related to another GEOMETRY object, based
on the specified DE-9IM pattern matrix string.
The DE-9IM standard identifies how two objects are spatially related to each other.

Behavior Type
Immutable

Syntax
ST_Relate(g1, g2, matrix )

Arguments
g1

Spatial object, type GEOMETRY

g2

Spatial object, type GEOMETRY

matrix

DE-9IM pattern matrix string, type CHAR(9). This string represents a 3 x 3 matrix of
restrictions on the dimensions of the respective intersections of the interior, boundary,
and exterior of the two geometries. Must contain exactly 9 of the following characters:
l

HP Vertica Analytic Database (7.1.x)

Page 96 of 181

Place
HP Vertica Place Functions: An Overview

Returns
BOOLEAN

Supported Data Types


Data Type

GEOMETRY

Point

Yes

Multipoint

Yes

Linestring

Yes

Multilinestring

Yes

Polygon

Yes

Multipolygon

Yes

GeometryCollection Yes

Examples
The following examples show how to use ST_Relate.
The DE-9IM pattern for "equals" is 'T*F**FFF2':
=> SELECT ST_Relate(ST_GeomFromText('LINESTRING(0 1,2 2)'),
ST_GeomFromText('LINESTRING(2 2,0 1)'), 'T*F**FFF2');
ST_Relate
-------------t
(1 row)

The DE-9IM pattern for "overlaps" is 'T*T***T**':


=> SELECT ST_Relate(ST_GeomFromText('POLYGON((-1 -1,0 1,2 2,-1 -1))'),
ST_GeomFromText('POLYGON((0 1,1 -1,1 1,0 1))'), 'T*T***T**');
ST_Relate
----------t
(1 row)

ST_SRID
Identifies the spatial reference system identifier (SRID) stored with a spatial object.

HP Vertica Analytic Database (7.1.x)

Page 97 of 181

Place
HP Vertica Place Functions: An Overview

The SRID of a GEOMETRY object can only be determined when passing an SRID to either ST_
GeomFromText or ST_GeomFromWKB. ST_SRID returns this stored value. SRID values of 0 to
232-1 are valid.

Behavior Type
Immutable

Syntax
ST_SRID(g )

Arguments
g

Spatial object for which you want the SRID, type GEOMETRY or GEOGRAPHY

Returns
INTEGER

Supported Data Types


Data Type

GEOMETRY GEOGRAPHY

Point

Yes

Yes

Multipoint

Yes

Yes

Linestring

Yes

Yes

Multilinestring

Yes

Yes

Polygon

Yes

Yes

Multipolygon

Yes

Yes

GeometryCollection Yes

No

Examples
The following examples show how to use ST_SRID.
The default SRID of a GEOMETRY object is 0:

HP Vertica Analytic Database (7.1.x)

Page 98 of 181

Place
HP Vertica Place Functions: An Overview

=> SELECT ST_SRID(ST_GeomFromText(


'POLYGON((-1 -1,2 2,0 1,-1 -1))'));
ST_SRID
--------0
(1 row)

The default SRID of a GEOGRAPHY object is 4326:


=> SELECT ST_SRID(ST_GeographyFromText(
'POLYGON((22 35,24 35,26 32,22 35))'));
ST_SRID
--------4326
(1 row)

ST_SymDifference
Calculates all the points in two GEOMETRY objects except for the points they have in common,
but including the boundaries of both objects.
This result is called the symmetric difference and is represented mathematically as: Closure (g1
g2) Closure (g2 g1)

Behavior Type
Immutable

Syntax
ST_SymDifference(g1, g2 )

Arguments
g1

Spatial object, type GEOMETRY

g2

Spatial object, type GEOMETRY

Returns
GEOMETRY

HP Vertica Analytic Database (7.1.x)

Page 99 of 181

Place
HP Vertica Place Functions: An Overview

Supported Data Types


Data Type

GEOMETRY

Point

Yes

Multipoint

Yes

Linestring

Yes

Multilinestring

Yes

Polygon

Yes

Multipolygon

Yes

GeometryCollection Yes

Examples
The following examples show how to use ST_SymDifference.
Returns the two linestrings:

=> SELECT ST_AsText(ST_SymDifference(ST_GeomFromText('LINESTRING(30 40,


30 55)'),ST_GeomFromText('LINESTRING(30 32.5,30 47.5)')));
ST_AsText
-----------------

HP Vertica Analytic Database (7.1.x)

Page 100 of 181

Place
HP Vertica Place Functions: An Overview

MULTILINESTRING ((30 47.5, 30 55),(30 32.5,30 40))


(1 row)

Returns four squares:

=> SELECT ST_AsText(ST_SymDifference(ST_GeomFromText('POLYGON((2 1,2 4,3 4,


3 1,2 1))'),ST_GeomFromText('POLYGON((1 2,1 3,4 3,4 2,1 2))')));
ST_AsText
------------------------------------------------------------------------MULTIPOLYGON (((2 1, 2 2, 3 2, 3 1, 2 1)), ((1 2, 1 3, 2 3, 2 2, 1 2)),
((2 3, 2 4, 3 4, 3 3, 2 3)), ((3 2, 3 3, 4 3, 4 2, 3 2)))
(1 row)

ST_Touches
Determines if two GEOMETRY objects touch at a single point or along a boundary, but do not have
interiors that intersect.

Behavior Type
Immutable

Syntax
ST_Touches(g1, g2 )

Arguments
g1

Spatial object, value of type GEOMETRY

g2

Spatial object, value of type GEOMETRY

HP Vertica Analytic Database (7.1.x)

Page 101 of 181

Place
HP Vertica Place Functions: An Overview

Returns
BOOLEAN

Supported Data Types


Data Type

GEOMETRY

Point

Yes

Multipoint

Yes

Linestring

Yes

Multilinestring

Yes

Polygon

Yes

Multipolygon

Yes

GeometryCollection Yes

Examples
The following examples show how to use ST_Touches.
Two polygons touch at a single point:
=> SELECT ST_Touches(ST_GeomFromText('POLYGON((-1 2,0 3,0 1,-1 2))'),
ST_GeomFromText('POLYGON((1 3,0 3,1 2,1 3))'));
ST_Touches
-----------t
(1 row)

Two polygons touch only along part of the boundary:


=> SELECT ST_Touches(ST_GeomFromText('POLYGON((-1 2,0 3,0 1,-1 2))'),
ST_GeomFromText('POLYGON((1 2,0 3,0 1,1 2))'));
ST_Touches
-----------t
(1 row)

Two polygons do not touch at any point:

HP Vertica Analytic Database (7.1.x)

Page 102 of 181

Place
HP Vertica Place Functions: An Overview

=> SELECT ST_Touches(ST_GeomFromText('POLYGON((-1 2,0 3,0 1,-1 2))'),


ST_GeomFromText('POLYGON((0 2,-1 3,-2 0,0 2))'));
ST_Touches
-----------f
(1 row)

ST_Union
Calculates the union of all points in two spatial objects.
This result is represented mathematically by: g1 g2

Behavior Type
Immutable

Syntax
ST_Union(g1, g2 )

Arguments
g1

Spatial object, type GEOMETRY

g2

Spatial object, type GEOMETRY

Returns
GEOMETRY

Supported Data Types


Data Type

GEOMETRY

Point

Yes

Multipoint

Yes

Linestring

Yes

Multilinestring

Yes

Polygon

Yes

HP Vertica Analytic Database (7.1.x)

Page 103 of 181

Place
HP Vertica Place Functions: An Overview

Multipolygon

Yes

GeometryCollection Yes

Example
The following example shows how to use ST_Union.
Returns a polygon that represents all the points contained in these two polygons:

=> SELECT ST_AsText(ST_Union(ST_GeomFromText('POLYGON((0 2,1 1,0 -1,-1 1,0 2))'),


ST_GeomFromText('POLYGON((-1 2, 0 0, -2 0, -1 2))')));
ST_AsText
-----------------------------------------------------------------------------POLYGON ((0 2, 1 1, 0 -1, -0.5 0, -2 0, -1 2, -0.666666666667 1.33333333333, 0 2))
(1 row)

ST_Within
If spatial object g1 is completely inside of spatial object g2, then ST_Within returns true. Both
parameters must be the same spatial data type. Either specify two GEOMETRYobjects or two
GEOGRAPHY objects.
If an object such as a point or linestring only exists along a polygon's boundary, then ST_Within
returns false. The interior of a linestring is all the points along the linestring except the start and end
points.
ST_Within(g1,g2) is functionally equivalent to ST_Contains(g2,g1).

HP Vertica Analytic Database (7.1.x)

Page 104 of 181

Place
HP Vertica Place Functions: An Overview

Behavior Type
Immutable

Syntax
ST_Within(g1, g2 )

Arguments
g1

Spatial object, type GEOMETRY or GEOGRAPHY

g2

Spatial object, type GEOMETRY or GEOGRAPHY

Returns
BOOLEAN

Supported Data Types


Data Type

GEOMETRY GEOGRAPHY

Point

Yes

Yes

Multipoint

Yes

No

Linestring

Yes

Yes

Multilinestring

Yes

No

Polygon

Yes

Yes

Multipolygon

Yes

Yes

GeometryCollection Yes

No

Compatible GEOGRAPHY pairs:


Data Type

GEOGRAPHY

Point-Point

Yes

Linestring-Point

Yes

HP Vertica Analytic Database (7.1.x)

Page 105 of 181

Place
HP Vertica Place Functions: An Overview

Polygon-Point

Yes

Multipolygon-Point Yes

Examples
The following examples show how to use ST_Within.
The first polygon is completely contained within the second polygon:
=> SELECT ST_Within(ST_GeomFromText('POLYGON((0 2,1 1,0 -1,0 2))'),
ST_GeomFromText('POLYGON((-1 3,2 1,0 -3,-1 3))'));
ST_Within
----------t
(1 row)

The point is on a vertex of the polygon, but not in its interior:


=> SELECT ST_Within (ST_GeographyFromText('POINT(30 25)'),
ST_GeographyFromText('POLYGON((25 25,25 35,32.2 35,30 25,25 25))'));
ST_Within
----------f
(1 row)

Two polygons are spatially equivalent:


=> SELECT ST_Within (ST_GeomFromText('POLYGON((-1 2, 0 3, 0 1, -1 2))'),
ST_GeomFromText('POLYGON((0 3, -1 2, 0 1, 0 3))'));
ST_Within
----------t
(1 row)

See Also
l

ST_Contains

ST_Overlaps

ST_X
Determines the x- coordinate for a GEOMETRY point or the longitude value for a GEOGRAPHY
point.

HP Vertica Analytic Database (7.1.x)

Page 106 of 181

Place
HP Vertica Place Functions: An Overview

Behavior Type
Immutable

Syntax
ST_X(g )

Arguments
g

Point of type GEOMETRY or GEOGRAPHY

Returns
FLOAT

Supported Data Types


Data Type

GEOMETRY GEOGRAPHY

Point

Yes

Yes

Multipoint

No

No

Linestring

No

No

Multilinestring

No

No

Polygon

No

No

Multipolygon

No

No

GeometryCollection No

No

Examples
The following examples show how to use ST_X.
Returns the x-coordinate:
=> SELECT ST_X(ST_GeomFromText('POINT(3.4 1.25)'));
ST_X
----3.4

HP Vertica Analytic Database (7.1.x)

Page 107 of 181

Place
HP Vertica Place Functions: An Overview

(1 row)

Returns the longitude value:


=> SELECT ST_X(ST_GeographyFromText('POINT(25.34 45.67)'));
ST_X
------25.34
(1 row)

ST_XMax
Returns the maximum x-coordinate of the minimum bounding rectangle of the GEOMETRYor
GEOGRAPHY object.
For GEOGRAPHY types, HP Vertica Place computes maximum coordinates by calculating the
maximum longitude of the great circle arc from (MAX(longitude), ST_YMin(GEOGRAPHY)) to
(MAX(longitude), ST_YMax(GEOGRAPHY)). In this case, MAX(longitude) is the maximum
longitude value of the geography object.
If either latitude or longitude is out of range, ST_XMax returns the maximum plain value of the
geography object.

Behavior Type
Immutable

Syntax
ST_XMax(g )

Arguments
g

Spatial object for which you want to find the maximum x-coordinate, type GEOMETRY or
GEOGRAPHY.

Returns
GEOMETRY or GEOGRAPHY

HP Vertica Analytic Database (7.1.x)

Page 108 of 181

Place
HP Vertica Place Functions: An Overview

Supported Data Types


Data Type

GEOMETRY GEOGRAPHY

Point

Yes

Yes

Multipoint

Yes

Yes

Linestring

Yes

Yes

Multilinestring

Yes

Yes

Polygon

Yes

Yes

Multipolygon

Yes

Yes

GeometryCollection Yes

No

Examples
The following examples show how to use ST_XMax.
Returns the maximum x-coordinate within a rectangle:
=> SELECT ST_XMax(ST_GeomFromText('POLYGON((0 1,0 2,1 2,1 1,0 1))'));
ST_XMax
----------1
(1 row)

Returns the maximum longitude value within a rectangle:


=> SELECT ST_XMax(ST_GeographyFromText(
'POLYGON((-71.50 42.35, -71.00 42.35, -71.00 42.38, -71.50 42.38, -71.50 42.35))'));
ST_XMax
---------71
(1 row)

ST_XMin
Returns the minimum x-coordinate of the minimum bounding rectangle of the GEOMETRYor
GEOGRAPHY object.
For GEOGRAPHY types, HP Vertica Place computes minimum coordinates by calculating the
minimum longitude of the great circle arc from (MIN(longitude), ST_YMin(GEOGRAPHY)) to (MIN

HP Vertica Analytic Database (7.1.x)

Page 109 of 181

Place
HP Vertica Place Functions: An Overview

(longitude), ST_YMax(GEOGRAPHY)). In this case, MIN(latitude) represents the minimum


longitude value of the geography object
If either latitude or longitude is out of range, ST_XMin returns the minimum plain value of the
geography object.

Behavior Type
Immutable

Syntax
ST_XMin(g )

Arguments
g

Spatial object for which you want to find the minimum x-coordinate, type GEOMETRY or
GEOGRAPHY.

Returns
GEOMETRY or GEOGRAPHY

Supported Data Types


Data Type

GEOMETRY GEOGRAPHY

Point

Yes

Yes

Multipoint

Yes

Yes

Linestring

Yes

Yes

Multilinestring

Yes

Yes

Polygon

Yes

Yes

Multipolygon

Yes

Yes

GeometryCollection Yes

No

Examples
The following examples show how to use ST_XMin.

HP Vertica Analytic Database (7.1.x)

Page 110 of 181

Place
HP Vertica Place Functions: An Overview

Returns the minimum x-coordinate within a rectangle:


=> SELECT ST_XMin(ST_GeomFromText('POLYGON((0 1,0 2,1 2,1 1,0 1))'));
ST_XMin
---------0
(1 row)

Returns the minimum longitude value within a rectangle:


=> SELECT ST_XMin(ST_GeographyFromText(
'POLYGON((-71.50 42.35, -71.00 42.35, -71.00 42.38, -71.50 42.38, -71.50 42.35))'));
ST_XMin
----------71.5
(1 row)

ST_Y
Determines the y-coordinate for a GEOMETRY point or the latitude value for a GEOGRAPHY
point.

Behavior Type
Immutable

Syntax
ST_Y(g )

Arguments
g

Point of type GEOMETRY or GEOGRAPHY

Returns
FLOAT

Supported Data Types


Data Type

GEOMETRY GEOGRAPHY

Point

Yes

HP Vertica Analytic Database (7.1.x)

Yes

Page 111 of 181

Place
HP Vertica Place Functions: An Overview

Multipoint

No

No

Linestring

No

No

Multilinestring

No

No

Polygon

No

No

Multipolygon

No

No

GeometryCollection No

No

Examples
The following examples show how to use ST_Y.
Returns the y-coordinate:
=> SELECT ST_Y(ST_GeomFromText('POINT(3 5.25)'));
ST_Y
-----5.25
(1 row)

Returns the latitude value:


=> SELECT ST_Y(ST_GeographyFromText('POINT(35.44 51.04)'));
ST_Y
------51.04
(1 row)

ST_YMax
Returns the maximum y-coordinate of the minimum bounding rectangle of the GEOMETRYor
GEOGRAPHY object.
For GEOGRAPHY types, HP Vertica Place computes maximum coordinates by calculating the
maximum latitude of the great circle arc from (ST_XMin(GEOGRAPHY), MAX(latitude)) to (ST_
XMax(GEOGRAPHY), MAX(latitude)). In this case, MAX(latitude) is the maximum latitude value of
the geography object.
If either latitude or longitude is out of range, ST_YMax returns the maximum plain value of the
geography object.

HP Vertica Analytic Database (7.1.x)

Page 112 of 181

Place
HP Vertica Place Functions: An Overview

Behavior Type
Immutable

Syntax
ST_YMax(g )

Arguments
g

Spatial object for which you want to find the maximum y-coordinate, type GEOMETRY or
GEOGRAPHY.

Returns
GEOMETRY or GEOGRAPHY

Supported Data Types


Data Type

GEOMETRY GEOGRAPHY

Point

Yes

Yes

Multipoint

Yes

Yes

Linestring

Yes

Yes

Multilinestring

Yes

Yes

Polygon

Yes

Yes

Multipolygon

Yes

Yes

GeometryCollection Yes

No

Examples
The following examples show how to use ST_YMax.
Returns the maximum y-coordinate within a rectangle:
=> SELECT ST_YMax(ST_GeomFromText('POLYGON((0 1,0 4,1 4,1 1,0 1))'));
ST_YMax

HP Vertica Analytic Database (7.1.x)

Page 113 of 181

Place
HP Vertica Place Functions: An Overview

----------4
(1 row)

Returns the maximum latitude value within a rectangle:


=> SELECT ST_YMax(ST_GeographyFromText(
'POLYGON((-71.50 42.35, -71.00 42.35, -71.00 42.38, -71.50 42.38, -71.50 42.35))'));
ST_YMax
-----------------42.3802715689979
(1 row)

ST_YMin
Returns the minimum y-coordinate of the minimum bounding rectangle of the GEOMETRYor
GEOGRAPHY object.
For GEOGRAPHY types, HP Vertica Place computes minimum coordinates by calculating the
minimum latitude of the great circle arc from (ST_XMin(GEOGRAPHY), MIN(latitude)) to (ST_
XMax(GEOGRAPHY), MIN(latitude)). In this case, MIN(latitude) represents the minimum latitude
value of the geography object.
If either latitude or longitude is out of range, ST_YMin returns the minimum plain value of the
geography object.

Behavior Type
Immutable

Syntax
ST_YMin(g )

Arguments
g

Spatial object for which you want to find the minimum y-coordinate, type GEOMETRY or
GEOGRAPHY.

Returns
GEOMETRY or GEOGRAPHY

HP Vertica Analytic Database (7.1.x)

Page 114 of 181

Place
HP Vertica Place Functions: An Overview

Supported Data Types


Data Type

GEOMETRY GEOGRAPHY

Point

Yes

Yes

Multipoint

Yes

Yes

Linestring

Yes

Yes

Multilinestring

Yes

Yes

Polygon

Yes

Yes

Multipolygon

Yes

Yes

GeometryCollection Yes

No

Examples
The following examples show how to use ST_YMin.
Returns the minimum y-coordinate within a rectangle:
=> SELECT ST_YMin(ST_GeomFromText('POLYGON((0 1,0 4,1 4,1 1,0 1))'));
ST_YMin
----------1
(1 row)

Returns the minimum latitude value within a rectangle:


=> SELECT ST_YMin(ST_GeographyFromText(
'POLYGON((-71.50 42.35, -71.00 42.35, -71.00 42.38, -71.50 42.38, -71.50 42.35))'));
ST_YMin
-----------------42.35
(1 row)

STV_Create_Index
Creates a spatial index on a set of polygons to speed up spatial intersection with a set of points.
A spatial index is created from an input polygon set, which can be the result of a query. Spatial
indexes are created in a global name space. HP Vertica uses a distributed plan whenever the input
table or projection is segmented across nodes of the cluster.

HP Vertica Analytic Database (7.1.x)

Page 115 of 181

Place
HP Vertica Place Functions: An Overview

The OVER() clause must be empty.

Behavior Type
Immutable
Note: Indexes are not connected to any specific table. Subsequent DML commands on the
underlying table or tables of the input polygon set do not modify the index.

Syntax
STV_Create_Index(gid, geom
USING PARAMETERS index='index_name'
[, overwrite={true | false } ]
[, max_mem_mb=maxmem_value]
[, skip_nonindexable_polygons={true | false } ] )
OVER()
[AS (polygons, srid, min_x, min_y, max_x, max_y, info) ]
FROM [table|subquery]

Arguments
gid

Name of an INTEGER column that uniquely identifies the polygon in the geom
parameter. The gid cannot be NULL.

geom

Name of a GEOMETRY column or expression that contains polygons and


multipolygons assumed to be in the two-dimensional Euclidean plane. Only
POLYGON and MULTIPOLYGON geometries are indexed. Other shape types are
excluded from the index and captured in the info field.

subquery

A SELECT statement that returns a polygon identifier column and polygon geometry
column.

table

Name of the database table that contains the geometry data.

Parameters
index = 'index_name'

Name of the index, type VARCHAR. The


maximum index name length is 128 bytes. The
slash, backslash, and tab characters are not
allowed in index names.

HP Vertica Analytic Database (7.1.x)

Page 116 of 181

Place
HP Vertica Place Functions: An Overview

overwrite = [true | false ]

(Optional) BOOLEAN that specifies whether to


overwrite the index if it exists. This parameter
cannot be NULL.
Default: false

max_mem_mb = maxmem_value

(Optional) A positive integer that assigns a limit


to the amount of memory in megabytes that
STV_Create_Index can allocate during index
construction. On a multi-node database this is
the memory limit per node. The default value is
256. Do not assign a value higher than the
amount of memory in the GENERALresource
pool. For more information about this pool, see
Using Queries to Monitor Resource Pool Size
and Usage .
Setting a value for max_mem_mb that is at or
near the maximum memory available on the
node can negatively affect your system's
performance. For example, it could cause other
queries to time out waiting for memory
resources during index construction.

skip_nonindexable_polygons = [true | false ]

(Optional) BOOLEAN
In rare cases, intricate polygons (for instance,
with too high resolution or anomalous spikes)
cannot be indexed. These polygons are
considered non-indexable. When set to
FALSE, non-indexable polygons cause the
index creation to fail. When set to TRUE, index
creation can succeed by excluding nonindexable polygons from the index and logging
their identifiers in the HP Vertica log file
UDxLogs/UDxFencedProcesses.log located
in the catalog directory.
Default: FALSE

HP Vertica Analytic Database (7.1.x)

Page 117 of 181

Place
HP Vertica Place Functions: An Overview

Returns
polygons

Number of polygons indexed.

SRID

Spatial reference system identifier.

min_x, min_y, max_x, max_y

Coordinates of the minimum bounding rectangle (MBR) of the


indexed geometries. (min_x, min_y) are the south-west
coordinates, and (max_x, max_y) are the north-east coordinates.

info

Lists the number of excluded geometries as well as their type that


were excluded from the index.

Supported Data Types


Data Type

GEOMETRY

Point

No

Multipoint

No

Linestring

No

Multilinestring

No

Polygon

Yes

Multipolygon

Yes

GeometryCollection No

Privileges
Any user with access to the STV_*_Index functions can describe, rename, or drop indexes created
by any other user.

Recommendations
l

Segment large polygon tables across multiple nodes. Table segmentation causes index creation
to run in parallel, leveraging the Massively Parallel Processing (MPP) architecture in HP Vertica.
This significantly reduces execution time on large tables.

HP Vertica Analytic Database (7.1.x)

Page 118 of 181

Place
HP Vertica Place Functions: An Overview

HP Vertica recommends that you segment the table from which you are building the index when
the total number of polygons is large.
l

STV_Create_Index can consume large amounts of processing time and memory.


HP Vertica recommends that when indexing new data for the first time, you monitor memory
usage to be sure it stays within safe limits. Memory usage depends on number of polygons,
number of vertices, and the amount of overlap among polygons.

STV_Create_Index tries to allocate memory before it starts creating the index. If it cannot
allocate enough memory, the function fails. If not enough memory is available, try the following:
n

Create the index at a time of less load on the system.

Avoid concurrent index creation.

Try segmenting the input table across the nodes of the cluster.

Limitations
l

The backslash or tab characters are not allowed in index names.


The following geometries are automatically excluded from the index:
n

Non-polygons

Geometries with NULL identifiers

NULL (multi) polygon

EMPTY (multi) polygon

Invalid (multi) polygon

Usage Tips
l

To cancel an STV_Create_Index run, enter Ctrl+C.

If there are no valid polygons in the geom column, STV_Create_Index reports an error in
vertica.log and stops index creation.

If index creation uses a large amount of memory, consider segmenting your data to utilize
parallel index creation.

HP Vertica Analytic Database (7.1.x)

Page 119 of 181

Place
HP Vertica Place Functions: An Overview

Examples
The following examples show how to use STV_Create_Index.
Create an index with a single literal argument:
=> SELECT STV_Create_Index(1, ST_GeomFromText('POLYGON((0 0,0 15.2,3.9 15.2,3.9 0,0 0))')
USING PARAMETERS index='my_polygon') OVER();
polygons | SRID | min_x | min_y | max_x | max_y | info
----------+------+-------+-------+-------+-------+-----1 |
0 |
0 |
0 |
3.9 | 15.2 |
(1 row)

Create an index from a table:


=> CREATE TABLE pols (gid INT, geom GEOMETRY(1000));
CREATETABLE
=> COPY pols(gid, gx filler LONG VARCHAR, geom AS ST_GeomFromText(gx)) FROM stdin
delimiter '|';
Enter data to be copied followed by a newline.
End with a backslash and a period on a line by itself.
>> 1|POLYGON((-31 74,8 70,8 50,-36 53,-31 74))
>> 2|POLYGON((-38 50,4 13,11 45,0 65,-38 50))
>> 3|POLYGON((10 20,15 60,20 45,46 15,10 20))
>> 4|POLYGON((5 20,9 30,20 45,36 35,5 20))
>> 5|POLYGON((12 23,9 30,20 45,36 35,37 67,45 80,50 20,12 23))
>> \.
=> SELECT STV_Create_Index(gid, geom USING PARAMETERS index='my_polygons_1',
overwrite=true,
max_mem_mb=256) OVER() FROM pols;
polygons | SRID | min_x | min_y | max_x | max_y | info
----------+------+-------+-------+-------+-------+-----5 |
0 |
-38 |
13 |
50 |
80 |
(1 row)

Create an index in parallel from a partitioned table:


=> CREATE TABLE pols (p INT, gid INT, geom GEOMETRY(1000)) SEGMENTED BY HASH(p) ALL
NODES;
CREATETABLE
=> COPY pols (p, gid, gx filler LONG VARCHAR, geom AS ST_GeomFromText(gx)) FROM stdin
delimiter '|';
Enter data to be copied followed by a newline.
End with a backslash and a period on a line by itself.
>> 1|10|POLYGON((-31 74,8 70,8 50,-36 53,-31 74))
>> 1|11|POLYGON((-38 50,4 13,11 45,0 65,-38 50))
>> 3|12|POLYGON((-12 42,-12 42,27 48,14 26,-12 42))
>> \.
=> SELECT STV_Create_Index(gid, geom USING PARAMETERS index='my_polygons',
overwrite=true,
max_mem_mb=256) OVER() FROM pols;
polygons | SRID | min_x | min_y | max_x | max_y | info

HP Vertica Analytic Database (7.1.x)

Page 120 of 181

Place
HP Vertica Place Functions: An Overview

----------+------+-------+-------+-------+-------+-----3 |
0 |
-38 |
13 |
27 |
74 |
(1 row)

See Also
l

Spatial Joins with ST_Intersects and STV_Intersect

STV_Describe_Index

STV_Drop_Index

STV_Intersect Scalar Function

STV_Intersect Transform Function

STV_Rename_Index

STV_Describe_Index
Retrieves information about an index that contains a set of polygons. If you do not pass any
parameters, STV_Describe_Index returns all of the defined indexes.
The OVER() clause must be empty.

Behavior Type
Immutable

Syntax
STV_Describe_Index ([USING PARAMETERS index='index_name' ] ) OVER ()

Arguments
index = 'index_name'

Name of the index, type VARCHAR. The maximum index name length is
128 bytes. The slash, backslash, and tab characters are not allowed in
index names.

HP Vertica Analytic Database (7.1.x)

Page 121 of 181

Place
HP Vertica Place Functions: An Overview

Returns
polygons

Number of polygons indexed.

SRID

Spatial reference system identifier.

min_x, min_y, max_x, max_y

Coordinates of the minimum bounding rectangle (MBR) of the


indexed geometries. (min_x, min_y) are the south-west
coordinates, and (max_x, max_y) are the north-east coordinates.

Privileges
Any user with access to the STV_*_Index functions can describe, rename, or drop indexes created
by any other user.

Examples
The following examples show how to use STV_Describe_Index.
Retrieve information about the index:
=> SELECT STV_Describe_Index (USING PARAMETERS index='my_polygons') OVER ();
polygons | SRID | min_x | min_y | max_x | max_y
----------+------+-------+-------+-------+------4 |
0 |
-1 |
-1 |
12 |
12
(1 row)

Return the names of all the defined indexes:


=> SELECT STV_Describe_Index() OVER ();
name
-----------------MA_counties_index
my_polygons
NY_counties_index
US_States_Index
(4 rows)

See Also
l

Spatial Joins with ST_Intersects and STV_Intersect

STV_Create_Index

HP Vertica Analytic Database (7.1.x)

Page 122 of 181

Place
HP Vertica Place Functions: An Overview

STV_Drop_Index

STV_Intersect Scalar Function

STV_Intersect Transform Function

STV_Rename_Index

STV_Drop_Index
Deletes a spatial index. If STV_Drop_Index cannot find the specified spatial index, it returns an
error.
The OVER clause must be empty.

Behavior Type
Immutable

Syntax
STV_Drop_Index(USINGPARAMETERSindex = 'index_name' ) OVER ()

Arguments
index = 'index_name'

Name of the index, type VARCHAR. The maximum index name length is
128 bytes. The slash, backslash, and tab characters are not allowed in
index names.

Example
The following example shows how to use STV_Drop_Index.
Drop an index:
=> SELECT STV_Drop_Index(USINGPARAMETERS index ='my_polygons') OVER ();
drop_index
-----------Index dropped
(1 row)

HP Vertica Analytic Database (7.1.x)

Page 123 of 181

Place
HP Vertica Place Functions: An Overview

SeeAlso
l

Spatial Joins with ST_Intersects and STV_Intersect

STV_Create_Index

STV_Describe_Index

STV_Intersect Scalar Function

STV_Intersect Transform Function

STV_Rename_Index

STV_DWithin
Determines if the shortest distance from the boundary of one spatial object to the boundary of
another object is within a specified distance.
Parameters g1 and g2 must be both GEOMETRY objects or both GEOGRAPHY objects.

Behavior Type
Immutable

Syntax
STV_DWithin(g1, g2, d )

Arguments
g1

Spatial object, type GEOMETRY or GEOGRAPHY

g2

Spatial object, type GEOMETRY or GEOGRAPHY

Value of type FLOAT indicating a distance. For GEOMETRY objects, the distance is
measured in Cartesian coordinate units. For GEOGRAPHY objects, the distance is
measured in meters.

Returns
BOOLEAN

HP Vertica Analytic Database (7.1.x)

Page 124 of 181

Place
HP Vertica Place Functions: An Overview

Supported Data Types


Data Type

GEOMETRY GEOGRAPHY

Point

Yes

Yes

Multipoint

Yes

Yes

Linestring

Yes

Yes

Multilinestring

Yes

Yes

Polygon

Yes

Yes

Multipolygon

Yes

Yes

GeometryCollection Yes

No

Compatible GEOGRAPHY pairs:


Data Type

GEOGRAPHY

Point-Point

Yes

Point-Linestring

Yes

Point-Polygon

Yes

Point-Multilinestring Yes
Point-Multipolygon

Yes

Examples
The following examples show how to use STV_DWithin.
Two geometries are one Cartesian coordinate unit from each other at their closest points:
=> SELECT STV_DWithin(ST_GeomFromText('POLYGON((-1 -1,2 2,0 1,-1 -1))'),
ST_GeomFromText('POLYGON((4 3,2 3,4 5,4 3))'),1);
STV_DWithin
------------t
(1 row)

If you reduce the distance to 0.99 units:

HP Vertica Analytic Database (7.1.x)

Page 125 of 181

Place
HP Vertica Place Functions: An Overview

=> SELECT STV_DWithin(ST_GeomFromText('POLYGON((-1 -1,2 2,0 1,-1 -1))'),


ST_GeomFromText('POLYGON((4 3,2 3,4 5,4 3))'),0.99);
STV_DWithin
------------f
(1 row)

The first polygon touches the second polygon:


=> SELECT STV_DWithin(ST_GeomFromText('POLYGON((-1 -1,2 2,0 1,-1 -1))'),
ST_GeomFromText('POLYGON((1 1,2 3,4 5,1 1))'),0.00001);
STV_DWithin
------------t
(1 row)

The first polygon is not within 1000 meters from the second polygon:
=> SELECT STV_DWithin(ST_GeomFromText('POLYGON((45.2 40,50.65 51.29,
55.67 47.6,50 47.6,45.2 40))'),ST_GeomFromText('POLYGON((25 25,25 30,
30 30,30 25,25 25))'), 1000);
STV_DWithin
-------------t
(1 row)

STV_Geography
Casts a GEOMETRY object into a GEOGRAPHY object. The SRID value does not affect the
results of HP Vertica Place queries.
When STV_Geography converts a GEOMETRY object to a GEOGRAPHY object, it sets its SRID
to 4326.

Behavior Type
Immutable

Syntax
STV_Geography(geom )

Arguments
geom

Spatial object that you want to cast into a GEOGRAPHY object, type GEOMETRY

HP Vertica Analytic Database (7.1.x)

Page 126 of 181

Place
HP Vertica Place Functions: An Overview

Returns
GEOGRAPHY

Supported Data Types


Data Type

GEOMETRY

Point

Yes

Multipoint

Yes

Linestring

Yes

Multilinestring

Yes

Polygon

Yes

Multipolygon

Yes

GeometryCollection No

Example
The following example shows how to use STV_Geography.
To calculate the centroid of the GEOGRAPHY object, convert it to a GEOMETRY object, then
convert it back to a GEOGRAPHY object:
=> CREATE TABLE geogs(g GEOGRAPHY);
CREATE TABLE
=> COPY geogs(gx filler LONG VARCHAR, geog AS ST_GeographyFromText(gx)) FROM stdin
delimiter '|';
Enter data to be copied followed by a newline.
End with a backslash and a period on a line by itself.
>> MULTIPOINT(-108.619726 45.000284,-107.866813 45.00107,-106.363711 44.994223,-70.847746
41.205814)
>> \.
=> SELECT ST_AsText(STV_Geography(ST_Centroid(STV_Geometry(g)))) FROM geogs;
ST_AsText
-------------------------------POINT (-98.424499 44.05034775)
(1 row)

STV_Geometry
Casts a GEOGRAPHY object into a GEOMETRY object.

HP Vertica Analytic Database (7.1.x)

Page 127 of 181

Place
HP Vertica Place Functions: An Overview

The SRID value does not affect the results of HP Vertica Place queries.

Behavior Type
Immutable

Syntax
STV_Geometry(geog )

Arguments
geog

Spatial object that you want to cast into a GEOMETRY object, type GEOGRAPHY

Returns
GEOMETRY

Supported Data Types


Data Type

GEOGRAPHY

Point

Yes

Multipoint

Yes

Linestring

Yes

Multilinestring

Yes

Polygon

Yes

Multipolygon

Yes

GeometryCollection No

Example
The following example shows how to use STV_Geometry.
Convert the GEOGRAPHY values to GEOMETRY values, then convert the result back to a
GEOGRAPHY type:
=> CREATE TABLE geogs(g GEOGRAPHY);
CREATE TABLE

HP Vertica Analytic Database (7.1.x)

Page 128 of 181

Place
HP Vertica Place Functions: An Overview

=> COPY geogs(gx filler LONG VARCHAR, geog AS ST_GeographyFromText(gx)) FROM stdin
delimiter '|';
Enter data to be copied followed by a newline.
End with a backslash and a period on a line by itself.
>> MULTIPOINT(-108.619726 45.000284,-107.866813 45.00107,-106.363711 44.994223,-70.847746
41.205814)
>> \.
=> SELECT ST_AsText(STV_Geography(ST_Centroid(STV_Geometry(g)))) FROM geogs;
ST_AsText
-------------------------------POINT (-98.424499 44.05034775)

STV_Intersect Scalar Function


Spatially intersects point with a set of polygons. The STV_Intersect scalar function returns the
identifier associated with an intersecting polygon.

Behavior Type
Immutable

Syntax
STV_Intersect(
[table.]geom
USING PARAMETERS index= 'index_name')
FROM table

Arguments
geom

A GEOMETRY column that contains points. The geom column can only contain POINT
geometries. If the column contains a different GEOMETRY type, STV_Intersect
terminates with an error.

Parameters
index = 'index_name'

Name of the spatial index that STV_Create_Index creates, type


VARCHAR.

Returns
The identifier of a matching polygon. If the point does not intersect any of the index's polygons, then
the STV_Intersect scalar function returns NULL.

HP Vertica Analytic Database (7.1.x)

Page 129 of 181

Place
HP Vertica Place Functions: An Overview

Example
The following example shows how to use STV_Intersect scalar.
Return the gid of a matching polygon or NULL:
=> CREATE TABLE polygons (gid INT, geom GEOMETRY(700));
CREATE TABLE
=> COPY polygons (gid, gx filler LONG VARCHAR, geom AS ST_GeomFromText(gx)) FROM stdin
delimiter '|';
Enter data to be copied followed by a newline.
End with a backslash and a period on a line by itself.
>> 1|POLYGON((-31 74,8 70,8 50,-36 53,-31 74))
>> 2|POLYGON((-38 50,4 13,11 45,0 65,-38 50))
>> 3|POLYGON((-18 42,-10 65,27 48,14 26,-18 42))
>> \.
=> SELECT STV_Create_Index(gid, geom USING PARAMETERS index='my_polygons',
overwrite=true,
max_mem_mb=256) OVER() FROM polygons;
polygons | SRID | min_x | min_y | max_x | max_y | info
----------+------+-------+-------+-------+-------+-----3 |
0 |
-38 |
13 |
27 |
74 |
(1 row)
=> CREATE TABLE points (gid INT, geom GEOMETRY(700));
CREATETABLE
=> COPY points (gid, gx filler LONG VARCHAR, geom AS ST_GeomFromText(gx)) FROM stdin
delimiter '|';
Enter data to be copied followed by a newline.
End with a backslash and a period on a line by itself.
>> 100|POINT(-1 52)
>> 101|POINT(-20 0)
>> 102|POINT(-8 25)
>> 103|POINT(0 0)
>> 104|POINT(1 5)
>> 105|POINT(20 45)
>> 106|POINT(-20 5)
>> 107|POINT(-20 1)
>> \.
=> SELECT gid AS pt_gid, STV_Intersect(geom USING PARAMETERS index='my_polygons') AS pol_
gid
FROM points_1 ORDERBY pt_gid;
pt_gid | pol_gid
--------+--------100 |
1
101 |
102 |
2
103 |
104 |
105 |
3
106 |
107 |
(8 rows)

HP Vertica Analytic Database (7.1.x)

Page 130 of 181

Place
HP Vertica Place Functions: An Overview

See Also
l

STV_Intersect: Scalar Function vs. Transform Function

STV_Intersect Transform Function

Best Practices for Spatial Joins

BestPractices for HPVerticaPlace

STV_Intersect Transform Function


Spatially intersects points and polygons. The STV_Intersect transform function returns a tuple with
matching point/polygon pairs. For every point, one, or many matching polygons may be returned.
You can improve performance when you parallelize the computation of the STV_Intersect transform
function over multiple nodes. To parallelize the computation, use an OVER(PARTITION BEST)
clause.

Behavior Type
Immutable

Syntax
STV_Intersect ([table.]gid, [table.]geom
USING PARAMETERS index='index_name')
OVER([PARTITIONBEST] ) AS (pt_gid, pol_gid)
FROM table

Arguments
gid

An INTEGER column that uniquely identifies points in the geom parameter.

geom

A GEOMETRY column that contains points. The geom column can only contain point
geometries. If the column contains a different geometry type, STV_Intersect terminates
with an error.

Parameters
index = 'index_name'

Name of the index created by STV_Create_Index, type VARCHAR.

HP Vertica Analytic Database (7.1.x)

Page 131 of 181

Place
HP Vertica Place Functions: An Overview

Returns
pt_gid

Unique identifier of the POINT geometry, type INTEGER.

pol_gid

Unique identifier of the POLYGON geometry, type INTEGER.

Examples
The following examples show how to use STV_Intersect transform.
Return the matching point-polygon pairs.
=> CREATE TABLE polygons (gid int, geom GEOMETRY(700));
CREATETABLE
=> COPY polygons (gid, gx filler LONG VARCHAR, geom AS ST_GeomFromText(gx)) FROM stdin
delimiter '|';
Enter data to be copied followed by a newline.
End with a backslash and a period on a line by itself.
>> 10|POLYGON((5 5, 5 10, 10 10, 10 5, 5 5))
>> 11|POLYGON((0 0, 0 2, 2 2, 2 0, 0 0))
>> 12|POLYGON((1 1, 1 3, 3 3, 3 1, 1 1))
>> 14|POLYGON((-1 -1, -1 12, 12 12, 12 -1, -1 -1))
>> \.
=> SELECT STV_Create_Index(gid, geom USING PARAMETERS index='my_polygons',
overwrite=true, max_mem_mb=256) OVER() FROM polygons;
polygons | SRID | min_x | min_y | max_x | max_y | info
----------+------+-------+-------+-------+-------+-----4 |
0 |
-1 |
-1 |
12 |
12 |
(1 row)
=> CREATE TABLE points (gid INT, geom GEOMETRY(700));
CREATETABLE
=> COPY points (gid, gx filler LONG VARCHAR, geom AS ST_GeomFromText(gx)) FROM stdin
delimiter '|';
Enter data to be copied followed by a newline.
End with a backslash and a period on a line by itself.
>> 1|POINT(9 9)
>> 2|POINT(0 1)
>> 3|POINT(2.5 2.5)
>> 4|POINT(0 0)
>> 5|POINT(1 5)
>> 6|POINT(1.5 1.5)
>> \.
=> SELECT STV_Intersect(gid, geom USING PARAMETERS index='my_polygons') OVER (PARTITION
BEST)
AS (point_id, polygon_gid)
FROM points;
point_id | polygon_gid
----------+------------5 |
14
1 |
14
1 |
10
4 |
14

HP Vertica Analytic Database (7.1.x)

Page 132 of 181

Place
HP Vertica Place Functions: An Overview

4
6
6
6
2
2
3
3
(12 rows)

|
|
|
|
|
|
|
|

11
12
14
11
14
11
12
14

You can improve query performance by using the STV_Intersect transform function in a WHERE
clause. Performance improves because this syntax eliminates all points that do not intersect
polygons in the index.
Return the count of points that only intersect polygon gid = 14:
=> SELECT COUNT(pt_id) FROM
(SELECT STV_Intersect(gid, geom USING PARAMETERS index='my_polygons')
OVER (PARTITION BEST) AS (pt_id, pol_id) FROM points)
AS T WHERE pol_id = 14;
COUNT
------6
(1 row)

See Also
l

STV_Intersect: Scalar Function vs. Transform Function

STV_Intersect Scalar Function

Best Practices for Spatial Joins

BestPractices for HPVerticaPlace

STV_IsValidReason
Determines if a polygon or multipolygon is well formed or valid. If the object is not valid, STV_
IsValidReason returns a string that explains where the invalidity occurs.
Spatial validity applies only to polygons and multipolygons. A polygon or multipolygon is valid if all
of the following are true:
l

The polygon is closed; its start point is the same as its end point.

Its boundary is a set of linestrings.

HP Vertica Analytic Database (7.1.x)

Page 133 of 181

Place
HP Vertica Place Functions: An Overview

The boundary does not touch or cross itself.

Any polygons in the interior that do not have more than one point touching the boundary of the
exterior polygon.

If you pass an invalid object to an HP Vertica Place function, the function fails or returns incorrect
results. To determine if a polygon is valid, first run ST_IsValid. ST_IsValid returns TRUE if the
polygon is valid, FALSE otherwise.
Important: STV_IsValidReason supports only polygon and multipolygon GEOMETRYdata
types.

Behavior Type
Immutable

Syntax
STV_IsValidReason(g )

Arguments
g

Polygon or multipolygon to test for validity, value of type GEOMETRY.

Returns
LONG VARCHAR

Example
The following example shows how to use STV_IsValidReason.
Returns a string describing where the polygon is invalid:
=> SELECT STV_IsValidReason(ST_GeomFromText('POLYGON((1 3,3 2,1 1,
3 0,1 0,1 3))'));
STV_IsValidReason
----------------------------------------------Ring Self-intersection at or near POINT (1 1)
(1 row)

HP Vertica Analytic Database (7.1.x)

Page 134 of 181

Place
HP Vertica Place Functions: An Overview

See Also
l

ST_IsValid

STV_LineStringPoint
Retrieves the vertices of a linestring or multilinestring. The values returned are points of either
GEOMETRY or GEOGRAPHY type depending on the input object's type. GEOMETRY points
inherit the SRID of the input object.
STV_LineStringPoint is an analytic function. For more information, see Analytic Functions.

Behavior Type
Immutable

Syntax
STV_LineStringPoint(g )
OVER([PARTITIONNODES] ) AS

Arguments
g

Linestring or multilinestring, value of type GEOMETRY or GEOGRAPHY

Returns
GEOMETRY or GEOGRAPHY

Supported Data Types


Data Type

GEOMETRY GEOGRAPHY

Point

No

No

Multipoint

No

No

Linestring

Yes

Yes

Multilinestring

Yes

Yes

Polygon

No

No

HP Vertica Analytic Database (7.1.x)

Page 135 of 181

Place
HP Vertica Place Functions: An Overview

Multipolygon

No

No

GeometryCollection No

No

Examples
The following examples show how to use STV_LineStringPoint.
Returns the vertices of the geometry linestring and their SRID:
=> SELECT ST_AsText(Point), ST_SRID(Point)
FROM (SELECT STV_LineStringPoint(
ST_GeomFromText('MULTILINESTRING((1 2, 2 3, 3 1, 4 2),
(10 20, 20 30, 30 10, 40 20))', 4269)) OVER () AS Point) AS foo;
ST_AsText
| ST_SRID
---------------+--------POINT (1 2)
|
4269
POINT (2 3)
|
4269
POINT (3 1)
|
4269
POINT (4 2)
|
4269
POINT (10 20) |
4269
POINT (20 30) |
4269
POINT (30 10) |
4269
POINT (40 20) |
4269
(8 rows)

Returns the vertices of the geography linestring:


=> SELECT ST_AsText(g)
FROM (SELECT STV_LineStringPoint(
ST_GeographyFromText('MULTILINESTRING ((42.1 71.0, 41.4 70.0, 41.3 72.9),
(42.99 71.46, 44.47 73.21)', 4269)) OVER () AS g) AS line_geog_points;
ST_AsText
--------------------POINT (42.1 71.0)
POINT (41.4 70.0)
POINT (41.3 72.9)
POINT (42.99 71.46)
POINT (44.47 73.21)
(5 rows)

See Also
STV_PolygonPoint

STV_NN
Calculates the distance of spatial objects from a reference object and returns (object, distance)
pairs in ascending order by distance from the reference object.

HP Vertica Analytic Database (7.1.x)

Page 136 of 181

Place
HP Vertica Place Functions: An Overview

Parameters g1 and g2 must be both GEOMETRY objects or both GEOGRAPHY objects.


STV_NN is an analytic function. For more information, see Analytic Functions.

Behavior Type
Immutable

Syntax
STV_NN(g, ref_obj, k ) OVER() AS

Arguments
g

Spatial object, value of type GEOMETRY or GEOGRAPHY

ref_obj

Reference object, type GEOMETRY or GEOGRAPHY

Number of rows to return, type INTEGER

Returns
(Object, distance) pairs, in ascending order by distance. If a parameter is EMPTY or NULL, then 0
rows are returned.

Supported Data Types


Data Type

GEOMETRY GEOGRAPHY

Point

Yes

Yes

Multipoint

Yes

Yes

Linestring

Yes

Yes

Multilinestring

Yes

Yes

Polygon

Yes

Yes

Multipolygon

Yes

Yes

GeometryCollection Yes

No

Example
The following example shows how to use STV_NN.

HP Vertica Analytic Database (7.1.x)

Page 137 of 181

Place
HP Vertica Place Functions: An Overview

Create a table and insert nine GEOGRAPHY points:


=> CREATE TABLE points (g geography);
CREATETABLE
=> COPY points (gx filler LONGVARCHAR, g AS ST_GeographyFromText(gx)) FROM stdin
delimiter '|';
Enter data to be copied followed by a newline.
End with a backslash and a period on a line by itself.
>> POINT (21.5 18.4)
>> POINT (21.5 19.2)
>> POINT (21.5 20.7)
>> POINT (22.5 16.4)
>> POINT (22.5 17.15)
>> POINT (22.5 18.33)
>> POINT (23.5 13.68)
>> POINT (23.5 15.9)
>> POINT (23.5 18.4)
>> \.

Calculate the distances (in meters) of objects in table points from the GEOGRAPHY point (23.5,
20).
Returns the five objects that are closest to that point:
=> SELECT ST_AsText(nn), dist FROM (SELECT STV_NN(g,
ST_GeographyFromText('POINT(23.5 20)'),5) OVER() AS (nn,dist) FROM points) AS example;
ST_AsText
|
dist
--------------------+-----------------POINT (23.5 18.4) | 177912.12757541
POINT (22.5 18.33) | 213339.210738322
POINT (21.5 20.7) | 222561.43679943
POINT (21.5 19.2) | 227604.371833335
POINT (21.5 18.4) | 275239.416790128
(5 rows)

STV_PolygonPoint
Retrieves the vertices of a polygon as individual points. The values returned are points of either
GEOMETRY or GEOGRAPHY type depending on the input object's type. GEOMETRY points
inherit the SRID of the input object.
STV_PolygonPoint is an analytic function. For more information, see Analytic Functions.

Behavior Type
Immutable

Syntax
STV_PolygonPoint(g )
OVER([PARTITIONNODES] ) AS

HP Vertica Analytic Database (7.1.x)

Page 138 of 181

Place
HP Vertica Place Functions: An Overview

Arguments
g

Polygon, value of type GEOMETRY or GEOGRAPHY

Returns
GEOMETRY or GEOGRAPHY

Supported Data Types


Data Type

GEOMETRY GEOGRAPHY

Point

No

No

Multipoint

No

No

Linestring

No

No

Multilinestring

No

No

Polygon

Yes

Yes

Multipolygon

Yes

Yes

GeometryCollection No

No

Examples
The following examples show how to use STV_PolygonPoint.
Returns the vertices of the geometry polygon:
=> SELECT ST_AsText(g) FROM (SELECT STV_PolygonPoint(ST_GeomFromText('POLYGON((1 2, 2 3,
3 1, 1 2))'))
OVER (PARTITION NODES) AS g) AS poly_points;
ST_AsText
------------POINT (1 2)
POINT (2 3)
POINT (3 1)
POINT (1 2)
(4 rows)

Returns the vertices of the geography polygon:

HP Vertica Analytic Database (7.1.x)

Page 139 of 181

Place
HP Vertica Place Functions: An Overview

=> SELECT ST_AsText(g) FROM (SELECT STV_PolygonPoint(ST_GeographyFromText('


POLYGON((25.5 28.76, 28.83 29.13, 27.2 30.99, 25.5 28.76))'))
OVER (PARTITION NODES) AS g) AS poly_points;
ST_AsText
--------------------POINT (25.5 28.76)
POINT (28.83 29.13)
POINT (27.2 30.99)
POINT (25.5 28.76)
(4 rows)

See Also
STV_LineStringPoint

STV_Refresh_Index
Appends newly added or updated polygons to an existing spatial index.
A spatial index is created from an input polygon set, which can be the result of a query. Spatial
indexes are created in a global name space. HP Vertica uses a distributed plan whenever the input
table or projection is segmented across nodes of the cluster.
The OVER() clause must be empty.

Behavior Type
Mutable

Syntax
STV_Refresh_Index(gid, geom
USING PARAMETERS index='index_name'
[, skip_nonindexable_polygons={true | false } ] )
OVER()
[AS (polygons, srid, min_x, min_y, max_x, max_y, info) ]
FROM table

Arguments
gid

Name of an INTEGER column that uniquely identifies the polygon in the geom parameter.
The gid cannot be NULL.

HP Vertica Analytic Database (7.1.x)

Page 140 of 181

Place
HP Vertica Place Functions: An Overview

geom

Name of a GEOMETRY column or expression that contains polygons and multipolygons


assumed to be in the two-dimensional Euclidean plane. Only POLYGON and
MULTIPOLYGON geometries are indexed. Other shape types are excluded from the
index and captured in the info field.

table

Name of the database table that contains the geometry data.

Parameters
index = 'index_name'

Name of the index, type VARCHAR. The


maximum index name length is 128 bytes. The
slash, backslash, and tab characters are not
allowed in index names.

skip_nonindexable_polygons = [true | false ]

[Optional] BOOLEAN
In rare cases, intricate polygons (such as
those with too-high a resolution or anomalous
spikes) cannot be indexed.
l

When set to false, non-indexable polygons


cause the index creation to fail.

When set to true, index excludes nonindexable polygons from the index so that
the operation can succeed. Logs identifiers
from non-indexable polygons are stored in
the vertica.log file in the catalog
directory.

Default value: false

Returns
polygons

Number of polygons indexed.

SRID

Spatial reference system identifier.

HP Vertica Analytic Database (7.1.x)

Page 141 of 181

Place
HP Vertica Place Functions: An Overview

min_x, min_y, max_x, max_y

Coordinates of the minimum bounding rectangle


(MBR) of the indexed geometries. (min_x, min_y) are
the south-west coordinates, and (max_x, max_y) are
the north-east coordinates.

info

Lists the number of excluded geometries as well as


their type that were excluded from the index.

indexed

Number of polygons indexed during the operation.

appended

Number of appended polygons.

updated

Number of updated polygons.

Supported Data Types


Data Type

GEOMETRY

Point

No

Multipoint

No

Linestring

No

Multilinestring

No

Polygon

Yes

Multipolygon

Yes

GeometryCollection No

Privileges
Any user with access to the STV_*_Index functions can describe, rename, or drop indexes created
by any other user.

Limitations
l

In rare cases, intricate polygons (such as those with too-high a resolution or anomalous spikes)
cannot be indexed. See the parameter skip_nonindexable_polygons.

HP Vertica Analytic Database (7.1.x)

Page 142 of 181

Place
HP Vertica Place Functions: An Overview

If you replace a valid polygon in the source table with an invalid polygon, STV_Refresh_Index
ignores the invalid polygon. As a result, the polygon originally indexed persists in the index.

The following geometries cannot be indexed:


n

Non-polygons

NULL gid

NULL (multi) polygon

EMPTY (multi) polygon

Invalid (multi) polygon

Usage Tips
l

To cancel an STV_Refresh_Index run, enter Ctrl+C.

If you use a source table that was not previously associated with the index, doing so overwrites
the index.

If STV_Refresh_Index has insufficient memory to process the query, then rebuild the index
using STV_Create_Index.

If there are no valid polygons in the geom column, STV_Refresh_Index reports an error in
vertica.log and stops the index refresh.

Examples
The following examples show how to use STV_Refresh_Index.
Refresh an index with a single literal argument:
=> SELECT STV_Create_Index(1, ST_GeomFromText('POLYGON((0 0,0 15.2,3.9 15.2,3.9 0,0 0))')
USING PARAMETERS index='my_polygon') OVER();
polygons | SRID | min_x | min_y | max_x | max_y | info
----------+------+-------+-------+-------+-------+-----1 |
0 |
0 |
0 |
3.9 | 15.2 |
(1 row)
=> SELECT STV_Refresh_Index(2, ST_GeomFromText('POLYGON((0 0,0 13.2,3.9 18.2,3.9 0,0 0))
')
USING PARAMETERS index='my_polygon') OVER();
polygons | SRID | min_x | min_y | max_x | max_y |
info
----------+------+-------+-------+-------+-------+---------------------2 |
0 |
0 |
0 |
3.9 | 18.2 | Polygons appended: 1
(1 row)

HP Vertica Analytic Database (7.1.x)

Page 143 of 181

Place
HP Vertica Place Functions: An Overview

Refresh an index from a table:


=> CREATE TABLE pols (gid INT, geom GEOMETRY);
CREATETABLE
=> COPY pols(gid, gx filler LONG VARCHAR, geom AS ST_GeomFromText(gx)) FROM stdin
delimiter '|';
Enter data to be copied followed by a newline.
End with a backslash and a period on a line by itself.
>> 1|POLYGON((-31 74,8 70,8 50,-36 53,-31 74))
>> 2|POLYGON((5 20,9 30,20 45,36 35,5 20))
>> 3|POLYGON((12 23,9 30,20 45,36 35,37 67,45 80,50 20,12 23))
>> \.
=> SELECT STV_Create_Index(gid, geom USING PARAMETERS index='my_polygons_1',
overwrite=true)
OVER() FROM pols;
polygons | SRID | min_x | min_y | max_x | max_y | info
----------+------+-------+-------+-------+-------+-----3 |
0 |
-36 |
20 |
50 |
80 |
(1 row)
=> COPY pols(gid, gx filler LONG VARCHAR, geom AS ST_GeomFromText(gx)) FROM stdin
delimiter '|';
Enter data to be copied followed by a newline.
End with a backslash and a period on a line by itself.
>> 6|POLYGON((-32 74,8 70,8 50,-36 53,-32 74))
>> \.
=> SELECT STV_Refresh_Index(gid, geom USING PARAMETERS index='my_polygons_1') OVER() FROM
pols;
polygons | SRID | min_x | min_y | max_x | max_y | info | indexed | appended | updated
----------+------+-------+-------+-------+-------+----------------+---------+---------4 |
0 |
-36 |
20 |
50 |
80 |
|
1 |
1 |
0
(1 row)

See Also
l

STV_Create_Index

STV_Describe_Index

STV_Drop_Index

STV_Rename_Index

STV_Rename_Index
Renames a spatial index. If the index format is out of date, you cannot rename the index.
A spatial index is created from an input polygon set, which can be the result of a query. Spatial
indexes are created in a global name space. HP Vertica uses a distributed plan whenever the input
table or projection is segmented across nodes of the cluster.
The OVER() clause must be empty.

HP Vertica Analytic Database (7.1.x)

Page 144 of 181

Place
HP Vertica Place Functions: An Overview

Behavior Type
Immutable

Syntax
STV_Rename_Index(USING PARAMETERS
source = 'old_index_name',
dest = 'new_index_name',
overwrite = ['true' | 'false' ]
)
OVER ()

Arguments
source = 'old_index_name'

Current name of the spatial index, type VARCHAR.

dest = 'new_index_name'

New name of the spatial index, type VARCHAR.

overwrite = ['true' | 'false' ]

(Optional) BOOLEAN that specifies whether to overwrite the


index if it exists. This parameter cannot be NULL.Default:
false

Privileges
Any user with access to the STV_*_Index functions can describe, rename, or drop indexes created
by any other user.

Limitations
The backslash or tab characters are not allowed in index names.

Example
The following example shows how to use STV_Rename_Index.
Rename an index:
=> SELECT STV_Rename_Index (
USINGPARAMETERS
source = 'my_polygons',
dest = 'US_states',
overwrite = 'false'
)
OVER ();

HP Vertica Analytic Database (7.1.x)

Page 145 of 181

Place
HP Vertica Place Functions: An Overview

rename_index
--------------Index renamed
(1 Row)

STV_ShpCreateTable
Returns a CREATE TABLE statement with the columns and types of the attributes found in the
specified shapefile.
The column types are sized according to the shapefile metadata. The size of the column is based
on the largest geometry found in the shapefile. The first column in the table is gid, which is an autoincrement IDENTITY primary key column. The cache value is set to 64 by default. The last column
is a GEOMETRY data type for storing the actual geometry data.

Behavior Type
Immutable

Syntax
STV_ShpCreateTable(USING PARAMETERS file='filename') OVER()

Arguments
file = 'filename'

Fully qualified path of the .dbf, .shp, or .shx file. (The extension is
optional.)

Returns
CREATE TABLE statement that matches the specified shapefile

Usage Tips
l

STV_ShpCreateTable returns a CREATE TABLE statement; but it does not create the table.
Modify the CREATE TABLE statement as needed, and then create the table before loading the
shapefile into the table.

To create a table with characters other than alphanumeric and underscore (_) characters, you
must specify the table name enclosed in double quotes, such as "counties%NY".

HP Vertica Analytic Database (7.1.x)

Page 146 of 181

Place
HP Vertica Place Functions: An Overview

The name of the table is the same as the name of the shapefile, without the directory name or
extension.

The shapefile must be accessible from the initiator node.

If the .shp and .shx files are corrupt, STV_ShpCreateTable returns an error. If the .shp and
.shx files are valid, but the .dbf file is corrupt, STV_ShpCreateTable ignores the .dbf file and
does not create columns for that data.

All the mandatory files (.dbf, .shp, .shx) must be in the same directory. If not, STV_
ShpCreateTable returns an error.

If the .dbf component of a shapefile contains a Numeric attribute, this field's values may lose
precision when the HP Vertica shapefile loader loads it into a table. The target field is a 64-bit
FLOAT column, which can only represent about 15 significant digits. In a .dbf file, numeric
fields can be up to 30 digits.
HP Vertica records all instances of shapefile values that are too long in the vertica.log file.

Example
The following example shows how to use STV_ShpCreateTable.
Returns a CREATE TABLE statement:
=> SELECT STV_ShpCreateTable
(USING PARAMETERS file='/shapefiles/tl_2010_us_state10.shp')
OVER() as create_table_states;
create_table_states
---------------------------------CREATE TABLE tl_2010_us_state10(-- table name derived from file name
gid IDENTITY(64) PRIMARY KEY,
REGION10 VARCHAR(2),
DIVISION10 VARCHAR(2),
STATEFP10 VARCHAR(2),
STATENS10 VARCHAR(8),
GEOID10 VARCHAR(2),
STUSPS10 VARCHAR(2),
NAME10 VARCHAR(100),
LSAD10 VARCHAR(2),
MTFCC10 VARCHAR(5),
FUNCSTAT10 VARCHAR(1),
ALAND10 FLOAT8,
AWATER10 FLOAT8,
INTPTLAT10 VARCHAR(11),
INTPTLON10 VARCHAR(12),
geom GEOMETRY(940845)
);

HP Vertica Analytic Database (7.1.x)

Page 147 of 181

Place
HP Vertica Place Functions: An Overview

(18 rows)

See Also
l

STV_ShpSource and STV_ShpParser

STV_ShpSource and STV_ShpParser


These two functions work with a COPY command to parse and load the geometries and attributes
from an Esri shapefile into a database table and convert them to the GEOMETRY data type format.
You must use these two functions together. An SRID is required.

Behavior Type
Immutable

Syntax
COPY table_name(col2, col3, ..., coln )
WITH SOURCE STV_ShpSource(file = 'filename'[, SRID=spatial reference identifier] )
PARSER STV_ShpParser()

Arguments
table_name

Name of the table in which to load the geometry data.

col1, col2, ...

Column names in the table that match the fields in the


external file. Run the CREATE TABLE command that STV_
ShpCreateTable creates. When you do so, these columns
correspond to the second through the second-to-last
columns.

file = 'filename'

Fully qualified path of the .dbf, .shp, or .shx file. (The


extension is optional.)

SRID=spatial reference identifier

Spatial reference identifier (SRID) associated with the


shape file, type INTEGER.

HP Vertica Analytic Database (7.1.x)

Page 148 of 181

Place
HP Vertica Place Functions: An Overview

Usage Tips
l

The COPY command fails if:


n

The shapefile cannot be located or opened.

The number of columns or the data types of the columns that STV_ShpParser creates do not
match the columns in the destination table. Use STV_ShpCreateTable to generate the
appropriate CREATE TABLE command.

One of the mandatory files is missing or cannot be opened. When opening a shapefile, you
must have three files: .dbf, .shp, and .shx.

Shapefiles loaded with NULL attributes will default to 0.

If the .shpand .shxfiles are corrupt, STV_ShpSource returns an error. If the .shpand .shx
files are valid, but the .dbffile is corrupt, STV_ShpSource ignores the .dbf file and does not
create columns for that data.

Any rejected records are saved in the /CopyErrorLogs directory under the catalog directory.

If the .dbf component of a shapefile contains a numeric attribute, this field's values may lose
precision when the HP Vertica Place shapefile loader loads it into a table. The target field is a 64bit FLOAT column, which can only represent about 15 significant digits; in a .dbf file, Numeric
fields can be up to 30 digits.
HP Vertica records all instances of shapefile values that are too long in the vertica.log file.

Example
The following example shows how to use STV_ShpSource and STV_ShpParser.
=> COPY tl_2010_us_state10 WITH SOURCE
STV_ShpSource(file='/shapefiles/tl_2010_us_state10.shp', SRID=4269) PARSER STV_ShpParser
();
Rows loaded
------------52

See Also
l

STV_ShpCreateTable

HP Vertica Analytic Database (7.1.x)

Page 149 of 181

Place
Spatial Joins with ST_Intersects and STV_Intersect

Spatial Joins with ST_Intersects and STV_


Intersect
Spatial joins allow you to identify spatial relationships between two sets of spatial data. For
example, you can use spatial joins to:
l

Calculate the density of mobile calls in various regions to determine the location of a new cell
phone tower.

Identify homes that fall within the impact zone of a hurricane.

Calculate the number of users who live within a certain ZIP code.

Calculate the number of customers in a retail store at any given time.

STV_Intersect: Scalar Function vs. Transform


Function
The STV_Intersect functions are similar in purpose, but you use them differently.
STV_Intersect
Function Type

Description

Performance

Scalar

Matches a point to a polygon. If

Eliminates points that do not

several polygons contain the point,

intersect with any indexed polygons,

this function returns a gid value.

avoiding unnecessary comparisons.

The result is a polygon gid or, if no


polygon contains the point, the
result is NULL.
Transform

Matches a point to all the polygons

Processes all input points regardless

that contain it. When a point does

of whether or not they intersect with

not intersect with any polygon in

the indexed polygons.

the index, the function returns no


rows.
In the following example, the STV_Intersect scalar function compares the points in the points
table to the polygons in a spatial index named my_polygons. STV_Intersect returns all points and
polygons that match exactly:

HP Vertica Analytic Database (7.1.x)

Page 150 of 181

Place
Spatial Joins with ST_Intersects and STV_Intersect

=> SELECT gid AS pt_gid


STV_Intersect(geom USING PARAMETERS index='my_polygons') AS pol_gid
FROM points ORDERBY pt_gid;
pt_gid | pol_gid
--------+--------100 |
2
101 |
102 |
2
103 |
104 |
105 |
3
106 |
107 |
(8 rows)

The following example shows how to use the STV_Intersect transform function to return
information about the three point-polygon pairs that match and each of the polygons they match:
=> SELECT STV_Intersect(gid, geom
USING PARAMETERS index='my_polygons')
OVER (PARTITIONBEST) AS (pt_gid, pol_id)
FROM points;
pt_gid | pol_id
--------+-------100 |
1
100 |
2
100 |
3
102 |
2
105 |
3
(3 rows)

See Also
l

STV_Intersect Scalar Function

STV_Intersect Transform Function

When to Use ST_Intersects vs. STV_Intersect


HP Vertica Place provides two capabilities to identify whether a set of points intersect with a set of
polygons. Depending on the size of your data set, choose the approach that gives the best
performance:
l

When comparing a set of geometries to a single geometry to see if they intersect, use the ST_
Intersects function.

To determine if a set of points intersects with a set of polygons in a medium-to-large data set,

HP Vertica Analytic Database (7.1.x)

Page 151 of 181

Place
Spatial Joins with ST_Intersects and STV_Intersect

first create a spatial index using STV_Create_Index. Then, use one of the STV_Intersect
functions to return the set of pairs that intersect.

Note: You can only perform spatial joins on GEOMETRY data.

Performing Spatial Joins with ST_Intersects


The ST_Intersects function determines if two GEOMETRY objects intersect or touch at a single
point.
Use ST_Intersects when you want to identify if a small set of geometries in a column intersect
with a given geometry.
For best performance, at least one of the arguments to ST_Intersects should be a constant
geometry.

Example
The following example uses ST_Intersects to compare a column of point geometries to a single
polygon. The table that contains the points has 1 million rows.
ST_Intersects returns only the points that intersect with the polygon. Those points represent
about 0.01% of the points in the table:
=> CREATE TABLE points_1m(gid IDENTITY, g GEOMETRY(100)) ORDER BY g;
=> COPY points_1m(wkt FILLER LONG VARCHAR(100), g AS ST_GeomFromText(wkt))
FROM LOCAL '/data/points.dat' DIRECT;
Rows Loaded
------------1000000
(1 row)
=> SELECT ST_AsText(g) FROM points_1m WHERE
ST_Intersects
(
g,
ST_GeomFromText('POLYGON((-71 42, -70.9 42, -70.9 42.1, -71 42.1, -71 42))')
);
st_astext
---------------------------POINT (-70.97532 42.03538)
POINT (-70.97421 42.0376)
POINT (-70.99004 42.07538)
POINT (-70.99477 42.08454)
POINT (-70.99088 42.08177)
POINT (-70.98643 42.07593)
POINT (-70.98032 42.07982)
POINT (-70.95921 42.00982)
POINT (-70.95115 42.02177)

HP Vertica Analytic Database (7.1.x)

Page 152 of 181

Place
Spatial Joins with ST_Intersects and STV_Intersect

...
(116 rows)

HP Vertica recommends that you test the intersections of two columns of geometries by creating a
spatial index. Use one of the STV_Intersect functions as described in .

Performing Spatial Joins with STV_Intersect


Functions
Suppose you want to process a medium-to-large spatial data set and determine which points
intersect with which polygons. In that case, first create a spatial index using STV_Create_Index.
Aspatial index provides efficient access to the set of polygons.
Then, use the STV_Intersect scalar or transform function to identify which point-polygon pairs
match.

Spatial Indexes and STV_Intersect


Before performing a spatial join using one of the STV_Intersect functions, you must first run STV_
Create_Index to create a database object that contains information about polygons. This object is
called a spatial index of the set of polygons. The spatial index improves the time it takes for the
STV_Intersect functions to access the polygon data.
HP Vertica Place creates spatial indexes in a global space. Thus, any user with access to the STV_
*_Index functions can describe, rename, or drop indexes created by any other user.
HP Vertica Place provides functions that work with spatial indexes:
l

STV_Create_IndexStores information about polygons in an index to improve performance.

STV_Describe_IndexRetrieves information about an index.

STV_Drop_IndexDeletes a spatial index.

STV_Refresh_IndexRefreshes a spatial index.

STV_Rename_IndexRenames a spatial index.

Best Practices for Spatial Joins


This topic describes best practices for performing spatial joins with HP Vertica Place. Use these
best practices to improve overall performance and optimize your spatial queries.

HP Vertica Analytic Database (7.1.x)

Page 153 of 181

Place
Spatial Joins with ST_Intersects and STV_Intersect

Best practices for using spatial joins in HP Vertica Place include:


l

Table segmentation to speed up index creation

Adequately sizing a geometry column to store point data

Loading Well-Known Text (WKT) directly into a Geometry column using ST_GeomFromText in a
COPY statement

Using OVER (PARTITIONBEST) with STV_Intersect transform queries

Best Practices Example


Note: The following example was originally published in an HP Vertica blog post about using
spatial data in museums. To read the entire blog, go to:
http://www.vertica.com/2014/11/04/using-location-data-with-hp-vertica-place/.
Before performing the steps in the following example, download place_output.csv.zip from the
HP Vertica Place GitHub repository (http://github.com/vertica/Place). You need to use the data set
from this repository.
1. Create the table for the polygons.large. Use a GEOMETRY column width that fits your data
without being excessively large. A good column-width fit improves performance. In addition,
segmenting the table by HASH provides the advantages of parallel computation.
=> CREATE TABLE artworks (gid int, g GEOMETRY(700)) SEGMENTED BY HASH(gid) ALL NODES;

2. Use a copy statement with ST_Buffer to create and load the polygons on which to run the
intersect. By using ST_Buffer in your copy statement, you can use that function to create the
polygons.
=> COPY artworks(gid, gx filler LONGVARCHAR, g AS ST_Buffer(ST_GeomFromText(gx),8))
FROM stdin delimiter ',';
>> 1, POINT(10 45)
>> 2, POINT(25 45)
>> 3, POINT(35 45)
>> 4, POINT(35 15)
>> 5, POINT(30 5)
>> 6, POINT(15 5)
>> \.

HP Vertica Analytic Database (7.1.x)

Page 154 of 181

Place
Spatial Joins with ST_Intersects and STV_Intersect

3. Create the table for the location data, represented by points. Point data can be perfectly stored
in a GEOMETRY column of 100 bytes. Larger sizes, however, can significantly degrade
spatial intersection performance. Again, segment the table by HASH to take advantage of
parallel computation.
=> CREATE TABLE usr_data (gid identity,usr_id int,date_time timestamp,g geometry(100))
SEGMENTED BY HASH(gid) ALL NODES;

4. During the copy statement, transform the location data to Well Known Text (WKT), and then
store the data in the table as Geometry data. You must perform this transformation because
your location data is not formatted as WKT. Use the function ST_GeomFromText to take the
newly transformed WKT and transform it to geometry data.
=> COPY usr_data(usr_id, date_time, x filler long varchar, y filler long varchar,
g as ST_GeomFromText('POINT(' || x || ' ' || y || ')'))
from LOCAL 'place_output.csv' delimiter ',' enclosed by '';

5. Create the spatial index for the polygons. You will use this index to speed up intersection
calculations.
=> SELECT STV_Create_Index(gid, g USING PARAMETERS index='art_index', overwrite=true)
OVER() FROM artworks;

6. Write an analytic query that returns the number of intersections per polygon, ignoring any usr_
id that intersects less than 20 times with a given polygon.
=> SELECT pol_gid,
COUNT(DISTINCT(usr_id)) AS count_user_visit
FROM
(SELECT pol_gid,
usr_id,
COUNT(usr_id) AS user_points_in
FROM
(SELECT STV_Intersect(usr_id, g USING PARAMETERS INDEX='art_index') OVER(PARTITION
BEST) AS (usr_id,

pol_gi
FROM usr_data
WHERE date_time BETWEEN '2014-07-02 09:30:20' AND '2014-07-02 17:05:00') AS c
GROUP BY pol_gid,
usr_id HAVING COUNT(usr_id) > 20) AS real_visits
GROUP BY pol_gid
ORDER BY count_user_visit DESC;

Optimizations in Example Query


This query has the following optimizations:

HP Vertica Analytic Database (7.1.x)

Page 155 of 181

Place
Spatial Joins with ST_Intersects and STV_Intersect

The time predicated is in the sub-query.

Using the location data table avoids the need for an expensive join.

The query uses OVER (PARTITIONBEST) to improve performance by partitioning the data.

The user_points_in gives an estimation of the combined time spent intersecting with the
artwork by all visitors.

Loading Spatial Data from Shapefiles


HP Vertica Place provides the capability to load and parse spatial data that is stored in Esri
shapefiles. Shapefiles describe points, lines, and polygons. A shapefile is actually made up of three
required files; all three files must be present and in the same directory to define the geometries:
l

.shpContains the geometry data.

.shxContains the positional index of the geometry.

.dbfContains the attributes for each geometry.

The HP Vertica Place functions that work with spatial data in shapefiles are:
l

STV_ShpCreateTableReturns a CREATE TABLE statement for creating a HP Vertica


database table that matches the data in the shapefile.

STV_ShpParser and STV_ShpSourceParse and load the geometries and attributes from an
Esri shapefile into a database table. You must use these two functions together.

The following table lists the shapefile shape types that HP Vertica Place support:
ESRIShapefile
Shape type

HP Vertica Place supports?

Null shape

Yes

Point

Yes

Polyline

Yes

Polygon

Yes

MultiPoint

Yes

HP Vertica Analytic Database (7.1.x)

Page 156 of 181

Place
Spatial Joins with ST_Intersects and STV_Intersect

ESRIShapefile
Shape type

HP Vertica Place supports?

PointZ

No

PolylineZ

No

PolygonZ

No

MultiPointZ

No

PointM

No

PolylineM

No

PolygonM

No

MultiPointM

No

MultiPatch

No

HP Vertica Analytic Database (7.1.x)

Page 157 of 181

Place
Working with Spatial Objects in Tables

Working with Spatial Objects in Tables


To work with spatial objects in a table, you must create columns for spatial data in tables and load
that data into the table.
l

Defining Table Columns for Spatial Data

Loading Spatial Data into Tables Using COPY

Loading Spatial Data into Tables Using INSERT

Retrieving Spatial Data from a Table

Identifying Null Spatial Objects

Defining Table Columns for Spatial Data


To define columns to contain GEOMETRY and GEOGRAPHY data, use this command:
CREATE TABLE [[db-name.]schema.]table-name (
column-name GEOMETRY[(length)],
column-name GEOGRAPHY[(length)]
);

If you omit the length specification, the default column size is 1 MB. The maximum column size is
10 MB. The upper limit is not enforced, but the HP Vertica Place functions can only accept or return
spatial data up to 10 MB.
You cannot modify the size or data type of a GEOMETRY or GEOGRAPHY column after creation.
If the column size you created is not sufficient, create a new column with the desired size. Then
copy the data from the old column, and drop the old column from the table.
You cannot import data to or export data from tables that contain spatial data of from another HP
Vertica database.
Important: A column width that is too large could impact performance. Use a column width
that fits the data without being excessively large.

Loading Spatial Data into Tables Using COPY


The following statements create a table with GEOMETRY and GEOGRAPHY columns. Then the
COPYstatement copies three rows of spatial data from a file into the table.

HP Vertica Analytic Database (7.1.x)

Page 158 of 181

Place
Working with Spatial Objects in Tables

=> CREATE TABLE locations (id INTEGER,


geom1 GEOMETRY(605),
geog2 GEOGRAPHY(605)
);

Create a text file named spatial.dat with three lines as follows:


1|POINT(2 3)|POINT(-85 15)
2|LINESTRING(-1 2, 1 5)|LINESTRING(-42.74 23.98, -62.19 23.78)
3|POLYGON((-1 2, 0 3, 1 2, -1 2))|POLYGON((-24 12, -15 23, -20 27, -24 12))

Use COPY to load the data into the table, making sure to specify the location of the file. The
following statement specifies a LONG VARCHAR(32000000) filler, which is the maximum size of a
WKT. You must specify a filler value large enough to hold the largest WKT you want to insert in the
table:
=> COPY locations(
id,
y FILLER LONG VARCHAR(605), geom1 AS ST_GeomFromText(y),
z FILLER LONG VARCHAR(605), geog2 AS ST_GeographyFromText(z)
) FROM LOCAL '<file_location>spatial.dat';

Loading Spatial Data into Tables Using INSERT


The following statements create a table with GEOMETRY and GEOGRAPHY columns. Then the
INSERTstatement inserts three rows of spatial data:
=> CREATE TABLE locations (id INTEGER,
geom1 GEOMETRY(200000),
geog2 GEOGRAPHY(200000)
);
=> INSERT INTO locations(id, geom1, geog2)
VALUES (1,
ST_GeomFromText('POINT(2 3)'),
ST_GeographyFromText('POINT(-85 15)')
);
=> INSERT INTO locations(id, geom1, geog2)
VALUES (2,
ST_GeomFromText('LINESTRING(-1 2, 1 5)'),
ST_GeographyFromText('LINESTRING(-42.74 23.98, -62.19 23.78)')
);
=> INSERT INTO locations(id, geom1, geog2)
VALUES (3,
ST_GeomFromText('POLYGON((-1 2, 0 3, 1 2, -1 2))'),
ST_GeographyFromText('POLYGON((-24 12, -15 23, -20 27, -24 12))')
);

HP Vertica Analytic Database (7.1.x)

Page 159 of 181

Place
Working with Spatial Objects in Tables

Retrieving Spatial Data from a Table


The following command retrieves the spatial data from the locations table and displays it in ASCII
format:
=> SELECT id, ST_AsText(geom1), ST_AsText(geog2)
FROM locations ORDER BY 1 ASC;
id | ST_AsText
| ST_AsText
----+----------------------------------+-------------------------------------1
| POINT (2 3)
| POINT (-85 15)
2
| LINESTRING (-1 2, 1 5)
| LINESTRING (-42.74 23.98, -62.19 23.78)
3
| POLYGON ((-1 2, 0 3, 1 2, -1 2)) | POLYGON ((-24 12, -15 23, -20 27, -24 12))

Identifying Null Spatial Objects


You can identify null GEOMETRY and GEOGRAPHY objects using the HP Vertica Place IS NULL
and IS NOT NULL constructs.
This example uses the following table, where the row with id=2 has a null value in the geog field.
=> SELECT id, ST_AsText(geom), ST_AsText(geog) FROM locations
ORDER BY 1 ASC;
id | ST_AsText
| ST_AsText
----+----------------------------------+-------------------------------------1 | POINT (2 3)
| POINT (-85 15)
2 | POINT (4 5)
|
3 | POLYGON ((-1 2, 0 3, 1 2, -1 2)) | POLYGON ((-24 12, -15 23, -20 27, -24 12))
4 | LINESTRING (-1 2, 1 5)
| LINESTRING (-42.74 23.98, -62.19 23.78)
(4 rows)

Identify all the rows that have a null geog value:


=> SELECT id, ST_AsText(geom), (ST_AsText(geog) IS NULL) FROM locations
ORDER BY 1 ASC;
id | ST_AsText | ?column?
----+----------------------------------+---------1 | POINT (2 3)
| f
2 | POINT (4 5)
| t
3 | POLYGON ((-1 2, 0 3, 1 2, -1 2)) | f
4 | LINESTRING (-1 2, 1 5)
| f
(4 rows)

Identify the rows where the geog value is not null:


=> SELECT id, ST_AsText(geom), (ST_AsText(geog) IS NOT NULL) FROM locations
ORDER BY 1 ASC;
id |
st_astext
| ?column?

HP Vertica Analytic Database (7.1.x)

Page 160 of 181

Place
Working with Spatial Objects in Tables

----+----------------------------------+---------1 | POINT (2 3)
| t
2 | POINT (4 5)
| f
3 | LINESTRING (-1 2, 1 5)
| t
4 | POLYGON ((-1 2, 0 3, 1 2, -1 2)) | t
(4 rows)

HP Vertica Analytic Database (7.1.x)

Page 161 of 181

Place
Working with Spatial Objects from Client Applications

Working with Spatial Objects from Client


Applications
The HP Vertica client driver libraries provide interfaces for connecting your client applications to
your HP Vertica database. The drivers simplify exchanging data for loading, report generation, and
other common database tasks.
There are three separate client drivers:
l

Open Database Connectivity (ODBC)The most commonly-used interface for third-party


applications and clients written in C, Python, PHP, Perl, and most other languages.

Java Database Connectivity (JDBC)Used by clients written in the Java programming


language.

ActiveX Data Objects for .NET (ADO.NET)Used by clients developed using Microsoft's .NET
Framework and written in C#, Visual Basic .NET, and other .NET languages.

HP Vertica Place supports the following new data types:


l

LONG VARCHAR

LONG VARBINARY

GEOMETRY

GEOGRAPHY

The client driver libraries support these data types; the following sections describe that support and
provide examples.

Using LONG VARCHAR and LONG VARBINARY Data


Types with ODBC
The ODBC drivers support the LONG VARCHAR and LONG VARBINARY data types similarly to
VARCHAR and VARBINARY data types. When binding input or output parameters to a LONG
VARCHAR or LONG VARBINARY column in a query, use the SQL_LONGVARCHAR and SQL_
LONGVARBINARY constants to set the column's data type. For example, to bind an input
parameter to a LONG VARCHAR column, you would use a statement that looks like this:

HP Vertica Analytic Database (7.1.x)

Page 162 of 181

Place
Working with Spatial Objects from Client Applications

rc = SQLBindParameter(hdlStmt, 1, SQL_PARAM_INPUT, SQL_C_CHAR, SQL_LONGVARCHAR,


80000, 0, (SQLPOINTER)myLongString, sizeof(myLongString), NULL);

Note: Do not use inefficient encoding formats for LONG VARBINARY and LONG VARCHAR
values. HP Vertica cannot load encoded values larger than 32MB, even if the decoded value is
less than 32 MB in size. For example, HP Vertica returns an error if you attempt to load a 32MB
LONG VARBINARY value encoded in octal format, since the octal encoding quadruples the
size of the value (each byte is converted into a backslash followed by three digits).

Using LONG VARCHAR and LONG VARBINARY Data


Types with JDBC
Using LONG VARCHAR and LONG VARBINARY data types in a JDBC client application is
similar to using VARCHAR and VARBINARY data types. The JDBC driver transparently handles
the conversion (for example, between a Java String object and a LONG VARCHAR). The
following example code demonstrates inserting and retrieving a LONG VARCHAR string. It uses
the JDBC Types class to determine the data type of the string returned by HP Vertica, although it
does not actually need to know whether the database column is a LONG VARCHAR or just a
VARCHAR in order to retrieve the value.
import java.sql.*;
import java.util.Properties;
public class LongVarcharExample {
public static void main(String[] args) {
try {
Class.forName("com.vertica.jdbc.Driver");
} catch (ClassNotFoundException e) {
System.err.println("Could not find the JDBC driver class.");
e.printStackTrace();
return;
}
Properties myProp = new Properties();
myProp.put("user", "ExampleUser");
myProp.put("password", "password123");
Connection conn;
try {
conn = DriverManager.getConnection(
"jdbc:vertica://VerticaHost:5433/ExampleDB",
myProp);
// establish connection and make a table for the data.
Statement stmt = conn.createStatement();
// How long we want the example string to be. This is
// larger than can fit into a traditional VARCHAR (which is limited
// to 65000.
int length = 100000;

HP Vertica Analytic Database (7.1.x)

Page 163 of 181

Place
Working with Spatial Objects from Client Applications

// Create a table with a LONG VARCHAR column that can store


// the string we want to insert.
stmt.execute("DROP TABLE IF EXISTS longtable CASCADE");
stmt.execute("CREATE TABLE longtable (text LONG VARCHAR(" + length
+ "))");
// Build a long string by appending an integer to a string builder
// until we hit the size limit. Will result in a string
// containing 01234567890123....
StringBuilder sb = new StringBuilder(length);
for (int i = 0; i < length; i++)
{
sb.append(i % 10);
}
String value = sb.toString();
System.out.println("String value is " + value.length() +
" characters long.");
// Create the prepared statement
PreparedStatement pstmt = conn.prepareStatement(
"INSERT INTO longtable (text)" +
" VALUES(?)");
try {
// Insert LONG VARCHAR value
System.out.println("Inserting LONG VARCHAR value");
pstmt.setString(1, value);
pstmt.addBatch();
pstmt.executeBatch();
// Query the table we created to get the value back.
ResultSet rs = null;
rs = stmt.executeQuery("SELECT * FROM longtable");
// Get metadata about the result set.
ResultSetMetaData rsmd = rs.getMetaData();
// Print the type of the first column. Should be
// LONG VARCHAR. Also check it against the Types class, to
// recognize it programmatically.
System.out.println("Column #1 data type is: " +
rsmd.getColumnTypeName(1));
if (rsmd.getColumnType(1) == Types.LONGVARCHAR) {
System.out.println("It is a LONG VARCHAR");
} else {
System.out.println("It is NOT a LONG VARCHAR");
}
// Print out the string length of the returned value.
while (rs.next()) {
// Use the same getString method to get the value that you
// use to get the value of a VARCHAR.
System.out.println("Returned string length: " +
rs.getString(1).length());
}
} catch (SQLException e) {
System.out.println("Error message: " + e.getMessage());
return; // Exit if there was an error
}

HP Vertica Analytic Database (7.1.x)

Page 164 of 181

Place
Working with Spatial Objects from Client Applications

// Cleanup
conn.close();
} catch (SQLException e) {
e.printStackTrace();
}
}
}

Note: Do not use inefficient encoding formats for LONG VARBINARY and LONG
VARCHAR values. HP Vertica cannot load encoded values larger than 32MB, even if the
decoded value is less than 32 MB in size. For example, HP Vertica returns an error if you
attempt to load a 32MB LONG VARBINARY value encoded in octal format, since the
octal encoding quadruples the size of the value (each byte is converted into a backslash
followed by three digits).

Using GEOMETRY and GEOGRAPHY Data Types in


ODBC
HP Vertica Place GEOMETRY and GEOGRAPHY data types are backed by LONG VARBINARY
native types and ODBC client applications treat them as binary data. However, these data types
have a format that is unique to HP Vertica. To manipulate this data in your C++ application, you
must use the functions in HP Vertica Place that convert them to a recognized format.
To convert a WKT or WKB to the GEOMETRY or GEOGRAPHY format, use one of the following
SQL functions:
l

ST_GeographyFromTextConverts a WKT to a GEOGRAPHY type.

ST_GeographyFromWKBConverts a WKB to a GEOGRAPHY type.

ST_GeomFromTextConverts a WKT to a GEOMETRY type.

ST_GeomFromWKBConverts a WKB to GEOMETRY type.

To convert a GEOMETRY or GEOGRAPHY object to its corresponding WKT or WKB, use one of
the following SQL functions:
l

ST_AsTextConverts a GEOMETRY or GEOGRAPHY object to a WKT, returns a


LONGVARCHAR.

HP Vertica Analytic Database (7.1.x)

Page 165 of 181

Place
Working with Spatial Objects from Client Applications

ST_AsBinaryConverts a GEOMETRY or GEOGRAPHY object to a WKB, returns a LONG


VARBINARY.

The following code example converts WKT data into GEOMETRY data using ST_GeomFromText
and stores it in a table. Later, this example retrieves the GEOMETRY data from the table and
converts it to WKT and WKB format using ST_AsText and ST_AsBinary.
// Compile on Linux using:
// g++ -g -I/opt/vertica/include -L/opt/vertica/lib64 -lodbc -o SpatialData
SpatialData.cpp
// Some standard headers
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <assert.h>
#include <sstream>
// Only needed for Windows clients
// #include <windows.h>
// Standard ODBC headers
#include <sql.h>
#include <sqltypes.h>
#include <sqlext.h>
// Helper function to print SQL error messages.
template <typename HandleT>
void reportError(int handleTypeEnum, HandleT hdl)
{
// Get the status records.
SQLSMALLINT
i, MsgLen;
SQLRETURN
ret2;
SQLCHAR
SqlState[6], Msg[SQL_MAX_MESSAGE_LENGTH];
SQLINTEGER
NativeError;
i = 1;
printf("\n");
while ((ret2 = SQLGetDiagRec(handleTypeEnum, hdl, i, SqlState, &NativeError,
Msg, sizeof(Msg), &MsgLen)) != SQL_NO_DATA) {
printf("error record %d\n", i);
printf("sqlstate: %s\n", SqlState);
printf("detailed msg: %s\n", Msg);
printf("native error code: %d\n\n", NativeError);
i++;
}
exit(EXIT_FAILURE); // bad form... but Ok for this demo
}
int main()
{
// Set up the ODBC environment
SQLRETURN ret;
SQLHENV hdlEnv;
ret = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &hdlEnv);
assert(SQL_SUCCEEDED(ret));
// Tell ODBC that the application uses ODBC 3.
ret = SQLSetEnvAttr(hdlEnv, SQL_ATTR_ODBC_VERSION,
(SQLPOINTER) SQL_OV_ODBC3, SQL_IS_UINTEGER);
assert(SQL_SUCCEEDED(ret));
// Allocate a database handle.

HP Vertica Analytic Database (7.1.x)

Page 166 of 181

Place
Working with Spatial Objects from Client Applications

SQLHDBC hdlDbc;
ret = SQLAllocHandle(SQL_HANDLE_DBC, hdlEnv, &hdlDbc);
assert(SQL_SUCCEEDED(ret));
// Connect to the database
printf("Connecting to database.\n");
const char *dsnName = "ExampleDB";
const char* userID = "dbadmin";
const char* passwd = "password123";
ret = SQLConnect(hdlDbc, (SQLCHAR*)dsnName,
SQL_NTS,(SQLCHAR*)userID,SQL_NTS,
(SQLCHAR*)passwd, SQL_NTS);
if(!SQL_SUCCEEDED(ret)) {
printf("Could not connect to database.\n");
reportError<SQLHDBC>(SQL_HANDLE_DBC, hdlDbc);
} else {
printf("Connected to database.\n");
}
// Disable AUTOCOMMIT
ret = SQLSetConnectAttr(hdlDbc, SQL_ATTR_AUTOCOMMIT, SQL_AUTOCOMMIT_OFF,
SQL_NTS);
// Set up a statement handle
SQLHSTMT hdlStmt;
SQLAllocHandle(SQL_HANDLE_STMT, hdlDbc, &hdlStmt);
// Drop any previously defined table.
ret = SQLExecDirect(hdlStmt, (SQLCHAR*)"DROP TABLE IF EXISTS polygons",
SQL_NTS);
if (!SQL_SUCCEEDED(ret)) {reportError<SQLHDBC>(SQL_HANDLE_STMT, hdlStmt);}
// Run query to create a table to hold a geometry.
ret = SQLExecDirect(hdlStmt,
(SQLCHAR*)"CREATE TABLE polygons(id INTEGER PRIMARY KEY, poly GEOMETRY);",
SQL_NTS);
if (!SQL_SUCCEEDED(ret)) {reportError<SQLHDBC>(SQL_HANDLE_STMT, hdlStmt);}
// Create the prepared statement. This will insert data into the
// table we created above. It uses the ST_GeomFromText function to convert the
// string-formatted polygon definition to a GEOMETRY datat type.
printf("Creating prepared statement\n");
ret = SQLPrepare (hdlStmt,
(SQLTCHAR*)"INSERT INTO polygons(id, poly) VALUES(?, ST_GeomFromText(?))",
SQL_NTS) ;
if (!SQL_SUCCEEDED(ret)) {reportError<SQLHDBC>(SQL_HANDLE_STMT, hdlStmt);}
SQLINTEGER id = 0;
int numBatches = 5;
int rowsPerBatch = 10;
// Polygon definition as a string.
char polygon[] = "polygon((1 1, 1 2, 2 2, 2 1, 1 1))";
// Bind variables to the parameters in the prepared SQL statement
ret = SQLBindParameter(hdlStmt, 1, SQL_PARAM_INPUT, SQL_C_LONG, SQL_INTEGER,
0, 0, &id, 0 , NULL);
if (!SQL_SUCCEEDED(ret)) {reportError<SQLHDBC>(SQL_HANDLE_STMT,hdlStmt);}
// Bind polygon string to the geometry column

HP Vertica Analytic Database (7.1.x)

Page 167 of 181

Place
Working with Spatial Objects from Client Applications

SQLBindParameter(hdlStmt, 2, SQL_PARAM_INPUT, SQL_C_CHAR, SQL_LONGVARCHAR,


strlen(polygon), 0, (SQLPOINTER)polygon, strlen(polygon), NULL);
if (!SQL_SUCCEEDED(ret)) {reportError<SQLHDBC>(SQL_HANDLE_STMT,hdlStmt);}
// Execute the insert
ret = SQLExecute(hdlStmt);
if(!SQL_SUCCEEDED(ret)) {
reportError<SQLHDBC>(SQL_HANDLE_STMT, hdlStmt);
} else {
printf("Executed batch.\n");
}
// Commit the transaction
printf("Committing transaction\n");
ret = SQLEndTran(SQL_HANDLE_DBC, hdlDbc, SQL_COMMIT);
if(!SQL_SUCCEEDED(ret)) {
reportError<SQLHDBC>(SQL_HANDLE_STMT, hdlStmt);
} else {
printf("Committed transaction\n");
}
// Now, create a query to retrieve the geometry.
ret = SQLAllocHandle(SQL_HANDLE_STMT, hdlDbc, &hdlStmt);
if (!SQL_SUCCEEDED(ret)) {reportError<SQLHDBC>(SQL_HANDLE_STMT, hdlStmt);}
printf("Getting data from table.\n");
// Execute a query to get the id, raw geometry data, and
// the geometry data as a string. Uses the ST_AsText SQL function to
// format raw data back into a string polygon definition
ret = SQLExecDirect(hdlStmt,
(SQLCHAR*)"select id,ST_AsBinary(poly),ST_AsText(poly) from polygons ORDER BY
id;",
SQL_NTS);
if (!SQL_SUCCEEDED(ret)) {reportError<SQLHDBC>(SQL_HANDLE_STMT,hdlStmt);}
SQLINTEGER idval;
// 10MB buffer to hold the raw data from the geometry (10Mb is the maximum
// length of a GEOMETRY)
SQLCHAR* polygonval = (SQLCHAR*)malloc(10485760);
SQLLEN polygonlen, polygonstrlen;
// Buffer to hold a LONGVARCHAR that can result from converting the
// geometry to a string.
SQLTCHAR* polygonstr = (SQLTCHAR*)malloc(33554432);
// Get the results of the query and print each row.
do {
ret = SQLFetch(hdlStmt);
if (SQL_SUCCEEDED(ret)) {
// ID column
ret = SQLGetData(hdlStmt, 1, SQL_C_LONG, &idval, 0, NULL);
if (!SQL_SUCCEEDED(ret)) {reportError<SQLHDBC>(SQL_HANDLE_STMT, hdlStmt);}
printf("id: %d\n",idval);
// The WKB format geometry data
ret = SQLGetData(hdlStmt, 2, SQL_C_BINARY, polygonval, 10485760,
&polygonlen);
if (!SQL_SUCCEEDED(ret)) {reportError<SQLHDBC>(SQL_HANDLE_STMT, hdlStmt);}
printf("Polygon in WKB format: ");
// Print each byte of polygonval buffer in hex format.
for (int z = 0; z < polygonlen; z++)
printf("%02x ",polygonval[z]);
printf("\n");

HP Vertica Analytic Database (7.1.x)

Page 168 of 181

Place
Working with Spatial Objects from Client Applications

// Geometry data formatted as a string.


ret = SQLGetData(hdlStmt, 3, SQL_C_TCHAR, polygonstr, 33554432,
&polygonstrlen);
if (!SQL_SUCCEEDED(ret)) {reportError<SQLHDBC>(SQL_HANDLE_STMT, hdlStmt);}
printf("Polygon in WKT format: %s\n", polygonstr);
}
} while(SQL_SUCCEEDED(ret));

free(polygonval);
free(polygonstr);
// Clean up
printf("Free handles.\n");
ret = SQLFreeHandle(SQL_HANDLE_STMT, hdlStmt);
if (!SQL_SUCCEEDED(ret)) {reportError<SQLHDBC>(SQL_HANDLE_STMT, hdlStmt);}
ret = SQLFreeHandle(SQL_HANDLE_DBC, hdlDbc);
if (!SQL_SUCCEEDED(ret)) {reportError<SQLHDBC>(SQL_HANDLE_STMT, hdlStmt);}
ret = SQLFreeHandle(SQL_HANDLE_ENV, hdlEnv);
if (!SQL_SUCCEEDED(ret)) {reportError<SQLHDBC>(SQL_HANDLE_STMT, hdlStmt);}
exit(EXIT_SUCCESS);
}

The output of running the above example is:


Connecting to database.
Connected to database.
Creating prepared statement
Executed batch.
Committing transaction
Committed transaction
Getting data from table.
id: 0
Polygon in WKB format: 01 03 00 00 00 01 00 00 00 05 00 00 00 00 00 00 00 00 00 f0 3f 00
00 00 00 00 00 f0 3f 00 00 00 00 00 00 f0 3f 00 00 00 00 00 00 00 40 00 00 00 00 00 00 00
40 00 00 00 00 00 00 00 40 00 00 00 00 00 00 00 40 00 00 00 00 00 00 f0 3f 00 00 00 00 00
00 f0 3f 00 00 00 00 00 00 f0 3f
Polygon in WKT format: POLYGON ((1 1, 1 2, 2 2, 2 1, 1 1))
Free handles.

Note: Do not use inefficient encoding formats for LONG VARBINARY and LONG VARCHAR
values. HP Vertica cannot load encoded values larger than 32 MB, even if the decoded value is
less than 32 MB in size. For example, HP Vertica returns an error if you attempt to load a 32
MB LONG VARBINARY value encoded in octal format, since the octal encoding quadruples
the size of the value (each byte is converted into a backslash followed by three digits).

HP Vertica Analytic Database (7.1.x)

Page 169 of 181

Place
Working with Spatial Objects from Client Applications

Using GEOMETRY and GEOGRAPHY Data Types in


JDBC
HP Vertica Place GEOMETRY and GEOGRAPHY data types are backed by LONG VARBINARY
native types and JDBC client applications treat them as binary data. However, these data types
have a format that is unique to HP Vertica. To manipulate this data in your Java application, you
must use the functions in HP Vertica Place that convert them to a recognized format.
To convert a WKT or WKB to the GEOMETRY or GEOGRAPHY format, use one of the following
SQL functions:
l

ST_GeographyFromTextConverts a WKT to a GEOGRAPHY type.

ST_GeographyFromWKBConverts a WKB to a GEOGRAPHY type.

ST_GeomFromTextConverts a WKT to a GEOMETRY type.

ST_GeomFromWKBConverts a WKB to GEOMETRY type.

To convert a GEOMETRY or GEOGRAPHY object to its corresponding WKT or WKB, use one of
the following SQL functions:
l

ST_AsTextConverts a GEOMETRY or GEOGRAPHY object to a WKT, returns a


LONGVARCHAR.

ST_AsBinaryConverts a GEOMETRY or GEOGRAPHY object to a WKB, returns a LONG


VARBINARY.

The following code example converts WKT and WKB data into GEOMETRY data using ST_
GeomFromText and ST_GeomFromWKB and stores it in a table. Later, this example retrieves the
GEOMETRY data from the table and converts it to WKT and WKB format using ST_AsText and ST_
AsBinary.
import java.io.InputStream;
import java.io.Reader;
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.PreparedStatement;
import java.sql.ResultSet;
import java.sql.Statement;
public class GeospatialDemo
{
public static void main(String [] args) throws Exception
{

HP Vertica Analytic Database (7.1.x)

Page 170 of 181

Place
Working with Spatial Objects from Client Applications

Class.forName("com.vertica.jdbc.Driver");
Connection conn =
DriverManager.getConnection("jdbc:vertica://localhost:5433/db",
"user", "password");
conn.setAutoCommit(false);
Statement stmt = conn.createStatement();
stmt.execute("CREATE TABLE polygons(id INTEGER PRIMARY KEY, poly GEOMETRY)");
int id = 0;
int numBatches = 5;
int rowsPerBatch = 10;
//batch inserting WKT data
PreparedStatement pstmt = conn.prepareStatement("INSERT INTO polygons
(id, poly) VALUES(?, ST_GeomFromText(?))");
for(int i = 0; i < numBatches; i++)
{
for(int j = 0; j < rowsPerBatch; j++)
{
//Insert your own WKT data here
pstmt.setInt(1, id++);
pstmt.setString(2, "polygon((1 1, 1 2, 2 2, 2 1, 1 1))");
pstmt.addBatch();
}
pstmt.executeBatch();
}
conn.commit();
pstmt.close();
//batch insert WKB data
pstmt = conn.prepareStatement("INSERT INTO polygons(id, poly)
VALUES(?, ST_GeomFromWKB(?))");
for(int i = 0; i < numBatches; i++)
{
for(int j = 0; j < rowsPerBatch; j++)
{
//Insert your own WKB data here
byte [] wkb = getWKB();
pstmt.setInt(1, id++);
pstmt.setBytes(2, wkb);
pstmt.addBatch();
}
pstmt.executeBatch();
}
conn.commit();
pstmt.close();
//selecting data as WKT
ResultSet rs = stmt.executeQuery("select ST_AsText(poly) from polygons");
while(rs.next())
{
String wkt = rs.getString(1);
Reader wktReader = rs.getCharacterStream(1);
//process the wkt as necessary
}
rs.close();

HP Vertica Analytic Database (7.1.x)

Page 171 of 181

Place
Working with Spatial Objects from Client Applications

//selecting data as WKB


rs = stmt.executeQuery("select ST_AsBinary(poly) from polygons");
while(rs.next())
{
byte [] wkb = rs.getBytes(1);
InputStream wkbStream = rs.getBinaryStream(1);
//process the wkb as necessary
}
rs.close();
//binding parameters in predicates
pstmt = conn.prepareStatement("SELECT id FROM polygons WHERE
ST_Contains(ST_GeomFromText(?), poly)");
pstmt.setString(1, "polygon((1 1, 1 2, 2 2, 2 1, 1 1))");
rs = pstmt.executeQuery();
while(rs.next())
{
int pk = rs.getInt(1);
//process the results as necessary
}
rs.close();
conn.close();
}
}

Using GEOMETRY and GEOGRAPHY Data Types in


ADO.NET
HP Vertica Place GEOMETRY and GEOGRAPHY data types are backed by LONG VARBINARY
native types and ADO.NET client applications treat them as binary data. However, these data
types have a format that is unique to HP Vertica. To manipulate this data in your C# application,
you must use the functions in HP Vertica Place that convert them to a recognized format.
To convert a WKT or WKB to the GEOMETRY or GEOGRAPHY format, use one of the following
SQL functions:
l

ST_GeographyFromTextConverts a WKT to a GEOGRAPHY type.

ST_GeographyFromWKBConverts a WKB to a GEOGRAPHY type.

ST_GeomFromTextConverts a WKT to a GEOMETRY type.

ST_GeomFromWKBConverts a WKB to GEOMETRY type.

To convert a GEOMETRY or GEOGRAPHY object to its corresponding WKT or WKB, use one of
the following SQL functions:

HP Vertica Analytic Database (7.1.x)

Page 172 of 181

Place
Working with Spatial Objects from Client Applications

ST_AsTextConverts a GEOMETRY or GEOGRAPHY object to a WKT, returns a


LONGVARCHAR.

ST_AsBinaryConverts a GEOMETRY or GEOGRAPHY object to a WKB, returns a LONG


VARBINARY.

The following C# code example converts WKT data into GEOMETRY data using ST_
GeomFromText and stores it in a table. Later, this example retrieves the GEOMETRY data from the
table and converts it to WKT and WKB format using ST_AsText and ST_AsBinary.
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Data;
using Vertica.Data.VerticaClient;
namespace ConsoleApplication
{
class Program
{
static void Main(string[] args)
{
VerticaConnectionStringBuilder builder =
new VerticaConnectionStringBuilder();
builder.Host = "VerticaHost";
builder.Database = "VMart";
builder.User = "ExampleUser";
builder.Password = "password123";
VerticaConnection _conn = new
VerticaConnection(builder.ToString());
_conn.Open();
VerticaCommand command = _conn.CreateCommand();
command.CommandText = "DROP TABLE IF EXISTS polygons";
command.ExecuteNonQuery();
command.CommandText =
"CREATE TABLE polygons (id INTEGER PRIMARY KEY, poly GEOMETRY)";
command.ExecuteNonQuery();
// Prepare to insert a polygon using a prepared statement. Use the
// ST_GeomFromtText SQl function to convert from WKT to GEOMETRY.
VerticaTransaction txn = _conn.BeginTransaction();
command.CommandText =
"INSERT into polygons VALUES(@id, ST_GeomFromText(@polygon))";
command.Parameters.Add(new
VerticaParameter("id", VerticaType.BigInt));
command.Parameters.Add(new
VerticaParameter("polygon", VerticaType.VarChar));
command.Prepare();
// Set the values for the parameters
command.Parameters["id"].Value = 0;
//
command.Parameters["polygon"].Value =
"polygon((1 1, 1 2, 2 2, 2 1, 1 1))";

HP Vertica Analytic Database (7.1.x)

Page 173 of 181

Place
Working with Spatial Objects from Client Applications

// Execute the query to insert the value


command.ExecuteNonQuery();
// Now query the table
VerticaCommand query = _conn.CreateCommand();
query.CommandText =
"SELECT id, ST_AsText(poly), ST_AsBinary(poly) FROM polygons;";
VerticaDataReader dr = query.ExecuteReader();
while (dr.Read())
{
Console.WriteLine("ID: " + dr[0]);
Console.WriteLine("Polygon WKT format data type: "
+ dr.GetDataTypeName(1) +
" Value: " + dr[1]);
// Get the WKB format of the polygon and print it out as hex.
Console.Write("Polygon WKB format data type: "
+ dr.GetDataTypeName(2));
Console.WriteLine(" Value: "
+ BitConverter.ToString((byte[])dr[2]));
}
_conn.Close();
}
}
}

The example code prints the following on the system console:


ID: 0
Polygon WKT format data type: LONG VARCHAR Value: POLYGON ((1 1, 1 2,
2 2, 2 1,1 1))
Polygon WKB format data type: LONG VARBINARY Value: 01-03-00-00-00-01
-00-00-00-05-00-00-00-00-00-00-00-00-00-F0-3F-00-00-00-00-00-00-F0-3F
-00-00-00-00-00-00-F0-3F-00-00-00-00-00-00-00-40-00-00-00-00-00-00-00
-40-00-00-00-00-00-00-00-40-00-00-00-00-00-00-00-40-00-00-00-00-00-00
-F0-3F-00-00-00-00-00-00-F0-3F-00-00-00-00-00-00-F0-3F

HP Vertica Analytic Database (7.1.x)

Page 174 of 181

Place
BestPractices for HPVerticaPlace

BestPractices for HPVerticaPlace


Hewlett-Packard recommends the following best practices for using HP Vertica Place.

Performance Optimization
Recommendation

Details

Use the minimum column size for

Performance degrades as column widths increase.

spatial data.

When creating columns for your spatial data, use the


smallest size column that can accommodate your
data. For example, use GEOMETRY(85) for point data.

Use GEOMETRYtypes where

Performance of functions on GEOGRAPHY types is

possible.

slower than functions that support GEOMETRY types.


Use GEOMETRY types where possible.

To improve the performance of the

You may improve the pruning efficiency of these

following functions, sort projections on

functions by sorting the projection on the

spatial columns:

GEOMETRYcolumn. However, sorting on a large


GEOMETRYcolumn may slow down data load.

STV_Intersect scalar function

ST_Distance

ST_Area

ST_Length

Spatial Joins with Points and Polygons


HP Vertica Place provides two ways to identify whether a set of points intersect with a set of
polygons. Depending on the size of your data set, choose the approach that gives the best
performance.
For a detailed example of best practices with spatial joins, see Best Practices for Spatial Joins.

HP Vertica Analytic Database (7.1.x)

Page 175 of 181

Place
BestPractices for HPVerticaPlace

Recommendation

Details

Use ST_Intersects to intersect a

When you intersect a set of geometries with a

constant geometry with a set of

geometry, use the ST_Intersects function. Express

geometries.

the constant geometry argument as a WKT or WKB.


For example:
ST_Intersects(geom,ST_GeomFromText(
'POLYGON((43.1 50.1,43.1 59.0,
48.9 59.0,43.1 50.1))'))
For more information, see Performing Spatial Joins
with ST_Intersects.

Use the STV_Intersect function when

Determine if a set of points intersects with a set of

you intersect a set of points with a set

polygons in a medium to large data set. First, create a

of polygons.

spatial index using STV_Create_Index. Then, use one


of the STV_Intersect functions to return the set of pairs
that intersect.
Spatial indexes provide the best performance for
accessing a large number of polygons. For more
information, see .

Perform spatial joins only on

Spatial intersection is optimized for GEOMETRYdata.

GEOMETRY data.

Spatial intersection is limited on GEOGRAPHYdata.


For GEOGRAPHY intersections see ST_Contains.

Use theSTV_Intersect scalar function

Using the STV_Intersect scalar function in a WHERE

in a WHERE clause.

clause can improve query performance. Points that lie


far away from the vicinity of the indexed polygons are
likely to be pruned.

When using the STV_Intersect

The STV_Intersect transform function does not require

transform function, partition the data

that you partition the data. However, you may improve

and use an OVER(PARTITION BEST)

performance by partitioning the data and using an

clause.

OVER(PARTITION BEST) clause.

Spatial Indexes
The STV_Create_Index function can consume large amounts of processing time and memory.
When you index new data for the first time, monitor memory usage to be sure it stays within safe
limits. Memory usage depends on:

HP Vertica Analytic Database (7.1.x)

Page 176 of 181

Place
BestPractices for HPVerticaPlace

Number of polygons

Number of vertices

Amount of overlap among polygons

Recommendation

Details

Segment polygon data when a table

Segmenting the data allows the index creation

contains a large number of polygons.

process to run in parallel. This is advantageous


because sometimes STV_Create_Index tasks cannot
be completed when large tables that are not
segmented prior to index creation.

Adjust STV_Create_Index parameters

The max_mem_mb parameter can affect the resource

as needed for memory allocation and

usage of STV_Create_Index. max_mem_mb assigns a

CPUusage.

limit to the amount of memory that STV_Create_


Index can allocate.
Default value: 256
Valid values: Any value less than or equal to the
amount of memory in the GENERAL resource pool.
Assigning a higher value results in an error.

Make changes if STV_Create_Index

Before STV_Create_Index starts creating the index, it

cannot allocate 300 MBmemory.

tries to allocate about 300 MB of memory. If that


much memory is not available, the function fails. If
you get a failure message, try these solutions:
l

Create the index at a time of less load on the


system.

Avoid concurrent index creation.

Add more memory to your system.

Create misplaced indexes again, if

When you back up your HP Vertica database, spatial

needed.

index files are not included. If you misplace an index,


use STV_Create_Index to re-create it.

HP Vertica Analytic Database (7.1.x)

Page 177 of 181

Place
BestPractices for HPVerticaPlace

Recommendation

Details

Use STV_Refresh_Index to add new or

Instead of rebuilding your spatial index each time you

updated polygons to an existing index.

add new or updated polygons to a table, you can use


STV_Refresh_Index to append the polygons to your
existing spatial index.

Checking Polygon Validity


Recommendation

Details

Run ST_IsValid to check if polygons

Many spatial functions do not check the validity of

are valid.

polygons.
l

Run ST_IsValid on all polygons to determine if they


are valid.

If your object is not valid, run STV_IsValidReason


to get information about the location of the invalid
polygon.

HP Vertica Analytic Database (7.1.x)

Page 178 of 181

Place
HP Vertica Place Limitations

HP Vertica Place Limitations


HP VerticaPlace has the following limitations:
l

You must run HP Vertica Place on the coinciding version of the HP Vertica Analytic Database
server.

You cannot access spatial indexes on newly added nodes.

Spatial Data Type Support Limitations


HP Vertica Place does not support all types of GEOMETRY and GEOGRAPHY objects. See the
respective function page for a list of objects that function supports. Spherical geometry is generally
more complex than Euclidean geometry. Thus, there are fewer spatial functions that support the
GEOGRAPHY data type.
Limitations of spatial data type support:
l

A GEOGRAPHY object is a spatial object defined on the surface of a perfect sphere of radius
6371 kilometers. This sphere approximates the shape of the earth. Other spatial programs may
use an ellipsoid to model the earth, resulting in slightly different data.

You cannot modify the size or data type of a GEOMETRY or GEOGRAPHY column after
creation.

You cannot import data to or export data from tables that contain spatial data from another HP
Vertica database.

You can only use the STV_Intersect functions with points and polygons.

GEOGRAPHY objects of type GEOMETRYCOLLECTION are not supported.

Values for longitude must be between -180 and +180 degrees. Values for latitude must be
between 90 and +90 degrees. The HP Vertica Place functions do not validate these values.

GEOMETRYCOLLECTION objects cannot contain empty objects. For example, you cannot
specify GEOMETRYCOLLECTION (LINESTRING(1 2, 3 4), POINT(5 6), POINT EMPTY).

If you pass a spatial function a NULL geometry, the function returns NULL, unless otherwise
specified. A result of NULL has no value.

HP Vertica Analytic Database (7.1.x)

Page 179 of 181

Place
HP Vertica Place Limitations

Polymorphic functions, such as NVL and GREATEST, do not accept GEOMETRY and
GEOGRAPHY arguments.

HP Vertica Analytic Database (7.1.x)

Page 180 of 181

We appreciate your feedback!


If you have comments about this document, you can contact the documentation team by email. If
an email client is configured on this system, click the link above and an email window opens with
the following information in the subject line:
Feedback on Place (Vertica Analytic Database 7.1.x)
Just add your feedback to the email and click send.
If no email client is available, copy the information above to a new message in a web mail client,
and send your feedback to vertica-docfeedback@hp.com.

HP Vertica Analytic Database

Page 181 of 181