Geographical elements

Geographical elements¶

Geographical indexing and search make use of some common elements that are described in this section.

Distance¶

Both geo distance search and buffer transformation take a spatial distance as argument. This distance is just a string with the form "1km", "1000m", etc. The following table shows the available options for distance units. The default distance unit is metre.

Values	Unit
mm, millimetres	millimetre
cm, centimetres	centimetre
dm, decimetres	decimetre
m, metres	metre
dam, decametres	decametre
hm, hectometres	hectometre
km, kilometres	kilometre
ft, foots	foot
yd, yards	yard
in, inches	inch
mi, miles	mile
M, NM, mil, nautical_miles	nautical mile

Example: the following geo distance search search for any rows where “place” is within one kilometer from the geo point (40.225479, -3.999278). The distance is expressed in kilometers.

SELECT * FROM "test".user WHERE lucene = '{
   filter: {
      type: "geo_distance",
      field: "place",
      latitude: 40.225479,
      longitude: -3.999278,
      max_distance: "1km"
   }
}';

Transformations¶

Geo shape mapper takes a list of geometrical transformations as argument. These transformations are sequentially applied to the shape that is going to be indexed or searched.

Bounding box transformation¶

Bounding box transformation returns the minimum bounding box of a shape, that is, the minimum rectangle containing the shape.

Syntax:

JSON syntax

{type: "bbox"}

Java Annotation syntax

@GeoTransformation(type = GeoTransformationType.BBOX))

Example: The following geo shape mapper will index only the bounding box of the WKT shape contained in the indexed column:

DDL with JSON syntax

CREATE TABLE IF NOT EXISTS "PUBLIC".BLOCK (
   id int,
   shape varchar,
   PRIMARY KEY (id)
) WITH "TEMPLATE=PARTITIONED";


CREATE INDEX BLOCK_LUCENE_IDX ON "PUBLIC".BLOCK(LUCENE)  
FULLTEXT '{
''refresh_seconds'':''60'',
''partitioner'':''{"type":"token","partitions":10}'',
''schema'':''{
     "fields": {
         "place_bbox": {
            type: "geo_shape",
            column: "shape",
            transformations: [{type: "bbox"}]
         }
      }
  }''
}';

Java Annotation Syntax

@QueryTextField(
    // Index configuration
    indexOptions = @IndexOptions(
        refreshSeconds = 60, 
        partitions = 10
    )
)
public class Block {

    @QueryTextField(geoShapeMappers = {
            @GeoShapeMapper(
                name = "place_bbox", 
                column = "shape", 
                transformations = @GeoTransformation(type = GeoTransformationType.BBOX))
    })
    @QuerySqlField
    private String shape;

    ...
}

Buffer transformation¶

Buffer transformation returns a buffer around a shape.

Syntax:

JSON syntax

{
   type: "buffer"
   (, min_distance: <distance> )?
   (, max_distance: <distance> )?
}

Java Annotation syntax

@GeoTransformation(type = GeoTransformationType.BUFFER 
    (, min_distance: <distance> )?
    (, min_distance: <distance> )?
)

where:

min_distance: the inside buffer distance. Optional.
max_distance: the outside buffer distance. Optional.

Example: the following geo shape mapper will index a buffer 50 kilometers around the WKT shape contained in the indexed column:

DDL with JSON Syntax

CREATE TABLE IF NOT EXISTS "PUBLIC".CITY (
   name varchar,
   shape geometry,
   PRIMARY KEY (name)
) WITH "TEMPLATE=PARTITIONED";


CREATE INDEX CITY_LUCENE_IDX ON "PUBLIC".CITY(LUCENE)  
FULLTEXT '{
''refresh_seconds'':''60'',
''partitioner'':''{"type":"token","partitions":10}'',
''schema'':''{
     "fields": {
         "place_buffer": {
            type: "geo_shape",
            column: "shape",
            max_levels: 15,
            transformations: [{type: "buffer", min_distance: "50km"}]
         }
      }
  }''
}';

Java Annotation Syntax

