Named entities

A named entity is a word or a phrase that distinguishes an object or a phenomenon among other objects or phenomena of a similar type. These can be names of cities, countries, currencies.

tip

From the point of view of the script code, a named entity is a named pattern defined using a named entity dictionary.

NLU rules can include named entities just like any other named pattern, and so recognize named entity dictionary entries in user requests.

Declaration

Follow the following steps to declare a pattern as a named entity. We shall be using a fragment of a cities dictionary for this example, placed into dicts/cities.csv.

1;New York City, New York, NY;{"name": "New York", "lat": 40.71427, "lon": -74.00597}

1. Import the named entity dictionary into the .sc script file via the require tag:

   require: dicts/cities.csv
       name = Cities
       var = Cities

2. Define an entity converter in one of the .js files or init blocks:

   $global.cityConverter = function($parseTree) {
       var id = $parseTree.Cities[0].value;
       return Cities[id].value;
   };
   tip

   Using converters is optional, but it simplifies accessing values associated with the entities in the dictionary.

3. Declare a named pattern using a special $entity pattern element. Pass the named entity dictionary name in angle brackets and the converter name as a parameter after ||:

   patterns:
       $city = $entity<Cities> || converter = cityConverter
   caution

   If a pattern is created with $entity<> and converter, its name must not match the name of an NLU core entity. For example, if a project has an $Example pattern and an Example entity, it might cause errors during the script execution.

How to use

Consider the following state that will trigger on requests with the $city entity mentioned:

state: City
    q!: * $city *

On an example request I come from New York, information on this entity will be contained in the $parseTree:

{
  "city": [
    {
      // Supplementary keys: tag, pattern, etc.
      "value": {
        "name": "New York",
        "lat": 40.71427,
        "lon": -74.00597
      }
    }
  ],
  "_city": {
    "name": "New York",
    "lat": 40.71427,
    "lon": -74.00597
  }
}

tip

The <pattern_name> key contains detailed information on all entities recognized in the request, while the _<pattern_name> contains only the value of the first such entity.

The value differs based on whether or not a converter is defined for the entity:

• If a converter is present, the value it returns is saved in $parseTree.
• If there is no converter, only the entity ID is saved.