vania-janet/multiturn-rag-retrieval-data huggingface dataset:
It has no example user utterances associated with it yet.
3. In the Add user examples field, type the following utterance, and then click Add example:

i'd like to make a reservation
4. Add these additional examples to help Watson recognize the reservation intent.

I want to reserve a table for dinner
Can 3 of us get a table for lunch?
do you have openings for next Wednesday at 7?
Is there availability for 4 on Tuesday night?
i'd like to come in for brunch tomorrow
can i reserve a table?
5. Click the Close![Close arrow](https://cloud.ibm.com/docs-content/v1/content/a2b18c153837bce00a5b4de496e4b4ca64bbf56e/assistant-data/images/close_arrow.png) icon to finish adding the reservation intent and its example utterances.







 Step 2: Add entities 

An entity definition includes a set of entity values that represent vocabulary that is often used in the context of a given intent. By defining entities, you can help your assistant identify references in the user input that are related to intents of interest. In this step, you will enable system entities that can recognize references to time, date, and numbers.



1. Click Entities to open the Entities page.
2. Enable system entities that can recognize date, time, and number references in user input. Click the System entities tab, and then turn on these entities:



* @sys-time
* @sys-date
* @sys-number





You have successfully enabled the @sys-date, @sys-time, and @sys-number system entities. Now you can use them in your dialog.





 Step 3: Add a dialog node with slots 

A dialog node represents the start of a thread of dialog between your assistant and the user. It contains a condition that must be met for the node to be processed by your assistant. At a minimum, it also contains a response.
To search for a keyword with the URL, use search as a parameter and set it equal to your keyword, for example, search=server.



 Searching by case number 

Enter the following to search support cases by case number:

Query
: number:CS1234567

URL
: https://cloud.ibm.com/unifiedsupport/cases?number=CS1234567





 Searching with multiple parameters 

You might want to search for both new and in progress support cases, limit the results to 25 per page, and displayed by severity. You also know that the case that you're looking for isn't going to be within the first couple of pages, so you want to start on page 5. Enter the following search query:

Query
: status:new,inProgress page:5 pageSize:25 sort:severity

URL
: https://cloud.ibm.com/unifiedsupport/cases?status=new&status=inProgress&pageSize=25&sort=severity







 Searching for resolved cases 

Enter the following query to view all of the resolved cases based on when they were last updated:

Query
: sort:updatedAT status:resolved

URL
: https://cloud.ibm.com/unifiedsupport/cases?sort=updatedAT&status=resolved







 Viewing support cases by using the API 

You can programmatically view a support case by using the API as shown in the following sample request. For more information, see the [Case Management API](https://cloud.ibm.com/apidocs/case-managementcasemanagement-createcase).

To view a case, see the following samples:



* Curl
* Java
* Python
* Go
* Node



curl -X GET 'https://support-center.cloud.ibm.com/case-management/v1/cases/{case_number}?fields=number,updated_at,resources' -H 'Authorization: TOKEN'

GetCaseOptions getCaseOptions = new GetCaseOptions.Builder()
.caseNumber(caseNumber)
For example, the input might include the information, There will be 6 of us dining at 7 PM. This one input contains two of the missing required values: the number of guests and time of the reservation. Your assistant recognizes and stores both of them, each one in its corresponding slot. It then displays the prompt that is associated with the next empty slot.

![Shows that two slots are filled, and the service prompts for the remaining one.](https://cloud.ibm.com/docs-content/v1/content/a2b18c153837bce00a5b4de496e4b4ca64bbf56e/assistant-data/images/pass-in-info.png)

Slots make it possible for your assistant to answer follow-up questions without having to reestablish the user's goal. For example, a user might ask for a weather forecast, then ask a follow-up question about weather in another location or on a different day. If you save the required forecast variables, such as location and day, in slots, then if a user asks a follow-up question with new variable values, you can overwrite the slot values with the new values provided, and give a response that reflects the new information. (For more information about how to call an external service from a dialog, see [Making programmatic calls from a dialog node](https://cloud.ibm.com/docs/assistant-data?topic=assistant-data-dialog-webhooks)).

![Shows someone asking for a weather forecast, and then following up with a question about weather for a different location and time.](https://cloud.ibm.com/docs-content/v1/content/a2b18c153837bce00a5b4de496e4b4ca64bbf56e/assistant-data/images/follow-up.png)

Using slots produces a more natural dialog flow between the user and your assistant, and is easier for you to manage than trying to collect the information by using many separate nodes.





 Adding slots 



1. Identify the units of information that you want to collect.
Domain-specific Relates to terms and concepts that have special meaning to an industry or business. In tennis, for example, the term love has a special meaning. It represents a zero score. If you built a tennis-related application, you would teach Discovery that the term love has a meaning in the domain of tennis that is different from the generally understood meaning. 
 Enrichment What you add to documents in your collection to identify or tag terms in the document that are significant. For example, when you apply the Entity enrichment, terms that mention city names or famous people are tagged as locations or people of interest. 
 Facet A category by which you can filter search query results. Automatically, facets based on entity types are applied to the query results for Document Retrieval projects and facets based on the parts of speech are applied to Content Mining projects. You can define your own facet categories based on document fields, including fields generated by enrichments, or based on dictionaries or patterns. [Learn more](https://cloud.ibm.com/docs/discovery-data?topic=discovery-data-facets) 
 Index As you upload data or connect to data that is stored in an external repository, the data is crawled and ingested. As part of the processing, an index is created to keep track of important information that is recognized from the source. The main difference between a data source and a collection is that content in the data source is crawled, normalized, and indexed as it is added to a collection. 
 Project A container for the collections of data that fuel your research or search applications. [Learn more](https://cloud.ibm.com/docs/discovery-data?topic=discovery-data-projects). 
 Regular expression A regular expression, also known as a regex, is a standardized format for defining search patterns. You can define patterns with special significance to your application. For example, the bill of materials (BOM) numbers for parts that you manufacture might have a standard syntax of two uppercase letters followed by four numbers (GT2345). You can teach Discovery to recognize BOM mentions by adding a regular expression that can recognize and tag occurrences of the pattern in text.
We recommend that you apply both available ratings to your results: Relevant and Not relevant. Only rating the Relevant documents does not provide the data needed. If you plan to score your documents, using both the Discovery tooling and the API, or if you plan to begin with the API and move to the tooling, use the 0 and 10 relevancy scores.
* A random sample of documents that are not explicitly given a relevance rating is assigned a relevance score of 0. It is not mandatory to apply a relevance score of 0 when you train your documents, but if you apply a relevance score of 0 to certain documents, relevancy training marks those documents as non-relevant examples, instead of treating them as a random sample of results from the query.
* The training queries must include some term overlap between the query and the desired answer so it can be retrieved by the Discovery service's initial search, which is broad in scope.



Watson uses training data to learn patterns and to generalize, not to memorize individual training queries. The service, therefore, might not always reproduce identical relevance results for any given training query.

Training cannot exceed the following maximum requirements:



* You cannot exceed 40 trained collections per environment.
* Within a single collection, you are limited to 10,000 training queries, with a maximum of 100 examples per query.







 Adding a query to the training-data set 

Use the POST /v1/environments/{environment_id}/collections/{collection_id}/training_data method to add a query to a collection's set of training data. The query is specified as a JSON object in the following format:

{
"query_id": "string",
"natural_language_query": "string",
"filter": "string",
"examples": [
{
"document_id": "string",
"cross_reference": "string",
"relevance": 0
}
]
}

The values in this object are as follows:



* query_id: A unique ID for the query. If you do not specify this field, the service automatically generates an ID.
There are many ways to run queries against Discovery and the different operations used can impact performance. These query characteristics can impact performance:



1. Length - Longer queries most likely have poorer performance.
2. Aggregations - Aggregations are a more complex query type, with nested aggregations having the highest impact on performance.
3. Operators - Wldcarding and fuzzy matching can impact performance.
4. Counts - Reducing the count of documents returned can improve performance; if you need to page through results, use the offset parameter.
5. Return fields - Limiting the fields returned to only those needed for your application can help (For example, don’t return the full text of the document if only the title and passage are needed.)



See [Query reference](https://cloud.ibm.com/docs/discovery?topic=discovery-query-reference) for details.





 Features used 

There are a number of features that enhance query results. The following features can impact performance:



1. Passage Retrieval - Passage retrieval searches within documents to find relevant snippets of text for your query. Use the passages.fields parameter to adjust which fields in the documents that passage retrieval searches. The parameter can help reduce the latency of passage retrieval when your content has many fields. For more information about passage retrieval, see [Passages](https://cloud.ibm.com/docs/discovery?topic=discovery-query-parameterspassages).
2. Relevancy Training - Relevancy training computes features for each top-level text field (fields at the same level as document_id in the JSON) in the collection. If there are many top level fields, this can cause a performance impact for a natural_language_query when using training. Reducing the number of top level fields can improve performance. This can be done via normalization or by manually editing the JSON to put fields that are not helpful to finding relevant content in a nested structure. Changing the fields used for training also has an impact on the model so you’ll need to consider both the impact to performance and accuracy of results if making this change.
,
"conditions": "refill_drink"
}
]
},
"source_dialog_node": "root"
}
]
}
],
},
"user_id": "faf4a112-f09f-4a95-a0be-43c496e6ac9a"
}
Show more

