IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.
« Set up an enrich processor Example: Enrich your data based on exact values »
Elastic Docs ›Elasticsearch Guide [8.15] ›Ingest pipelines ›Enrich your data

Example: Enrich your data based on geolocation

edit

Example: Enrich your data based on geolocation

edit

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.

resp = client.indices.create(
    index="postal_codes",
    mappings={
        "properties": {
            "location": {
                "type": "geo_shape"
            },
            "postal_code": {
                "type": "keyword"
            }
        }
    },
)
print(resp)
response = client.indices.create(
  index: 'postal_codes',
  body: {
    mappings: {
      properties: {
        location: {
          type: 'geo_shape'
        },
        postal_code: {
          type: 'keyword'
        }
      }
    }
  }
)
puts response
const response = await client.indices.create({
  index: "postal_codes",
  mappings: {
    properties: {
      location: {
        type: "geo_shape",
      },
      postal_code: {
        type: "keyword",
      },
    },
  },
});
console.log(response);
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.

resp = client.index(
    index="postal_codes",
    id="1",
    refresh="wait_for",
    document={
        "location": {
            "type": "envelope",
            "coordinates": [
                [
                    13,
                    53
                ],
                [
                    14,
                    52
                ]
            ]
        },
        "postal_code": "96598"
    },
)
print(resp)
response = client.index(
  index: 'postal_codes',
  id: 1,
  refresh: 'wait_for',
  body: {
    location: {
      type: 'envelope',
      coordinates: [
        [
          13,
          53
        ],
        [
          14,
          52
        ]
      ]
    },
    postal_code: '96598'
  }
)
puts response
const response = await client.index({
  index: "postal_codes",
  id: 1,
  refresh: "wait_for",
  document: {
    location: {
      type: "envelope",
      coordinates: [
        [13, 53],
        [14, 52],
      ],
    },
    postal_code: "96598",
  },
});
console.log(response);
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 
resp = client.enrich.put_policy(
    name="postal_policy",
    geo_match={
        "indices": "postal_codes",
        "match_field": "location",
        "enrich_fields": [
            "location",
            "postal_code"
        ]
    },
)
print(resp)
response = client.enrich.put_policy(
  name: 'postal_policy',
  body: {
    geo_match: {
      indices: 'postal_codes',
      match_field: 'location',
      enrich_fields: [
        'location',
        'postal_code'
      ]
    }
  }
)
puts response
const response = await client.enrich.putPolicy({
  name: "postal_policy",
  geo_match: {
    indices: "postal_codes",
    match_field: "location",
    enrich_fields: ["location", "postal_code"],
  },
});
console.log(response);
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. 
resp = client.ingest.put_pipeline(
    id="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"
            }
        }
    ],
)
print(resp)
const response = await client.ingest.putPipeline({
  id: "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",
      },
    },
  ],
});
console.log(response);
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.

resp = client.index(
    index="users",
    id="0",
    pipeline="postal_lookup",
    document={
        "first_name": "Mardy",
        "last_name": "Brown",
        "geo_location": "POINT (13.5 52.5)"
    },
)
print(resp)
const response = await client.index({
  index: "users",
  id: 0,
  pipeline: "postal_lookup",
  document: {
    first_name: "Mardy",
    last_name: "Brown",
    geo_location: "POINT (13.5 52.5)",
  },
});
console.log(response);
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.

resp = client.get(
    index="users",
    id="0",
)
print(resp)
response = client.get(
  index: 'users',
  id: 0
)
puts response
const response = await client.get({
  index: "users",
  id: 0,
});
console.log(response);
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)"
  }
}
« Set up an enrich processor Example: Enrich your data based on exact values »