English

Request Topics

This page explains how to talk with Crystal.

Remember

Before you start to talk with your data, please make sure that you have familiarized with the concept of Topic and all that is related to it, as Topics are the foundational units of information that enable meaningful interactions with Crystal.

In particular, you would need to be comfortable with the following concepts:

  • Objectives, Visualizations, Entities, Time Range Filters, Dynamic Filters

  • Configured Topics, Auto-generated Topics

If you need, you can deep-dive here before proceeding!

Conversation Basics

Asking a question to Crystal means asking a Topic.

To make a question, you just need to ask for the components of the Topic you have in mind, one after the other, and that's it! You are ready to talk with Crystal.

In particular, in your question:

  • you must include the Objective (or Visualization) and the Entity (or Entities) for that Topic

  • you can also optionally include other details such as Time Range and Dynamic Filters

As a best practice, make sure your questions go straight to the point, are clear and concise.

Let's see how to write a question step-by-step!

Remember

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

All you need to do is keep them in mind and it will be up to Crystal to provide you with the best type of Topic for your needs!

Introduce Your Question (Optional)

You may start with any natural question formula such as a request, a command or, why not, a greeting!

Examples

  • "Hey Crystal!"

  • "Can I see the …"

  • "Show me the…"

Specify the Topic (Mandatory)

Next, specify the Topic you want to ask for.

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

As far as the Objective is concerned, you also have the options to:

  • name a corresponding Visualization

  • express the purpose of the Topic with a phrase

As far as the Entities are concerned, you may specify:

  • 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?"

Deep Dive!

  • 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 capability Entity-Based Conversation, 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 simply ask "Sales by country", Crystal will directly return a Breakdown Visualization for the Objective Composition

    • if you simply ask "Total of sales", Crystal will directly return a Scaled-up Number Visualization for Objective Highlight

  • when the Objective is not specified, Crystal will assume that you are asking for a Composition: therefore, a breakdown will be returned by default (if the underlying data allow it)

Filter by Time Range (Optional)

After specifying the Topic you wish to ask for, you can add a time range to capture a specific moment in time of your data.

Examples

  • "… in the past six months …"

  • "… for the last year …"

  • "… in 2019 ..."

Remember

Each Topic always comes with a Time Filter applied because an analysis that is not restricted in terms of time is not possible. 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.

To do so, you need to 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

  • specifying only the Filter Value directly, by implying the Filter name

Examples

  • "… for Country Spain"

  • "… for Spain"

Deep Dive!

  • In the first example, there is both the Filter and the Filter Value:

    • "… for Country" = Filter

    • "Spain" = Filter Value

  • In the second example, there is only the 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 Filters among the ones that 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

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 the presence of 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 "North-Italy"

Partial Match

The text in the question is not exactly the same as in the data source, but some parts are missing.

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 provide a ranking of the most relevant terms, with the highest-scoring words as possible filter values.

Let’s make an example.

By accidentally typing "nrd Italy" instead of "North-Italy", the search engine will find possible filter values and assign a ranking:

  • North-Italy;

  • Italy;

  • South-Italy;

  • Italy.

Since "North Italy" has a higher score, it will be the closest to the value typed and so recognized as the right filter value to select and no need for more questions.

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 which value you want.

In Brief...

You can refer to this table as a quick guide to ask your questions.

Example

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

N.StepMandatory / OptionalExample

1

Question Formula

Optional

Can I see

2

Objective / Visualization

Mandatory / Highly Recommended (*)

the comparison between

3

Main Entity / Entities

Mandatory

Sales and Leads

4

Time Range Filter

Optional

in the past six months

5

Dynamic Filter #1

Optional

for Spain

6

Dynamic Filter #2

Optional

and for Italy?

Please Note

As shown in the example, 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

By specifying the Time Range and Dynamic Filters, you are able to manipulate the Topic as you like.

Otherwise, 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

(*) Crystal can infer the Objectives and Visualizations where not expressed only in few cases (for Composition and Highlight Objectives).

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 have total freedom of expression!

All because Crystal can:

  • recognize words and sentences even if spelled wrong or incomplete

Learn More!

For example, no matter if you spell:

  • Month & Day as Numbers (“Total of Sales for 2022 10”, “Total of Sales for 2022 10 7”).

  • Month as a Word ("Total of Sales for 2022 October” or “Total of Sales for October 2022”).

  • Month Abbreviations (“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 current language but are officially used as part of the jargon, for example anglicisms

Learn More!

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

You can use English words in your queries even though you are asking in anther language.

Crystal will understand.

  • recognise 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, you can use some tricks that can come in quite handy.

Deep dive on Crystal's advanced conversational capabilities!

Jump to Section

pageEntity-Based ConversationpageContext MemorypageAutocomplete

Keep talking to your data!

Last updated