This documentation contains work-in-progress information for future Elastic Stack and Cloud releases. Use the version selector to view supported release docs. It also contains some Elastic Cloud serverless information. Check out our serverless docs for more details.

« Example: Enrich your data based on geolocation Example: Enrich your data by matching a value to a range »

› › ›

Example: Enrich your data based on exact values

edit

Example: Enrich your data based on exact values

edit

match enrich policies match enrich data to incoming documents based on an exact value, such as a email address or ID, using a term query.

The following example creates a match enrich policy that adds user name and contact information to incoming documents based on an email address. It then adds the match enrich policy to a processor in an ingest pipeline.

Use the create index API or index API to create a source index.

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

resp = client.index(
    index="users",
    id="1",
    refresh="wait_for",
    document={
        "email": "mardy.brown@asciidocsmith.com",
        "first_name": "Mardy",
        "last_name": "Brown",
        "city": "New Orleans",
        "county": "Orleans",
        "state": "LA",
        "zip": 70116,
        "web": "mardy.asciidocsmith.com"
    },
)
print(resp)

response = client.index(
  index: 'users',
  id: 1,
  refresh: 'wait_for',
  body: {
    email: 'mardy.brown@asciidocsmith.com',
    first_name: 'Mardy',
    last_name: 'Brown',
    city: 'New Orleans',
    county: 'Orleans',
    state: 'LA',
    zip: 70_116,
    web: 'mardy.asciidocsmith.com'
  }
)
puts response

const response = await client.index({
  index: "users",
  id: 1,
  refresh: "wait_for",
  document: {
    email: "mardy.brown@asciidocsmith.com",
    first_name: "Mardy",
    last_name: "Brown",
    city: "New Orleans",
    county: "Orleans",
    state: "LA",
    zip: 70116,
    web: "mardy.asciidocsmith.com",
  },
});
console.log(response);

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"
}

Use the create enrich policy API to create an enrich policy with the match 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

resp = client.enrich.put_policy(
    name="users-policy",
    match={
        "indices": "users",
        "match_field": "email",
        "enrich_fields": [
            "first_name",
            "last_name",
            "city",
            "zip",
            "state"
        ]
    },
)
print(resp)

response = client.enrich.put_policy(
  name: 'users-policy',
  body: {
    match: {
      indices: 'users',
      match_field: 'email',
      enrich_fields: [
        'first_name',
        'last_name',
        'city',
        'zip',
        'state'
      ]
    }
  }
)
puts response

const response = await client.enrich.putPolicy({
  name: "users-policy",
  match: {
    indices: "users",
    match_field: "email",
    enrich_fields: ["first_name", "last_name", "city", "zip", "state"],
  },
});
console.log(response);

PUT /_enrich/policy/users-policy
{
  "match": {
    "indices": "users",
    "match_field": "email",
    "enrich_fields": ["first_name", "last_name", "city", "zip", "state"]
  }
}

Use the execute enrich policy API to create an enrich index for the policy.

POST /_enrich/policy/users-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 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.

resp = client.ingest.put_pipeline(
    id="user_lookup",
    processors=[
        {
            "enrich": {
                "description": "Add 'user' data based on 'email'",
                "policy_name": "users-policy",
                "field": "email",
                "target_field": "user",
                "max_matches": "1"
            }
        }
    ],
)
print(resp)

const response = await client.ingest.putPipeline({
  id: "user_lookup",
  processors: [
    {
      enrich: {
        description: "Add 'user' data based on 'email'",
        policy_name: "users-policy",
        field: "email",
        target_field: "user",
        max_matches: "1",
      },
    },
  ],
});
console.log(response);

PUT /_ingest/pipeline/user_lookup
{
  "processors" : [
    {
      "enrich" : {
        "description": "Add 'user' data based on 'email'",
        "policy_name": "users-policy",
        "field" : "email",
        "target_field": "user",
        "max_matches": "1"
      }
    }
  ]
}

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

resp = client.index(
    index="my-index-000001",
    id="my_id",
    pipeline="user_lookup",
    document={
        "email": "mardy.brown@asciidocsmith.com"
    },
)
print(resp)

const response = await client.index({
  index: "my-index-000001",
  id: "my_id",
  pipeline: "user_lookup",
  document: {
    email: "mardy.brown@asciidocsmith.com",
  },
});
console.log(response);

PUT /my-index-000001/_doc/my_id?pipeline=user_lookup
{
  "email": "mardy.brown@asciidocsmith.com"
}

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="my-index-000001",
    id="my_id",
)
print(resp)

response = client.get(
  index: 'my-index-000001',
  id: 'my_id'
)
puts response

const response = await client.get({
  index: "my-index-000001",
  id: "my_id",
});
console.log(response);

GET /my-index-000001/_doc/my_id

The API returns the following response:

{
  "found": true,
  "_index": "my-index-000001",
  "_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"
  }
}

« Example: Enrich your data based on geolocation Example: Enrich your data by matching a value to a range »