Entities and their purpose in LUIS

The primary purpose of entities is to give the client application predictable extraction of data. An optional, secondary purpose is to boost the prediction of the intent with descriptors.

There are two types of entities:

  • machine-learned - from context
  • non-machine-learned - for exact text matches

Always begin with a machine-learned entity because that provides the widest range of data extraction choices.

Entity compared to intent

The entity represents a data concept inside the utterance that you want extracted.

Consider the following 3 utterances:

Utterance Data extracted Explanation
Help - Nothing to extract.
Send Bob a present Bob, present Bob is definitely important to completing the task. The present may be enough information or the bot may need to clarify what the present is with a follow-up question.
Send Bob a box of chocolates. The two important pieces of data, Bob and the box of chocolates, is important to completing the user's request.

An utterance can include many entities or none at all. A client application may need the entity to perform its task.

By comparison, the prediction of the intent for an utterance is required and represents the entire utterance. LUIS requires example utterances are contained in an intent. If the primary intention of the utterance isn't important to the client application, add all the utterances to the None intent.

If you find, later in the app lifecycle, you want to break out the utterances, you can easily do that. This can be to organize the utterances while you are authoring, or it can be to use the predicted intention in the client application.

There is no requirement to use the predicted intent in the client application, but it is returned as part of the prediction endpoint response.

Entities represent data

Entities are data you want to pull from the utterance. This can be a name, date, product name, or any group of words.

Utterance Entity Data
Buy 3 tickets to New York Prebuilt number
Location.Destination
3
New York
Buy a ticket from New York to London on March 5 Location.Origin
Location.Destination
Prebuilt datetimeV2
New York
London
March 5, 2018

While intents are required, entities are optional. You do not need to create entities for every concept in your app, but only for those required for the client application to take action.

If your utterances do not have details your bot needs to continue, you do not need to add them. As your app matures, you can add them later.

If you're not sure how you would use the information, add a few common prebuilt entities such as datetimeV2, ordinal, email, and phone number.

Design entities for decomposition

Begin your entity design with a machine-learned entity. This allows for easy design growth and changes of your entity over time. Add subcomponents (child entities) with constraints and descriptors to complete the entity design.

Designing for decomposition allows LUIS to return a deep degree of entity resolution to your client application. This allows your client-application to focus on business rules and leave data resolution to LUIS.

Machine-learned entities are primary data collections

Machine-learned entities are the top-level data unit. Subcomponents are child entities of machine-learned entities.

Constraints are exact-text matching entities that apply rules to identify and extract data. Descriptors are features applied to boost the relevance of the words or phrases for the prediction.

Types of entities

Choose the entity based on how the data should be extracted and how it should be represented after it is extracted.

Entity type Purpose
Machine-learned Parent grouping of entities, regardless of entity type. Machine-learned entities learn from context in the utterance. This makes variation of placement in example utterances significant.
List List of items and their synonyms extracted with exact text match.
Pattern.any Entity where end of entity is difficult to determine.
Prebuilt Already trained to extract specific kind of data such as URL or email. Some of these prebuilt entities are defined in the open-source Recognizers-Text project. If your specific culture or entity isn't currently supported, contribute to the project.
Regular Expression Uses regular expression for exact text match.

Entity role defines context

An entity's role is the named alias based on context within the utterance. An example is an utterance for booking a flight that has two locations, origin and destination.

Book a flight from Seattle to Cairo

The two examples of a location entity need to be extracted. The client-application needs to know the type of location for each in order to complete the ticket purchase. The location entity needs two roles of origin and destination and both need to be marked in the example utterances.

If LUIS finds the location but can't determine the role, the location entity is still returned. The client application would need to follow up with a question to determine which type of location the user meant.

Multiple entities can exist in an utterance and can be extracted without using roles. If the context of the sentence indicates the entity value, then a role should be used.

If the utterance includes a list of locations, I want to travel to Seattle, Cairo, and London., this is a list where each item doesn't have an additional meaning.

If you need more than the maximum number of entities

If you need more than the limit, contact support. To do so, gather detailed information about your system, go to the LUIS website, and then select Support. If your Azure subscription includes support services, contact Azure technical support.

Entity prediction status

The LUIS portal shows when the entity, in an example utterance, has a different entity prediction than the entity you selected. This different score is based on the current trained model.

Next steps

Learn concepts about good utterances.

See Add entities to learn more about how to add entities to your LUIS app.