HP Vertica 7.1.x Place

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.
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
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
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
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
Page 7 of 181
Place

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
Page 8 of 181
Place
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).
=> SELECT LON_WITHIN(15,16,0,1600);
Page 9 of 181
Place
LON_WITHIN
-----------f
(1 row)
=> SELECT LON_WITHIN(15,16,0,1700);
LON_WITHIN
-----------t
(1 row)

=> 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.
=> SELECT LL_WITHIN(16,15,12,13,445);
LL_WITHIN
----------t
(1 row)

First, determine the distance on a meridian:
=> SELECT ST_Distance(ST_GeographyFromText('POINT(15 16)'), ST_GeographyFromText('POINT
(15 12)'))/1000 <= 440;
?column?
----------
Page 10 of 181
Place
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):
=> SELECT BB_WITHIN(14,30,23.0,45,13,37);
BB_WITHIN
----------f
(1 row)

=> 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
Page 11 of 181
Place

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
Run Examples of HPVertica Place

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.

To install or upgrade HP Vertica Place:
Page 12 of 181
Place
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.
Page 13 of 181
Place
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.

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:
Page 14 of 181
Place
# 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
Page 15 of 181
Place

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.
Page 16 of 181
Place
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 ',';
>>1, POINT(42 71)
>>\.
=> SELECT gid, ST_AsText(geog) FROM point_geog;
gid |
ST_AsText
-----+--------------1 | POINT (42 71)
(1 row)
Page 17 of 181
Place
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 '|';
>>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 '|';
>>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:
Page 18 of 181
Place
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
>>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 '|';
>>1|LINESTRING(42.1 71, 41.4 70, 41.3 72.9, 42.99 71.46, 44.47 73.21)
>>\.
Page 19 of 181
Place
=> 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 '|';
>>1|MULTILINESTRING((1 5, 2 4, 5 3, 6 6),(3 5, 3 7))
>>\.
=> SELECT gid, ST_AsText(geom) FROM multilinestring_geom;
Page 20 of 181
Place
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 '|';
>>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 '|';
Page 21 of 181
Place

>>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
>>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
Page 22 of 181
Place

>>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
>>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:
Page 23 of 181
Place
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:
Page 24 of 181
Place
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.
Page 25 of 181
Place
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.
Page 26 of 181
Place
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.
Page 27 of 181
Place
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.
Page 28 of 181
Place
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.
Page 29 of 181
Place
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.
Page 30 of 181
Place
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.
Page 31 of 181
Place
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).
Page 32 of 181
Place
Page 33 of 181
Place

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

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.

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:
Page 34 of 181
Place
=> 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.
Page 35 of 181
Place

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:
Page 36 of 181
Place
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.
Page 37 of 181
Place
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
Page 38 of 181
Place
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
STV_Geography
STV_Geometry
ST_GeomFromText
ST_GeomFromWKB
Page 39 of 181
Place
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 )
Page 40 of 181
Place
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
Page 41 of 181
Place
(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.
Page 42 of 181
Place
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

Data Type
GEOMETRY GEOGRAPHY
Point
Yes
Yes
Multipoint
Yes
Yes
Linestring
Yes
Yes
Multilinestring
Yes
Yes
Polygon
Yes
Yes
Multipolygon
Yes
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
Page 43 of 181
Place
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;
>> 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
Page 44 of 181
Place
Syntax
ST_AsText(g )
Arguments
g
Spatial object for which you want the WKT string, type GEOMETRY or GEOGRAPHY
Returns
LONG VARCHAR

Data Type
GEOMETRY GEOGRAPHY
Point
Yes
Yes
Multipoint
Yes
Yes
Linestring
Yes
Yes
Multilinestring
Yes
Yes
Polygon
Yes
Yes
Multipolygon
Yes
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;
Page 45 of 181
Place

>> 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 )
Page 46 of 181
Place
Arguments
g
Spatial object for which you want the boundary, type GEOMETRY
Returns
GEOMETRY

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
------------------------------------------------------------------
Page 47 of 181
Place
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
Page 48 of 181
Place

