Академический Документы
Профессиональный Документы
Культура Документы
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.
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
9
11
12
12
12
14
16
17
Point
17
Multipoint
18
Linestring
18
Multilinestring
20
Polygon
21
Multipolygon
22
23
23
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
34
34
34
Supported SRIDs
35
36
Function-Naming Conventions
36
36
36
40
ST_Area
40
ST_AsBinary
42
ST_AsText
44
ST_Boundary
46
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
129
131
STV_IsValidReason
133
STV_LineStringPoint
135
STV_NN
136
STV_PolygonPoint
138
STV_Refresh_Index
140
STV_Rename_Index
144
STV_ShpCreateTable
146
148
150
150
Page 6 of 181
Place
Contents
151
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
158
158
158
159
160
160
162
Using LONG VARCHAR and LONG VARBINARY Data Types with ODBC
162
Using LONG VARCHAR and LONG VARBINARY Data Types with JDBC
163
165
170
172
175
Performance Optimization
175
175
Spatial Indexes
176
178
179
181
Page 7 of 181
Place
HP Vertica Place: An Overview
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
Convert to and from well-known text (WKT) and well-known binary (WKB) representations of
spatial objects
Page 8 of 181
Place
HP Vertica Place: An Overview
Page 9 of 181
Place
HP Vertica Place: An Overview
LON_WITHIN
-----------f
(1 row)
=> SELECT LON_WITHIN(15,16,0,1700);
LON_WITHIN
-----------t
(1 row)
Page 10 of 181
Place
HP Vertica Place: An Overview
f
(1 row)
=> SELECT ST_Distance(ST_GeographyFromText('POINT(15 16)'), ST_GeographyFromText('POINT
(15 12)'))/1000 <= 445;
?column?
---------t
(1 row)
Next, calculate the distance on the great circle arc from (longitude center, lat) to (longitude,
latitude):
=> SELECT ST_DISTANCE(ST_GeographyFromText('POINT(15 16)'), ST_GeographyFromText('POINT
(13 16)'))/1000 <= 440;
?column?
---------t
(1 row)
=> SELECT ST_DISTANCE(ST_GeographyFromText('POINT(15 16)'), ST_GeographyFromText('POINT
(13 16)'))/1000 <= 445;
?column?
---------t
(1 row)
TKTKTK
Page 11 of 181
Place
HP Vertica Place Installation Overview
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.
Page 12 of 181
Place
HP Vertica Place Installation Overview
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
HP Vertica Place Installation Overview
Troubleshooting:
l
You must install HP Vertica Place on all nodes before you run the HP Vertica Place installation
script.
Before you install HP Vertica Place, verify that the HP Vertica server is installed on all nodes in
your cluster. HP Vertica Place must run on the matching version of the HP Vertica Analytics
Platform.
Upgrading is not supported for Innovations versions of HP Vertica Place. You must uninstall the
Innovations .rpm or .deb package before installing the official version.
An error message that reads libgeos_c.so.1: cannot open shared object file indicates
that theHP Vertica Place .rpm or .deb was not installed on every node.
4. Log in as root.
5. Find the HP Vertica Place package that is installed:
For rpm packages:
# rpm -qa | grep vertica-place
Page 14 of 181
Place
HP Vertica Place Installation Overview
6. Uninstall the HP Vertica Place package from each node in your cluster:
For rpm packages:
# rpm -e <place_rpm_file_name>
Page 15 of 181
Place
OGC Spatial Definitions
Page 16 of 181
Place
OGC Spatial Definitions
Spatial Classes
HP Vertica Place supports several classes of objects, as defined in the OGC standards.
Point
A location in two-dimensional space that is identified by one of the following:
l
X and Y coordinates
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)
Page 17 of 181
Place
OGC Spatial Definitions
Multipoint
A set of one or more points. A multipoint object has dimension 0 and no boundary.
Examples
The following example uses a GEOMETRY multipoint:
=> CREATE TABLE mpoint_geo (gid int, geom GEOMETRY(1000));
CREATETABLE
=> COPY mpoint_geo(gid, gx filler LONGVARCHAR, geom AS ST_GeomFromText(gx)) FROM stdin
delimiter '|';
Enter data to be copied followed by a newline.
End with a backslash and a period on a line by itself.
>>1|MULTIPOINT(4 7, 8 10)
>>\.
=> SELECT gid, ST_AsText(geom) FROM mpoint_geo;
gid |
st_astext
-----+----------------------1 | MULTIPOINT (7 8, 6 9)
(1 row)
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
OGC Spatial Definitions
Examples
The following example uses the GEOMETRY type to create a table, use copy to load a linestring to
the table, and then queries the table to view the linestring:
=> CREATE TABLE linestring_geom (gid int, geom GEOMETRY(1000));
CREATETABLE
=> COPY linestring_geom(gid, gx filler LONG VARCHAR, geom AS ST_GeomFromText(gx)) FROM
stdin delimiter '|';
Enter data to be copied followed by a newline.
End with a backslash and a period on a line by itself.
>>1|LINESTRING(0 0, 1 1, 2 2, 3 4, 2 4, 1 5)
>>\.
=> SELECT gid, ST_AsText(geom) FROM linestring_geom;
gid |
ST_AsText
-----+------------------------------------------1 | LINESTRING (0 0, 1 1, 2 2, 3 4, 2 4, 1 5)
(1 row)
The following example uses the GEOGRAPHY type to create a table, use copy to load a linestring
to the table, and then queries the table to view the linestring:
=> CREATE TABLE linestring_geog (gid int, geog GEOGRAPHY(1000));
CREATETABLE
=> COPY linestring_geog(gid, gx filler LONGVARCHAR, geog AS ST_GeographyFromText(gx))
FROM stdin delimiter '|';
Enter data to be copied followed by a newline.
End with a backslash and a period on a line by itself.
>>1|LINESTRING(42.1 71, 41.4 70, 41.3 72.9, 42.99 71.46, 44.47 73.21)
>>\.
Page 19 of 181
Place
OGC Spatial Definitions
Multilinestring
A collection of zero or more linestrings. A multilinestring has no dimension. The boundary of a
multilinestring is a multipoint object containing the start and end points of all the linestrings.
The following are examples of multilinestrings:
Examples
The following example uses the GEOMETRY type to create a table, use copy to load a
multilinestring to the table, and then queries the table to view the multilinestring:
=> CREATE TABLE multilinestring_geom (gid int, geom GEOMETRY(1000));
CREATETABLE
=> COPY multilinestring_geom(gid, gx filler LONGVARCHAR, geom AS ST_GeomFromText(gx))
FROM stdin delimiter '|';
Enter data to be copied followed by a newline.
End with a backslash and a period on a line by itself.
>>1|MULTILINESTRING((1 5, 2 4, 5 3, 6 6),(3 5, 3 7))
>>\.
=> SELECT gid, ST_AsText(geom) FROM multilinestring_geom;
Page 20 of 181
Place
OGC Spatial Definitions
gid |
ST_AsText
-----+---------------------------------------------------1 | MULTILINESTRING ((1 5, 2 4, 5 3, 6 6), (3 5, 3 7))
(1 row)
The following example uses the GEOGRAPHY type to create a table, use copy to load a
multilinestring to the table, and then queries the table to view the multilinestring:
=> CREATE TABLE multilinestring_geog (gid int, geog GEOGRAPHY(1000));
CREATETABLE
=> COPY multilinestring_geog(gid, gx filler LONGVARCHAR, geog AS ST_GeographyFromText
(gx)) FROM stdin delimiter '|';
Enter data to be copied followed by a newline.
End with a backslash and a period on a line by itself.
>>1|MULTILINESTRING((42.1 71, 41.4 70, 41.3 72.9), (42.99 71.46, 44.47 73.21))
>>\.
=> SELECT gid, ST_AsText(geog) FROM multilinestring_geog;
gid |
ST_AsText
-----+---------------------------------------------------------------------------1 | MULTILINESTRING((42.1 71, 41.4 70, 41.3 72.9), (42.99 71.46, 44.47 73.21))
(1 row)
Polygon
An object identified by a set of closed linestrings. A polygon can have one or more holes, as defined
by interior boundaries, but all points must be connected. Two examples of polygons are:
Examples
The following example uses the GEOMETRY type to create a table, use copy to load a polygon into
the table, and then queries the table to view the polygon:
=> CREATE TABLE polygon_geom (gid int, geom GEOMETRY(1000));
CREATETABLE
=> COPY polygon_geom(gid, gx filler LONG VARCHAR, geom AS ST_GeomFromText(gx)) FROM stdin
delimiter '|';
Enter data to be copied followed by a newline.
Page 21 of 181
Place
OGC Spatial Definitions
The following example uses the GEOGRAPHY type to create a table, use copy to load a polygon
into the table, and then queries the table to view the polygon:
=> CREATE TABLE polygon_geog (gid int, geog GEOGRAPHY(1000));
CREATETABLE
=> COPY polygon_geog(gid, gx filler LONG VARCHAR, geog AS ST_GeographyFromText(gx)) FROM
stdin delimiter '|';
Enter data to be copied followed by a newline.
End with a backslash and a period on a line by itself.
>>1|POLYGON((42.1 71, 41.4 70, 41.3 72.9, 44.47 73.21, 42.99 71.46, 42.1 71))
>>\.
=> SELECT gid, ST_AsText(geog) FROM polygon_geog;
gid |
ST_AsText
-----+--------------------------------------------------------------------------1 | POLYGON((42.1 71, 41.4 70, 41.3 72.9, 44.47 73.21, 42.99 71.46, 42.1 71))
(1 row)
Multipolygon
A collection of zero or more polygons that do not overlap.
Examples
The following example uses the GEOMETRY type to create a table, use copy to load a
multipolygon into the table, and then queries the table to view the polygon:
=> CREATE TABLE multipolygon_geom (gid int, geom GEOMETRY(1000));
CREATETABLE
=> COPY multipolygon_geom(gid, gx filler LONG VARCHAR, geom AS ST_GeomFromText(gx)) FROM
Page 22 of 181
Place
OGC Spatial Definitions
The following example uses the GEOGRAPHY type to create a table, use copy to load a
multipolygon into the table, and then queries the table to view the polygon:
=> CREATE TABLE multipolygon_geog (gid int, geog GEOGRAPHY(1000));
CREATETABLE
=> COPY polygon_geog(gid, gx filler LONG VARCHAR, geog AS ST_GeographyFromText(gx)) FROM
stdin delimiter '|';
Enter data to be copied followed by a newline.
End with a backslash and a period on a line by itself.
>>1|POLYGON((42.1 71, 41.4 70, 41.3 72.9, 44.47 73.21, 42.99 71.46, 42.1 71))
>>\.
=> SELECT gid, ST_AsText(geog) FROM polygon_geog;
gid |
ST_AsText
-----+--------------------------------------------------------------------------1 | POLYGON(((42.1 71, 41.4 70, 41.3 72.9, 42.1 71)),((44.47 73.21, 42.99 71.46, 42.1
71, 44.47 73.21)))
(1 row)
Page 23 of 181
Place
OGC Spatial Definitions
WKT Example
Description
POINT(1 2)
MULTIPOINT(0 0,1 1)
LINESTRING(1.5 2.45,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).
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
A set containing the point (5,8) and the line from (1,3) to
(1,4)
3,1 4))
POINT EMPTY
MULTIPOINT EMPTY
LINESTRING EMPTY
MULTILINESTRING EMPTY
MULTILINESTRING(EMPTY)
POLYGON EMPTY
POLYGON(EMPTY)
MULTIPOLYGON EMPTY
MULTIPOLYGON(EMPTY)
Invalid WKTs are:
Page 24 of 181
Place
OGC Spatial Definitions
Spatial Definitions
The OGC defines properties that describe
l
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
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
OGC Spatial Definitions
Buffer
The set of all points that are within or equal to a specified distance from the boundary of a spatial
object. The distance can be positive or negative.
Positive buffer:
Negative buffer:
Contains
One spatial object contains another spatial object if its interior includes all points of the other object.
If an object such as a point or linestring only exists along a polygon's boundary, the polygon does
not contain it. If a point is on a linestring, the linestring contains it; the interior of a linestring is all the
points on the linestring except the start and end points.
Contains(a, b) is spatially equivalent to within(b, a).
Convex Hull
The smallest convex polygon that contains one or more spatial objects.
In the following figure, the dotted lines represent the convex hull for a linestring and a triangle.
Page 26 of 181
Place
OGC Spatial Definitions
Crosses
Two spatial objects cross if both of the following are true:
l
The two objects have some but not all interior points in common.
The dimension of the result of their intersection is less than the maximum dimension of the two
objects.
Disjoint
Two spatial objects have no points in common; they do not intersect or touch.
Envelope
The minimum bounding rectangle that contains a spatial object.
The envelope for the following polygon is represented by the dotted lines in the following figure.
Page 27 of 181
Place
OGC Spatial Definitions
Equals
Two spatial objects are equal when their coordinates match exactly. Synonymous with spatially
equivalent.
The order of the points do not matter in determining spatial equivalence:
l
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
OGC Spatial Definitions
Overlaps
If a spatial object shares space with another object, but is not contained within that object, the
objects overlap. The objects must overlap at their interiors; if two objects touch at a single point or
intersect only along a boundary, they do not overlap.
Relates
When a spatial object is spatially related to another object as defined by a DE-9IM pattern matrix
string.
A DE-9IM pattern matrix string identifies how two spatial objects are spatially related to each other.
For more information about the DE-9IM standard, see Understanding Spatial Relations.
Page 29 of 181
Place
OGC Spatial Definitions
Simple
For points, multipoints, linestrings, or multilinestrings, a spatial object is simple if it does not
intersect itself or has no self-tangency points.
Polygons, multipolygons, and geometrycollections are always simple.
Symmetric Difference
The set of all points of a pair of spatial objects where the objects do not intersect. This difference is
spatially equivalent to the union of the two objects less their intersection. The symmetric difference
contains the boundaries of the intersections.
In the following figure, the shaded areas represent the symmetric difference of the two rectangles.
The following figure shows the symmetric difference of two overlapping linestrings.
Page 30 of 181
Place
OGC Spatial Definitions
Union
For two or more spatial objects, the set of all points in all the objects.
Validity
For a polygon or multipolygon, when all of the following are true:
l
Page 31 of 181
Place
OGC Spatial Definitions
No two linestrings in the boundary cross. The linestrings in the boundary may touch at a point
but they cannot cross.
Any polygons in the interior must be completely contained; they cannot touch the boundary of
the exterior polygon except at a vertex.
Valid polygons:
Invalid polygon:
Within
A spatial object is considered within another spatial object when all its points are inside the other
object's interior. Thus, if a point or linestring only exists along a polygon's boundary, it is not
considered within the polygon. The polygon boundary is not part of its interior.
If a point is on a linestring, it is considered within the linestring. The interior of a linestring is all the
points along the linestring, except the start and end points.
Within(a, b) is spatially equivalent to contains(b, a).
Page 32 of 181
Place
OGC Spatial Definitions
Page 33 of 181
Place
HP Vertica Place Spatial Objects
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.
Page 34 of 181
Place
HP Vertica Place Spatial Objects
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 Functions: An Overview
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.
Page 36 of 181
Place
HP Vertica Place Functions: An Overview
Function Category
Description
Predicate functions
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
functions
Page 37 of 181
Place
HP Vertica Place Functions: An Overview
Function Category
Description
Operator functions
Function Names
l
ST_Boundary
ST_Buffer
ST_Centroid
ST_ConvexHull
ST_Difference
ST_Envelope
ST_Intersection
STV_NN
ST_SymDifference
ST_Union
A spatial object or
Rows from a table that contain spatial
objects
Page 38 of 181
Place
HP Vertica Place Functions: An Overview
Function Category
Description
Attribute functions
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
GeographyFromText
l
ST_
GeographyFromWKB
STV_Geography
STV_Geometry
ST_GeomFromText
ST_GeomFromWKB
Page 39 of 181
Place
HP Vertica Place Functions: An Overview
Function Category
Description
Function Names
l
STV_Create_Index
STV_Describe_Index
STV_Drop_Index
STV_Refresh_Index
STV_Rename_Index
STV_Intersect Scalar
Function
STV_Intersect
Transform Function
your database
HP Vertica database.
STV_
ShpCreateTable
STV_ShpSource and
STV_ShpParser
ST_Area
Calculates the area of a spatial object.
The units are:
l
Behavior Type
Immutable
Syntax
ST_Area(g )
Page 40 of 181
Place
HP Vertica Place Functions: An Overview
Arguments
g
Spatial object for which you want to calculate the area, type GEOMETRY or GEOGRAPHY
Returns
FLOAT
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)
Page 41 of 181
Place
HP Vertica Place Functions: An Overview
(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
HP Vertica Place Functions: An Overview
The Open Geospatial Consortium (OGC) defines the format of a WKB representation in the Simple
Feature Access Part 1 - Common Architecture specification.
Behavior Type
Immutable
Syntax
ST_AsBinary(g )
Arguments
g
Spatial object for which you want the WKB, type GEOMETRY or GEOGRAPHY
Returns
LONG VARBINARY
GEOMETRY GEOGRAPHY
Point
Yes
Yes
Multipoint
Yes
Yes
Linestring
Yes
Yes
Multilinestring
Yes
Yes
Polygon
Yes
Yes
Multipolygon
Yes
Yes
GeometryCollection Yes
No
Example
The following example shows how to use ST_AsBinary.
Retrieve WKB and WKT representations:
=> CREATE TABLE locations (id INTEGER, name VARCHAR(100), geom1 GEOMETRY(800), geom2
Page 43 of 181
Place
HP Vertica Place Functions: An Overview
GEOGRAPHY);
CREATE TABLE
=> COPY locations
(id, geom1x FILLER LONG VARCHAR(800), geom1 AS ST_GeomFromText(geom1x), geom2x FILLER
LONG VARCHAR (800),
geom2 AS ST_GeographyFromText(geom2x))
FROM stdin;
Enter data to be copied followed by a newline.
End with a backslash and a period on a line by itself.
>> 1|POINT(2 3)|
>> 2|LINESTRING(2 4,1 5)|
>> 3||POLYGON((-70.96 43.27,-70.67 42.95,-66.90 44.74,-67.81 46.08,-67.81 47.20,-69.22
47.43,-71.09 45.25,-70.96 43.27))
>> \.
=> SELECT id, ST_AsText(geom1),ST_AsText(geom2) FROM locations ORDER BY id ASC;
id |
ST_AsText
|
ST_AsText
----+-----------------------+--------------------------------------------1 | POINT (2 3)
|
2 | LINESTRING (2 4, 1 5) |
3 |
| POLYGON ((-70.96 43.27, -70.67 42.95, -66.9 44.74, -67.81
46.08, -67.81 47.2, -69.22 47.43, -71.09 45.25, -70.96 43.27))
=> SELECT id, ST_AsBinary(geom1),ST_AsBinary(geom2) FROM locations ORDER BY id ASC;
.
.
.
(3 rows)
Calculate the length of a WKB using the HP Vertica SQL function LENGTH:
=> SELECT LENGTH(ST_AsBinary(St_GeomFromText('POLYGON ((-1 2, 0 3, 1 2,
0 1, -1 2))')));
LENGTH
-------93
(1 row)
See Also
l
ST_AsText
ST_AsText
Creates the well-known text (WKT) representation of a spatial object. Use this function when you
need to specify a spatial object in ASCII form.
The Open Geospatial Consortium (OGC) defines the format of a WKT string in the Simple Feature
Access Part 1 - Common Architecture specification.
Behavior Type
Immutable
Page 44 of 181
Place
HP Vertica Place Functions: An Overview
Syntax
ST_AsText(g )
Arguments
g
Spatial object for which you want the WKT string, type GEOMETRY or GEOGRAPHY
Returns
LONG VARCHAR
GEOMETRY GEOGRAPHY
Point
Yes
Yes
Multipoint
Yes
Yes
Linestring
Yes
Yes
Multilinestring
Yes
Yes
Polygon
Yes
Yes
Multipolygon
Yes
Yes
GeometryCollection Yes
No
Example
The following example shows how to use ST_AsText.
Retrieve WKB and WKT representations:
=> CREATE TABLE locations (id INTEGER, name VARCHAR(100), geom1 GEOMETRY(800),
geom2 GEOGRAPHY);
CREATE TABLE
=> COPY locations
(id, geom1x FILLER LONG VARCHAR(800), geom1 AS ST_GeomFromText(geom1x), geom2x FILLER
LONG VARCHAR (800),
geom2 AS ST_GeographyFromText(geom2x))
FROM stdin;
Enter data to be copied followed by a newline.
Page 45 of 181
Place
HP Vertica Place Functions: An Overview
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
HP Vertica Place Functions: An Overview
Arguments
g
Spatial object for which you want the boundary, type GEOMETRY
Returns
GEOMETRY
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)
Page 47 of 181
Place
HP Vertica Place Functions: An Overview
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
Returns
GEOMETRY
Page 48 of 181
Place
HP Vertica Place Functions: An Overview
GEOMETRY
Point
Yes
Multipoint
Yes
Linestring
Yes
Multilinestring
Yes
Polygon
Yes
Multipolygon
Yes
GeometryCollection Yes
Usage Tips
l
If you specify a positive distance, ST_Buffer returns a polygon that represents the points within
or equal to the distance outside the object. If you specify a negative distance, ST_Buffer returns
a polygon that represents the points within or equal to the distance inside the object.
For points, multipoints, linestrings, and multilinestrings, if you specify a negative distance, ST_
Buffer returns an empty polygon.
The HP Vertica Place version of ST_Buffer returns the buffer as a polygon, so the buffer object
has corners at its vertices. It does not contain rounded corners.
Example
The following example shows how to use ST_Buffer.
Returns a GEOMETRY object:
=> SELECT ST_AsText(ST_Buffer(ST_GeomFromText('POLYGON((0 1,1 4,4 3,0 1))'),1));
ST_AsText
-----------------------------------------------------------------------------POLYGON ((-0.188847498856 -0.159920845081, -1.12155598386 0.649012935089, 0.290814745534
4.76344136152,
0.814758063466 5.02541302048, 4.95372324225 3.68665254814, 5.04124517538 2.45512549204,
-0.188847498856 -0.159920845081))
(1 row)
Page 49 of 181
Place
HP Vertica Place Functions: An Overview
ST_Centroid
Calculates the geometric centerthe centroidof a spatial object. If points or linestrings or both
are present in a geometry with polygons, only the polygons contribute to the calculation of the
centroid. Similarly, if points are present with linestrings, the points do not contribute to the
calculation of the centroid.
To calculate the centroid of a GEOGRAPHY object, see the examples for STV_Geometry and
STV_Geography.
Behavior Type
Immutable
Syntax
ST_Centroid(g )
Arguments
g
Spatial object for which you want to calculate the centroid, type GEOMETRY
Returns
GEOMETRY (POINT only)
GEOMETRY
Point
Yes
Multipoint
Yes
Linestring
Yes
Multilinestring
Yes
Polygon
Yes
Multipolygon
Yes
GeometryCollection Yes
Page 50 of 181
Place
HP Vertica Place Functions: An Overview
Examples
The following examples show how to use ST_Centroid.
Calculate the centroid for a polygon:
=> SELECT ST_AsText(ST_Centroid(ST_GeomFromText('POLYGON((-1 -1,2 2,-1 2,
-1 -1))')));
ST_AsText
-----------POINT (-0 1)
(1 row)
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
HP Vertica Place Functions: An Overview
If an object such as a point or linestring only exists along a spatial object's boundary, then ST_
Contains returns false. The interior of a linestring is all the points on the linestring except the start
and end points.
ST_Contains(g1, g2) is functionally equivalent to ST_Within(g2, g1).
Behavior Type
Immutable
Syntax
ST_Contains(g1, g2 )
Arguments
g1
g2
Returns
BOOLEAN
GEOMETRY GEOGRAPHY
Point
Yes
Yes
Multipoint
Yes
No
Linestring
Yes
Yes
Multilinestring
Yes
No
Polygon
Yes
Yes
Multipolygon
Yes
Yes
GeometryCollection Yes
No
Page 52 of 181
Place
HP Vertica Place Functions: An Overview
Data Type
GEOGRAPHY
Point-Point
Yes
Linestring-Point
Yes
Polygon-Point
Yes
Multipolygon-Point Yes
Examples
The following examples show how to use ST_Contains.
The first polygon does not completely contain the second polygon:
=> SELECT ST_Contains(ST_GeomFromText('POLYGON((0 2,1 1,0 -1,0 2))'),
ST_GeomFromText('POLYGON((-1 3,2 1,0 -3,-1 3))'));
ST_Contains
------------f
(1 row)
Page 53 of 181
Place
HP Vertica Place Functions: An Overview
Page 54 of 181
Place
HP Vertica Place Functions: An Overview
See Also
l
ST_Overlaps
ST_Within
ST_ConvexHull
Calculates the smallest convex GEOMETRY object that contains a GEOMETRY object.
Behavior Type
Immutable
Syntax
ST_ConvexHull(g )
Arguments
g
Spatial object for which you want the convex hull, type GEOMETRY
Returns
GEOMETRY
GEOMETRY
Page 55 of 181
Place
HP Vertica Place Functions: An Overview
Point
Yes
Multipoint
Yes
Linestring
Yes
Multilinestring
Yes
Polygon
Yes
Multipolygon
Yes
GeometryCollection Yes
Examples
The following examples show how to use ST_ConvexHull.
For a pair of points in a geometry collection:
=> SELECT ST_AsText(ST_ConvexHull(ST_GeomFromText('GEOMETRYCOLLECTION(
POINT(1 1),POINT(0 0))')));
ST_AsText
----------------------LINESTRING (1 1, 0 0)
(1 row)
The solid lines represent the original geometry collection and the dashed lines represent the convex
hull.
Page 56 of 181
Place
HP Vertica Place Functions: An Overview
ST_Crosses
Determines if one GEOMETRY object spatially crosses another GEOMETRY object. If two objects
touch only at a border, ST_Crosses returns FALSE.
Two objects spatially cross when both of the following are true:
l
The two objects have some, but not all, interior points in common.
The dimension of the result of their intersection is less than the maximum dimension of the two
objects.
Behavior Type
Immutable
Syntax
ST_Crosses(g1, g2 )
Arguments
g1
g2
Returns
BOOLEAN
Page 57 of 181
Place
HP Vertica Place Functions: An Overview
GEOMETRY
Point
Yes
Multipoint
Yes
Linestring
Yes
Multilinestring
Yes
Polygon
Yes
Multipolygon
Yes
GeometryCollection Yes
Examples
The following examples show how to use ST_Crosses.
Page 58 of 181
Place
HP Vertica Place Functions: An Overview
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
HP Vertica Place Functions: An Overview
Arguments
g1
g2
Returns
GEOMETRY
GEOMETRY
Point
Yes
Multipoint
Yes
Linestring
Yes
Multilinestring
Yes
Polygon
Yes
Multipolygon
Yes
GeometryCollection Yes
Examples
The following examples show how to use ST_Difference.
Two overlapping linestrings:
=> SELECT ST_AsText(ST_Difference(ST_GeomFromText('LINESTRING(0 0,0 2)'),
ST_GeomFromText('LINESTRING(0 1,0 2)')));
ST_AsText
----------------------LINESTRING (0 0, 0 1)
(1 row)
=> SELECT ST_AsText(ST_Difference(ST_GeomFromText('LINESTRING(0 0,0 3)'),
ST_GeomFromText('LINESTRING(0 1,0 2)')));
ST_AsText
-----------------------------------------MULTILINESTRING ((0 0, 0 1), (0 2, 0 3))
(1 row)
Page 60 of 181
Place
HP Vertica Place Functions: An Overview
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
HP Vertica Place Functions: An Overview
Behavior Type
Immutable
Syntax
ST_Disjoint(g1, g2 )
Arguments
g1
g2
Returns
BOOLEAN
GEOMETRY
Point
Yes
Multipoint
Yes
Linestring
Yes
Multilinestring
Yes
Polygon
Yes
Multipolygon
Yes
GeometryCollection Yes
Examples
The following examples show how to use ST_Disjoint.
Two non-intersecting or touching polygons:
=> SELECT ST_Disjoint (ST_GeomFromText('POLYGON((-1 2,0 3,0 1,-1 2))'),
Page 62 of 181
Place
HP Vertica Place Functions: An Overview
ST_GeomFromText('POLYGON((1 0, 1 1, 2 2, 1 0))'));
ST_Disjoint
------------t
(1 row)
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
HP Vertica Place Functions: An Overview
Arguments
g1
g2
Returns
FLOAT
GEOMETRY GEOGRAPHY
Point
Yes
Yes
Multipoint
Yes
Yes
Linestring
Yes
Yes
Multilinestring
Yes
Yes
Polygon
Yes
Yes
Multipolygon
Yes
Yes
GeometryCollection Yes
No
Examples
The following examples show how to use ST_Distance.
Distance between two polygons:
=> SELECT ST_Distance(ST_GeomFromText('POLYGON((-1 -1,2 2,0 1,-1 -1))'),
ST_GeomFromText('POLYGON((3 3,1 5,-1 3,0 4,2 6,3 3))'));
ST_Distance
----------------1.4142135623731
(1 row)
Page 64 of 181
Place
HP Vertica Place Functions: An Overview
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
GEOMETRY
Point
Yes
Multipoint
Yes
Linestring
Yes
Multilinestring
Yes
Polygon
Yes
Multipolygon
Yes
GeometryCollection Yes
Page 65 of 181
Place
HP Vertica Place Functions: An Overview
Example
The following example shows how to use ST_Envelope.
Returns the minimum bounding rectangle:
=> SELECT ST_AsText(ST_Envelope(ST_GeomFromText('POLYGON((0 0,1 1,1 2,2 2,
2 1,3 0,1.5 -1.5,0 0))')));
ST_AsText
------------------------------------------POLYGON ((0 -1.5, 3 -1.5, 3 2, 0 2, 0 -1.5))
(1 row)
ST_Equals
Determines if two spatial objects are spatially equivalent. The coordinates of the two objects and
their WKT/WKB representations must match exactly for ST_Equals to return TRUE.
The order of the points do not matter in determining spatial equivalence:
l
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
HP Vertica Place Functions: An Overview
Behavior Type
Immutable
Syntax
ST_Equals(g1, g2 )
Arguments
g1
g2
Returns
BOOLEAN
GEOMETRY GEOGRAPHY
Point
Yes
Yes
Multipoint
Yes
Yes
Linestring
Yes
Yes
Multilinestring
Yes
Yes
Polygon
Yes
Yes
Multipolygon
Yes
Yes
GeometryCollection Yes
No
Examples
The following examples show how to use ST_Equals.
Two linestrings:
=> SELECT ST_Equals (ST_GeomFromText('LINESTRING(-1 2, 0 3)'),
Page 67 of 181
Place
HP Vertica Place Functions: An Overview
ST_GeomFromText('LINESTRING(0 3, -1 2)'));
ST_Equals
-------------t
(1 row)
Two polygons:
=> SELECT ST_Equals (ST_GeographyFromText('POLYGON((43.22 42.21,40.3 39.88,
42.1 50.03,43.22 42.21))'),ST_GeographyFromText('POLYGON((43.22 42.21,
40.3 39.88,42.1 50.31,43.22 42.21))'));
ST_Equals
-------------f
(1 row)
ST_GeographyFromText
Converts a well-known text (WKT) string into its corresponding GEOGRAPHY object. Use this
function to convert a WKT string into the format expected by the HP Vertica Place functions.
A GEOGRAPHY object is a spatial object with coordinates (longitude, latitude) defined on the
surface of the earth. Coordinates are expressed in degrees (longitude, latitude) from reference
planes dividing the earth.
The maximum size of a GEOGRAPHY object is 10 MB. If you pass a WKT to ST_
GeographyFromText, the result is a spatial object whose size is greater than 10 MB, ST_
GeographyFromText returns an error.
The Open Geospatial Consortium (OGC) defines the format of a WKT string in Section 7 in the
Simple Feature Access Part 1 - Common Architecture specification.
Behavior Type
Immutable
Syntax
ST_GeographyFromText(wkt [USING PARAMETERS ignore_errors={'y'|'n'} ] )
Arguments
wkt
Page 68 of 181
Place
HP Vertica Place Functions: An Overview
ignore_errors
Returns
GEOGRAPHY
GEOGRAPHY
Point
Yes
Multipoint
Yes
Linestring
Yes
Multilinestring
Yes
Polygon
Yes
Multipolygon
Yes
GeometryCollection No
Example
The following example shows how to use ST_GeographyFromText.
Convert WKT into a GEOGRAPHY object:
=> CREATE TABLE wkt_ex (g GEOGRAPHY);
CREATE TABLE
=> INSERT INTO wkt_ex VALUES(ST_GeographyFromText('POLYGON((1 2,3 4,2 3,1 2))'));
OUTPUT
-------1
(1 row)
Page 69 of 181
Place
HP Vertica Place Functions: An Overview
ST_GeographyFromWKB
Converts a well-known binary (WKB) value into its corresponding GEOGRAPHY object. Use this
function to convert a WKB into the format expected by HP Vertica Place functions.
A GEOGRAPHY object is a spatial object defined on the surface of the earth. Coordinates are
expressed in degrees (longitude, latitude) from reference planes dividing the earth. All calculations
are in meters.
The maximum size of a GEOGRAPHY object is 10 MB. If you pass a WKB to ST_
GeographyFromWKB that results in a spatial object whose size is greater than 10 MB, ST_
GeographyFromWKB returns an error.
The Open Geospatial Consortium (OGC) defines the format of a WKB representation in Section 8 in
the Simple Feature Access Part 1 - Common Architecture specification.
Behavior Type
Immutable
Syntax
ST_GeographyFromWKB(wkb [USING PARAMETERS ignore_errors={'y'|'n'} ] )
Arguments
wkb
ignore_errors
Returns
GEOGRAPHY
Page 70 of 181
Place
HP Vertica Place Functions: An Overview
GEOGRAPHY
Point
Yes
Multipoint
Yes
Linestring
Yes
Multilinestring
Yes
Polygon
Yes
Multipolygon
Yes
GeometryCollection No
Example
The following example shows how to use ST_GeographyFromWKB.
Convert WKB into a GEOGRAPHY object:
=> CREATE TABLE wkb_ex (g GEOGRAPHY);
CREATE TABLE
=> INSERT INTO wkb_ex VALUES(ST_GeographyFromWKB(X'0103000000010000000 ... );
OUTPUT
-------1
(1 row)
ST_GeometryType
Determines the class of a spatial object.
Behavior Type
Immutable
Syntax
ST_GeometryType(g )
Page 71 of 181
Place
HP Vertica Place Functions: An Overview
Arguments
g
Spatial object for which you want the class, type GEOMETRY or GEOGRAPHY
Returns
VARCHAR
GEOMETRY GEOGRAPHY
Point
Yes
Yes
Multipoint
Yes
Yes
Linestring
Yes
Yes
Multilinestring
Yes
Yes
Polygon
Yes
Yes
Multipolygon
Yes
Yes
GeometryCollection Yes
No
Example
The following example shows how to use ST_GeometryType.
Returns spatial class:
=> SELECT ST_GeometryType(ST_GeomFromText('GEOMETRYCOLLECTION(LINESTRING(1 1,
2 2), POLYGON((1 3,4 5,2 2,1 3)))'));
ST_GeometryType
----------------------ST_GeometryCollection
(1 row)
ST_GeomFromText
Converts a well-known text (WKT) string into its corresponding GEOMETRY object. Use this
function to convert a WKT string into the format expected by the HP Vertica Place functions.
Page 72 of 181
Place
HP Vertica Place Functions: An Overview
A GEOMETRY object is a spatial object defined by the coordinates of a plane. Coordinates are
expressed as points on a Cartesian plane (x,y). SRID values of 0 to 232-1 are valid. SRID values
outside of this range will generate an error.
The maximum size of a GEOMETRY object is 10 MB. If you pass a WKT to ST_GeomFromText
and the result is a spatial object whose size is greater than 10 MB, ST_GeomFromText returns an
error.
The Open Geospatial Consortium (OGC) defines the format of a WKT representation. See section 7
in the Simple Feature Access Part 1 - Common Architecture specification.
Behavior Type
Immutable
Syntax
ST_GeomFromText(wkt [, srid] [USING PARAMETERS ignore_errors={'y'|'n'} ])
Arguments
wkt
srid
ignore_errors
Returns
GEOMETRY
GEOMETRY
Page 73 of 181
Place
HP Vertica Place Functions: An Overview
Point
Yes
Multipoint
Yes
Linestring
Yes
Multilinestring
Yes
Polygon
Yes
Multipolygon
Yes
GeometryCollection No
Example
The following example shows how to use ST_GeomFromText.
Convert WKT into a GEOMETRY object:
=> SELECT ST_Area(ST_GeomFromText('POLYGON((1 1,2 3,3 5,0 5,1 -2,0 0,1 1))'));
ST_Area
--------6
(1 row)
ST_GeomFromWKB
Converts the well-known binary (WKB) value to its corresponding GEOMETRY object. Use this
function to convert a WKB into the format expected by many of the HP Vertica Place functions.
A GEOMETRY object is a spatial object with coordinates (x,y) defined in the Cartesian plane.
The maximum size of a GEOMETRY object is 10 MB. If you pass a WKB to ST_GeomFromWKB and
the result is a spatial object whose size is greater than 10 MB, ST_GeomFromWKB returns an error.
The Open Geospatial Consortium (OGC) defines the format of a WKB representation in section 8 in
the Simple Feature Access Part 1 - Common Architecture specification.
Behavior Type
Immutable
Syntax
ST_GeomFromWKB(wkb[, srid]
[USING PARAMETERS ignore_errors={'y'|'n'} ])
Page 74 of 181
Place
HP Vertica Place Functions: An Overview
Arguments
wkb
srid
ignore_errors
Returns
GEOMETRY
GEOMETRY
Point
Yes
Multipoint
Yes
Linestring
Yes
Multilinestring
Yes
Polygon
Yes
Multipolygon
Yes
GeometryCollection Yes
Example
The following example shows how to use ST_GeomFromWKB.
Convert GEOMETRY into WKT:
Page 75 of 181
Place
HP Vertica Place Functions: An Overview
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
GEOMETRY
Point
Yes
Multipoint
Yes
Page 76 of 181
Place
HP Vertica Place Functions: An Overview
Linestring
Yes
Multilinestring
Yes
Polygon
Yes
Multipolygon
Yes
GeometryCollection Yes
Examples
The following examples show how to use ST_Intersection.
Two polygons intersect at a single point:
Two polygons:
Page 77 of 181
Place
HP Vertica Place Functions: An Overview
Page 78 of 181
Place
HP Vertica Place Functions: An Overview
ST_Intersects
Determines if two GEOMETRY objects intersect or touch at a single point. If ST_Disjoint returns
TRUE, ST_Intersects returns FALSE for the same GEOMETRY objects.
Behavior Type
Immutable
Syntax
ST_Intersects(g1, g2 )
Arguments
g1
g2
Returns
BOOLEAN
GEOMETRY
Point
Yes
Multipoint
Yes
Linestring
Yes
Multilinestring
Yes
Polygon
Yes
Multipolygon
Yes
GeometryCollection Yes
Examples
The following examples show how to use ST_Intersects.
Page 79 of 181
Place
HP Vertica Place Functions: An Overview
Page 80 of 181
Place
HP Vertica Place Functions: An Overview
(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
HP Vertica Place Functions: An Overview
Arguments
g
Returns
BOOLEAN
GEOMETRY GEOGRAPHY
Point
Yes
Yes
Multipoint
Yes
Yes
Linestring
Yes
Yes
Multilinestring
Yes
Yes
Polygon
Yes
Yes
Multipolygon
Yes
Yes
GeometryCollection Yes
No
Example
The following example shows how to use ST_IsEmpty.
An empty polygon:
=> SELECT ST_IsEmpty(ST_GeomFromText('GeometryCollection EMPTY'));
ST_IsEmpty
-----------t
(1 row)
ST_IsSimple
Determines if a spatial object does not intersect itself or touch its own boundary at any point.
Page 82 of 181
Place
HP Vertica Place Functions: An Overview
Behavior Type
Immutable
Syntax
ST_IsSimple(g )
Arguments
g
Returns
BOOLEAN
GEOMETRY GEOGRAPHY
Point
Yes
Yes
Multipoint
Yes
No
Linestring
Yes
Yes
Multilinestring
Yes
No
Polygon
Yes
Yes
Multipolygon
Yes
No
GeometryCollection No
No
Examples
The following examples show how to use ST_IsSimple.
Polygon does not intersect itself:
Page 83 of 181
Place
HP Vertica Place Functions: An Overview
Page 84 of 181
Place
HP Vertica Place Functions: An Overview
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.
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
HP Vertica Place Functions: An Overview
Syntax
ST_IsValid(g )
Arguments
g
Returns
BOOLEAN
GEOMETRY
Point
No
Multipoint
No
Linestring
No
Multilinestring
No
Polygon
Yes
Multipolygon
Yes
GeometryCollection No
Examples
The following examples show how to use ST_IsValid.
Valid polygon:
Page 86 of 181
Place
HP Vertica Place Functions: An Overview
Invalid polygon:
Invalid polygon:
Page 87 of 181
Place
HP Vertica Place Functions: An Overview
Invalid multipolygon:.
Page 88 of 181
Place
HP Vertica Place Functions: An Overview
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
HP Vertica Place Functions: An Overview
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
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
GEOMETRY GEOGRAPHY
Point
Yes
Yes
Multipoint
Yes
Yes
Linestring
Yes
Yes
Multilinestring
Yes
Yes
Page 90 of 181
Place
HP Vertica Place Functions: An Overview
Polygon
Yes
Yes
Multipolygon
Yes
Yes
GeometryCollection Yes
No
Examples
The following examples show how to use ST_Length.
Returns length in Cartesian coordinate units:
=> SELECT ST_Length(ST_GeomFromText('LINESTRING(-1 -1,2 2,4 5,6 7)'));
ST_Length
-----------------10.6766190873295
(1 row)
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
HP Vertica Place Functions: An Overview
Returns
INTEGER
GEOMETRY GEOGRAPHY
Point
No
No
Multipoint
No
No
Linestring
Yes
Yes
Multilinestring
No
No
Polygon
No
No
Multipolygon
No
No
GeometryCollection No
No
Examples
The following examples show how to use ST_NumPoints.
Returns the number of vertices in a linestring:
=> SELECT ST_NumPoints(ST_GeomFromText('LINESTRING(1.33 1.56,2.31 3.4,2.78 5.82,
3.76 3.9,4.11 3.27,5.85 4.34,6.9 4.231,7.61 5.77)'));
ST_NumPoints
-------------8
(1 row)
Page 92 of 181
Place
HP Vertica Place Functions: An Overview
ST_Overlaps
Determines if a GEOMETRY object shares space with another GEOMETRY object, but is not
completely contained within that object. They must overlap at their interiors. If two objects touch at
a single point or intersect only along a boundary, they do not overlap. Both parameters must have
the same dimension; otherwise, ST_Overlaps returns FALSE.
Behavior Type
Immutable
Syntax
ST_Overlaps (g1, g2 )
Arguments
g1
g2
Returns
BOOLEAN
GEOMETRY
Point
Yes
Multipoint
Yes
Linestring
Yes
Multilinestring
Yes
Polygon
Yes
Multipolygon
Yes
GeometryCollection Yes
Page 93 of 181
Place
HP Vertica Place Functions: An Overview
Examples
The following examples show how to use ST_Overlaps.
Polygon_1 overlaps but does not completely contain Polygon_2:
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
HP Vertica Place Functions: An Overview
Arguments
g
Returns
GEOMETRY or GEOGRAPHY (POINT only)
GEOMETRY GEOGRAPHY
Point
No
No
Multipoint
No
No
Linestring
Yes
Yes
Multilinestring
No
No
Polygon
No
No
Multipolygon
No
No
GeometryCollection No
No
Examples
The following examples show how to use STV_Create_Index.
Returns the fifth point:
=> SELECT ST_AsText(ST_PointN(ST_GeomFromText('
LINESTRING(1 1,1 3,2 5,3 3,4 3,5 4,6 4,7 5)'),5));
ST_AsText
-----------POINT(4 3)
(1 row)
Page 95 of 181
Place
HP Vertica Place Functions: An Overview
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
HP Vertica Place Functions: An Overview
Returns
BOOLEAN
GEOMETRY
Point
Yes
Multipoint
Yes
Linestring
Yes
Multilinestring
Yes
Polygon
Yes
Multipolygon
Yes
GeometryCollection Yes
Examples
The following examples show how to use ST_Relate.
The DE-9IM pattern for "equals" is 'T*F**FFF2':
=> SELECT ST_Relate(ST_GeomFromText('LINESTRING(0 1,2 2)'),
ST_GeomFromText('LINESTRING(2 2,0 1)'), 'T*F**FFF2');
ST_Relate
-------------t
(1 row)
ST_SRID
Identifies the spatial reference system identifier (SRID) stored with a spatial object.
Page 97 of 181
Place
HP Vertica Place Functions: An Overview
The SRID of a GEOMETRY object can only be determined when passing an SRID to either ST_
GeomFromText or ST_GeomFromWKB. ST_SRID returns this stored value. SRID values of 0 to
232-1 are valid.
Behavior Type
Immutable
Syntax
ST_SRID(g )
Arguments
g
Spatial object for which you want the SRID, type GEOMETRY or GEOGRAPHY
Returns
INTEGER
GEOMETRY GEOGRAPHY
Point
Yes
Yes
Multipoint
Yes
Yes
Linestring
Yes
Yes
Multilinestring
Yes
Yes
Polygon
Yes
Yes
Multipolygon
Yes
Yes
GeometryCollection Yes
No
Examples
The following examples show how to use ST_SRID.
The default SRID of a GEOMETRY object is 0:
Page 98 of 181
Place
HP Vertica Place Functions: An Overview
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
HP Vertica Place Functions: An Overview
GEOMETRY
Point
Yes
Multipoint
Yes
Linestring
Yes
Multilinestring
Yes
Polygon
Yes
Multipolygon
Yes
GeometryCollection Yes
Examples
The following examples show how to use ST_SymDifference.
Returns the two linestrings:
Place
HP Vertica Place Functions: An Overview
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
g2
Place
HP Vertica Place Functions: An Overview
Returns
BOOLEAN
GEOMETRY
Point
Yes
Multipoint
Yes
Linestring
Yes
Multilinestring
Yes
Polygon
Yes
Multipolygon
Yes
GeometryCollection Yes
Examples
The following examples show how to use ST_Touches.
Two polygons touch at a single point:
=> SELECT ST_Touches(ST_GeomFromText('POLYGON((-1 2,0 3,0 1,-1 2))'),
ST_GeomFromText('POLYGON((1 3,0 3,1 2,1 3))'));
ST_Touches
-----------t
(1 row)
Place
HP Vertica Place Functions: An Overview
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
GEOMETRY
Point
Yes
Multipoint
Yes
Linestring
Yes
Multilinestring
Yes
Polygon
Yes
Place
HP Vertica Place Functions: An Overview
Multipolygon
Yes
GeometryCollection Yes
Example
The following example shows how to use ST_Union.
Returns a polygon that represents all the points contained in these two polygons:
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).
Place
HP Vertica Place Functions: An Overview
Behavior Type
Immutable
Syntax
ST_Within(g1, g2 )
Arguments
g1
g2
Returns
BOOLEAN
GEOMETRY GEOGRAPHY
Point
Yes
Yes
Multipoint
Yes
No
Linestring
Yes
Yes
Multilinestring
Yes
No
Polygon
Yes
Yes
Multipolygon
Yes
Yes
GeometryCollection Yes
No
GEOGRAPHY
Point-Point
Yes
Linestring-Point
Yes
Place
HP Vertica Place Functions: An Overview
Polygon-Point
Yes
Multipolygon-Point Yes
Examples
The following examples show how to use ST_Within.
The first polygon is completely contained within the second polygon:
=> SELECT ST_Within(ST_GeomFromText('POLYGON((0 2,1 1,0 -1,0 2))'),
ST_GeomFromText('POLYGON((-1 3,2 1,0 -3,-1 3))'));
ST_Within
----------t
(1 row)
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.
Place
HP Vertica Place Functions: An Overview
Behavior Type
Immutable
Syntax
ST_X(g )
Arguments
g
Returns
FLOAT
GEOMETRY GEOGRAPHY
Point
Yes
Yes
Multipoint
No
No
Linestring
No
No
Multilinestring
No
No
Polygon
No
No
Multipolygon
No
No
GeometryCollection No
No
Examples
The following examples show how to use ST_X.
Returns the x-coordinate:
=> SELECT ST_X(ST_GeomFromText('POINT(3.4 1.25)'));
ST_X
----3.4
Place
HP Vertica Place Functions: An Overview
(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
Place
HP Vertica Place Functions: An Overview
GEOMETRY GEOGRAPHY
Point
Yes
Yes
Multipoint
Yes
Yes
Linestring
Yes
Yes
Multilinestring
Yes
Yes
Polygon
Yes
Yes
Multipolygon
Yes
Yes
GeometryCollection Yes
No
Examples
The following examples show how to use ST_XMax.
Returns the maximum x-coordinate within a rectangle:
=> SELECT ST_XMax(ST_GeomFromText('POLYGON((0 1,0 2,1 2,1 1,0 1))'));
ST_XMax
----------1
(1 row)
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
Place
HP Vertica Place Functions: An Overview
Behavior Type
Immutable
Syntax
ST_XMin(g )
Arguments
g
Spatial object for which you want to find the minimum x-coordinate, type GEOMETRY or
GEOGRAPHY.
Returns
GEOMETRY or GEOGRAPHY
GEOMETRY GEOGRAPHY
Point
Yes
Yes
Multipoint
Yes
Yes
Linestring
Yes
Yes
Multilinestring
Yes
Yes
Polygon
Yes
Yes
Multipolygon
Yes
Yes
GeometryCollection Yes
No
Examples
The following examples show how to use ST_XMin.
Place
HP Vertica Place Functions: An Overview
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
Returns
FLOAT
GEOMETRY GEOGRAPHY
Point
Yes
Yes
Place
HP Vertica Place Functions: An Overview
Multipoint
No
No
Linestring
No
No
Multilinestring
No
No
Polygon
No
No
Multipolygon
No
No
GeometryCollection No
No
Examples
The following examples show how to use ST_Y.
Returns the y-coordinate:
=> SELECT ST_Y(ST_GeomFromText('POINT(3 5.25)'));
ST_Y
-----5.25
(1 row)
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.
Place
HP Vertica Place Functions: An Overview
Behavior Type
Immutable
Syntax
ST_YMax(g )
Arguments
g
Spatial object for which you want to find the maximum y-coordinate, type GEOMETRY or
GEOGRAPHY.
Returns
GEOMETRY or GEOGRAPHY
GEOMETRY GEOGRAPHY
Point
Yes
Yes
Multipoint
Yes
Yes
Linestring
Yes
Yes
Multilinestring
Yes
Yes
Polygon
Yes
Yes
Multipolygon
Yes
Yes
GeometryCollection Yes
No
Examples
The following examples show how to use ST_YMax.
Returns the maximum y-coordinate within a rectangle:
=> SELECT ST_YMax(ST_GeomFromText('POLYGON((0 1,0 4,1 4,1 1,0 1))'));
ST_YMax
Place
HP Vertica Place Functions: An Overview
----------4
(1 row)
ST_YMin
Returns the minimum y-coordinate of the minimum bounding rectangle of the GEOMETRYor
GEOGRAPHY object.
For GEOGRAPHY types, HP Vertica Place computes minimum coordinates by calculating the
minimum latitude of the great circle arc from (ST_XMin(GEOGRAPHY), MIN(latitude)) to (ST_
XMax(GEOGRAPHY), MIN(latitude)). In this case, MIN(latitude) represents the minimum latitude
value of the geography object.
If either latitude or longitude is out of range, ST_YMin returns the minimum plain value of the
geography object.
Behavior Type
Immutable
Syntax
ST_YMin(g )
Arguments
g
Spatial object for which you want to find the minimum y-coordinate, type GEOMETRY or
GEOGRAPHY.
Returns
GEOMETRY or GEOGRAPHY
Place
HP Vertica Place Functions: An Overview
GEOMETRY GEOGRAPHY
Point
Yes
Yes
Multipoint
Yes
Yes
Linestring
Yes
Yes
Multilinestring
Yes
Yes
Polygon
Yes
Yes
Multipolygon
Yes
Yes
GeometryCollection Yes
No
Examples
The following examples show how to use ST_YMin.
Returns the minimum y-coordinate within a rectangle:
=> SELECT ST_YMin(ST_GeomFromText('POLYGON((0 1,0 4,1 4,1 1,0 1))'));
ST_YMin
----------1
(1 row)
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.
Place
HP Vertica Place Functions: An Overview
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
subquery
A SELECT statement that returns a polygon identifier column and polygon geometry
column.
table
Parameters
index = 'index_name'
Place
HP Vertica Place Functions: An Overview
max_mem_mb = maxmem_value
(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
Place
HP Vertica Place Functions: An Overview
Returns
polygons
SRID
info
GEOMETRY
Point
No
Multipoint
No
Linestring
No
Multilinestring
No
Polygon
Yes
Multipolygon
Yes
GeometryCollection No
Privileges
Any user with access to the STV_*_Index functions can describe, rename, or drop indexes created
by any other user.
Recommendations
l
Segment large polygon tables across multiple nodes. Table segmentation causes index creation
to run in parallel, leveraging the Massively Parallel Processing (MPP) architecture in HP Vertica.
This significantly reduces execution time on large tables.
Place
HP Vertica Place Functions: An Overview
HP Vertica recommends that you segment the table from which you are building the index when
the total number of polygons is large.
l
STV_Create_Index 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
Try segmenting the input table across the nodes of the cluster.
Limitations
l
Non-polygons
Usage Tips
l
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.
Place
HP Vertica Place Functions: An Overview
Examples
The following examples show how to use STV_Create_Index.
Create an index with a single literal argument:
=> SELECT STV_Create_Index(1, ST_GeomFromText('POLYGON((0 0,0 15.2,3.9 15.2,3.9 0,0 0))')
USING PARAMETERS index='my_polygon') OVER();
polygons | SRID | min_x | min_y | max_x | max_y | info
----------+------+-------+-------+-------+-------+-----1 |
0 |
0 |
0 |
3.9 | 15.2 |
(1 row)
Place
HP Vertica Place Functions: An Overview
----------+------+-------+-------+-------+-------+-----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.
The OVER() clause must be empty.
Behavior Type
Immutable
Syntax
STV_Describe_Index ([USING PARAMETERS index='index_name' ] ) OVER ()
Arguments
index = 'index_name'
Name of the index, type VARCHAR. The maximum index name length is
128 bytes. The slash, backslash, and tab characters are not allowed in
index names.
Place
HP Vertica Place Functions: An Overview
Returns
polygons
SRID
Privileges
Any user with access to the STV_*_Index functions can describe, rename, or drop indexes created
by any other user.
Examples
The following examples show how to use STV_Describe_Index.
Retrieve information about the index:
=> SELECT STV_Describe_Index (USING PARAMETERS index='my_polygons') OVER ();
polygons | SRID | min_x | min_y | max_x | max_y
----------+------+-------+-------+-------+------4 |
0 |
-1 |
-1 |
12 |
12
(1 row)
See Also
l
STV_Create_Index
Place
HP Vertica Place Functions: An Overview
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
index = 'index_name'
Name of the index, type VARCHAR. The maximum index name length is
128 bytes. The slash, backslash, and tab characters are not allowed in
index names.
Example
The following example shows how to use STV_Drop_Index.
Drop an index:
=> SELECT STV_Drop_Index(USINGPARAMETERS index ='my_polygons') OVER ();
drop_index
-----------Index dropped
(1 row)
Place
HP Vertica Place Functions: An Overview
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.
Parameters g1 and g2 must be both GEOMETRY objects or both GEOGRAPHY objects.
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
Place
HP Vertica Place Functions: An Overview
GEOMETRY GEOGRAPHY
Point
Yes
Yes
Multipoint
Yes
Yes
Linestring
Yes
Yes
Multilinestring
Yes
Yes
Polygon
Yes
Yes
Multipolygon
Yes
Yes
GeometryCollection Yes
No
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)
Place
HP Vertica Place Functions: An Overview
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
Place
HP Vertica Place Functions: An Overview
Returns
GEOGRAPHY
GEOMETRY
Point
Yes
Multipoint
Yes
Linestring
Yes
Multilinestring
Yes
Polygon
Yes
Multipolygon
Yes
GeometryCollection No
Example
The following example shows how to use STV_Geography.
To calculate the centroid of the GEOGRAPHY object, convert it to a GEOMETRY object, then
convert it back to a GEOGRAPHY object:
=> CREATE TABLE geogs(g GEOGRAPHY);
CREATE TABLE
=> COPY geogs(gx filler LONG VARCHAR, geog AS ST_GeographyFromText(gx)) FROM stdin
delimiter '|';
Enter data to be copied followed by a newline.
End with a backslash and a period on a line by itself.
>> MULTIPOINT(-108.619726 45.000284,-107.866813 45.00107,-106.363711 44.994223,-70.847746
41.205814)
>> \.
=> SELECT ST_AsText(STV_Geography(ST_Centroid(STV_Geometry(g)))) FROM geogs;
ST_AsText
-------------------------------POINT (-98.424499 44.05034775)
(1 row)
STV_Geometry
Casts a GEOGRAPHY object into a GEOMETRY object.
Place
HP Vertica Place Functions: An Overview
The SRID value does not affect the results of HP Vertica Place queries.
Behavior Type
Immutable
Syntax
STV_Geometry(geog )
Arguments
geog
Spatial object that you want to cast into a GEOMETRY object, type GEOGRAPHY
Returns
GEOMETRY
GEOGRAPHY
Point
Yes
Multipoint
Yes
Linestring
Yes
Multilinestring
Yes
Polygon
Yes
Multipolygon
Yes
GeometryCollection No
Example
The following example shows how to use STV_Geometry.
Convert the GEOGRAPHY values to GEOMETRY values, then convert the result back to a
GEOGRAPHY type:
=> CREATE TABLE geogs(g GEOGRAPHY);
CREATE TABLE
Place
HP Vertica Place Functions: An Overview
=> COPY geogs(gx filler LONG VARCHAR, geog AS ST_GeographyFromText(gx)) FROM stdin
delimiter '|';
Enter data to be copied followed by a newline.
End with a backslash and a period on a line by itself.
>> MULTIPOINT(-108.619726 45.000284,-107.866813 45.00107,-106.363711 44.994223,-70.847746
41.205814)
>> \.
=> SELECT ST_AsText(STV_Geography(ST_Centroid(STV_Geometry(g)))) FROM geogs;
ST_AsText
-------------------------------POINT (-98.424499 44.05034775)
Behavior Type
Immutable
Syntax
STV_Intersect(
[table.]geom
USING PARAMETERS index= 'index_name')
FROM table
Arguments
geom
A GEOMETRY column that contains points. The geom column can only contain POINT
geometries. If the column contains a different GEOMETRY type, STV_Intersect
terminates with an error.
Parameters
index = 'index_name'
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.
Place
HP Vertica Place Functions: An Overview
Example
The following example shows how to use STV_Intersect scalar.
Return the gid of a matching polygon or NULL:
=> CREATE TABLE polygons (gid INT, geom GEOMETRY(700));
CREATE TABLE
=> COPY polygons (gid, gx filler LONG VARCHAR, geom AS ST_GeomFromText(gx)) FROM stdin
delimiter '|';
Enter data to be copied followed by a newline.
End with a backslash and a period on a line by itself.
>> 1|POLYGON((-31 74,8 70,8 50,-36 53,-31 74))
>> 2|POLYGON((-38 50,4 13,11 45,0 65,-38 50))
>> 3|POLYGON((-18 42,-10 65,27 48,14 26,-18 42))
>> \.
=> SELECT STV_Create_Index(gid, geom USING PARAMETERS index='my_polygons',
overwrite=true,
max_mem_mb=256) OVER() FROM polygons;
polygons | SRID | min_x | min_y | max_x | max_y | info
----------+------+-------+-------+-------+-------+-----3 |
0 |
-38 |
13 |
27 |
74 |
(1 row)
=> CREATE TABLE points (gid INT, geom GEOMETRY(700));
CREATETABLE
=> COPY points (gid, gx filler LONG VARCHAR, geom AS ST_GeomFromText(gx)) FROM stdin
delimiter '|';
Enter data to be copied followed by a newline.
End with a backslash and a period on a line by itself.
>> 100|POINT(-1 52)
>> 101|POINT(-20 0)
>> 102|POINT(-8 25)
>> 103|POINT(0 0)
>> 104|POINT(1 5)
>> 105|POINT(20 45)
>> 106|POINT(-20 5)
>> 107|POINT(-20 1)
>> \.
=> SELECT gid AS pt_gid, STV_Intersect(geom USING PARAMETERS index='my_polygons') AS pol_
gid
FROM points_1 ORDERBY pt_gid;
pt_gid | pol_gid
--------+--------100 |
1
101 |
102 |
2
103 |
104 |
105 |
3
106 |
107 |
(8 rows)
Place
HP Vertica Place Functions: An Overview
See Also
l
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
geom
A GEOMETRY column that contains points. The geom column can only contain point
geometries. If the column contains a different geometry type, STV_Intersect terminates
with an error.
Parameters
index = 'index_name'
Place
HP Vertica Place Functions: An Overview
Returns
pt_gid
pol_gid
Examples
The following examples show how to use STV_Intersect transform.
Return the matching point-polygon pairs.
=> CREATE TABLE polygons (gid int, geom GEOMETRY(700));
CREATETABLE
=> COPY polygons (gid, gx filler LONG VARCHAR, geom AS ST_GeomFromText(gx)) FROM stdin
delimiter '|';
Enter data to be copied followed by a newline.
End with a backslash and a period on a line by itself.
>> 10|POLYGON((5 5, 5 10, 10 10, 10 5, 5 5))
>> 11|POLYGON((0 0, 0 2, 2 2, 2 0, 0 0))
>> 12|POLYGON((1 1, 1 3, 3 3, 3 1, 1 1))
>> 14|POLYGON((-1 -1, -1 12, 12 12, 12 -1, -1 -1))
>> \.
=> SELECT STV_Create_Index(gid, geom USING PARAMETERS index='my_polygons',
overwrite=true, max_mem_mb=256) OVER() FROM polygons;
polygons | SRID | min_x | min_y | max_x | max_y | info
----------+------+-------+-------+-------+-------+-----4 |
0 |
-1 |
-1 |
12 |
12 |
(1 row)
=> CREATE TABLE points (gid INT, geom GEOMETRY(700));
CREATETABLE
=> COPY points (gid, gx filler LONG VARCHAR, geom AS ST_GeomFromText(gx)) FROM stdin
delimiter '|';
Enter data to be copied followed by a newline.
End with a backslash and a period on a line by itself.
>> 1|POINT(9 9)
>> 2|POINT(0 1)
>> 3|POINT(2.5 2.5)
>> 4|POINT(0 0)
>> 5|POINT(1 5)
>> 6|POINT(1.5 1.5)
>> \.
=> SELECT STV_Intersect(gid, geom USING PARAMETERS index='my_polygons') OVER (PARTITION
BEST)
AS (point_id, polygon_gid)
FROM points;
point_id | polygon_gid
----------+------------5 |
14
1 |
14
1 |
10
4 |
14
Place
HP Vertica Place Functions: An Overview
4
6
6
6
2
2
3
3
(12 rows)
|
|
|
|
|
|
|
|
11
12
14
11
14
11
12
14
You can improve query performance by using the STV_Intersect transform function in a WHERE
clause. Performance improves because this syntax eliminates all points that do not intersect
polygons in the index.
Return the count of points that only intersect polygon gid = 14:
=> SELECT COUNT(pt_id) FROM
(SELECT STV_Intersect(gid, geom USING PARAMETERS index='my_polygons')
OVER (PARTITION BEST) AS (pt_id, pol_id) FROM points)
AS T WHERE pol_id = 14;
COUNT
------6
(1 row)
See Also
l
STV_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.
Place
HP Vertica Place Functions: An Overview
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
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)
Place
HP Vertica Place Functions: An Overview
See Also
l
ST_IsValid
STV_LineStringPoint
Retrieves the vertices of a linestring or multilinestring. The values returned are points of either
GEOMETRY or GEOGRAPHY type depending on the input object's type. GEOMETRY points
inherit the SRID of the input object.
STV_LineStringPoint is an analytic function. For more information, see Analytic Functions.
Behavior Type
Immutable
Syntax
STV_LineStringPoint(g )
OVER([PARTITIONNODES] ) AS
Arguments
g
Returns
GEOMETRY or GEOGRAPHY
GEOMETRY GEOGRAPHY
Point
No
No
Multipoint
No
No
Linestring
Yes
Yes
Multilinestring
Yes
Yes
Polygon
No
No
Place
HP Vertica Place Functions: An Overview
Multipolygon
No
No
GeometryCollection No
No
Examples
The following examples show how to use STV_LineStringPoint.
Returns the vertices of the geometry linestring and their SRID:
=> SELECT ST_AsText(Point), ST_SRID(Point)
FROM (SELECT STV_LineStringPoint(
ST_GeomFromText('MULTILINESTRING((1 2, 2 3, 3 1, 4 2),
(10 20, 20 30, 30 10, 40 20))', 4269)) OVER () AS Point) AS foo;
ST_AsText
| ST_SRID
---------------+--------POINT (1 2)
|
4269
POINT (2 3)
|
4269
POINT (3 1)
|
4269
POINT (4 2)
|
4269
POINT (10 20) |
4269
POINT (20 30) |
4269
POINT (30 10) |
4269
POINT (40 20) |
4269
(8 rows)
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.
Place
HP Vertica Place Functions: An Overview
Behavior Type
Immutable
Syntax
STV_NN(g, ref_obj, k ) OVER() AS
Arguments
g
ref_obj
Returns
(Object, distance) pairs, in ascending order by distance. If a parameter is EMPTY or NULL, then 0
rows are returned.
GEOMETRY GEOGRAPHY
Point
Yes
Yes
Multipoint
Yes
Yes
Linestring
Yes
Yes
Multilinestring
Yes
Yes
Polygon
Yes
Yes
Multipolygon
Yes
Yes
GeometryCollection Yes
No
Example
The following example shows how to use STV_NN.
Place
HP Vertica Place Functions: An Overview
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
Place
HP Vertica Place Functions: An Overview
Arguments
g
Returns
GEOMETRY or GEOGRAPHY
GEOMETRY GEOGRAPHY
Point
No
No
Multipoint
No
No
Linestring
No
No
Multilinestring
No
No
Polygon
Yes
Yes
Multipolygon
Yes
Yes
GeometryCollection No
No
Examples
The following examples show how to use STV_PolygonPoint.
Returns the vertices of the geometry polygon:
=> SELECT ST_AsText(g) FROM (SELECT STV_PolygonPoint(ST_GeomFromText('POLYGON((1 2, 2 3,
3 1, 1 2))'))
OVER (PARTITION NODES) AS g) AS poly_points;
ST_AsText
------------POINT (1 2)
POINT (2 3)
POINT (3 1)
POINT (1 2)
(4 rows)
Place
HP Vertica Place Functions: An Overview
See Also
STV_LineStringPoint
STV_Refresh_Index
Appends newly added or updated polygons to an existing spatial index.
A spatial index is created from an input polygon set, which can be the result of a query. Spatial
indexes are created in a global name space. HP Vertica uses a distributed plan whenever the input
table or projection is segmented across nodes of the cluster.
The OVER() clause must be empty.
Behavior Type
Mutable
Syntax
STV_Refresh_Index(gid, geom
USING PARAMETERS index='index_name'
[, skip_nonindexable_polygons={true | false } ] )
OVER()
[AS (polygons, srid, min_x, min_y, max_x, max_y, info) ]
FROM table
Arguments
gid
Name of an INTEGER column that uniquely identifies the polygon in the geom parameter.
The gid cannot be NULL.
Place
HP Vertica Place Functions: An Overview
geom
table
Parameters
index = 'index_name'
[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 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.
Returns
polygons
SRID
Place
HP Vertica Place Functions: An Overview
info
indexed
appended
updated
GEOMETRY
Point
No
Multipoint
No
Linestring
No
Multilinestring
No
Polygon
Yes
Multipolygon
Yes
GeometryCollection No
Privileges
Any user with access to the STV_*_Index functions can describe, rename, or drop indexes created
by any other user.
Limitations
l
In rare cases, intricate polygons (such as those with too-high a resolution or anomalous spikes)
cannot be indexed. See the parameter skip_nonindexable_polygons.
Place
HP Vertica Place Functions: An Overview
If you replace a valid polygon in the source table with an invalid polygon, STV_Refresh_Index
ignores the invalid polygon. As a result, the polygon originally indexed persists in the index.
Non-polygons
NULL gid
Usage Tips
l
If you use a source table that was not previously associated with the index, doing so overwrites
the index.
If STV_Refresh_Index has insufficient memory to process the query, then rebuild the index
using STV_Create_Index.
If there are no valid polygons in the geom column, STV_Refresh_Index reports an error in
vertica.log and stops the index refresh.
Examples
The following examples show how to use STV_Refresh_Index.
Refresh an index with a single literal argument:
=> SELECT STV_Create_Index(1, ST_GeomFromText('POLYGON((0 0,0 15.2,3.9 15.2,3.9 0,0 0))')
USING PARAMETERS index='my_polygon') OVER();
polygons | SRID | min_x | min_y | max_x | max_y | info
----------+------+-------+-------+-------+-------+-----1 |
0 |
0 |
0 |
3.9 | 15.2 |
(1 row)
=> SELECT STV_Refresh_Index(2, ST_GeomFromText('POLYGON((0 0,0 13.2,3.9 18.2,3.9 0,0 0))
')
USING PARAMETERS index='my_polygon') OVER();
polygons | SRID | min_x | min_y | max_x | max_y |
info
----------+------+-------+-------+-------+-------+---------------------2 |
0 |
0 |
0 |
3.9 | 18.2 | Polygons appended: 1
(1 row)
Place
HP Vertica Place Functions: An Overview
See Also
l
STV_Create_Index
STV_Describe_Index
STV_Drop_Index
STV_Rename_Index
STV_Rename_Index
Renames a spatial index. If the index format is out of date, you cannot rename the index.
A spatial index is created from an input polygon set, which can be the result of a query. Spatial
indexes are created in a global name space. HP Vertica uses a distributed plan whenever the input
table or projection is segmented across nodes of the cluster.
The OVER() clause must be empty.
Place
HP Vertica Place Functions: An Overview
Behavior Type
Immutable
Syntax
STV_Rename_Index(USING PARAMETERS
source = 'old_index_name',
dest = 'new_index_name',
overwrite = ['true' | 'false' ]
)
OVER ()
Arguments
source = 'old_index_name'
dest = 'new_index_name'
Privileges
Any user with access to the STV_*_Index functions can describe, rename, or drop indexes created
by any other user.
Limitations
The backslash or tab characters are not allowed in index names.
Example
The following example shows how to use STV_Rename_Index.
Rename an index:
=> SELECT STV_Rename_Index (
USINGPARAMETERS
source = 'my_polygons',
dest = 'US_states',
overwrite = 'false'
)
OVER ();
Place
HP Vertica Place Functions: An Overview
rename_index
--------------Index renamed
(1 Row)
STV_ShpCreateTable
Returns a CREATE TABLE statement with the columns and types of the attributes found in the
specified shapefile.
The column types are sized according to the shapefile metadata. The size of the column is based
on the largest geometry found in the shapefile. The first column in the table is gid, which is an autoincrement IDENTITY primary key column. The cache value is set to 64 by default. The last column
is a GEOMETRY data type for storing the actual geometry data.
Behavior Type
Immutable
Syntax
STV_ShpCreateTable(USING PARAMETERS file='filename') OVER()
Arguments
file = 'filename'
Fully qualified path of the .dbf, .shp, or .shx file. (The extension is
optional.)
Returns
CREATE TABLE statement that matches the specified shapefile
Usage Tips
l
STV_ShpCreateTable returns a CREATE TABLE statement; but it does not create the table.
Modify the CREATE TABLE statement as needed, and then create the table before loading the
shapefile into the table.
To create a table with characters other than alphanumeric and underscore (_) characters, you
must specify the table name enclosed in double quotes, such as "counties%NY".
Place
HP Vertica Place Functions: An Overview
The name of the table is the same as the name of the shapefile, without the directory name or
extension.
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)
);
Place
HP Vertica Place Functions: An Overview
(18 rows)
See Also
l
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
file = 'filename'
Place
HP Vertica Place Functions: An Overview
Usage Tips
l
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.
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
Place
Spatial Joins with ST_Intersects and STV_Intersect
Calculate the density of mobile calls in various regions to determine the location of a new cell
phone tower.
Calculate the number of users who live within a certain ZIP code.
Description
Performance
Scalar
Place
Spatial Joins with ST_Intersects and STV_Intersect
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 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,
Place
Spatial Joins with ST_Intersects and STV_Intersect
first create a spatial index using STV_Create_Index. Then, use one of the STV_Intersect
functions to return the set of pairs that intersect.
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)
Place
Spatial Joins with ST_Intersects and STV_Intersect
...
(116 rows)
HP Vertica recommends that you test the intersections of two columns of geometries by creating a
spatial index. Use one of the STV_Intersect functions as described in .
Place
Spatial Joins with ST_Intersects and STV_Intersect
Loading Well-Known Text (WKT) directly into a Geometry column using ST_GeomFromText in a
COPY statement
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)
>> \.
Place
Spatial Joins with ST_Intersects and STV_Intersect
3. Create the table for the location data, represented by points. Point data can be perfectly stored
in a GEOMETRY column of 100 bytes. Larger sizes, however, can significantly degrade
spatial intersection performance. Again, segment the table by HASH to take advantage of
parallel computation.
=> CREATE TABLE usr_data (gid identity,usr_id int,date_time timestamp,g geometry(100))
SEGMENTED BY HASH(gid) ALL NODES;
4. During the copy statement, transform the location data to Well Known Text (WKT), and then
store the data in the table as Geometry data. You must perform this transformation because
your location data is not formatted as WKT. Use the function ST_GeomFromText to take the
newly transformed WKT and transform it to geometry data.
=> COPY usr_data(usr_id, date_time, x filler long varchar, y filler long varchar,
g as ST_GeomFromText('POINT(' || x || ' ' || y || ')'))
from LOCAL 'place_output.csv' delimiter ',' enclosed by '';
5. Create the spatial index for the polygons. You will use this index to speed up intersection
calculations.
=> SELECT STV_Create_Index(gid, g USING PARAMETERS index='art_index', overwrite=true)
OVER() FROM artworks;
6. Write an analytic query that returns the number of intersections per polygon, ignoring any usr_
id that intersects less than 20 times with a given polygon.
=> SELECT pol_gid,
COUNT(DISTINCT(usr_id)) AS count_user_visit
FROM
(SELECT pol_gid,
usr_id,
COUNT(usr_id) AS user_points_in
FROM
(SELECT STV_Intersect(usr_id, g USING PARAMETERS INDEX='art_index') OVER(PARTITION
BEST) AS (usr_id,
pol_gi
FROM usr_data
WHERE date_time BETWEEN '2014-07-02 09:30:20' AND '2014-07-02 17:05:00') AS c
GROUP BY pol_gid,
usr_id HAVING COUNT(usr_id) > 20) AS real_visits
GROUP BY pol_gid
ORDER BY count_user_visit DESC;
Place
Spatial Joins with ST_Intersects and STV_Intersect
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.
The HP Vertica Place functions that work with spatial data in shapefiles are:
l
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
Null shape
Yes
Point
Yes
Polyline
Yes
Polygon
Yes
MultiPoint
Yes
Place
Spatial Joins with ST_Intersects and STV_Intersect
ESRIShapefile
Shape type
PointZ
No
PolylineZ
No
PolygonZ
No
MultiPointZ
No
PointM
No
PolylineM
No
PolygonM
No
MultiPointM
No
MultiPatch
No
Place
Working with Spatial Objects in Tables
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.
Place
Working with Spatial Objects in Tables
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';
Place
Working with Spatial Objects in Tables
Place
Working with Spatial Objects in Tables
----+----------------------------------+---------1 | POINT (2 3)
| t
2 | POINT (4 5)
| f
3 | LINESTRING (-1 2, 1 5)
| t
4 | POLYGON ((-1 2, 0 3, 1 2, -1 2)) | t
(4 rows)
Place
Working with Spatial Objects from Client Applications
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.
LONG VARCHAR
LONG VARBINARY
GEOMETRY
GEOGRAPHY
The client driver libraries support these data types; the following sections describe that support and
provide examples.
Place
Working with Spatial Objects from Client Applications
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).
Place
Working with Spatial Objects from Client Applications
Place
Working with Spatial Objects from Client Applications
// Cleanup
conn.close();
} catch (SQLException e) {
e.printStackTrace();
}
}
}
Note: Do not use inefficient encoding formats for LONG VARBINARY and LONG
VARCHAR values. HP Vertica cannot load encoded values larger than 32MB, even if the
decoded value is less than 32 MB in size. For example, HP Vertica returns an error if you
attempt to load a 32MB LONG VARBINARY value encoded in octal format, since the
octal encoding quadruples the size of the value (each byte is converted into a backslash
followed by three digits).
To convert a GEOMETRY or GEOGRAPHY object to its corresponding WKT or WKB, use one of
the following SQL functions:
l
Place
Working with Spatial Objects from Client Applications
The following code example converts WKT data into GEOMETRY data using ST_GeomFromText
and stores it in a table. Later, this example retrieves the GEOMETRY data from the table and
converts it to WKT and WKB format using ST_AsText and ST_AsBinary.
// Compile on Linux using:
// g++ -g -I/opt/vertica/include -L/opt/vertica/lib64 -lodbc -o SpatialData
SpatialData.cpp
// Some standard headers
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <assert.h>
#include <sstream>
// Only needed for Windows clients
// #include <windows.h>
// Standard ODBC headers
#include <sql.h>
#include <sqltypes.h>
#include <sqlext.h>
// Helper function to print SQL error messages.
template <typename HandleT>
void reportError(int handleTypeEnum, HandleT hdl)
{
// Get the status records.
SQLSMALLINT
i, MsgLen;
SQLRETURN
ret2;
SQLCHAR
SqlState[6], Msg[SQL_MAX_MESSAGE_LENGTH];
SQLINTEGER
NativeError;
i = 1;
printf("\n");
while ((ret2 = SQLGetDiagRec(handleTypeEnum, hdl, i, SqlState, &NativeError,
Msg, sizeof(Msg), &MsgLen)) != SQL_NO_DATA) {
printf("error record %d\n", i);
printf("sqlstate: %s\n", SqlState);
printf("detailed msg: %s\n", Msg);
printf("native error code: %d\n\n", NativeError);
i++;
}
exit(EXIT_FAILURE); // bad form... but Ok for this demo
}
int main()
{
// Set up the ODBC environment
SQLRETURN ret;
SQLHENV hdlEnv;
ret = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &hdlEnv);
assert(SQL_SUCCEEDED(ret));
// Tell ODBC that the application uses ODBC 3.
ret = SQLSetEnvAttr(hdlEnv, SQL_ATTR_ODBC_VERSION,
(SQLPOINTER) SQL_OV_ODBC3, SQL_IS_UINTEGER);
assert(SQL_SUCCEEDED(ret));
// Allocate a database handle.
Place
Working with Spatial Objects from Client Applications
SQLHDBC hdlDbc;
ret = SQLAllocHandle(SQL_HANDLE_DBC, hdlEnv, &hdlDbc);
assert(SQL_SUCCEEDED(ret));
// Connect to the database
printf("Connecting to database.\n");
const char *dsnName = "ExampleDB";
const char* userID = "dbadmin";
const char* passwd = "password123";
ret = SQLConnect(hdlDbc, (SQLCHAR*)dsnName,
SQL_NTS,(SQLCHAR*)userID,SQL_NTS,
(SQLCHAR*)passwd, SQL_NTS);
if(!SQL_SUCCEEDED(ret)) {
printf("Could not connect to database.\n");
reportError<SQLHDBC>(SQL_HANDLE_DBC, hdlDbc);
} else {
printf("Connected to database.\n");
}
// Disable AUTOCOMMIT
ret = SQLSetConnectAttr(hdlDbc, SQL_ATTR_AUTOCOMMIT, SQL_AUTOCOMMIT_OFF,
SQL_NTS);
// Set up a statement handle
SQLHSTMT hdlStmt;
SQLAllocHandle(SQL_HANDLE_STMT, hdlDbc, &hdlStmt);
// Drop any previously defined table.
ret = SQLExecDirect(hdlStmt, (SQLCHAR*)"DROP TABLE IF EXISTS polygons",
SQL_NTS);
if (!SQL_SUCCEEDED(ret)) {reportError<SQLHDBC>(SQL_HANDLE_STMT, hdlStmt);}
// Run query to create a table to hold a geometry.
ret = SQLExecDirect(hdlStmt,
(SQLCHAR*)"CREATE TABLE polygons(id INTEGER PRIMARY KEY, poly GEOMETRY);",
SQL_NTS);
if (!SQL_SUCCEEDED(ret)) {reportError<SQLHDBC>(SQL_HANDLE_STMT, hdlStmt);}
// Create the prepared statement. This will insert data into the
// table we created above. It uses the ST_GeomFromText function to convert the
// string-formatted polygon definition to a GEOMETRY datat type.
printf("Creating prepared statement\n");
ret = SQLPrepare (hdlStmt,
(SQLTCHAR*)"INSERT INTO polygons(id, poly) VALUES(?, ST_GeomFromText(?))",
SQL_NTS) ;
if (!SQL_SUCCEEDED(ret)) {reportError<SQLHDBC>(SQL_HANDLE_STMT, hdlStmt);}
SQLINTEGER id = 0;
int numBatches = 5;
int rowsPerBatch = 10;
// Polygon definition as a string.
char polygon[] = "polygon((1 1, 1 2, 2 2, 2 1, 1 1))";
// Bind variables to the parameters in the prepared SQL statement
ret = SQLBindParameter(hdlStmt, 1, SQL_PARAM_INPUT, SQL_C_LONG, SQL_INTEGER,
0, 0, &id, 0 , NULL);
if (!SQL_SUCCEEDED(ret)) {reportError<SQLHDBC>(SQL_HANDLE_STMT,hdlStmt);}
// Bind polygon string to the geometry column
Place
Working with Spatial Objects from Client Applications
Place
Working with Spatial Objects from Client Applications
free(polygonval);
free(polygonstr);
// Clean up
printf("Free handles.\n");
ret = SQLFreeHandle(SQL_HANDLE_STMT, hdlStmt);
if (!SQL_SUCCEEDED(ret)) {reportError<SQLHDBC>(SQL_HANDLE_STMT, hdlStmt);}
ret = SQLFreeHandle(SQL_HANDLE_DBC, hdlDbc);
if (!SQL_SUCCEEDED(ret)) {reportError<SQLHDBC>(SQL_HANDLE_STMT, hdlStmt);}
ret = SQLFreeHandle(SQL_HANDLE_ENV, hdlEnv);
if (!SQL_SUCCEEDED(ret)) {reportError<SQLHDBC>(SQL_HANDLE_STMT, hdlStmt);}
exit(EXIT_SUCCESS);
}
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).
Place
Working with Spatial Objects from Client Applications
To convert a GEOMETRY or GEOGRAPHY object to its corresponding WKT or WKB, use one of
the following SQL functions:
l
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
{
Place
Working with Spatial Objects from Client Applications
Class.forName("com.vertica.jdbc.Driver");
Connection conn =
DriverManager.getConnection("jdbc:vertica://localhost:5433/db",
"user", "password");
conn.setAutoCommit(false);
Statement stmt = conn.createStatement();
stmt.execute("CREATE TABLE polygons(id INTEGER PRIMARY KEY, poly GEOMETRY)");
int id = 0;
int numBatches = 5;
int rowsPerBatch = 10;
//batch inserting WKT data
PreparedStatement pstmt = conn.prepareStatement("INSERT INTO polygons
(id, poly) VALUES(?, ST_GeomFromText(?))");
for(int i = 0; i < numBatches; i++)
{
for(int j = 0; j < rowsPerBatch; j++)
{
//Insert your own WKT data here
pstmt.setInt(1, id++);
pstmt.setString(2, "polygon((1 1, 1 2, 2 2, 2 1, 1 1))");
pstmt.addBatch();
}
pstmt.executeBatch();
}
conn.commit();
pstmt.close();
//batch insert WKB data
pstmt = conn.prepareStatement("INSERT INTO polygons(id, poly)
VALUES(?, ST_GeomFromWKB(?))");
for(int i = 0; i < numBatches; i++)
{
for(int j = 0; j < rowsPerBatch; j++)
{
//Insert your own WKB data here
byte [] wkb = getWKB();
pstmt.setInt(1, id++);
pstmt.setBytes(2, wkb);
pstmt.addBatch();
}
pstmt.executeBatch();
}
conn.commit();
pstmt.close();
//selecting data as WKT
ResultSet rs = stmt.executeQuery("select ST_AsText(poly) from polygons");
while(rs.next())
{
String wkt = rs.getString(1);
Reader wktReader = rs.getCharacterStream(1);
//process the wkt as necessary
}
rs.close();
Place
Working with Spatial Objects from Client Applications
To convert a GEOMETRY or GEOGRAPHY object to its corresponding WKT or WKB, use one of
the following SQL functions:
Place
Working with Spatial Objects from Client Applications
The following C# code example converts WKT data into GEOMETRY data using ST_
GeomFromText and stores it in a table. Later, this example retrieves the GEOMETRY data from the
table and converts it to WKT and WKB format using ST_AsText and ST_AsBinary.
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Data;
using Vertica.Data.VerticaClient;
namespace ConsoleApplication
{
class Program
{
static void Main(string[] args)
{
VerticaConnectionStringBuilder builder =
new VerticaConnectionStringBuilder();
builder.Host = "VerticaHost";
builder.Database = "VMart";
builder.User = "ExampleUser";
builder.Password = "password123";
VerticaConnection _conn = new
VerticaConnection(builder.ToString());
_conn.Open();
VerticaCommand command = _conn.CreateCommand();
command.CommandText = "DROP TABLE IF EXISTS polygons";
command.ExecuteNonQuery();
command.CommandText =
"CREATE TABLE polygons (id INTEGER PRIMARY KEY, poly GEOMETRY)";
command.ExecuteNonQuery();
// Prepare to insert a polygon using a prepared statement. Use the
// ST_GeomFromtText SQl function to convert from WKT to GEOMETRY.
VerticaTransaction txn = _conn.BeginTransaction();
command.CommandText =
"INSERT into polygons VALUES(@id, ST_GeomFromText(@polygon))";
command.Parameters.Add(new
VerticaParameter("id", VerticaType.BigInt));
command.Parameters.Add(new
VerticaParameter("polygon", VerticaType.VarChar));
command.Prepare();
// Set the values for the parameters
command.Parameters["id"].Value = 0;
//
command.Parameters["polygon"].Value =
"polygon((1 1, 1 2, 2 2, 2 1, 1 1))";
Place
Working with Spatial Objects from Client Applications
Place
BestPractices for HPVerticaPlace
Performance Optimization
Recommendation
Details
spatial data.
possible.
spatial columns:
ST_Distance
ST_Area
ST_Length
Place
BestPractices for HPVerticaPlace
Recommendation
Details
geometries.
of polygons.
GEOMETRY data.
in a WHERE clause.
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:
Place
BestPractices for HPVerticaPlace
Number of polygons
Number of vertices
Recommendation
Details
CPUusage.
needed.
Place
BestPractices for HPVerticaPlace
Recommendation
Details
Details
are valid.
polygons.
l
Place
HP Vertica Place Limitations
You must run HP Vertica Place on the coinciding version of the HP Vertica Analytic Database
server.
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.
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.
Place
HP Vertica Place Limitations
Polymorphic functions, such as NVL and GREATEST, do not accept GEOMETRY and
GEOGRAPHY arguments.