@QueryTextField(
    // Index configuration
    indexOptions = @IndexOptions(
        refreshSeconds = 60, 
        partitions = 10
    )
)
public class City {

    @QueryTextField(geoShapeMappers = {
            @GeoShapeMapper(
            name = "place_buffer", 
            column = "shape", 
            transformations = @GeoTransformation(type = GeoTransformationType.BUFFER, max_distance = "50km"))
    })
    @QuerySqlField
    private Geometry shape;

    ...
}

Centroid transformation¶

Centroid transformation returns the geometric center of a shape.

Syntax:

JSON syntax

{
   type: "centroid"
}

Java Annotation syntax

@GeoTransformation(type = GeoTransformationType.CENTROID)

Example: The following geo shape mapper will index only the centroid of the WKT shape contained in the indexed column:

DDL with JSON Syntax

CREATE TABLE IF NOT EXISTS "PUBLIC".CITY (
   name varchar,
   shape geometry,
   PRIMARY KEY (name)
) WITH "TEMPLATE=PARTITIONED";


CREATE INDEX CITY_LUCENE_IDX ON "PUBLIC".CITY(LUCENE)  
FULLTEXT '{
''refresh_seconds'':''60'',
''partitioner'':''{"type":"token","partitions":10}'',
''schema'':''{
     "fields": {
         "place_centroid": {
            type: "geo_shape",
            column: "shape",
            max_levels: 15,
            transformations: [{type: "centroid"}]
         }
      }
  }''
}';

Java Annotation Syntax

@QueryTextField(
    // Index configuration
    indexOptions = @IndexOptions(
        refreshSeconds = 60, 
        partitions = 10
    )
)
public class City {

    @QueryTextField(geoShapeMappers = {
            @GeoShapeMapper(
                name = "place_centroid", 
                column = "shape", 
                transformations = @GeoTransformation(type = GeoTransformationType.CENTROID), max_levels = 15))
    })
    @QuerySqlField
    private Geometry shape;

    ...
}

Convex hull transformation¶

Convex hull transformation returns the convex envelope of a shape.

Syntax:

JSON syntax

{
   type: "convex_hull"
}

Java Annotation syntax

@GeoTransformation(type = GeoTransformationType.CONVEX_HULL)

Example: The following geo shape mapper will index only the convex hull of the WKT shape contained in the indexed column:

DDL with JSON Syntax

CREATE TABLE IF NOT EXISTS "PUBLIC".BLOCK (
   id int,
   shape varchar,
   PRIMARY KEY (id)
) WITH "TEMPLATE=PARTITIONED";


CREATE INDEX BLOCK_LUCENE_IDX ON "PUBLIC".BLOCK(LUCENE)  
FULLTEXT '{
''refresh_seconds'':''60'',
''partitioner'':''{"type":"token","partitions":10}'',
''schema'':''{
     "fields": {
         "place_convexhull": {
            type: "geo_shape",
            column: "shape",
            transformations: [{type: "convex_hull"}]
         }
      }
  }''
}';

Java Annotation Syntax

@QueryTextField(
    // Index configuration
    indexOptions = @IndexOptions(
        refreshSeconds = 60, 
        partitions = 10
    )
)
public class Block {

    @QueryTextField(geoShapeMappers = {
            @GeoShapeMapper(
                name = "place_convexhull", 
                column = "shape", 
                transformations = @GeoTransformation(type = GeoTransformationType.CONVEX_HULL))
    })
    @QuerySqlField
    private String shape;

    ...
}

Shapes¶

Geo shape search allows the recursive definition of the search shape as a group of transformations over other shapes.

WKT shape¶

A shape defined in Well Known Text (WKT) format.

Syntax:

{type: "wkt", value: <value>}

where:

value: A string containing the WKT shape. Mandatory.

Example: The following geo shape search will retrieve shapes intersecting a WKT shape:

SELECT * FROM "shapes".block WHERE lucene = '{
   refresh: true,
   filter: {
      type: "geo_shape",
      field: "place",
      operation: "intersects",
      shape: {
        type: "wkt",
        value: "LINESTRING(-80.90 29.05, -80.51 28.47, -80.60 28.12, -80.00 26.85, -80.05 26.37)"
      }
   }
}';