Data Type
GEOMETRY
Point
Yes
Multipoint
Yes
Linestring
Yes
Multilinestring
Yes
Polygon
Yes
Multipolygon
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)
Page 49 of 181
Place
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)

Data Type
GEOMETRY
Point
Yes
Multipoint
Yes
Linestring
Yes
Multilinestring
Yes
Polygon
Yes
Multipolygon
Yes
Page 50 of 181
Place
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.
Page 51 of 181
Place
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
Returns
BOOLEAN

Data Type
GEOMETRY GEOGRAPHY
Point
Yes
Yes
Multipoint
Yes
No
Linestring
Yes
Yes
Multilinestring
Yes
No
Polygon
Yes
Yes
Multipolygon
Yes
Yes
No
Compatible GEOGRAPHY pairs:
Page 52 of 181
Place
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)
Page 53 of 181
Place
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)
Page 54 of 181
Place
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

Data Type
GEOMETRY
Page 55 of 181
Place
Point
Yes
Multipoint
Yes
Linestring
Yes
Multilinestring
Yes
Polygon
Yes
Multipolygon
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.
Page 56 of 181
Place
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
Returns
BOOLEAN
Page 57 of 181
Place

Data Type
GEOMETRY
Point
Yes
Multipoint
Yes
Linestring
Yes
Multilinestring
Yes
Polygon
Yes
Multipolygon
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)
Page 58 of 181
Place
=> 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 )
Page 59 of 181
Place
Arguments
g1
g2
Returns
GEOMETRY

Data Type
GEOMETRY
Point
Yes
Multipoint
Yes
Linestring
Yes
Multilinestring
Yes
Polygon
Yes
Multipolygon
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)
Page 60 of 181
Place
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.
Page 61 of 181
Place
Behavior Type
Immutable
Syntax
ST_Disjoint(g1, g2 )
Arguments
g1
g2
Returns
BOOLEAN

Data Type
GEOMETRY
Point
Yes
Multipoint
Yes
Linestring
Yes
Multilinestring
Yes
Polygon
Yes
Multipolygon
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))'),
Page 62 of 181
Place
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 )
Page 63 of 181
Place
Arguments
g1
g2
Returns
FLOAT

Data Type
GEOMETRY GEOGRAPHY
Point
Yes
Yes
Multipoint
Yes
Yes
Linestring
Yes
Yes
Multilinestring
Yes
Yes
Polygon
Yes
Yes
Multipolygon
Yes
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)'),
Page 64 of 181
Place
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

Data Type
GEOMETRY
Point
Yes
Multipoint
Yes
Linestring
Yes
Multilinestring
Yes
Polygon
Yes
Multipolygon
Yes
Page 65 of 181
Place
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.
Page 66 of 181
Place
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

Data Type
GEOMETRY GEOGRAPHY
Point
Yes
Yes
Multipoint
Yes
Yes
Linestring
Yes
Yes
Multilinestring
Yes
Yes
Polygon
Yes
Yes
Multipolygon
Yes
Yes
No
Examples
The following examples show how to use ST_Equals.
Two linestrings:
=> SELECT ST_Equals (ST_GeomFromText('LINESTRING(-1 2, 0 3)'),
Page 67 of 181
Place
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
Page 68 of 181
Place
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

Data Type
GEOGRAPHY
Point
Yes
Multipoint
Yes
Linestring
Yes
Multilinestring
Yes
Polygon
Yes
Multipolygon
Yes
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)
Page 69 of 181
Place
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
Page 70 of 181
Place

Data Type
GEOGRAPHY
Point
Yes
Multipoint
Yes
Linestring
Yes
Multilinestring
Yes
Polygon
Yes
Multipolygon
Yes
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 )
Page 71 of 181
Place
Arguments
g
Spatial object for which you want the class, type GEOMETRY or GEOGRAPHY
Returns
VARCHAR

