Entity options

There are several entity options that change the behavior of entity matching and data extraction. These options are pre-configured for system entities, so you can not change them for system entities. However, you can change them for your own custom entities. You can create different kinds of entities, depending on the options selected:

There are also two options that do not determine the kind of entity, but do affect the behavior of entity matching:

This document describes each of these options.

Where to find this data

When building an agent, it is most common to use the Dialogflow ES console (visit documentation, open console). The instructions below focus on using the console. To access entity options data:

  1. Go to the Dialogflow ES console.
  2. Select an agent.
  3. Select Entities in the left sidebar menu.
  4. Select the Custom tab for custom entities defined for your agent or the System tab for system entities used by your agent.
  5. See the following checkbox options for any existing entities:
    • Define synonyms
    • Regexp entity (custom entity only)
    • Allow automated expansion (custom entity only)
    • Fuzzy matching (custom entity only)

If you are building an agent using the API instead of the console, see the EntityTypes reference. The API field names are similar to the console field names. The instructions below highlight any important differences between the console and the API.

Map entity

Map entities provide a map from reference values to synonyms for each reference value. Each map entity entry contains a single reference value and a list of synonyms. For example, each of the following rows are entity entries for a size entity type:

Reference value Synonyms
S S, small, tiny, little
M M, medium, average
L L, large, huge, big

Notice that the reference value is included in the synonym list for each entity entry above. In order for a reference value to be matched, it needs to be included as a synonym itself. When you initially enter a reference value with the console, it is automatically added as a synonym.

If any of the synonyms are matched for an end-user expression part, the associated reference value is extracted for the match and is used to resolve the associated parameter value.

It is okay for the reference value to be omitted from the synonym list. This just means that it is not matched to an end-user expression part, but it is used as the extracted value when one of its synonyms is matched. This is desirable when you use special strings for reference values that are not typed or spoken by end-users.

Many system entities are map entities. For example, the @sys.date system entity matches common date inputs like "January 1, 2015" or "The first of January of 2015". Both of those inputs are mapped to a reference value in ISO-8601 format: "2015-01-01T12:00:00-03:00".

To create a map entity:

  • Using the console, uncheck the Regexp entity option and check the Define synonyms option.
  • Using the API, set the EntityType kind field to KIND_MAP.

List entity

List entities provide a list of single value entity entries. They do not have reference values and synonyms. For example, each of the following rows are entity entries for a material entity type:

Value
fabric
wood
metal

If any value is matched for an end-user expression part, the value is extracted for the match and is used to resolve the associated parameter value.

Many system entities are list entities. For example, the @sys.color system entity matches common color inputs like "red" or "blue". When a color is matched, the extracted value does not map to any reference value. For example, shades of red, such as "scarlet" or "crimson", are not mapped to "red" and are extracted as their original values "scarlet" and "crimson".

To create a list entity:

  • Using the console, uncheck the Regexp entity option and uncheck the Define synonyms option.
  • Using the API, set the EntityType kind field to KIND_LIST.

Composite entity

A composite entity is a special kind of list entity. Entity entries for list entities typically contain simple words or phrases, but they may also contain other entity types. When an entity type is referenced in another entity type, the reference is called an alias. When a list entity contains aliases to other entity types, it is called a composite entity.

When creating an alias, you supply the name of the referenced entity type and a property name of your choosing. When a composite entity is matched at runtime, the extracted value is returned as a JSON object, with alias property names used as JSON property names. The format for entering an alias is:

@entity-name:property-name

For example, you could create a place entity type that matches either a city or a state with the following entity entries:

Value
@sys.geo-city:city
@sys.geo-state:state

If an end-user expression contains a "Nashville" part, the place entity type is matched. The extracted value is returned as: {"city": "Nashville"}.

You can also use multiple entity aliases in an entity entry. Consider the following move custom entity type that contains aliases to a direction entity type and the @sys.number system entity type:

Direction custom map entity type:

Reference value Synonyms
forward forward, forwards
back back, backward, backwards

Move custom list entity type:

Value
@sys.number:steps steps @direction:direction

If the move entity is matched to an end-user expression that contains "five steps backward", the move entity will be matched. The extracted value is returned as: {"steps": 5, "direction": "back"}.

Many system entities are composite entities. For example, the @sys.unit-currency system entity is used for matching amounts of money with a currency name. It matches end-user expressions like "50 euros" or "twenty dollars and five cents". The extracted value is returned as a JSON object like: {"amount": 50, "currency": "EUR"}

Regexp entity

With regexp entities, you can provide regular expressions for matching. For more information, see Regexp entities.

To create a regexp entity:

  • Using the console, check the Regexp entity option.
  • Using the API, set the EntityType kind field to KIND_REGEXP.

Automated expansion

You can enable automated expansion for a custom entity type. When enabled, your agent can recognize values that have not been explicitly provided. For example, consider a shopping list entity type:

Value
bread
butter
milk
apple
ice cream

If an end-user expression is "I need to buy some carrots", "carrots" will be matched for this entity type, even though it's not provided. The agent recognizes that "carrots" is contextually similar to other values.

You should follow the best practices when considering automated expansion:

  • Enabling automated expansion doesn't guarantee entity extraction. For a finite list, you should provide the complete list instead of providing a partial list and enabling automated expansion.
  • If you enable automated expansion in more than one entity, it may cause conflicts and unexpected classification results.
  • To ensure better parameter extraction quality, it is crucial to provide diverse training data which cover all the use-cases in which a given entity can be found in the expected agent's traffic. With not enough examples, automated entities expansion might not work as expected.

To enable automated expansion:

  • Using the console, check the Allow automated expansion option.
  • Using the API, set the EntityType autoExpansionMode field to AUTO_EXPANSION_MODE_DEFAULT.

Fuzzy matching

You can enable fuzzy matching for a custom entity. With fuzzy matching enabled, the ordering of the words in a value or synonym does not matter. For more information, see Fuzzy matching.

To enable fuzzy matching:

  • Using the console, check the Fuzzy matching option.
  • Using the API, set the EntityType enableFuzzyExtraction field to true.
Previous
Entities
Next
System entities