Request Topics

This page explains how to talk with Crystal.

Remember

Before you start to talk with your data, make sure that you are familiar with the concept of Topics, as they are the foundational units of information that enable meaningful interactions with Crystal.

In particular, you must be comfortable with the following concepts:

Objectives, Visualizations, Entities, Time Range Filters, Dynamic Filters
Configured Topics, Auto-generated Topics

To refresh your memory, find all the information you need here before proceeding!

Conversation Basics

Asking a question to Crystal means asking about a Topic.

To ask a question, you just need to ask for the components of the Topic you have in mind, one after the other. That's all you need to start talking with Crystal!

In particular, your question should:

Include the Objective (or Visualization) and the Entity (or Entities) for that Topic
Optionally include other details such as Time Range and Dynamic Filters.

Make sure your questions are straightforward, clear, and concise.

Discover the step-by-step process to write a question.

Remember

The following conversation rules consider the specific logics of both Configured Topics and Auto-generated Topics.

Keep them in mind and Crystal will deliver the best type of Topic related to your needs!

Introduce Your Question (Optional)

Start with any natural question formula, such as a request, an order, or even a greeting!

Examples

"Hey Crystal!"
"Can I see the …"
"Show me the…"

Specify the Topic (Mandatory)

Next, specify the Topic you want to ask about.

This means communicating the Objective and the Main Entity (or Main Entities) that constitute that Topic.

The two options to communicate an Objective are:

Naming a corresponding Visualization
Specifying the purpose of the Topic with a phrase

To specify an Entity, you can communicate:

A single Main Entity
Multiple Main Entities

Examples

" … the Comparison between Sales and Leads … "
"… the Breakdown of Users by Country …"
"Who were the top sellers in the last month?"

Dive deeper!

In the first example, the Topic is made of the following elements:
- Comparison = Objective
- Sales and Leads = Main Entities

In the second example, the Topic is made of the following elements:
- Breakdown = Visualization (of Objective Composition)
- Users by Country = Main Entity

In the third example, the Topic is made of the following elements:
- Who were the top = expression referring to the Ranking Objective
- Sellers = Main Entity

Remember

With the new Entity-Based Conversation capability, you should also consider the following new features:

In some specific cases, Crystal is able to infer the Objective and Visualization even though they are not explicit:
- If you ask for "Sales by country", Crystal will directly return a Breakdown Visualization for the Composition Objective.
- If you ask for "Total of sales", Crystal will directly return a Scaled-up Number Visualization for Highlight Objective.
When the Objective is not specified, Crystal will assume that you are asking for a Composition: therefore, it will return a default breakdown (if the underlying data makes it possible).

Filter by Time Range (Optional)

After specifying the Topic you're interested in, you can add a time range to capture a specific moment in time.

Examples

"… in the past six months …"
"… for the last year …"
"… in 2019 ..."

Remember

Time Filters can be dynamic (e.g. "today", "this year", etc.) or custom (e.g. "from 01/03/2023 to 29/12/2024").
Each Topic always comes with a Time Filter because it is not possible to have an analysis with no time time restriction. Time Filters are applied by default by the Admin during the Topic Configuration process.
If you do not include a specific time interval in your request, your data will be displayed following the default time range set up by your Admin. However, by specifying another time range in your question, you are changing the default settings.

Filter by Dynamic Filters (Optional)

Finally, if you want to further narrow down the scope of your analysis, you can add a Dynamic Filter, i.e. an Entity used as a Filter instead of as the Main Entity.

All you'll need to do is introduce the Filter with the correct preposition (e.g."for", "in", etc) and then add the Filter, by either:

Specifying the name of the Filter and the relative Filter Value, i.e. the specific instance for that Entity
Only specifying the Filter Value directly, by implying the Filter name.

Examples

"… for Country Spain"
"… for Spain"

Diver deeper!

The first example includes both a Filter and a Filter Value:
- "… for Country" = Filter
- "Spain" = Filter Value

The second example only includes a Filter Value:
- "… for Spain" = Filter Value

Remember

Dynamic Filters can be numeric (currencies, item codes, or sizes) or non-numeric (countries, towns, areas, item names, customer names)
You can only choose from the Filters your Admin has configured and made available for the selected Topic

