{"id":46561,"date":"2017-09-27T00:00:00","date_gmt":"2017-09-27T07:00:00","guid":{"rendered":"https:\/\/griddb-linux-hte8hndjf8cka8ht.westus-01.azurewebsites.net\/blog\/using-geometry-values-griddb\/"},"modified":"2025-11-13T12:54:31","modified_gmt":"2025-11-13T20:54:31","slug":"using-geometry-values-griddb","status":"publish","type":"post","link":"https:\/\/griddb.net\/en\/blog\/using-geometry-values-griddb\/","title":{"rendered":"Using Geometry Values with GridDB"},"content":{"rendered":"

Introduction<\/h2>\n

Data comes in many, many forms. It comes temporally as well as spatially. GridDB’s Timeseries containers as well as its TQL and time-specific API operations cover the time aspect of data. GridDB has geospatial data covered as well in GridDB Standard Edition and Advanced Edition. Support is provided with Geometry Columns and Data Types<\/b> along with specialized Geometry Operations<\/b> through TQL as well as through the C and Java APIs.<\/p>\n

In GridDB, Geometry values can be created to represent 5<\/b> general models or shapes.<\/p>\n

POINT<\/h3>\n

A coordinate point in either two dimensional or three dimensional space.
\n2D and 3D Points<\/b><\/p>\n

\nGeometry point = Geometry.valueOf(\"POINT(1 3.4)\");\nGeometry threeDPt = Geometry.valueOf(\"POINT(2 -3 0.43)\");\n<\/pre>\n
\"points\"<\/p>\n
LINESTRING<\/h3>\n
A set of one or more interconnected<\/i> lines in two or three dimensional space. They are represented by two or more points.
\n\"\"<\/p>\n
POLYGON<\/h3>\n
A closed area in either two or three dimensional space. The area consists of three or more points that are connected from a starting point, or VERTEX<\/code>, to the endpoints and back to the starting point. It is possible to have the surface or area to have gaps or islands that are not part of the model by specifying the internal areas to exclude from the outer area.
\n2D Polygon<\/b><\/p>\n
\nGeometry polygon = Geometry.valueOf(\"POLYGON((0 0, 1 0, 1 1, 0 1, 0 0))\");\n<\/pre>\n
3D Polygon<\/b><\/p>\n
\nGeometry threeDSurface = Geometry.valueOf(\"POLYGON((0 0 0, 1 0 1, 1 1 1, 0 1 0, 0 0 0))\");\n<\/pre>\n
\"example-polygons\"<\/p>\n
POLYHEDRALSURFACE<\/h3>\n
The POLYHEDRALSURFACE<\/code> surface consists of vertices, edges, and facets<\/i>. Simple examples tetrahedrons, polyhedrons, and octohedral surfaces. The POLYHEDRALSURFACE<\/i> can only be a three-dimensional shape. This means all the points that make up its edges are supposed to contain 3 coordinates<\/b>. Polyhedral surfaces can be thought of as a full three-dimensional extension of the POLYGON<\/i> in that the shape can enclose a volume where its faces are each comprised of a closed polygonal surface.
\nExample<\/b><\/p>\n
\nGeometry polySurface = Geometry.valueOf(  \n\"POLYHEDRALSURFACE ( ((0 0 0, 0 1 0, 1 1 0, 1 0 0, 0 0 0)),\" \n+ \"((0 0 0, 0 1 0, 0 1 1, 0 0 1, 0 0 0 )),\" \n+ \"((0 0 0, 1 0 0, 1 0 1, 0 0 1, 0 0 0)),\" + \n\"((1 1 1, 1 0 1, 0 0 1, 0 1 1, 1 1 1)) ,\" + \n\"((1 1 1, 1 0 1, 1 0 0, 1 1 0, 1 1 1)),\" + \n\"((1 1 1, 1 1 0, 0 1 0, 0 1 1, 1 1 1)) )\");\n<\/pre>\n
Every set of coordinates should be enclosed by double-parenthesis ((<\/code> , ))<\/code> because it represents a closed face that will make up part of the three-dimensional enclosed surface. Think of the faces as POLYGON<\/code>‘s that make up the sides of the surface. All these are then grouped and connected together to form the three-dimensional surface object.
\n\"Polyhedral<\/p>\n
QUADRATICSURFACE<\/h3>\n
A three dimensional quadratic surface. These objects are curved surfaces in three-dimensional space by the equation: f(X) = <AX,X> + BX + C<\/code>. Create a surface by inserting 16<\/b> numbers that represent the coefficents<\/i> of making that surface equation.
\nThe QUADRATICSURFACE<\/i> is different from the other four Geometry objects in that its WKT (Well-Known-Text format) inputs are coefficients to an equation rather than coordinates in the 3D plane. This equation,<\/p>\n
ax2<\/sup>+by2<\/sup>+cz2<\/sup>+2fyz+2gzx+2hxy+2px+2qy+2rz+d = 0<\/pre>\n
When converted into a quadratic-form<\/i> matrix:<\/p>\n\n\n\n\n\n
a<\/i><\/td>\nh<\/i><\/td>\ng<\/i><\/td>\np<\/i><\/tr>\n
h<\/i><\/td>\nb<\/i><\/td>\nf<\/i><\/td>\nq<\/i><\/td>\n<\/tr>\n
g<\/i><\/td>\nf<\/i><\/td>\nc<\/i><\/td>\nr<\/i><\/td>\n<\/tr>\n
p<\/i><\/td>\nq<\/i><\/td>\nr<\/i><\/td>\nd<\/i><\/td>\n<\/tr>\n<\/table>\n
Example Surface<\/b><\/p>\n
\nGSRow* row;\nconst GSChar* wkt = \"QUADRATICSURFACE(( 84 2 3 5 6 7 8 9 10 12 13 14 15 16 17 18 ))\";\n\/\/ (snip)\ngsGetNextRow(rowSet,row);\ngsSetRowFieldByGeometry(row,4,wkt);\ngsPutRow(timeseries,NULL,row,NULL);\n<\/pre>\n
Examples of quadric surfaces include parallel planes, hyperboloids, cones, cylinders and spheres. These types of surfaces are mapped to different polynomial equations. Some of these equations may not have certain factors or coefficients. For example, there may be no x<\/code>‘s in the equation like in <\/p>\n
\ny2<\/sup> + z2<\/sup> - 1\n<\/pre>\n
Since there are no x’s<\/i> in the equation, replace all coefficients that are near x like a,h,p<\/i> with 0’s. When entering the matrix values for the QUADRATICSURFACE<\/b> WKT, there must always be 16<\/b> values, with any missing values replaced with a 0.<\/p>\n
More examples and information on quadric surfaces can be found in this Wolfram Alpha page<\/a>.
\n\"example-quadratics\"<\/p>\n
Creating Objects with WKT Format<\/h2>\n
Creating any of these objects in GridDB is fairly simple. All that is needed on the development end is to know how to establish the model in WKT<\/code> form. WKT (Well-Known-Text) text formatting is a text markup language used for representing vector geometry objects on a map or in a spatial reference system. If the WKT string is parsed correctly, the Geometry is created and inserted into its respective column into the Collection or Timeseries. There are certain characteristics of WKT format that should be noted and followed or else errors will be thrown or the Geometry object will not be created. <\/p>\n
General Formatting Rules<\/h5>\n
When stating the shape of the Geometry (POINT,LINESTRING,etc.) ensure that you use ALL UPPERCASE LETTERS<\/b> and correct syntax. If not done so, the object will not be created and exceptions<\/i> could be raised. Ensure that the formatting is correct and there are no syntax errors such as not having correct amount of parenthesis or not using proper spacing.<\/p>\n
If you wish to create an empty Geometry object, create a POINT(EMPTY)<\/code> geometry.
\nEmpty LINESTRING and POLYGON<\/b><\/p>\n
\nGeometry emptyPoint = Geometry.valueOf(\"POINT(EMPTY)\");\n<\/pre>\n
You can learn more about general WKT formatting on this Wikipedia page<\/a>.<\/p>\n
Range Restrictions<\/h5>\n
In some GIS<\/i>-supporting (Geographic Information System) databases, the ranges or values of points can include special values like NaN<\/code>, INF<\/code>, -INF<\/code> (Not-a-Number, Negative and Positive Infinity). Only numerical-types can be used which include positive or negative floating point numbers.<\/p>\n
Forming Closed Surfaces<\/h5>\n
Usually Geometries beyond POINT and QUADRATICSURFACE consist of points that are connected. The points, once connected together, form lines that will make up the edges. The edges usually converge to form a closed surface. For all Geometries except POINT<\/i>, more than one data point is needed.<\/p>\n
Dimensions of Geometry Values<\/h5>\n
The points that make a Geometry can only be in two-dimensional or three-dimensional<\/i> format. Also, when creating points to outline an object the dimensions must stay consistent (i.e a polygon that has a coordinate in 2D must have all its other coordinates in 2D). Points are separated by commas: ,<\/code> and the x,y,z<\/code> coordinates are delimited by SPACES<\/code><\/p>\n
Defining Geometric Columns and Indexes<\/h2>\n
Geometry columns can be added to the column schema for a container either in a static fashion or a dynamic fashion. The Geometry<\/code> can be directly imported from the GridDB library and can be set as a column type for a class schema<\/i> for a container. You can also set an index on a Geometry column by setting a SPATIAL<\/code> index flag.
\nJava Container Creation<\/b><\/p>\n
\n\/\/ (snip)\nimport com.toshiba.mwcloud.gs.Geometry;\nimport com.toshiba.mwcloud.gs.GeometryOperator;\n\/\/(snip)\nstatic class Shape {\n\t@RowKey String name;\n\tdouble perimeter;\n\tdouble volume;\n\tDate creation;\n\tGeometry geom;\n\n\tpublic String toString(){\n\t\treturn String.format(\"Shape: Name = %s, Perimeter = %f, \n                                   Volume = %f, Creation Date = %s, WKT = %s\", \n                                name,perimeter,volume,creation.toString(),geom.toString());\n\/\/(snip)\nCollection<String,Shape> geometryCollection =  \n              gridstore.putCollection(\"GeometryCollection101\",Shape.class);\n\/\/ (snip)\ngeometryCollection.createIndex(\"geom\",IndexType.SPATIAL);\n<\/pre>\n
There is no explicit GSGeometry struct or enum in GridDB’s C API. When creating a container with a dynamic schema using ContainerInfo<\/code> and ColumnInfo<\/code> objects, set the ColumnInfo’s type<\/i> as GS_TYPE_GEOMETRY<\/code>. If you are using struct-bindings<\/b>, set the column type that you wish to set as Geometry to have the type const GSChar*<\/code>. From there, set the column’s type to Geometry when performing the struct-bindings. Simply set the column value with its WKT<\/b> form and GridDB will convert it to its binary equivalent in the database.
\nC Container Creation<\/b><\/p>\n
\ntypedef struct {\n\tconst GSChar* name;\n\tGSTimestamp timestamp;\n\tdouble volume;\n\tdouble perimeter;\n\tconst GSChar* shape;\n} GeometryRow;\n\nGS_STRUCT_BINDING(GeometryRow,\n\tGS_STRUCT_BINDING_KEY(name, GS_TYPE_STRING)\n\tGS_STRUCT_BINDING_ELEMENT(timestamp,GS_TYPE_TIMESTAMP)\n\tGS_STRUCT_BINDING_ELEMENT(volume,GS_TYPE_DOUBLE)\n\tGS_STRUCT_BINDING_ELEMENT(perimeter,GS_TYPE_DOUBLE)\n\tGS_STRUCT_BINDING_ELEMENT(shape,GS_TYPE_GEOMETRY));\n\/\/(snip)\nGSCollection* collection;\ngsPutCollection(gridstore,\"GeometryCollection311\", \nGS_GET_STRUCT_BINDING(GeometryRow),NULL,GS_FALSE,&collection);\n\ngsCreateIndex(collection,\"shape\",GS_INDEX_FLAG_SPATIAL);\n\nGeometryRow gRow; \ngRow.name = \"FirstPoint\";\ngRow.timestamp = gsCurrentTime();\ngRow.volume = 0;\n\ndouble x, y, z;\nsscanf(wkt,\"POINT(%lf %lf %lf)\",&x,&y,&z);\ngRow.perimeter = sqrt((x * x) + (y * y) + (z * z));\ngRow.shape = \"POINT(1 4.23 4.2)\";\n\ngsPutRow(collection,NULL,&gRow,NULL);\n<\/pre>\n
Spatial Operations in GridDB’s API<\/h2>\n
Geometric data values, when inserted into a GridDB database, are stored in binary<\/i> form, much like BLOB<\/code> data types. This means that performing direct equality operations are not allowed with TQL<\/code>.
\nExample of Invalid TQL<\/b><\/p>\n
\nSELECT * WHERE geom = ST_GeomFromText('POINT(2 4 5)') #(Throws Error)\n<\/pre>\n
In Java it is possible to compare the Geometry values directly to each using the API from GridDB.<\/p>\n
\nGeometry pointToFind = Geometry.valueOf(\"POINT(0 4)\");\n\/\/ (snip)\nwhile(rowSet.hasNext){\n     Row row = rowSet.next();\n     Geometry rowPoint = row.getGeometry(4);\n     boolean match = rowPoint.equals(pointToFind);\n     System.out.println(match);\n<\/pre>\n
One spatial operation that is allowed through GridDB’s API and TQL is a SPATIAL INTERSECTION<\/code>. This translates to searching for a common area or volume between the two objects. A 3D intersection consists of determining a Minimum Bounding Box<\/i>, known as a rectangular parallelepiped, where the two objects intersect. When objects are two-dimensional, the z-coordinates have range values of (-INF,INF)<\/code>. This means that checking against a 2D dimensional object with a 3D dimensional object will have a more inclusive z-range to increase the chances of intersection.<\/p>\n
When comparing an object with a POINT<\/i>, the bounding box’s vertices are made up of the points. The box’s vertices are all on the same side and have a length of 0. If comparing a POINT to a non-point object, GridDB will check if the bounding box contains the point in its area.<\/p>\n
When comparing between shapes that are not points, such as two POLYGON<\/i> objects, the bounding box will have minimum and maximum x, y, and z coordinates that will make up the intersection’s spatial structure.<\/p>\n
Examples of Spatial Intersections<\/b>
\n\"spatial-intersection-thumbnail\"<\/p>\n
Issuing Geometric Queries with GridDB API<\/h3>\n
Intersection queries can be made quickly without TQL on Collection<\/code> containers by issuing .query(String column,Geometry geom,GeometryOperator operator)<\/code> in Java or gsQueryByGeometry()<\/code>. This query will search and fetch all rows
\nwhose ‘column’ value will intersect with const GSChar* geometry<\/code>.
\nJava<\/b><\/p>\n
\nGeometry intersection = Geometry.valueOf(\"POLYGON((0 0 0, 2 0 0, 2 2 0, 0 2 0, 0 0 0))\");\n\nQuery query = geometryCollection.query(\"geom\",intersection, \n GeometryOperator.INTERSECT);\n\nRowSet rowSet = query.fetch(false);\nwhile(rowSet.hasNext()){\n\tShape shape = rowSet.next();\n\tSystem.out.println(shape);\n<\/pre>\n
C<\/b><\/p>\n
\nGSQuery* query;\nGSRowSet* rowSet;\nGeometryRow geometryRow;\n\nconst GSChar* point = \"POINT(1 4.56 4.2)\";\ngsQueryByGeometry(collection,\"shape\",point,GS_GEOMETRY_OPERATOR_INTERSECT,&query);\n\ngsFetch(query,GS_FALSE,&rowSet);\n\nwhile(gsHasNextRow(rowSet)){\n\tgsGetNextRow(rowSet, &fetchedRow);\n\tGSChar timeStr[GS_TIME_STRING_SIZE_MAX];\n\tgsFormatTime(fetchedRow.timestamp,timeStr,sizeof(timeStr));\n\n\tprintf(\"Name = %s\",fetchedRow.name);\n\tprintf(\" Timestamp = %s\",timeStr);\n\tprintf(\" Volume = %.2lf\", fetchedRow.volume);\n\tprintf(\" Perimeter = %.2lf\", fetchedRow.perimeter);\n\tprintf(\" Shape = %sn\",fetchedRow.shape);\n<\/pre>\n
TQL Queries with Geometry Values<\/h3>\n
TQL can be used to check for geometric intersections along with other conditions you wish to specify. In the case of comparing two non-quadratic<\/i> shapes, you can use the GIS function ST_MBRIntersects(geometry1,geometry2)<\/code>. If you wish to specify a Geometry to check for an intersection, simply enter the shape in WKT form and turn it into a Geometry object with TQL’s ST_GeomFromText(wkt)<\/code> function. <\/p>\n
Let’s say we want to fetch up to 5 rows whose ‘geom’ column value intersects with POLYGON<\/b>:
\nPOLYGON((2 2 4, 5 2 4, 5 2 8, 2 2 8, 2 2 4))<\/code> AND<\/b> whose value<\/i> column is greater than 7.5 in descending<\/i> order. You could issue the query as follows: <\/p>\n
\nString tql = \"SELECT * WHERE ST_MBRIntersects(geom,\" +  \n\"ST_GeomFromText('POLYGON((2 2 4, 5 2 4, 5 2 8, 2 2 8, 2 2 4))'))\"\n+ \" AND value > 7.5 ORDER BY value DESC LIMIT 5\";\n\nQuery<Row> query = collection.query(tql);\n<\/pre>\n
One thing to note about ST_MBRIntersects<\/i> is that you cannot use QUADRATICSURFACES<\/i> for comparison. In the case that you want to check for intersection between a quadratic surface<\/i> and a non-quadratic-surface<\/i>. You can use the ST_QSFMBRIntersects(quadratic,geometry)<\/code> to check for the intersection and use ST_MakeQSF(A00,A10,A20,A01...)<\/code> The A00, A10, A20,A01<\/i> are used to represent the coefficents of the <AX,X> + BX + C<\/code> equation that make up the Quadratic Surface.
\nExample of Quadratic Surface Query<\/b><\/p>\n
\nGSQuery* query;\nGSRowSet* rowSet;\n\ngsQuery(timeseries, \n  \"select * where STQSFMBRIntersects( \nST_MakeQSF(84,2,3,5,6,7,8,9,10,12,13,14,15,16,17,18),geom) AND id='row1'\", \n&query);\n\ngsFetch(query,GS_FALSE,&rowSet);\n<\/pre>\n
Best Uses of Spatial Data <\/h2>\n
Geometric and spatial data types are highly useful in domains like engineering, science, architecture, geography, and IoT. In geography or IoT, spatial data can be used to represent latitude, longitude, and elevation of sensors or objects. On example could be the last three categories can be represented as three-dimensional point in the format POINT(latitude longitude elevation)<\/code>. You can use spatial intersections with POINT’s<\/i> to find a row at a specific location. <\/p>\n
POLYGON<\/i>‘s can be used to find rows that are within a geographic range. For example, a geometric query can be used with POLYGON(57 110, 59 110, 59 130, 57 130, 57 110)<\/code> to find all rows within the area between 57 and 59 latitude and between 130 and 110 longitude. <\/p>\n
Linestrings, polygons, and surfaces can be used to represent vectors or three dimensional object. Being able to create, store, query, and index spatial data is especially useful for fields like engineering and architecture where buildings and devices are based off of 3D designs. <\/p>\n
A specific use case for GridDB could involve creating a collection of traffic sensors. It can store and track general data like whether its active or how many cars it has seen and other values. You can store its geographic location in terms of a POINT<\/b> with the GEOMETRY<\/b>. Intersection queries can be used to find filter based on locations using either API functions or TQL. <\/p>\n
Traffic Sensor in Java<\/b><\/p>\n
\npublic class TrafficLight {\n\t@RowKey\n\tpublic  String tag; \/\/ Sensor Id of Smart Traffic Light\t\n\tpublic Geometry point; \/\/ Latitude, Longitude, and Elevation of Sensor\n\tpublic Date installation; \/\/ Time of installation to the Traffic Grid\n\tpublic boolean active; \/\/ Whether the traffic light sensor has been activated\n\tpublic int reports; \/\/ Number of reports that the Traffic Light has issued\n\tpublic String streets; \/\/ Cross streets of Traffic Light\n\/\/ (snip)\n<\/pre>\n
Querying the Traffic Collection in Java<\/b><\/p>\n
\nCollection<String,TrafficLight> trafficLightCollection =  \n  gridstore.putCollection(\"trafficLights101\",TrafficLight.class);\n\/\/ (snip)\ntrafficLightCollection.createIndex(\"point\",IndexType.SPATIAL);\n\/\/ (snip)\n\/\/ Search for a specific POINT\nString ptTql = \"SELECT * WHERE ST_MBRIntersects(point,\" +\n                \"ST_GeomFromText('POINT(47.33 84.72 0.7)'))\";\n\nQuery<TrafficLight> ptQuery = trafficLightCollection.query(ptTql);\n\/\/ (snip)\n\/\/ Search for Point in a 2D Range using POLYGON\nString tql = \"SELECT * WHERE ST_MBRIntersects(point,\" + \n            \"ST_GeomFromText('POLYGON((49.00 86.00, 51.00 86.00,\" +\n             \"51.00 87.00, 49.00 87.00, 49.00 86.00))'))\";\n\nQuery<TrafficLight> query = trafficLightCollection.query(tql);\n<\/pre>\n
Using GridDB Standard Edition<\/h2>\n
In GridDB Community edition it is possible to create Geometry<\/b> objects but it is not possible to insert them as column values or use them as part of a container’s schema. These features are only available for Standard Edition<\/b> and beyond. GridDB Standard Edition can be used with AWS<\/a>. General setup and configuration information can be found in the Quick Start Guide<\/a>.<\/p>\n
More information on the GEOMETRY type can be found in this section<\/a> of the GridDB SE Technical Reference. There are more details on Spatial operations<\/a> in the API Reference manual. GridDB uses regular expressions patterns to determine if an enter format is valid WKT. The patterns that are acceptable can be found in this section of the GridDB source code<\/a>. <\/p>\n