Skip to content

Commit c30ab86

Browse files
mjmbischoffjrodewig
mjmbischoff
and
jrodewig
authored
[DOCS] Document range enrich policy (#79607)
Adding docs for the range enrich policy Co-authored-by: James Rodewig <[email protected]>
1 parent 4d8dd1f commit c30ab86

File tree

5 files changed

+177
-3
lines changed

5 files changed

+177
-3
lines changed

‎docs/reference/ingest/apis/enrich/put-enrich-policy.asciidoc‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -98,6 +98,11 @@ Matches enrich data to incoming documents based on a
9898
Matches enrich data to incoming documents based on a
9999
<<query-dsl-term-query,`term` query>>. For an example, see
100100
<<match-enrich-policy-type>>.
101+
102+
`range`:::
103+
Matches a number, date, or IP address in incoming documents to a range in the
104+
enrich index based on a <<query-dsl-term-query,`term` query>>. For an example,
105+
see <<range-enrich-policy-type>>.
101106
--
102107
+
103108
.Properties of `<policy-type>`

‎docs/reference/ingest/enrich.asciidoc‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -218,9 +218,6 @@ Instead, you can:
218218
to delete the previous enrich policy.
219219
// end::update-enrich-policy[]
220220

221-
include::geo-match-enrich-policy-type-ex.asciidoc[]
222-
include::match-enrich-policy-type-ex.asciidoc[]
223-
224221
[[ingest-enrich-components]]
225222
==== Enrich components
226223

@@ -271,3 +268,7 @@ How often {es} checks whether unused enrich indices can be deleted. Defaults to
271268

272269
`enrich.max_concurrent_policy_executions`::
273270
Maximum number of enrich policies to execute concurrently. Defaults to `50`.
271+
272+
include::geo-match-enrich-policy-type-ex.asciidoc[]
273+
include::match-enrich-policy-type-ex.asciidoc[]
274+
include::range-enrich-policy-type-ex.asciidoc[]

‎docs/reference/ingest/geo-match-enrich-policy-type-ex.asciidoc‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -165,6 +165,8 @@ The API returns the following response:
165165
--------------------------------------------------
166166
DELETE /_ingest/pipeline/postal_lookup
167167
DELETE /_enrich/policy/postal_policy
168+
DELETE /postal_codes
169+
DELETE /users
168170
--------------------------------------------------
169171
// TEST[continued]
170172
////

‎docs/reference/ingest/match-enrich-policy-type-ex.asciidoc‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -146,6 +146,8 @@ The API returns the following response:
146146
--------------------------------------------------
147147
DELETE /_ingest/pipeline/user_lookup
148148
DELETE /_enrich/policy/users-policy
149+
DELETE /my-index-000001
150+
DELETE /users
149151
--------------------------------------------------
150152
// TEST[continued]
151153
////

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

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
[role="xpack"]
2+
[testenv="basic"]
3+
[[range-enrich-policy-type]]
4+
=== Example: Enrich your data by matching a value to a range
5+
6+
A `range` <<enrich-policy,enrich policy>> uses a <<query-dsl-term-query,`term`
7+
query>> to match a number, date, or IP address in incoming documents to a range
8+
of the same type in the enrich index. Matching a range to a range is not
9+
supported.
10+
11+
The following example creates a `range` enrich policy that adds a descriptive network name and
12+
responsible department to incoming documents based on an IP address. It then
13+
adds the enrich policy to a processor in an ingest pipeline.
14+
15+
Use the <<indices-create-index, create index API>> with the appropriate mappings to create a source index.
16+
17+
[source,console]
18+
----
19+
PUT /networks
20+
{
21+
"mappings": {
22+
"properties": {
23+
"range": { "type": "ip_range" },
24+
"name": { "type": "keyword" },
25+
"department": { "type": "keyword" }
26+
}
27+
}
28+
}
29+
----
30+
31+
The following index API request indexes a new document to that index.
32+
33+
[source,console]
34+
----
35+
PUT /networks/_doc/1?refresh=wait_for
36+
{
37+
"range": "10.100.0.0/16",
38+
"name": "production",
39+
"department": "OPS"
40+
}
41+
----
42+
// TEST[continued]
43+
44+
Use the create enrich policy API to create an enrich policy with the
45+
`range` policy type. This policy must include:
46+
47+
* One or more source indices
48+
* A `match_field`,
49+
the field from the source indices used to match incoming documents
50+
* Enrich fields from the source indices you'd like to append to incoming
51+
documents
52+
53+
Since we plan to enrich documents based on an IP address, the policy's
54+
`match_field` must be an `ip_range` field.
55+
56+
[source,console]
57+
----
58+
PUT /_enrich/policy/networks-policy
59+
{
60+
"range": {
61+
"indices": "networks",
62+
"match_field": "range",
63+
"enrich_fields": ["name", "department"]
64+
}
65+
}
66+
----
67+
// TEST[continued]
68+
69+
Use the <<execute-enrich-policy-api,execute enrich policy API>> to create an
70+
enrich index for the policy.
71+
72+
[source,console]
73+
----
74+
POST /_enrich/policy/networks-policy/_execute
75+
----
76+
// TEST[continued]
77+
78+
79+
Use the <<put-pipeline-api,create or update pipeline API>> to create an ingest
80+
pipeline. In the pipeline, add an <<enrich-processor,enrich processor>> that
81+
includes:
82+
83+
* Your enrich policy.
84+
* The `field` of incoming documents used to match documents
85+
from the enrich index.
86+
* The `target_field` used to store appended enrich data for incoming documents.
87+
This field contains the `match_field` and `enrich_fields` specified in your
88+
enrich policy.
89+
90+
[source,console]
91+
----
92+
PUT /_ingest/pipeline/networks_lookup
93+
{
94+
"processors" : [
95+
{
96+
"enrich" : {
97+
"description": "Add 'network' data based on 'ip'",
98+
"policy_name": "networks-policy",
99+
"field" : "ip",
100+
"target_field": "network",
101+
"max_matches": "10"
102+
}
103+
}
104+
]
105+
}
106+
----
107+
// TEST[continued]
108+
109+
Use the ingest pipeline to index a document. The incoming document should
110+
include the `field` specified in your enrich processor.
111+
112+
[source,console]
113+
----
114+
PUT /my-index-000001/_doc/my_id?pipeline=networks_lookup
115+
{
116+
"ip": "10.100.34.1"
117+
}
118+
----
119+
// TEST[continued]
120+
121+
To verify the enrich processor matched and appended the appropriate field data,
122+
use the <<docs-get,get API>> to view the indexed document.
123+
124+
[source,console]
125+
----
126+
GET /my-index-000001/_doc/my_id
127+
----
128+
// TEST[continued]
129+
130+
The API returns the following response:
131+
132+
[source,console-result]
133+
----
134+
{
135+
"_index" : "my-index-000001",
136+
"_id" : "my_id",
137+
"_version" : 1,
138+
"_seq_no" : 0,
139+
"_primary_term" : 1,
140+
"found" : true,
141+
"_source" : {
142+
"ip" : "10.100.34.1",
143+
"network" : [
144+
{
145+
"name" : "production",
146+
"range" : "10.100.0.0/16",
147+
"department" : "OPS"
148+
}
149+
]
150+
}
151+
}
152+
----
153+
// TESTRESPONSE[s/"_seq_no": \d+/"_seq_no" : $body._seq_no/ s/"_primary_term":1/"_primary_term" : $body._primary_term/]
154+
155+
////
156+
[source,console]
157+
--------------------------------------------------
158+
DELETE /_ingest/pipeline/networks_lookup
159+
DELETE /_enrich/policy/networks-policy
160+
DELETE /networks
161+
DELETE /my-index-000001
162+
--------------------------------------------------
163+
// TEST[continued]
164+
////

0 commit comments

Comments
 (0)