Note that the structure of a suggestion response is very similar to the structure of an option response. As with options, each suggestion includes a label that can be displayed to the user and a value specifying the input that should be sent back to the assistant if the user chooses the corresponding suggestion. To implement suggestion responses in your application, you can use the same approach that you would use for option responses.

For more information about the disambiguation feature, see [Disambiguation](https://cloud.ibm.com/docs/assistant?topic=assistant-dialog-runtimedialog-runtime-disambiguation).





 Search 

This feature is available only to users with a paid plan.

The search response type is used by a search skill to return the results from a Watson Discovery search. A search response includes an array of results, each of which provides information about a match returned from the Discovery search query:

{
"output": {
"generic": [
{
"response_type": "search",
"header": "I found the following information that might be helpful.",
"results":
{
"title": "About",
"body": "IBM Watson Assistant is a cognitive bot that you can customize for your business needs, and deploy across multiple channels to bring help to your customers where and when they need it.",
"url": "https://cloud.ibm.com/docs/assistant?topic=assistant-index",
"id": "6682eca3c5b3778ccb730b799a8063f3",
"result_metadata": {
Query result for example: equivalent interval expressions when you deal with DAY, HOUR, MINUTE and SECOND time units.

 LONG_VERSION SHORT_VERSION 

 2018-10-15 08:33:00.84 2018-10-15 08:33:00.84 







 columnReference 





 qualifiedName 

A qualified name is a sequence of identifiers that are separated by .. For example, a column name can be qualified by the name of the relation the column is defined in.

Qualified names are available in the following context:



* [functionOrAggregate](https://cloud.ibm.com/docs/sql-query?topic=sql-query-sql-referencefunctionOrAggregate)
* [lateralView](https://cloud.ibm.com/docs/sql-query?topic=sql-query-sql-referencelateralView)
* [sample](https://cloud.ibm.com/docs/sql-query?topic=sql-query-sql-referencesample)







 Related references - primary expression 

For more information about the clauses that are used by a primary expression, see the following topics:



* [caseExpression](https://cloud.ibm.com/docs/sql-query?topic=sql-query-sql-referencecaseExpression)
* [castExpression](https://cloud.ibm.com/docs/sql-query?topic=sql-query-sql-referencecastExpression)
* [constant](https://cloud.ibm.com/docs/sql-query?topic=sql-query-sql-referenceconstant)
* [columnReference](https://cloud.ibm.com/docs/sql-query?topic=sql-query-sql-referencecolumnReference)
* [expression](https://cloud.ibm.com/docs/sql-query?topic=sql-query-sql-referenceexpression)
* [functionOrAggregate](https://cloud.ibm.com/docs/sql-query?topic=sql-query-sql-referencefunctionOrAggregate)
"aggregation": "nested(enriched_text.entities).filter(enriched_text.entities.type::Organization).term(enriched_text.entities.text,count:3)"
}

The query results in an aggregations object that looks as follows:

{
"aggregations": [
{
"type": "nested",
"path": "enriched_text.entities",
"matching_results": 1993,
"aggregations":
{
"type": "filter",
"match": "enriched_text.entities.type::Organization",
"matching_results": 645,
"aggregations":
{
"type": "term",
"field": "enriched_text.entities.text",
"count": 3,
"results":
{
"key": "IBM",
"matching_results": 36
},
{
"key": "Docker",
"matching_results": 12
},
{
"key": "OpenShift",
"matching_results": 12
}
]
}
]
}
]
}
]
}
Show more

The nested() segment of the query found 1993 enriched_text.entities nested objects. The filter was applied to those objects and found 645 enriched_text.entities of type Organization.





 Terminal operations 

For most aggregation types, when you construct a query with multiple aggregation operations, the first operation is applied to the documents. Then, the output of that operation is used as the input for the next operation. However, a subset of the aggregation types are terminal operations. The output of a terminal operation is not used as input for the next aggregation. Instead, the output is returned in a discrete group.
In this case, the syntax allows for white space between elements, and what an element can be in order to suit the AQL purposes is also defined.Note that the term Alternation in this case means choice. Using a vertical bar between elements indicates that a choice exists, which can be grouped by using ( ) .

Pattern -> Alternation
Alternation -> Sequence | Sequence | ... | Sequence
Sequence -> Optional Optional ... Optional
Optional -> Repeat | Repeat ? Repeat -> Atom | Atom { min, max }
Atom -> <view_name.column_name>
'string'
<'string' [match parameters]>
/regex/
<Token>
Group
Group -> ( Pattern )

Specifically, an Atom can have six formats:



* <view_name.column_name>

Specifies a column from one of the views, table, or table function references that are named in the from list of the extract pattern statement.
* 'string'

Specifies a match to the specified string by using the AQL default dictionary match semantics.
* <'string' [match parameters]>

Specifies a match to the specified string by using the dictionary matching semantics that are specified by the [match parameters]. The format of [match parameters] is case (exact | insensitive). This format specifies the type of case-folding that is used to determine the string matches. To specify an exact case-sensitive match, select exact. To specify a match that is not case-sensitive match, select the default value insensitive.
* /regex/

Specifies a character-based regular expression match with matching constrained to a single token in the document text. In addition, the syntax allows a special token gap construct to be specified in a sequence expression to indicate a match between min and max number of tokens.
* <token>

A match for any token.
* [return clause]

Generates extracted values for each match of the pattern expression according to the return clause. The return clause has the same semantics as the return clause in an extract regex statement.
* [with inline_match on <viewname.colname>]
* [Annotated mentions](https://cloud.ibm.com/docs/assistant-data?topic=assistant-data-intentsintents-annotated-mentions)
* [Directly referencing an entity name in an intent example](https://cloud.ibm.com/docs/assistant-data?topic=assistant-data-intentsintents-entity-as-example)





 Referencing entity values and synonyms in intent examples 

If you have defined, or plan to define, entities that are related to this intent, mention the entity values or synonyms in some of the examples. Doing so helps to establish a relationship between the intent and entities. It is a weak relationship, but it does inform the model.



 Important 



* Intent example data should be representative and typical of data that your users provide. Examples can be collected from actual user data, or from people who are experts in your specific field. The representative and accurate nature of the data is important.
* Both training and test data (for evaluation purposes) should reflect the distribution of intents in real usage. Generally, more frequent intents have relatively more examples, and better response coverage.
* You can include punctuation in the example text, as long as it appears naturally. If you believe that some users express their intents with examples that include punctuation, and some users will not, include both versions. Generally, the more coverage for various patterns, the better the response.









 Annotated mentions 

As you define entities, you can annotate mentions of the entity directly from your existing intent user examples. A relationship that you identify in this way between the intent and the entity is not used by the intent classification model. However, when you add the mention to the entity, it is also added to that entity as new value. And when you add the mention to an existing entity value, it is also added to that entity value as new synonym. Intent classification does use these types of dictionary references in intent user examples to establish a weak reference between an intent and an entity.
* Event detection - The subject/action/object semantic role extraction checks for terms/actions such as "acquisition", "election results", or "IPO".
* Trending topics in the news - Identify popular topics and monitor increases and decreases in how frequently they (or related topics) are mentioned.



For information about writing queries for IBM Watson™ Discovery News, see:



* [Querying Watson Discovery News](https://cloud.ibm.com/docs/discovery?topic=discovery-query-conceptsquerying-news)
* [Query concepts](https://cloud.ibm.com/docs/discovery?topic=discovery-query-concepts)
* [Query reference](https://cloud.ibm.com/docs/discovery?topic=discovery-query-reference)



You cannot adjust the IBM Watson™ Discovery News configuration, train, or add documents to the IBM Watson™ Discovery News collection.

IBM Watson™ Discovery News queries display approximately 50 words from each article in the text JSON field. These words are extracted from the highlights. See [highlight](https://cloud.ibm.com/docs/discovery?topic=discovery-query-parametershighlight) for an explanation of highlights. Highlights do not need to be explicitly included in your query to enable this behavior.

The maximum number of results returned for a IBM Watson™ Discovery News query is 50. Use additional queries and the offset parameter to return more than 50 results.

This version of IBM Watson™ Discovery News debuted on 31 July 2017. IBM Watson™ Discovery News Original was retired from service 15 January 2018.
For more information about filtering vs. querying, see [Differences between the filter and query parameters](https://cloud.ibm.com/docs/discovery?topic=discovery-query-parametersfiltervquery).





 How to structure an aggregation 

Aggregations return a set of data values; for example, top keywords, overall sentiment of entities, and more. For the full list of aggregation options, see [Aggregations](https://cloud.ibm.com/docs/discovery?topic=discovery-query-referenceaggregations).

![Example aggregation query structure](https://cloud.ibm.com/docs-content/v1/content/ded4adc3ea0bd2a81b113c579f2b1183926da211/discovery/images/aggregation_structure.png)

This example aggregation finds all of the concepts in your collection. The delimiter in this query is . and the operator is (), see [Query operators](https://cloud.ibm.com/docs/discovery?topic=discovery-query-operators) to learn about other operators available in the Discovery Query Language.



 Example aggregation queries 

There are several types of ways you can aggregate results with Discovery News, including top values, sum, min, max, average, timeslice, and histogram. You can also add filters and nest aggregations.



 Filter aggregations 

This example aggregation returns the number of articles found in Discovery News about the Pittsburgh Steelers and how many of those results have a positive, negative, or neutral sentiment.



* filter(enriched_text.entities.text:"Pittsburgh Steelers").term(enriched_text.sentiment.document.label,count:3)



This example aggregation first filters a set of articles in Discovery News to only the ones that include the entities text of twitter. Next, the aggregation divides those articles by the document sentiment types. Only the top 3 document sentiment types (positive, negative, neutral) are returned.



* filter(enriched_text.entities.text:twitter).term(enriched_text.sentiment.document.label,count:3)







 Nested aggregations