IBM Cloud Docs
Manage enrichments

Manage enrichments

Apply enrichments to fields in your documents to make meaningful information easier to find and return in searches.

You typically apply enrichments to fields at the time that you create the enrichment. However, you can apply enrichments to fields later. You might want to apply an existing enrichment to a new custom field that you create by using the SDU tool, for example. You can remove enrichments that you applied to fields also.

For more information about available enrichments, see the following topics:

To apply enrichments to a Content Mining project, you should use the Content Mining application instead of using the Discovery user interface. When you use the Content Mining application, it ensures that the enrichments are accepted in the Content Mining project. For more information about applying enrichments such as a dictionary or phrase sentiment to a Content Mining project, see Enrich your collection.

To manage enrichments, complete the following steps:

  1. From the navigation pane, open the Manage collections page, and then click a collection to open it.

  2. Click the Enrichments tab.

    A list of available enrichments is displayed.

    You can identify built-in enrichments because they are categorized as type System. The list also includes any custom enrichments that were created in any of the projects in your service instance.

  3. Find the enrichment that you want to apply or remove.

  4. Click the twistie in the associated field to expand a list of fields.

  5. Do one of the following things:

    • To apply an enrichment to documents, select the field or fields that you want to enrich. You can apply enrichments to the text and html fields, and to custom fields that were added from uploaded JSON or CSV files or from the Smart Document Understanding (SDU) tool.

      If the field that you choose comes from a JSON file, after you apply the enrichment, the field data type is converted to an array. The field is converted to an array even if it contains a single value. For example, "field1": "Discovery" becomes "field1": ["Discovery"]. Only the first 50,000 characters of a custom field from a JSON file are enriched.

    • To remove an enrichment, clear the checkboxes for fields that you want to remove the enrichment from.

  6. Click Apply changes and reprocess to apply your changes to the collection.

Deleting an enrichment

You can delete a custom enrichment that you built to teach Discovery about your service. Custom enrichments include dictionaries, regular expressions, patterns, and so on. For more information, see Adding domain-specific resources.

You cannot delete a prebuilt enrichment. Prebuilt enrichments include the Natural Language Understanding enrichments, such as the Entities enrichment, that are built into the product. To determine which enrichments are built in, check the Type column of the Enrichments page for a collection. Prebuilt enrichments have the System type.

To delete a custom enrichment, complete the following steps:

  1. Open a project that uses the custom enrichment.

  2. Click Manage collections, and then open a collection where the enrichment is in use.

  3. From the Enrichments page of a collection, remove the enrichment from any fields where it is applied.

  4. Click Apply changes and reprocess, and then wait for the system to process the documents in your collection without the enrichment.

  5. Repeat the previous step for every collection in every project where the enrichment is used.

    Remember, a custom enrichment can be used by any collection in any project within a single Discovery service instance.

  6. From any of the collections that used the enrichment, open the Enrichments page, and then click the delete icon to delete the enrichment.

The custom enrichment is removed from the Enrichments list everywhere in this service instance.

Using the API to manage enrichments

To apply an enrichment to data by using the API, complete the following steps:

  1. First, you must know the unique ID of the enrichment that you want to apply. For more information, see Enrichment IDs.
  2. Use the Create collection or Update collection methods to apply an enrichment to the documents in a collection. For more information, see Apply enrichment by using the API

Enrichment IDs

If you want to apply a custom enrichment that you created for one collection to another collection, you must know the unique ID that was generated for the enrichment when it was created. Use the API to list enrichments from the project where the custom enrichment is in use. The list that is returned includes enrichment ID information.

For prebuilt enrichments, the unique IDs do not change. The following table lists the IDs that are associated with each prebuilt enrichment type and identifies the collection languages for which the enrichment is supported. An enrichment cannot be applied to a collection unless the collection language is supported by the enrichment.

Prebuilt enrichment IDs
Name Enrichment ID Supported languages
Contracts 701db916-fc83-57ab-0000-000000000014 en
Entities 701db916-fc83-57ab-0000-00000000001e ar, de, en, es, fr, it, ja, ko, nl, pt, zh-CN
Keywords 701db916-fc83-57ab-0000-000000000018 ar, de, en, es, fr, it, ja, ko, nl, pt, zh-CN
Part of Speech 701db916-fc83-57ab-0000-000000000002 All supported languages
Sentiment of Document 701db916-fc83-57ab-0000-000000000016 ar, de, en, es, fr, it, ja, ko, nl, pt, zh-CN
Table Understanding 701db916-fc83-57ab-0000-000000000012 All supported languages

For more information about all of the supported languages, see Language support.

Apply enrichments by using the API

To apply an enrichment by using the API, complete the following steps:

  1. Determine the base URL for the endpoint and the token or API key for your deployment.

    For more information, see Building custom applications with the API.

  2. Get the project ID for your project.

    From the product user interface, go to the Integrate and Deploy > View API information page, and then copy the project ID.

  3. If you don't know the ID of the collection that you want to apply the enrichment to, get a list of your collections to find it.

    For example:

    GET $authentication $url/v2/projects/$project_id/collections?version=2019-11-22
    

    The collection_id is returned.

  4. Send a GET request to return the configuration of the collection that lists the applied enrichments.

    For example:

    GET $authentication $url/v2/projects/$project_id/collections/$collection_id?version=2019-11-22
    

    For the enrichment IDs for the prebuilt enrichments, see Enrichment IDs.

  5. Add the enrichment that you want to apply.

    For example, to add the Keywords enrichment, you can include the enrichment in the enrichments list. First, get its ID from the table.

    The Keywords enrichment ID is 701db916-fc83-57ab-0000-000000000018. To indicate that you want to apply the Keywords enrichment to the content in the text field of the documents in the collection, you can represent it in JSON format as follows:

    {
        "enrichment_id" : "701db916-fc83-57ab-0000-000000000018",
        "fields" : [ "text" ]
    }
    

    Any enrichments that you specify replace the default enrichments. Therefore, if you want to retain a default enrichment, don't forget to include it in the list of enrichments that you apply to the collection. For a list of default enrichments per project type, see Default enrichments per project type.

    For example, to retain the Entities enrichment and add the Keywords enrichment, you might specify the following in the request body.

    "enrichments": [
      {
        "enrichment_id": "701db916-fc83-57ab-0000-00000000001e",
        "fields": [
          "text"
        ]
      },
      {
        "enrichment_id": "701db916-fc83-57ab-0000-000000000018",
        "fields": [
          "text"
        ]
      } 
    ]
    
  6. Submit the updated JSON request body with the update collection method to apply the enrichment to your collection.

    For example:

    POST $authentication -d '$requestBody' $url/v2/projects/$project_id/collections/$collection_id?version=2019-11-22
    

Default enrichments per project type

Some prebuilt enrichments are applied automatically to collections in a project based on the project type. The following table shows the default enrichments that are applied to each project type.

Default enrichments per project type
This table has row and column headers. The row headers identify project types. The column headers identify different enrichments. To understand which enrichments are applied to a project type by default, go to the row that describes the enrichments, and find the columns for the project type that you are interested in.
Enrichment Document Retrieval Document Retrieval for Contracts Conversational Search Content Mining
Contracts checkmark icon
Entities checkmark icon checkmark icon
Keywords
Part of Speech checkmark icon
Sentiment of Document
Table Understanding checkmark icon