Finally, in the case of numeric Dynamic Filters, you can also specify a condition on the Filter Values such as "greater than", "less than", and "between".

Examples

"List of codes for (number of) products sold..."

"...greater than 200"
"...lower than 200"
"...between 200 and 300"

How does it work?

When you request to apply a Filter in a conversation, Crystal can:

Recognize the filter by exact match
- For example, when the question is: "Show me the total sales for France," and the filter is "France".

Exact Match

This is when the text included in the question is the same as in the data source (unless a change is already included in the preprocessing, such as punctuation marks or special characters).

This is the easiest case for Crystal to recognize.

If the filter is "Italy" and you write "Italy" in the question, the system will recognize it immediately.

Recognize the filter by partial match
- For example, when you ask: "Show me the total sales for "Italy", but the set Filter is "Northern Italy".

Partial Match

This is when the text in the question is not exactly the same as in the data source, and some parts are missing too.

This is considered a ‘partial match’: the system needs help from the machine-learning model NER (Named-Entity Recognition).

NER is a search engine that can analyze all the words in a sentence and rank the most relevant terms, with the highest-scoring words as possible filter values.

Example:

If you accidentally type "nrthern Italy" instead of "Northern Italy", the search engine will find possible filter values and assign a ranking:

Northern Italy;
Italy;
Southern Italy;
Italy.

Since "Northern Italy" has a higher score, it will be the closest to the typed value, and therefore recognized as the right filter value to select. No extra questions needed.

On the other hand, if you are looking for the total sales for the Australian market and type: "Total Sales for Austr" with Australia and Austria in your data source, the NER will find two values with equivalent scores: Australia and Austria.

Since Crystal cannot be sure which of the two you need, the Disambiguation capability will come into play, asking you to choose between the two values.

In Brief...

Here is a quick guide to help you ask your questions on Crystal.

Example

"Can I see the comparison between Sales and Leads in the past six months for Spain and for Italy?"

Step

Mandatory / Optional

Example

Question Formula

Optional

Can I see

Objective / Visualization

Mandatory / Highly Recommended (*)

the comparison between

Main Entity / Entities

Mandatory

Sales and Leads

Time Range Filter

Optional

in the past six months

Dynamic Filter #1

Optional

for Spain

Dynamic Filter #2

Optional

and for Italy?

Note

As shown in the example above, you can ask for more than one Dynamic Filter at the same time, by concatenating them in the same question.

Simply use the formula "and for" and specify the other Filter(s).

Remember

When you specify the Time Range and Dynamic Filters, you can then manipulate the Topic as you want.

However, if you just specify the Topic by expressing the Objective and Main Entities (e.g. "the comparison between Sales and Leads"), you will see the default Time Range and the Filters set by the Admin.

Attention

(*) There are only a few cases in which Crystal can infer the Objectives and Visualizations (for Composition and Highlight Objectives), if these aren't specifically expressed.

Hence, as a general rule, it is always better to specify the Objective.

In the absence of a clear Objective that cannot be deduced, Crystal will try to return a Composition Objective, i.e. a Breakdown Visualization.

Express Yourself Naturally

With Crystal, you can express yourself as if you were speaking to a person.

That's because Crystal can:

Recognize words and sentences, even if spelled wrong or incomplete.

Learn More

For example, whether you spell:

Month & Day as numbers (“Total of Sales for 2022 10”, “Total of Sales for 2022 10 7”).
A month spelled out as a word ("Total of Sales for 2022 October” or “Total of Sales for October 2022”).
A month abbreviated (“Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec”).
Numbers with comma or dot (1,000 or 1.000)

Crystal will understand.

Recognize words that are not in the selected language but are officially used as part of the company jargon (e.g. anglicisms)

Learn More

For example, this can happen when using time aggregations, as words like "quarter" are frequently used in other languages too.

You can use English words in your queries even if you selected another language to speak in.

Crystal will understand.

Recognize synonyms and nuances

Learn More

When talking to Crystal, you can use the terminology that is most appropriate to the analysis context.

With aliasing, you can teach Crystal the language of your business by assigning synonyms to the Entities of your Topics.

To know more, consult the following articles:

Advanced Capabilities

When requesting a Topic, check out a few tricks that can come in handy on Crystal's advanced conversational capabilities!

Jump to Section

Keep talking to your data!

Last updated 2 months ago