Data Type
GEOMETRY GEOGRAPHY
Point
Yes
Yes
Multipoint
Yes
Yes
Linestring
Yes
Yes
Multilinestring
Yes
Yes
Polygon
Yes
Yes
Multipolygon
Yes
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.
Page 72 of 181
Place
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

Data Type
GEOMETRY
Page 73 of 181
Place
Point
Yes
Multipoint
Yes
Linestring
Yes
Multilinestring
Yes
Polygon
Yes
Multipolygon
Yes
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'} ])
Page 74 of 181
Place
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

Data Type
GEOMETRY
Point
Yes
Multipoint
Yes
Linestring
Yes
Multilinestring
Yes
Polygon
Yes
Multipolygon
Yes
Example
The following example shows how to use ST_GeomFromWKB.
Convert GEOMETRY into WKT:
Page 75 of 181
Place
=> 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
g2
Returns
GEOMETRY

Data Type
GEOMETRY
Point
Yes
Multipoint
Yes
Page 76 of 181
Place
Linestring
Yes
Multilinestring
Yes
Polygon
Yes
Multipolygon
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:
Page 77 of 181
Place
=> 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)
Page 78 of 181
Place
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
g2
Returns
BOOLEAN

Data Type
GEOMETRY
Point
Yes
Multipoint
Yes
Linestring
Yes
Multilinestring
Yes
Polygon
Yes
Multipolygon
Yes
Examples
The following examples show how to use ST_Intersects.
Page 79 of 181
Place
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_Intersects
-------------t
Page 80 of 181
Place
(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 )
Page 81 of 181
Place
Arguments
g
Returns
BOOLEAN

Data Type
GEOMETRY GEOGRAPHY
Point
Yes
Yes
Multipoint
Yes
Yes
Linestring
Yes
Yes
Multilinestring
Yes
Yes
Polygon
Yes
Yes
Multipolygon
Yes
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.
Page 82 of 181
Place
Behavior Type
Immutable
Syntax
ST_IsSimple(g )
Arguments
g
Returns
BOOLEAN

Data Type
GEOMETRY GEOGRAPHY
Point
Yes
Yes
Multipoint
Yes
No
Linestring
Yes
Yes
Multilinestring
Yes
No
Polygon
Yes
Yes
Multipolygon
Yes
No
No
Examples
The following examples show how to use ST_IsSimple.
Polygon does not intersect itself:
Page 83 of 181
Place
=> 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:
Page 84 of 181
Place
=> 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.
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
Page 85 of 181
Place
Syntax
ST_IsValid(g )
Arguments
g
Polygon or multipolygon to test for validity, value of type GEOMETRY
Returns
BOOLEAN

Data Type
GEOMETRY
Point
No
Multipoint
No
Linestring
No
Multilinestring
No
Polygon
Yes
Multipolygon
Yes
Examples
The following examples show how to use ST_IsValid.
Valid polygon:
Page 86 of 181
Place
=> 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:
Page 87 of 181
Place
=> 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:
Page 88 of 181
Place
=> 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:
Page 89 of 181
Place
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

Data Type
GEOMETRY GEOGRAPHY
Point
Yes
Yes
Multipoint
Yes
Yes
Linestring
Yes
Yes
Multilinestring
Yes
Yes
Page 90 of 181
Place
Polygon
Yes
Yes
Multipolygon
Yes
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
Page 91 of 181
Place
Returns
INTEGER

Data Type
GEOMETRY GEOGRAPHY
Point
No
No
Multipoint
No
No
Linestring
Yes
Yes
Multilinestring
No
No
Polygon
No
No
Multipolygon
No
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)
Page 92 of 181
Place
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
g2
Returns
BOOLEAN

