Edit

Pattern syntax

  • Article

Important

LUIS will be retired on October 1st 2025 and starting April 1st 2023 you will not be able to create new LUIS resources. We recommend migrating your LUIS applications to conversational language understanding to benefit from continued product support and multilingual capabilities.

Pattern syntax is a template for an utterance. The template should contain words and entities you want to match as well as words and punctuation you want to ignore. It is not a regular expression.

Caution

Patterns only include machine-learning entity parents, not subentities. Entities in patterns are surrounded by curly brackets, {}. Patterns can include entities, and entities with roles. Pattern.any is an entity only used in patterns.

Pattern syntax supports the following syntax:

Function Syntax Nesting level Example
entity {} - curly brackets 2 Where is form {entity-name}?
optional [] - square brackets

There is a limit of 3 on nesting levels of any combination of optional and grouping		 2 The question mark is optional [?]
grouping () - parentheses 2 is (a | b)
or | - vertical bar (pipe)

There is a limit of 2 on the vertical bars (Or) in one group		 - Where is form ({form-name-short} | {form-name-long} | {form-number})
beginning and/or end of utterance ^ - caret - ^begin the utterance
the utterance is done^
^strict literal match of entire utterance with {number} entity^

Nesting syntax in patterns

The optional syntax, with square brackets, can be nested two levels. For example: [[this]is] a new form. This example allows for the following utterances:

Nested optional utterance example Explanation
this is a new form matches all words in pattern
is a new form matches outer optional word and non-optional words in pattern
a new form matches required words only

The grouping syntax, with parentheses, can be nested two levels. For example: (({Entity1:RoleName1} | {Entity1:RoleName2} ) | {Entity2} ). This feature allows any of the three entities to be matched.

If Entity1 is a Location with roles such as origin (Seattle) and destination (Cairo) and Entity 2 is a known building name from a list entity (RedWest-C), the following utterances would map to this pattern:

Nested grouping utterance example Explanation
RedWest-C matches outer grouping entity
Seattle matches one of the inner grouping entities
Cairo matches one of the inner grouping entities

Nesting limits for groups with optional syntax

A combination of grouping with optional syntax has a limit of 3 nesting levels.

Allowed Example
Yes ( [ ( test1 | test2 ) ] | test3 )
No ( [ ( [ test1 ] | test2 ) ] | test3 )

Nesting limits for groups with or-ing syntax

A combination of grouping with or-ing syntax has a limit of 2 vertical bars.

Allowed Example
Yes ( test1 | test2 | ( test3 | test4 ) )
No ( test1 | test2 | test3 | ( test4 | test5 ) )

Syntax to add an entity to a pattern template

To add an entity into the pattern template, surround the entity name with curly braces, such as Who does {Employee} manage?.

Pattern with entity
Who does {Employee} manage?

Syntax to add an entity and role to a pattern template

An entity role is denoted as {entity:role} with the entity name followed by a colon, then the role name. To add an entity with a role into the pattern template, surround the entity name and role name with curly braces, such as Book a ticket from {Location:Origin} to {Location:Destination}.

Pattern with entity roles
Book a ticket from {Location:Origin} to {Location:Destination}

Syntax to add a pattern.any to pattern template

The Pattern.any entity allows you to add an entity of varying length to the pattern. As long as the pattern template is followed, the pattern.any can be any length.

To add a Pattern.any entity into the pattern template, surround the Pattern.any entity with the curly braces, such as How much does {Booktitle} cost and what format is it available in?.

Pattern with Pattern.any entity
How much does {Booktitle} cost and what format is it available in?
Book titles in the pattern
How much does steal this book cost and what format is it available in?
How much does ask cost and what format is it available in?
How much does The Curious Incident of the Dog in the Night-Time cost and what format is it available in?

The words of the book title are not confusing to LUIS because LUIS knows where the book title ends, based on the Pattern.any entity.

Explicit lists

create an Explicit List through the authoring API to allow the exception when:

  • Your pattern contains a Pattern.any
  • And that pattern syntax allows for the possibility of an incorrect entity extraction based on the utterance.

For example, suppose you have a pattern containing both optional syntax, [], and entity syntax, {}, combined in a way to extract data incorrectly.

Consider the pattern `[find] email about {subject} [from {person}]'.

In the following utterances, the subject and person entity are extracted correctly and incorrectly:

Utterance Entity Correct extraction
email about dogs from Chris subject=dogs
person=Chris		 ✔
email about the man from La Mancha subject=the man
person=La Mancha		 X

In the preceding table, the subject should be the man from La Mancha (a book title) but because the subject includes the optional word from, the title is incorrectly predicted.

To fix this exception to the pattern, add the man from la mancha as an explicit list match for the {subject} entity using the authoring API for explicit list.

Syntax to mark optional text in a template utterance

Mark optional text in the utterance using the regular expression square bracket syntax, []. The optional text can nest square brackets up to two brackets only.

Pattern with optional text Meaning
[find] email about {subject} [from {person}] find and from {person} are optional
`Can you help me[?] The punctuation mark is optional

Punctuation marks (?, !, .) should be ignored and you need to ignore them using the square bracket syntax in patterns.

Next steps

Learn more about patterns:

Understand how sentiment is returned in the .json response.