Bounding box shape¶

Buffer transformation returns the minimum bounding box of a shape, that is, the minimum rectangle containing the shape.

Syntax:

{type: "bbox", shape: <shape>}

where:

shape: the shape to be transformed. Mandatory.

Example: The following geo shape search will retrieve shapes intersecting the bounding box of a WKT shape:

SELECT * FROM "shapes".block WHERE lucene = '{
   refresh: true,
   filter: {
      type: "geo_shape",
      field: "place",
      operation: "intersects",
      shape: {
         type: "bbox",
         shape: {
            type: "wkt",
            value: "LINESTRING(-80.90 29.05, -80.51 28.47, -80.60 28.12, -80.00 26.85, -80.05 26.37)"
         }
      }
   }
}';

Buffer shape¶

Buffer transformation returns a buffer around a shape.

Syntax:

{
   type: "buffer",
   shape: <shape>
   (, min_distance: <distance> )?
   (, max_distance: <distance> )?
}

where:

shape: the shape to be transformed. Mandatory.
min_distance: the inside buffer distance. Optional.
max_distance: the outside buffer distance. Optional.

Example: the following geo shape search will retrieve shapes intersecting with a shape defined by a buffer 10 kilometers around a segment of the Florida's coastline:

SELECT * FROM "shapes".block WHERE lucene = '{
   refresh: true,
   filter: {
      type: "geo_shape",
      field: "place",
      operation: "intersects",
      shape: {
         type: "buffer",
         max_distance: "10km",
         shape: {
            type: "wkt",
            value: "LINESTRING(-80.90 29.05, -80.51 28.47, -80.60 28.12, -80.00 26.85, -80.05 26.37)"
         }
      }
   }
}';

Centroid shape¶

Centroid transformation returns the geometric center of a shape.

Syntax:

{type: "centroid", shape: <shape>}

where:

shape: the shape to be transformed. Mandatory.

Example: The following geo shape search will retrieve shapes intersecting the centroid of a WKT shape:

SELECT * FROM "shapes".block WHERE lucene = '{
   refresh: true,
   filter: {
      type: "geo_shape",
      field: "place",
      operation: "intersects",
      shape: {
         type: "centroid",
         shape: {
            type: "wkt",
            value: "LINESTRING(-80.90 29.05, -80.51 28.47, -80.60 28.12, -80.00 26.85, -80.05 26.37)"
         }
      }
   }
}';

Convex hull shape¶

Convex hull transformation returns the convex envelope of a shape.

Syntax:

{type: "convex_hull", shape: <shape>}

where:

shape: the shape to be transformed. Mandatory.

Example: The following geo shape search will retrieve shapes intersecting the convex hull of a WKT shape:

SELECT * FROM "shapes".block WHERE lucene = '{
   refresh: true,
   filter: {
      type: "geo_shape",
      field: "place",
      operation: "intersects",
      shape: {
         type: "convex_hull",
         shape: {
            type: "wkt",
            value: "LINESTRING(-80.90 29.05, -80.51 28.47, -80.60 28.12, -80.00 26.85, -80.05 26.37)"
         }
      }
   }
}';

Difference shape¶

Difference transformation subtracts the specified shapes.

Syntax:

{type: "difference", shapes: [ <shape> (, <shape>)* ] }

where:

shapes: the shapes to be subtracted. Mandatory.

Intersection shape¶

Intersection transformation intersects the specified shapes.

Syntax:

{type: "intersection", shapes: [ <shape> (, <shape>)* ] }

where:

shapes: the shapes to be intersected. Mandatory.

Union shape¶

Union transformation adds the specified shapes.

Syntax:

{type: "union", shapes: [ <shape> (, <shape>)* ] }

where:

shapes: the shapes to be added. Mandatory.

Keys	Action
`?`	Open this help
`n`	Next page
`p`	Previous page
`s`	Search