elasticsearch/docs/reference/ingest/range-enrich-policy-type-ex.asciidoc

[role="xpack"]
[[range-enrich-policy-type]]
=== Example: Enrich your data by matching a value to a range

A `range` <<enrich-policy,enrich policy>> uses a <<query-dsl-term-query,`term`
query>> to match a number, date, or IP address in incoming documents to a range
of the same type in the enrich index. Matching a range to a range is not
supported.

The following example creates a `range` enrich policy that adds a descriptive network name and
responsible department to incoming documents based on an IP address. It then
adds the enrich policy to a processor in an ingest pipeline.

Use the <<indices-create-index, create index API>> with the appropriate mappings to create a source index.

[source,console]
----
PUT /networks
{
  "mappings": {
    "properties": {
      "range": { "type": "ip_range" },
      "name": { "type": "keyword" },
      "department": { "type": "keyword" }
    }
  }
}
----

The following index API request indexes a new document to that index.

[source,console]
----
PUT /networks/_doc/1?refresh=wait_for
{
  "range": "10.100.0.0/16",
  "name": "production",
  "department": "OPS"
}
----
// TEST[continued]

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

* One or more source indices
* A `match_field`,
the field from the source indices used to match incoming documents
* Enrich fields from the source indices you'd like to append to incoming
documents

Since we plan to enrich documents based on an IP address, the policy's
`match_field` must be an `ip_range` field.

[source,console]
----
PUT /_enrich/policy/networks-policy
{
  "range": {
    "indices": "networks",
    "match_field": "range",
    "enrich_fields": ["name", "department"]
  }
}
----
// TEST[continued]

Use the <<execute-enrich-policy-api,execute enrich policy API>> to create an
enrich index for the policy.

[source,console]
----
POST /_enrich/policy/networks-policy/_execute
----
// TEST[continued]


Use the <<put-pipeline-api,create or update pipeline API>> to create an ingest
pipeline. In the pipeline, add an <<enrich-processor,enrich processor>> that
includes:

* Your enrich policy.
* The `field` of incoming documents used to match 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.

[source,console]
----
PUT /_ingest/pipeline/networks_lookup
{
  "processors" : [
    {
      "enrich" : {
        "description": "Add 'network' data based on 'ip'",
        "policy_name": "networks-policy",
        "field" : "ip",
        "target_field": "network",
        "max_matches": "10"
      }
    }
  ]
}
----
// TEST[continued]

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

[source,console]
----
PUT /my-index-000001/_doc/my_id?pipeline=networks_lookup
{
  "ip": "10.100.34.1"
}
----
// TEST[continued]

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

[source,console]
----
GET /my-index-000001/_doc/my_id
----
// TEST[continued]

The API returns the following response:

[source,console-result]
----
{
  "_index" : "my-index-000001",
  "_id" : "my_id",
  "_version" : 1,
  "_seq_no" : 0,
  "_primary_term" : 1,
  "found" : true,
  "_source" : {
    "ip" : "10.100.34.1",
    "network" : [
      {
        "name" : "production",
        "range" : "10.100.0.0/16",
        "department" : "OPS"
      }
    ]
  }
}
----
// TESTRESPONSE[s/"_seq_no": \d+/"_seq_no" : $body._seq_no/ s/"_primary_term":1/"_primary_term" : $body._primary_term/]

////
[source,console]
--------------------------------------------------
DELETE /_ingest/pipeline/networks_lookup
DELETE /_enrich/policy/networks-policy
DELETE /networks
DELETE /my-index-000001
--------------------------------------------------
// TEST[continued]
////