Loading

Example: Enrich your data based on geolocation

Stack Serverless

geo_match enrich policies match enrich data to incoming documents based on a geographic location, using a geo_shape query.

The following example creates a geo_match enrich policy that adds postal codes to incoming documents based on a set of coordinates. It then adds the geo_match enrich policy to a processor in an ingest pipeline.

Use the create index API to create a source index containing at least one geo_shape field.

 PUT /postal_codes { "mappings": { "properties": { "location": { "type": "geo_shape" }, "postal_code": { "type": "keyword" } } } }

Use the index API to index enrich data to this source index.

 PUT /postal_codes/_doc/1?refresh=wait_for { "location": { "type": "envelope", "coordinates": [ [ 13.0, 53.0 ], [ 14.0, 52.0 ] ] }, "postal_code": "96598" }

Use the create enrich policy API to create an enrich policy with the geo_match policy type. This policy must include:

  • One or more source indices
  • A match_field, the geo_shape field from the source indices used to match incoming documents
  • Enrich fields from the source indices you’d like to append to incoming documents
 PUT /_enrich/policy/postal_policy { "geo_match": { "indices": "postal_codes", "match_field": "location", "enrich_fields": [ "location", "postal_code" ] } }

Use the execute enrich policy API to create an enrich index for the policy.

 POST /_enrich/policy/postal_policy/_execute?wait_for_completion=false

Use the create or update pipeline API to create an ingest pipeline. In the pipeline, add an enrich processor that includes:

  • Your enrich policy.
  • The field of incoming documents used to match the geoshape of documents from the enrich index.
  • The target_field used to store appended enrich data for incoming documents. This field contains the match_field and enrich_fields specified in your enrich policy.
  • The shape_relation, which indicates how the processor matches geoshapes in incoming documents to geoshapes in documents from the enrich index. See Spatial Relations for valid options and more information.
 PUT /_ingest/pipeline/postal_lookup { "processors": [ { "enrich": { "description": "Add 'geo_data' based on 'geo_location'", "policy_name": "postal_policy", "field": "geo_location", "target_field": "geo_data", "shape_relation": "INTERSECTS" } } ] }

Use the ingest pipeline to index a document. The incoming document should include the field specified in your enrich processor.

 PUT /users/_doc/0?pipeline=postal_lookup { "first_name": "Mardy", "last_name": "Brown", "geo_location": "POINT (13.5 52.5)" }

To verify the enrich processor matched and appended the appropriate field data, use the get API to view the indexed document.

 GET /users/_doc/0

The API returns the following response:

{ "found": true, "_index": "users", "_id": "0", "_version": 1, "_seq_no": 55, "_primary_term": 1, "_source": { "geo_data": { "location": { "type": "envelope", "coordinates": [[13.0, 53.0], [14.0, 52.0]] }, "postal_code": "96598" }, "first_name": "Mardy", "last_name": "Brown", "geo_location": "POINT (13.5 52.5)" } }