Data Type
GEOMETRY
Point
Yes
Multipoint
Yes
Linestring
Yes
Multilinestring
Yes
Polygon
Yes
Multipolygon
Yes
Page 93 of 181
Place
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 )
Page 94 of 181
Place
Arguments
g
Linestring to search, type GEOMETRY or GEOGRAPHY
Point in the linestring to be returned, type INTEGER
Returns
GEOMETRY or GEOGRAPHY (POINT only)

Data Type
GEOMETRY GEOGRAPHY
Point
No
No
Multipoint
No
No
Linestring
Yes
Yes
Multilinestring
No
No
Polygon
No
No
Multipolygon
No
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('
Page 95 of 181
Place
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
g2
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
Page 96 of 181
Place
Returns
BOOLEAN

Data Type
GEOMETRY
Point
Yes
Multipoint
Yes
Linestring
Yes
Multilinestring
Yes
Polygon
Yes
Multipolygon
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.
Page 97 of 181
Place
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

Data Type
GEOMETRY GEOGRAPHY
Point
Yes
Yes
Multipoint
Yes
Yes
Linestring
Yes
Yes
Multilinestring
Yes
Yes
Polygon
Yes
Yes
Multipolygon
Yes
Yes
No
Examples
The following examples show how to use ST_SRID.
The default SRID of a GEOMETRY object is 0:
Page 98 of 181
Place
=> 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
g2
Returns
GEOMETRY
Page 99 of 181
Place

Data Type
GEOMETRY
Point
Yes
Multipoint
Yes
Linestring
Yes
Multilinestring
Yes
Polygon
Yes
Multipolygon
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
-----------------
Page 100 of 181
Place
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
Page 101 of 181
Place
Returns
BOOLEAN

Data Type
GEOMETRY
Point
Yes
Multipoint
Yes
Linestring
Yes
Multilinestring
Yes
Polygon
Yes
Multipolygon
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_Touches
-----------t
(1 row)
Two polygons touch only along part of the boundary:

ST_Touches
-----------t
(1 row)
Two polygons do not touch at any point:
Page 102 of 181
Place

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
g2
Returns
GEOMETRY

Data Type
GEOMETRY
Point
Yes
Multipoint
Yes
Linestring
Yes
Multilinestring
Yes
Polygon
Yes
Page 103 of 181
Place
Multipolygon
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).
Page 104 of 181
Place
Behavior Type
Immutable
Syntax
ST_Within(g1, g2 )
Arguments
g1
g2
Returns
BOOLEAN

Data Type
GEOMETRY GEOGRAPHY
Point
Yes
Yes
Multipoint
Yes
No
Linestring
Yes
Yes
Multilinestring
Yes
No
Polygon
Yes
Yes
Multipolygon
Yes
Yes
No

Data Type
GEOGRAPHY
Point-Point
Yes
Linestring-Point
Yes
Page 105 of 181
Place
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.
Page 106 of 181
Place
Behavior Type
Immutable
Syntax
ST_X(g )
Arguments
g
Point of type GEOMETRY or GEOGRAPHY
Returns
FLOAT

