Circle ingest processor

Introduced 0.2.0

The circle ingest processor converts a circle — supplied as either Well-Known Text (WKT) or GeoJSON — into a regular polygon approximation at index time and stores it in a geo_shape or shape field. Circles model uniform coverage areas such as a broadcast radius, a delivery zone, a geofence, or a "within 500 m of this point" catchment.

Lucenia indexes the polygonized representation, so the full set of spatial queries (geo_shape intersects, within, disjoint, and contains) works against the resulting field with no client-side preprocessing.

For directional or asymmetric coverage — a cellular sector, a sensor footprint — use the ellipse processor instead, which takes two axes and an orientation.

Request fields

Field	Type	Description	Required
field	String	The source field containing the circle. The value must be either a WKT CIRCLE(...) string or a GeoJSON-style object (see Input formats).	Yes
error_distance	Double	The maximum tolerated error, in meters, between the true circle and its polygon approximation. Smaller values produce more polygon sides at the cost of indexing speed and storage.	Yes
shape_type	String	The field-mapping type used for the output polygon. Must be either geo_shape (geographic lat/lon) or shape (cartesian X/Y).	Yes
target_field	String	The field that will receive the polygonized circle. Defaults to the same value as field, overwriting the original circle.	No
ignore_missing	Boolean	If true and the source field is missing from the document, the processor exits without modifying the document. Defaults to false.	No

error_distance is always interpreted as a positive distance; a negative value is coerced to its absolute value.

Input formats

Well-Known Text (WKT)

Lucenia extends WKT with a CIRCLE primitive, taking a center and a radius in meters:

CIRCLE (centerLon centerLat radiusMeters)

A circle centered at (20, 20) with a 40-meter radius:

CIRCLE (20 20 40)

GeoJSON

{
  "type": "Circle",
  "coordinates": [20, 20],
  "radius": "40m"
}

radius accepts natural-language distances (for example, "40m", "500cm", or "1.2km").

Example

Step 1: Create the index

Map the destination field as geo_shape so the polygonized circle can be queried geographically:

PUT /circles
{
  "settings": { "number_of_replicas": 0 },
  "mappings": {
    "properties": {
      "name":   { "type": "keyword" },
      "circle": { "type": "geo_shape" }
    }
  }
}

Step 2: Create the ingest pipeline

PUT /_ingest/pipeline/circle_to_poly
{
  "description": "converts from circle to poly",
  "processors": [
    {
      "circle": {
        "field": "circle",
        "error_distance": 50.0,
        "shape_type": "geo_shape"
      }
    }
  ]
}

Step 3: Index a document through the pipeline

The processor replaces the value of circle with a polygon before the document is indexed:

PUT /circles/_doc/1?pipeline=circle_to_poly
{
  "name": "my_circle",
  "circle": "CIRCLE (20 20 40)"
}

The GeoJSON form is equivalent:

PUT /circles/_doc/2?pipeline=circle_to_poly
{
  "name": "depot_catchment",
  "circle": {
    "type": "Circle",
    "coordinates": [20.01, 20.02],
    "radius": "250m"
  }
}

Step 4: Query the coverage

Because the indexed value is a standard geo_shape polygon, any geo_shape query works:

GET /circles/_search
{
  "query": {
    "geo_shape": {
      "circle": {
        "shape": {
          "type": "envelope",
          "coordinates": [ [19.99, 20.02], [20.03, 19.99] ]
        },
        "relation": "intersects"
      }
    }
  }
}

Tuning error_distance

The number of polygon sides is derived from error_distance together with the circle's radius, so the same tolerance produces more sides on a larger circle. As a rule of thumb:

• Use a small value (centimeters to a few meters) when downstream analytics depend on precise boundary geometry — for example, finding narrow strips of overlap between adjacent coverage areas.
• Use a larger value (tens of meters) when ingesting millions of circles and approximate footprints are sufficient — for example, coarse heatmaps, or screening queries later refined by a more expensive check.

Output shape type

• geo_shape — geographic coordinates (longitude, latitude in degrees). Use this when the circle is defined in WGS84 and you want spherical-earth semantics.
• shape — planar X/Y coordinates. Use this when the circle is already in a projected coordinate system. To reproject incoming geometries from another CRS first, chain this with the spatial reprojection processor.

info

target_field defaults to field, which replaces the original circle with its polygonized form. Set target_field to a different field to keep the original WKT or GeoJSON alongside the indexed polygon.

Errors you may hit

Message	Cause
field [x] is null, cannot process it.	The source field is present but null, and ignore_missing is false.
field [x] must be a WKT Circle or a GeoJSON Circle value	The source field is neither a string nor an object.
found [POLYGON] instead of circle	The value parsed as a valid geometry, but not a circle.
invalid circle definition	The value could not be parsed — a missing radius, absent or malformed coordinates, or a type that is not Circle.
illegal [shape_type] value [x]. valid values are [SHAPE, GEO_SHAPE]	shape_type was something other than shape or geo_shape.