289 lines
7.3 KiB
Plaintext
289 lines
7.3 KiB
Plaintext
[role="xpack"]
|
|
[testenv="basic"]
|
|
[[ingest-enriching-data]]
|
|
== Enrich your data
|
|
|
|
You can use the <<enrich-processor,enrich processor>>
|
|
to append data from existing indices
|
|
to incoming documents during ingest.
|
|
|
|
For example, you can use the enrich processor to:
|
|
|
|
* Identify web services or vendors based on known IP addresses
|
|
* Add product information to retail orders based on product IDs
|
|
* Supplement contact information based on an email address
|
|
* Add postal codes based on user coordinates
|
|
|
|
|
|
[float]
|
|
[[enrich-setup]]
|
|
=== Set up an enrich processor
|
|
|
|
To set up an enrich processor and learn how it works,
|
|
follow these steps:
|
|
|
|
. Check the <<enrich-prereqs, prerequisites>>.
|
|
. <<create-enrich-source-index>>.
|
|
. <<create-enrich-policy>>.
|
|
. <<execute-enrich-policy>>.
|
|
. <<add-enrich-processor>>.
|
|
. <<ingest-enrich-docs>>.
|
|
|
|
Once you have an enrich processor set up,
|
|
you can <<update-enrich-data,update your enrich data>>
|
|
and <<update-enrich-policies, update your enrich policies>>
|
|
using the <<enrich-apis,enrich APIs>>.
|
|
|
|
[IMPORTANT]
|
|
====
|
|
The enrich processor performs several operations
|
|
and may impact the speed of your <<pipeline,ingest pipeline>>.
|
|
|
|
We strongly recommend testing and benchmarking your enrich processors
|
|
before deploying them in production.
|
|
|
|
We do not recommend using the enrich processor to append real-time data.
|
|
The enrich processor works best with reference data
|
|
that doesn't change frequently.
|
|
====
|
|
|
|
[float]
|
|
[[enrich-prereqs]]
|
|
==== Prerequisites
|
|
|
|
include::{docdir}/ingest/apis/enrich/put-enrich-policy.asciidoc[tag=enrich-policy-api-prereqs]
|
|
|
|
[float]
|
|
[[create-enrich-source-index]]
|
|
==== Create a source index
|
|
|
|
To begin,
|
|
create one or more source indices.
|
|
|
|
A _source index_ contains data you want to append to incoming documents.
|
|
You can index and manage documents in a source index
|
|
like a regular index.
|
|
|
|
The following <<docs-index_,index API>> request creates the `users` source index
|
|
containing user data.
|
|
This request also indexes a new document to the `users` source index.
|
|
|
|
[source,console]
|
|
----
|
|
PUT /users/_doc/1?refresh=wait_for
|
|
{
|
|
"email": "mardy.brown@asciidocsmith.com",
|
|
"first_name": "Mardy",
|
|
"last_name": "Brown",
|
|
"city": "New Orleans",
|
|
"county": "Orleans",
|
|
"state": "LA",
|
|
"zip": 70116,
|
|
"web": "mardy.asciidocsmith.com"
|
|
}
|
|
----
|
|
|
|
You also can set up {beats-ref}/getting-started.html[{beats}],
|
|
such as a {filebeat-ref}/filebeat-getting-started.html[{filebeat}],
|
|
to automatically send and index documents
|
|
to your source indices.
|
|
See {beats-ref}/getting-started.html[Getting started with {beats}].
|
|
|
|
|
|
[float]
|
|
[[create-enrich-policy]]
|
|
==== Create an enrich policy
|
|
|
|
Use the <<put-enrich-policy-api,put enrich policy API>>
|
|
to create an enrich policy.
|
|
|
|
include::{docdir}/ingest/apis/enrich/put-enrich-policy.asciidoc[tag=enrich-policy-def]
|
|
|
|
[source,console]
|
|
----
|
|
PUT /_enrich/policy/users-policy
|
|
{
|
|
"match": {
|
|
"indices": "users",
|
|
"match_field": "email",
|
|
"enrich_fields": ["first_name", "last_name", "city", "zip", "state"]
|
|
}
|
|
}
|
|
----
|
|
// TEST[continued]
|
|
|
|
|
|
[float]
|
|
[[execute-enrich-policy]]
|
|
==== Execute an enrich policy
|
|
|
|
Use the <<execute-enrich-policy-api,execute enrich policy API>>
|
|
to create an enrich index for the policy.
|
|
|
|
include::apis/enrich/execute-enrich-policy.asciidoc[tag=execute-enrich-policy-def]
|
|
|
|
The following request executes the `users-policy` enrich policy.
|
|
Because this API request performs several operations,
|
|
it may take a while to return a response.
|
|
|
|
[source,console]
|
|
----
|
|
POST /_enrich/policy/users-policy/_execute
|
|
----
|
|
// TEST[continued]
|
|
|
|
|
|
[float]
|
|
[[add-enrich-processor]]
|
|
==== Add the enrich processor to an ingest pipeline
|
|
|
|
Use the <<put-pipeline-api,put pipeline API>>
|
|
to create an ingest pipeline.
|
|
Include an <<enrich-processor,enrich processor>>
|
|
that uses your enrich policy.
|
|
|
|
When defining an enrich processor,
|
|
you must include the following:
|
|
|
|
* The field used to match incoming documents
|
|
to documents in the enrich index.
|
|
+
|
|
This field should be included in incoming documents.
|
|
|
|
* The target field added to incoming documents.
|
|
This field contains all appended enrich data.
|
|
|
|
The following request adds a new pipeline, `user_lookup`.
|
|
This pipeline includes an enrich processor
|
|
that uses the `users-policy` enrich policy.
|
|
|
|
[source,console]
|
|
----
|
|
PUT /_ingest/pipeline/user_lookup
|
|
{
|
|
"description" : "Enriching user details to messages",
|
|
"processors" : [
|
|
{
|
|
"enrich" : {
|
|
"policy_name": "users-policy",
|
|
"field" : "email",
|
|
"target_field": "user",
|
|
"max_matches": "1"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
----
|
|
// TEST[continued]
|
|
|
|
Because the enrich policy type is `match`,
|
|
the enrich processor matches incoming documents
|
|
to documents in the enrich index
|
|
based on match field values.
|
|
The enrich processor then appends the enrich field data
|
|
from matching documents in the enrich index
|
|
to the target field of incoming documents.
|
|
|
|
Because the `max_matches` option for the enrich processor is `1`,
|
|
the enrich processor appends the data from only the best matching document
|
|
to each incoming document's target field as an object.
|
|
|
|
If the `max_matches` option were greater than `1`,
|
|
the processor could append data from up to the `max_matches` number of documents
|
|
to the target field as an array.
|
|
|
|
If the incoming document matches no documents in the enrich index,
|
|
the processor appends no data.
|
|
|
|
You also can add other <<ingest-processors,processors>>
|
|
to your ingest pipeline.
|
|
You can use these processors to change or drop incoming documents
|
|
based on your criteria.
|
|
See <<ingest-processors>> for a list of built-in processors.
|
|
|
|
|
|
[float]
|
|
[[ingest-enrich-docs]]
|
|
==== Ingest and enrich documents
|
|
|
|
Index incoming documents using your ingest pipeline.
|
|
|
|
The following <<docs-index_,index API>> request uses the ingest pipeline
|
|
to index a document
|
|
containing the `email` field
|
|
specified in the enrich processor.
|
|
|
|
[source,console]
|
|
----
|
|
PUT /my_index/_doc/my_id?pipeline=user_lookup
|
|
{
|
|
"email": "mardy.brown@asciidocsmith.com"
|
|
}
|
|
----
|
|
// 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/_doc/my_id
|
|
----
|
|
// TEST[continued]
|
|
|
|
The API returns the following response:
|
|
|
|
[source,console-result]
|
|
----
|
|
{
|
|
"found": true,
|
|
"_index": "my_index",
|
|
"_type": "_doc",
|
|
"_id": "my_id",
|
|
"_version": 1,
|
|
"_seq_no": 55,
|
|
"_primary_term": 1,
|
|
"_source": {
|
|
"user": {
|
|
"email": "mardy.brown@asciidocsmith.com",
|
|
"first_name": "Mardy",
|
|
"last_name": "Brown",
|
|
"zip": 70116,
|
|
"city": "New Orleans",
|
|
"state": "LA"
|
|
},
|
|
"email": "mardy.brown@asciidocsmith.com"
|
|
}
|
|
}
|
|
----
|
|
// TESTRESPONSE[s/"_seq_no": \d+/"_seq_no" : $body._seq_no/ s/"_primary_term":1/"_primary_term" : $body._primary_term/]
|
|
|
|
|
|
[float]
|
|
[[update-enrich-data]]
|
|
=== Update your enrich index
|
|
|
|
include::{docdir}/ingest/apis/enrich/execute-enrich-policy.asciidoc[tag=update-enrich-index]
|
|
|
|
If wanted, you can <<docs-reindex,reindex>>
|
|
or <<docs-update-by-query,update>> any already ingested documents
|
|
using your ingest pipeline.
|
|
|
|
|
|
[float]
|
|
[[update-enrich-policies]]
|
|
=== Update an enrich policy
|
|
|
|
include::apis/enrich/put-enrich-policy.asciidoc[tag=update-enrich-policy]
|
|
|
|
////
|
|
[source,console]
|
|
--------------------------------------------------
|
|
DELETE /_ingest/pipeline/user_lookup
|
|
|
|
DELETE /_enrich/policy/users-policy
|
|
--------------------------------------------------
|
|
// TEST[continued]
|
|
////
|