Tutorial: Group and extract related data

In this tutorial, add a composite entity to bundle extracted data of various types into a single containing entity. By bundling the data, the client application can easily extract related data in different data types.

The purpose of the composite entity is to group related entities into a parent category entity. The information exists as separate entities before a composite is created.

The composite entity is a good fit for this type of data because the data:

  • Are related to each other.
  • Use a variety of entity types.
  • Need to be grouped and processed by client app as a unit of information.

In this tutorial, you learn how to:

  • Import example app
  • Create intent
  • Add composite entity
  • Train
  • Publish
  • Get intents and entities from endpoint

For this article, you can use the free LUIS account in order to author your LUIS application.

Import example app

  1. Download and save the app JSON file from the List entity tutorial.

  2. Import the JSON into a new app.

  3. From the Manage section, on the Versions tab, clone the version, and name it composite. Cloning is a great way to play with various LUIS features without affecting the original version. Because the version name is used as part of the URL route, the name can't contain any characters that are not valid in a URL.

Composite entity

In this app, the department name is defined in the Department list entity and includes synonyms.

The TransferEmployeeToDepartment intent has example utterances to request an employee be moved to a new department.

Example utterances for this intent include:

Example utterances
move John W. Smith to the accounting department
transfer Jill Jones from to R&D

The move request should include the department name, and the employee name.

Add the PersonName prebuilt entity to help with common data type extraction

LUIS provides several prebuilt entities for common data extraction.

  1. Select Build from the top navigation, then select Entities from the left navigation menu.

  2. Select Manage prebuilt entity button.

  3. Select PersonName from the list of prebuilt entities then select Done.

    Screenshot of number select in prebuilt entities dialog

    This entity helps you add name recognition to your client application.

Create composite entity from example utterances

  1. Select Intents from the left navigation.

  2. Select TransferEmployeeToDepartment from the intents list.

  3. In the utterance place John Jackson in engineering, select the personName entity, John Jackson, then select Wrap in composite entity in the pop-up menu list for the following utterance.

    Screenshot of selecting wrap composite in drop down dialog

  4. Then immediately select the last entity, engineering in the utterance. A green bar is drawn under the selected words indicating a composite entity. In the pop-up menu, enter the composite name TransferEmployeeInfo then select enter.

    Screenshot of entering composite name in drop down dialog

  5. In What type of entity do you want to create?, all the fields required are in the list: personName and Department. Select Done. Notice that the prebuilt entity, personName, was added to the composite entity. If you could have a prebuilt entity appear between the beginning and ending tokens of a composite entity, the composite entity must contain those prebuilt entities. If the prebuilt entities are not included, the composite entity is not correctly predicted but each individual element is.

    Screenshot of entering composite name in drop down dialog

Label example utterances with composite entity

  1. In each example utterance, select the left-most entity that should be in the composite. Then select Wrap in composite entity.

  2. Select the last word in the composite entity then select TransferEmployeeInfo from the pop-up menu.

  3. Verify all utterances in the intent are labeled with the composite entity.

Train the app so the changes to the intent can be tested

  1. In the top right side of the LUIS website, select the Train button.

    Train button

  2. Training is complete when you see the green status bar at the top of the website confirming success.

    Trained status bar

Publish the app so the trained model is queryable from the endpoint

In order to receive a LUIS prediction in a chat bot or other client application, you need to publish the app to the endpoint.

  1. Select Publish in the top right navigation.

    LUIS publish to endpoint button in top right menu

  2. Select the Production slot and the Publish button.

    LUIS publish to endpoint

  3. Publishing is complete when you see the green status bar at the top of the website confirming success.

    LUIS publish to endpoint

  4. Select the endpoints link in the green status bar to go to the Keys and endpoints page. The endpoint URLs are listed at the bottom.

Get intent and entity prediction from endpoint

  1. In the Manage section (top right menu), on the Keys and endpoints page (left menu), select the endpoint URL at the bottom of the page. This action opens another browser tab with the endpoint URL in the address bar.

    The endpoint URL looks like https://<region>.api.cognitive.microsoft.com/luis/v2.0/apps/<appID>?verbose=true&subscription-key=<YOUR_KEY>&<optional-name-value-pairs>&q=<user-utterance-text>.

  2. Go to the end of the URL in the address and enter Move Jill Jones to DevOps. The last querystring parameter is q, the utterance query.

    Since this test is to verify the composite is extracted correctly, a test can either include an existing sample utterance or a new utterance. A good test is to include all the child entities in the composite entity.

    {
      "query": "Move Jill Jones to DevOps",
      "topScoringIntent": {
        "intent": "TransferEmployeeToDepartment",
        "score": 0.9882747
      },
      "intents": [
        {
          "intent": "TransferEmployeeToDepartment",
          "score": 0.9882747
        },
        {
          "intent": "None",
          "score": 0.00925369747
        }
      ],
      "entities": [
        {
          "entity": "jill jones",
          "type": "builtin.personName",
          "startIndex": 5,
          "endIndex": 14
        },
        {
          "entity": "devops",
          "type": "Department",
          "startIndex": 19,
          "endIndex": 24,
          "resolution": {
            "values": [
              "Development Operations"
            ]
          }
        },
        {
          "entity": "jill jones to devops",
          "type": "TransferEmployeeInfo",
          "startIndex": 5,
          "endIndex": 24,
          "score": 0.9607566
        }
      ],
      "compositeEntities": [
        {
          "parentType": "TransferEmployeeInfo",
          "value": "jill jones to devops",
          "children": [
            {
              "type": "builtin.personName",
              "value": "jill jones"
            },
            {
              "type": "Department",
              "value": "devops"
            }
          ]
        }
      ]
    }
    

    This utterance returns a composite entities array. Each entity is given a type and value. To find more precision for each child entity, use the combination of type and value from the composite array item to find the corresponding item in the entities array.

Clean up resources

When no longer needed, delete the LUIS app. To do so, select My apps from the top left menu. Select the ellipsis (...) to the right of the app name in the app list, select Delete. On the pop-up dialog Delete app?, select Ok.

Next steps

This tutorial created a composite entity to encapsulate existing entities. This allows the client application to find a group of related data in different datatypes to continue the conversation. A client application for this Human Resources app could ask what day and time the move needs to begin and end. It could also ask about other logistics of the move such as a physical phone.