Data Type
GEOMETRY GEOGRAPHY
Point
Yes
Yes
Multipoint
No
No
Linestring
No
No
Multilinestring
No
No
Polygon
No
No
Multipolygon
No
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
Page 107 of 181
Place
(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
Page 108 of 181
Place

Data Type
GEOMETRY GEOGRAPHY
Point
Yes
Yes
Multipoint
Yes
Yes
Linestring
Yes
Yes
Multilinestring
Yes
Yes
Polygon
Yes
Yes
Multipolygon
Yes
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
Page 109 of 181
Place
(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

Data Type
GEOMETRY GEOGRAPHY
Point
Yes
Yes
Multipoint
Yes
Yes
Linestring
Yes
Yes
Multilinestring
Yes
Yes
Polygon
Yes
Yes
Multipolygon
Yes
Yes
No
Examples
The following examples show how to use ST_XMin.
Page 110 of 181
Place
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

Data Type
GEOMETRY GEOGRAPHY
Point
Yes
Yes
Page 111 of 181
Place
Multipoint
No
No
Linestring
No
No
Multilinestring
No
No
Polygon
No
No
Multipolygon
No
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.
Page 112 of 181
Place
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

Data Type
GEOMETRY GEOGRAPHY
Point
Yes
Yes
Multipoint
Yes
Yes
Linestring
Yes
Yes
Multilinestring
Yes
Yes
Polygon
Yes
Yes
Multipolygon
Yes
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
Page 113 of 181
Place
----------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
Page 114 of 181
Place

Data Type
GEOMETRY GEOGRAPHY
Point
Yes
Yes
Multipoint
Yes
Yes
Linestring
Yes
Yes
Multilinestring
Yes
Yes
Polygon
Yes
Yes
Multipolygon
Yes
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.
Page 115 of 181
Place
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.
Page 116 of 181
Place
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
Page 117 of 181
Place
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.

Data Type
GEOMETRY
Point
No
Multipoint
No
Linestring
No
Multilinestring
No
Polygon
Yes
Multipolygon
Yes
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.
Page 118 of 181
Place
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.
Page 119 of 181
Place
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 '|';
>> 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;
----------+------+-------+-------+-------+-------+-----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 '|';
>> 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;
Page 120 of 181
Place
----------+------+-------+-------+-------+-------+-----3 |
0 |
-38 |
13 |
27 |
74 |
(1 row)
See Also
l
STV_Describe_Index
STV_Drop_Index
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.
Behavior Type
Immutable
Syntax
STV_Describe_Index ([USING PARAMETERS index='index_name' ] ) OVER ()
Arguments
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.
Page 121 of 181
Place
Returns
polygons
SRID
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
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
STV_Create_Index
Page 122 of 181
Place
STV_Drop_Index
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
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)
Page 123 of 181
Place
SeeAlso
l
STV_Create_Index
STV_Describe_Index
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.
Behavior Type
Immutable
Syntax
STV_DWithin(g1, g2, d )
Arguments
g1
g2
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
Page 124 of 181
Place

Data Type
GEOMETRY GEOGRAPHY
Point
Yes
Yes
Multipoint
Yes
Yes
Linestring
Yes
Yes
Multilinestring
Yes
Yes
Polygon
Yes
Yes
Multipolygon
Yes
Yes
No

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:
Page 125 of 181
Place

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:

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
Page 126 of 181
Place
Returns
GEOGRAPHY

Data Type
GEOMETRY
Point
Yes
Multipoint
Yes
Linestring
Yes
Multilinestring
Yes
Polygon
Yes
Multipolygon
Yes
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 '|';
>> 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.
Page 127 of 181
Place
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

Data Type
GEOGRAPHY
Point
Yes
Multipoint
Yes
Linestring
Yes
Multilinestring
Yes
Polygon
Yes
Multipolygon
Yes
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
Page 128 of 181
Place
=> COPY geogs(gx filler LONG VARCHAR, geog AS ST_GeographyFromText(gx)) FROM stdin
delimiter '|';
>> 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)

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
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.
Page 129 of 181
Place
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 '|';
>> 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))
>> \.
overwrite=true,
max_mem_mb=256) OVER() FROM polygons;
----------+------+-------+-------+-------+-------+-----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 '|';
>> 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)
Page 130 of 181
Place
See Also
l

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
Name of the index created by STV_Create_Index, type VARCHAR.
Page 131 of 181
Place
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 '|';
>> 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))
>> \.
overwrite=true, max_mem_mb=256) OVER() FROM polygons;
----------+------+-------+-------+-------+-------+-----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 '|';
>> 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
Page 132 of 181
Place
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_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.
Page 133 of 181
Place
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)
Page 134 of 181
Place
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

Data Type
GEOMETRY GEOGRAPHY
Point
No
No
Multipoint
No
No
Linestring
Yes
Yes
Multilinestring
Yes
Yes
Polygon
No
No
Page 135 of 181
Place
Multipolygon
No
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.
Page 136 of 181
Place

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.

