This page is for anyone who has administrator access to Yellowfin and wishes to enable Guided NLQ on a view. If you're looking for information on how to ask questions with Guided NLQ, visit our quick reference to Guided NLQ.
What is Guided NLQ?
Guided Natural Language Query (NLQ) provides users with an intuitive and easy-to-use tool to find answers to their questions. Users won’t need a degree in anything to use this tool: simply start typing a question and Yellowfin will guide you along the way.
Implementing Guided NLQ within your Yellowfin instance may reduce requests to analysts because users should now be able to find the answers to their questions by themselves. Presuming a typical level of access, users can start with asking a question, produce charts and tables on the fly (as answers), and insert those results in stories, dashboards and presentations.
Before you start
Guided NLQ is available in Yellowfin 9.7 and later. When upgrading from prior versions, please consider the following information.
For convenience, we’ve automatically enabled Guided NLQ for our Ski Team tutorial data on fresh installs of Yellowfin 9.7 and beyond. Updating an existing version of Yellowfin will not automatically enable Guided NLQ for Ski Team.
Configure Guided NLQ
There are four steps to using Guided NLQ:
- Have an active Yellowfin license (Guided NLQ is enabled on all existing licenses by default)
- Enable Guided NLQ at role level
- Enable Guided NLQ at view level
- Enable Guided NLQ at field level
Check your license
Your existing Yellowfin license already includes Guided NLQ access. To confirm this at any time, visit the License Management admin page within Yellowfin and scroll down to the row for Guided NLQ Access.
Enable guided NLQ at role level
Guided NLQ can be enabled and disabled by role. There are two roles for Guided NLQ.
Guided NLQ User
- A user with this role can access Guided NLQ to ask questions of the data they have access to.
- Any role that has Create or Update Report access automatically has the Guided NLQ User role enabled upon upgrading to Yellowfin 9.7 or later.
Guided NLQ Manager
- A user with this role can configure Guided NLQ settings for views they access to update.
- Any role that has Create or Update View access will have the Guided NLQ Manager role enabled upon upgrading to Yellowfin 9.7 or later.
Based on the above, this means that the standard System Administrator role has both Guided NLQ roles enabled by default for both upgrades and fresh installs of Yellowfin 9.7 or later. In addition, any roles, whether default or custom, may also have one or both of these Guided NLQ roles enabled: Guided NLQ Manager for roles with access to edit views, and Guided NLQ User for roles with access to create and update reports.
For further information on roles and how to enable and disable them, please see our wiki page on roles.
Enable Guided NLQ at view level
Guided NLQ works with any Yellowfin view, regardless of the underlying data source. Generating queries via Guided NLQ is a live and interactive experience, so to ensure the best user experience, we suggest you follow these guidelines:
- Select only the fields likely to be used within questions: the fewer dimensions, the faster the performance because Yellowfin attempts to cache all their values and will perform a live query against the source for any that are not cached.
- Prevent loading filter values if there is a risk of any problems in bringing back large lists of dimensional values from the datasource.
- Select views that are optimally structured for fast response times.
- Select views that are stored within a high-performance DBMS.
- Turn off value filtering for very large views so that Guided NLQ doesn’t cache the dimension values, which may be memory intensive.
Also, don’t forget to check and/or update your column names so that your audience understands what they mean if they’re not already familiar with the data.
Guided NLQ can be enabled and disabled per Yellowfin view. By default, Guided NLQ is disabled for new and existing views. However, the Yellowfin tutorial data view, Ski Team, has Guided NLQ enabled for all fresh installations (from 9.7 onwards). You can enable Guided NLQ from your view’s settings — without editing the view itself.
The table below describes the options available.
Enable View for Guided NLQ
Toggle this on to enable Guided NLQ for this view. This is the only mandatory option on this page for enabling Guided NLQ.
Primary Date Field
From this dropdown, select the default date field for Guided NLQ to use. When your question contains the date range (for example, ‘Show profit margin for this month’), Guided NLQ will use this date field, which you can alter.
Note that this field is also used for Assisted Insights. An additional field called Scope of Analysis - Date Period will appear when this field is not empty and it is used only for Assisted Insights. Therefore, you can ignore the Scope of Analysis - Date Period field for Guided NLQ.
Custom Help Text - NLQ
Add content to this text field if you wish to display any specific text for the current view. When using this view with Guided NLQ, this text will be displayed on the dropdown for switching views, alongside the view name and description.
- From the burger bun (), click Browse, then Views to display a list of available views
- Find the view you wish to use with NLQ, and right-click on it to display a pop-up menu
- Hover your mouse on Edit, then select Automation Settings
The Automation Settings dialog box will appear
- Click the toggle for Enable View for NLQ to activate it
- Use the table of information above these steps to choose whether you wish to configure any other general aspects of Guided NLQ
- Click the Continue button
Yellowfin will switch tabs to the Key Variables tab where you can configure individual fields for use with Guided NLQ
The Automation Settings dialog box won’t save your settings until you’ve clicked the Submit button on the Key Variables tab. Any time you visit the Automation Settings dialog box, you must continue to the Key Variables tab and click on Submit. This saves any changes to both tabs of the dialog box.
Enable Guided NLQ at field level
Once Guided NLQ is enabled at the view level, specific fields can be enabled for use within Guided NLQ. This means you can limit the number of fields available for asking questions via Guided NLQ.
For example, you might choose to exclude fields that might not typically be asked in a question, such as ID fields or URL fields. There are two benefits to excluding unnecessary fields:
- Users won’t be lost in a sea of unnecessary options when they ask a question
- System speed is less likely to be impacted (particularly important for large data sets)
You may also wish to include preset filters to help simplify and speed up Guided NLQ. These preset filters refine the results from Guided NLQ using tools you’re probably already familiar with — filter groups and/or calculated filters (take your pick). See the section below on focus areas for more information.
When you select each field to include with Guided NLQ, you will notice a number of other options available, depending on whether the field is a metric, a dimension or a date field. The table below indicates where fields used with Guided NLQ may also be used elsewhere in Yellowfin. For example, a custom chart color is system-wide, and will therefore be used with Guided NLQ and with all charts. We recommend you keep this in mind if you’re considering changing system-wide settings, as the changes will reach beyond Guided NLQ.
A dropdown on the left displays any default aggregation applied to the field. This can be edited from the dropdown if required.
The field name can be edited here, but note that it will be updated everywhere else it’s used (the view, reports etc.).
Use this checkbox to enable or disable Guided NLQ at field level. If the checkbox is greyed out, check for these situations and correct, if necessary.
Guided NLQ only
Plural (dimensions only)
Only editable if a field has been enabled for either Assisted Insights or Guided NLQ. In Guided NLQ, this will ensure that plurals are shown as needed when someone is asking a question, and when certain types of results are displayed.
Assisted Insights, Signals and Guided NLQ
This dropdown lets you customize the format of metrics and dates. For example, you can use the typical date format options to display a yyyy-MM-dd date as MM d yyyy.
You may also set the date default after you’ve chosen your preferred format by clicking on the date displayed on the dropdown above the Custom menu option.
This column is displayed only if the date field uses DateFormatter or TimestampFormatter. Use this field to see and set the date granularity with one click using this dropdown menu. When a date field appears in a question, Guided NLQ uses its granularity as the suggested default and when building charts with a date axis.
Custom Chart Color
Any custom chart colors set here will be used when Guided NLQ creates charts.
Filter Value Case
Selecting Uppercase or Lowercase for this field activates a backend operation which converts the filter value into the selected case. Anything you set for a field here will be used when Yellowfin runs an SQL query with this field. It is never reflected in how field values are displayed when asking a question within Guided NLQ.
If a dimension or date field has this option set, it must be included with every Guided NLQ question. In Guided NLQ, an orange dot will appear next to mandatory fields in the dropdowns for the date blocks and ‘Where’ blocks of a sentence (these are the two clauses where filters can be used). Make sure that anyone using Guided NLQ with a view with mandatory filters is aware of the mandatory filters.
Field Usage Restrictions
This red checkbox works differently to the blue tick-style checkboxes. If a red checkbox on the dropdown is checked, some restrictions have been applied. Click on the dropdown to see the full list.
The Load Filter Values is used only for Guided NLQ. For fields with many values, this option can be disabled (red cross on) to prevent Yellowfin from querying the database for possible values when Guided NLQ displays the field values as a list. This can improve performance of the system. The user can instead type a value.
System wide (excluding Load Filter Values which is used for
Guided NLQ only)
Load Filter Values is enabled (red cross off)
All of the above fields can be enabled and/or configured for NLQ via the Automation Settings dialog box. As noted in the table, some of those settings may also affect other areas of Yellowfin, such as reports or Assisted Insights. Make sure that you are aware of shared settings before you save any changes.
- Ensure you have followed the steps above to configure the first tab of the Automation Settings dialog box and that you are viewing the Key Variables tab
- Locate the column called Guided NLQ and check the checkbox for any fields you wish to include in Guided NLQ
- Use the table above these steps to judge whether any other columns need adjusting (none of them are mandatory for Guided NLQ to function, once enabled)
- Scroll down to check if you have any preset filters that you’d like to include as focus areas (see section below for further details)
- When you’ve finished your adjustments, click the Submit button
Guided NLQ is now enabled for your view.
Include focus areas (optional)
Some views are complex in nature, and queries written against them may require complex ‘where’ clauses or a repetitive use of simple filter logic. Focus areas simplify these scenarios for Guided NLQ users. Including focus areas with Guided NLQ is entirely optional and is done per view when enabling and disabling fields for Guided NLQ.
Let’s take our tutorial data of Ski Team as an example. Ski Team athlete regions include Asia, Australia, Europe, Africa, North America and South America. Let’s say you wanted to query on the combined regions of EMEA (Europe and Africa), APAC (Asia and Australia) and the Americas (North and South America), and specifically on the upcoming athletes under the age of 18 from each of those regions.
You can bundle this information up into focus areas for Guided NLQ by first creating either calculated filters or filter groups for each combined region, then ticking the checkbox for their use in Guided NLQ. Any available focus areas from your view will be displayed at the bottom of the Key Variables tab of the Automation Settings dialog box:
Once selected for use within Guided NLQ, the dropdown at the top of the Ask a Question window will display the focus areas that you’ve activated:
When a user selects a focus area, it will act as a filter on the user’s question. It will display only the results that match both the question and the focus area.
Later on: embed Guided NLQ
Like most other elements of Yellowfin, you can embed and whitelabel Guided NLQ according to your needs.
You can embed Guided NLQ: