diff --git a/docs/reference/ingest/apis/enrich/put-enrich-policy.asciidoc b/docs/reference/ingest/apis/enrich/put-enrich-policy.asciidoc index 26ab8e1afbd58..5701db4ee18bf 100644 --- a/docs/reference/ingest/apis/enrich/put-enrich-policy.asciidoc +++ b/docs/reference/ingest/apis/enrich/put-enrich-policy.asciidoc @@ -98,6 +98,11 @@ Matches enrich data to incoming documents based on a Matches enrich data to incoming documents based on a <>. For an example, see <>. + +`range`::: +Matches a number, date, or IP address in incoming documents to a range in the +enrich index based on a <>. For an example, +see <>. -- + .Properties of `` diff --git a/docs/reference/ingest/enrich.asciidoc b/docs/reference/ingest/enrich.asciidoc index 051d4bebcd6d1..0813f45840475 100644 --- a/docs/reference/ingest/enrich.asciidoc +++ b/docs/reference/ingest/enrich.asciidoc @@ -218,9 +218,6 @@ Instead, you can: to delete the previous enrich policy. // end::update-enrich-policy[] -include::geo-match-enrich-policy-type-ex.asciidoc[] -include::match-enrich-policy-type-ex.asciidoc[] - [[ingest-enrich-components]] ==== Enrich components @@ -271,3 +268,7 @@ How often {es} checks whether unused enrich indices can be deleted. Defaults to `enrich.max_concurrent_policy_executions`:: Maximum number of enrich policies to execute concurrently. Defaults to `50`. + +include::geo-match-enrich-policy-type-ex.asciidoc[] +include::match-enrich-policy-type-ex.asciidoc[] +include::range-enrich-policy-type-ex.asciidoc[] \ No newline at end of file diff --git a/docs/reference/ingest/geo-match-enrich-policy-type-ex.asciidoc b/docs/reference/ingest/geo-match-enrich-policy-type-ex.asciidoc index 9425b6555b6cd..f586b61388ebc 100644 --- a/docs/reference/ingest/geo-match-enrich-policy-type-ex.asciidoc +++ b/docs/reference/ingest/geo-match-enrich-policy-type-ex.asciidoc @@ -166,6 +166,8 @@ The API returns the following response: -------------------------------------------------- DELETE /_ingest/pipeline/postal_lookup DELETE /_enrich/policy/postal_policy +DELETE /postal_codes +DELETE /users -------------------------------------------------- // TEST[continued] //// diff --git a/docs/reference/ingest/match-enrich-policy-type-ex.asciidoc b/docs/reference/ingest/match-enrich-policy-type-ex.asciidoc index bed504b725db6..fa33d75fff69a 100644 --- a/docs/reference/ingest/match-enrich-policy-type-ex.asciidoc +++ b/docs/reference/ingest/match-enrich-policy-type-ex.asciidoc @@ -147,6 +147,8 @@ The API returns the following response: -------------------------------------------------- DELETE /_ingest/pipeline/user_lookup DELETE /_enrich/policy/users-policy +DELETE /my-index-000001 +DELETE /users -------------------------------------------------- // TEST[continued] //// diff --git a/docs/reference/ingest/range-enrich-policy-type-ex.asciidoc b/docs/reference/ingest/range-enrich-policy-type-ex.asciidoc new file mode 100644 index 0000000000000..e502c089ae540 --- /dev/null +++ b/docs/reference/ingest/range-enrich-policy-type-ex.asciidoc @@ -0,0 +1,165 @@ +[role="xpack"] +[testenv="basic"] +[[range-enrich-policy-type]] +=== Example: Enrich your data by matching a value to a range + +A `range` <> uses a <> 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 <> 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 <> to create an +enrich index for the policy. + +[source,console] +---- +POST /_enrich/policy/networks-policy/_execute +---- +// TEST[continued] + + +Use the <> to create an ingest +pipeline. In the pipeline, add an <> 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 <> 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", + "_type" : "_doc", + "_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] +////