Data Type
GEOMETRY GEOGRAPHY
Point
Yes
Yes
Multipoint
Yes
Yes
Linestring
Yes
Yes
Multilinestring
Yes
Yes
Polygon
Yes
Yes
Multipolygon
Yes
Yes
No
Example
The following example shows how to use STV_NN.
Page 137 of 181
Place
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 '|';
>> 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
Page 138 of 181
Place
Arguments
g
Polygon, value of type GEOMETRY or GEOGRAPHY
Returns

Data Type
GEOMETRY GEOGRAPHY
Point
No
No
Multipoint
No
No
Linestring
No
No
Multilinestring
No
No
Polygon
Yes
Yes
Multipolygon
Yes
Yes
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:
Page 139 of 181
Place
=> 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.
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.
Page 140 of 181
Place
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
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
SRID
Page 141 of 181
Place
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.

Data Type
GEOMETRY
Point
No
Multipoint
No
Linestring
No
Multilinestring
No
Polygon
Yes
Multipolygon
Yes
Privileges
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.
Page 142 of 181
Place
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))')
----------+------+-------+-------+-------+-------+-----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))
')
polygons | SRID | min_x | min_y | max_x | max_y |
info
----------+------+-------+-------+-------+-------+---------------------2 |
0 |
0 |
0 |
3.9 | 18.2 | Polygons appended: 1
(1 row)
Page 143 of 181
Place
Refresh an index from a table:

=> CREATE TABLE pols (gid INT, geom GEOMETRY);
CREATETABLE
delimiter '|';
>> 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;
----------+------+-------+-------+-------+-------+-----3 |
0 |
-36 |
20 |
50 |
80 |
(1 row)
delimiter '|';
>> 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.
Page 144 of 181
Place
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
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 ();
Page 145 of 181
Place
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".
Page 146 of 181
Place
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)
);
Page 147 of 181
Place
(18 rows)
See Also
l

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.
Page 148 of 181
Place
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
Page 149 of 181
Place
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:
Page 150 of 181
Place
=> 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
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,
Page 151 of 181
Place
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)
Page 152 of 181
Place
...
(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.

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.
Page 153 of 181
Place
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)
>> \.
Page 154 of 181
Place
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:
Page 155 of 181
Place
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
Page 156 of 181
Place
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
Page 157 of 181
Place

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

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.

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.
Page 158 of 181
Place
=> 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';

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)')
);
VALUES (2,
ST_GeomFromText('LINESTRING(-1 2, 1 5)'),
ST_GeographyFromText('LINESTRING(-42.74 23.98, -62.19 23.78)')
);
VALUES (3,
ST_GeomFromText('POLYGON((-1 2, 0 3, 1 2, -1 2))'),
ST_GeographyFromText('POLYGON((-24 12, -15 23, -20 27, -24 12))')
);
Page 159 of 181
Place

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))

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?
Page 160 of 181
Place
----+----------------------------------+---------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)
Page 161 of 181
Place
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:
Page 162 of 181
Place
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;
Page 163 of 181
Place
// 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
}
Page 164 of 181
Place
// 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.
Page 165 of 181
Place
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);
// Allocate a database handle.
Page 166 of 181
Place
SQLHDBC hdlDbc;
ret = SQLAllocHandle(SQL_HANDLE_DBC, hdlEnv, &hdlDbc);
// 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);
// 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) ;
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
Page 167 of 181
Place
SQLBindParameter(hdlStmt, 2, SQL_PARAM_INPUT, SQL_C_CHAR, SQL_LONGVARCHAR,

strlen(polygon), 0, (SQLPOINTER)polygon, strlen(polygon), NULL);
// Execute the insert
ret = SQLExecute(hdlStmt);
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);
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);
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);
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);
printf("id: %d\n",idval);
// The WKB format geometry data
ret = SQLGetData(hdlStmt, 2, SQL_C_BINARY, polygonval, 10485760,
&polygonlen);
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");
Page 168 of 181
Place
// Geometry data formatted as a string.

ret = SQLGetData(hdlStmt, 3, SQL_C_TCHAR, polygonstr, 33554432,
&polygonstrlen);
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);
ret = SQLFreeHandle(SQL_HANDLE_DBC, hdlDbc);
ret = SQLFreeHandle(SQL_HANDLE_ENV, hdlEnv);
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).
Page 169 of 181
Place

JDBC
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.
SQL functions:
l
l

LONGVARCHAR.

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
{
Page 170 of 181
Place
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();
}
}
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();
}
}
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();
Page 171 of 181
Place
//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();
}
}

ADO.NET
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.
SQL functions:
l
Page 172 of 181
Place

LONGVARCHAR.

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)";
// 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))";
Page 173 of 181
Place
// Execute the query to insert the value

// 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
Page 174 of 181
Place

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.
Page 175 of 181
Place
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:
Page 176 of 181
Place
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.
Page 177 of 181
Place
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.
Page 178 of 181
Place

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.
Page 179 of 181
Place
Polymorphic functions, such as NVL and GREATEST, do not accept GEOMETRY and
GEOGRAPHY arguments.
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.
Page 181 of 181

HP Vertica 7.1.x Place

Enviado por

Dados do documento

Direitos autorais

Formatos disponíveis

Compartilhar este documento

Compartilhar ou incorporar documento

Opções de compartilhamento

Você considera este documento útil?

Este conteúdo é inapropriado?

Direitos autorais:

Formatos disponíveis

HP Vertica 7.1.x Place

Enviado por

Direitos autorais:

Formatos disponíveis

Place

HP Vertica Analytic Database

Document Release Date: 7/21/2016

Restricted Rights Legend

HP Vertica Analytic Database

HP Vertica Place: An Overview

Mapping Geospatial Package Functions to HP Vertica Place Functions

HP Vertica Place Installation Overview

Downloading the HP Vertica Place Package

Installing or Upgrading HP Vertica Place

Uninstalling HP Vertica Place

OGC Spatial Definitions

Spatial Object Representations

WellKnown Text (WKT)

Well-Known Binary (WKB)

HP Vertica Analytic Database

HP Vertica Place Spatial Objects

Supported Spatial Objects

Spatial Reference Identifiers (SRIDs)

HP Vertica Place Functions: An Overview

Verifying Spatial Objects Validity

Spatial Functions Categories

HP Vertica Place Functions

HP Vertica Analytic Database (7.1.x)

HP Vertica Analytic Database (7.1.x)

STV_Intersect Scalar Function

STV_Intersect Transform Function

STV_ShpSource and STV_ShpParser

Spatial Joins with ST_Intersects and STV_Intersect

HP Vertica Analytic Database (7.1.x)

When to Use ST_Intersects vs. STV_Intersect

Performing Spatial Joins with ST_Intersects

Working with Spatial Objects in Tables

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

Working with Spatial Objects from Client Applications

Using GEOMETRY and GEOGRAPHY Data Types in ODBC

Using GEOMETRY and GEOGRAPHY Data Types in JDBC

Using GEOMETRY and GEOGRAPHY Data Types in ADO.NET

BestPractices for HPVerticaPlace

Spatial Joins with Points and Polygons

Checking Polygon Validity

HP Vertica Place Limitations

We appreciate your feedback!

HP Vertica Analytic Database (7.1.x)

HP Vertica Place: An Overview

Store objects in and retrieve them from an HP Vertica database

An object contains self-intersection or self-tangency points

Shortest distance between two objects

Size of an object (length, area)

Centroid for one or more objects

Buffer around one or more 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)

Mapping Geospatial Package Functions to HP

Migrating from LAT_WITHIN to Determine Latitude

HP Vertica Place SQL Function

Migrating from LON_WITHIN to Determine Longitude

HP Vertica Analytic Database (7.1.x)

HP Vertica Place SQL Function