Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.activeviam.com/llms.txt

Use this file to discover all available pages before exploring further.

The Atoti Tableau Adapter connects Tableau to an Atoti application so that cube data can be visualized directly in Tableau. It combines Tableau’s visualization capabilities with Atoti’s multidimensional data model. Understanding how Tableau interprets cube data and behaves in different modes ensures accurate analysis.
This feature is experimental. It must be manually enabled with the following property: activeviam.feature.experimental.atoti_sql_server.enabled=true.
Prerequisites
  • An active Atoti application with a cube available.
  • Tableau Desktop or Tableau Cloud access.
  • Atoti Tableau Adapter configured and running.
  • Basic knowledge of Atoti cubes and Tableau concepts such as dimensions, measures, and aggregation.

​
How is an Atoti cube represented in Tableau?

Once connected through the Tableau Adapter, the cube appears on Tableau’s data source page. When Atoti exposes a cube to BI tools, it builds a flat table whose columns are the cube’s levels and measures. Not every element of the cube is exposed: the sections below describe which ones are included and which are excluded.

​
Levels and measures exposed by Atoti

The visibility of a level or a measure in an Atoti cube is respected. For levels, this means the level’s hierarchy is marked as visible; for measures, the measure itself has a visible flag. Elements marked as hidden in the cube configuration are excluded. There are special cases:
  • The AllMember level is never included.
  • The measure hierarchy itself is never included.

​
Analysis hierarchies

Analysis hierarchies whose members are user-defined (i.e., hardcoded within the project rather than derived from data in a store) are not exposed to BI tools. Analysis hierarchies whose members are derived from a store field are exposed normally. To link an analysis hierarchy to one or more store fields, its description must be customized, as in the example below: 
final IActivePivotInstanceDescription cubeDescription =
    StartBuilding.cube("cube")
        .withDimension("dimension")
        .withAnalysisHierarchy("analysisHierarchy", "pluginKey")
        .withCustomizations(
            desc ->
                desc.setLevels(List.of(new AxisLevelDescription("levelName", "storeField"))))
        .build();
return cubeDescription;

​
Fields classification by Tableau

Field is the term used by Tableau to designate a column in a discovered SQL table. In this case, this refers to both exposed cube levels and measures. Internally, Tableau automatically identifies each field as a dimension or measure. This classification is made depending on the type of data the field contains. A field is also classified as discrete or continuous based on Tableau’s standard logic. More information can be found in the official documentation. The image below illustrates how Atoti exposed levels and measures are represented in the Data pane.
Tableau measures and levels

​
How to reproduce the cube’s structure

Tableau is unaware of the cube’s structure behind the SQL table. This is why no hierarchies are present in the Data pane once the connection has been established. It is still possible to reproduce the cube’s structure in Tableau, as explained below.

​
Create a hierarchy

  1. Right-click the dimension (Atoti level) in the Data pane.
  2. Select Hierarchy and Create Hierarchy.
Create a hierarchy in Tableau

​
Add a level to an existing hierarchy

  1. Right-click the dimension (Atoti level) in the Data pane.
  2. Select Hierarchy and Add to Hierarchy.
Add a level to an existing hierarchy in Tableau

​
Adjust the granularity of the dashboard

Once a hierarchy has been created and populated, it can be used to drill down or up. This can be done by clicking on the + or - icon next to the hierarchy level:
Lowest granularity level
Higher granularity level

​
Save the structure

Once the cube’s structure has been reproduced, it is possible to save it for later Tableau sessions using the Tableau-specific .tds file format.
  1. Right-click on the cube’s name in the Data pane
  2. Select Add to Saved Data Sources
  3. Save the file using the .tds format
Save TDS

​
How live mode works

In live mode, Tableau sends a SQL query to the cube each time a visualization is displayed.

​
Use of measures

When a measure is placed in the view, Tableau adds an aggregation operator (for example, SUM(Mtm.SUM)). Atoti ignores this operator because the measure is already aggregated in the cube. Changing the aggregation function in Tableau does not affect the cube result. Changing a measure to a dimension or an attribute does not change the result either. Tableau still displays a single value per member. This value corresponds to the aggregated value computed by Atoti from multiple underlying facts.
In extract mode or when joining with other tables, Tableau may apply aggregation on its side.

​
How extract mode works

Extract mode retrieves data from the cube and stores it locally in Tableau. No live queries are sent after extraction, so data can be queried even if the cube is offline.

​
Considerations

  • Apply filters to limit the extraction scope.
  • Hide unnecessary fields to reduce data volume.
  • Aggregation operators are applied by Tableau in this mode.
  • Be cautious with reaggregation:
    • Mtm.SUM can be reaggregated with SUM or AVG.
    • Non-linear measures cannot be reaggregated.

​
What are the supported data types?

The following types are supported without any required action:
  • String
  • Double
  • Boolean
  • Long
  • Int
  • Float
  • Array
Non-standard data types are currently not supported.

​
Date and time support

Tableau’s default behavior with date and time fields is to extract the different parts of those fields to allow drilldown. For example, the year of a date field is extracted first, and the user can then drill down to the month and the day. This behavior may lead to incorrect results, due to a semantic gap between SQL and the Atoti OLAP Cube. Tableau extracts the date component using SQL functions (EXTRACT, CAST, TRUNC), and may reaggregate the values, leading to incorrect results. The following error message is displayed when it occurs: Atoti does not support Tableau's default behavior with date fields
More generally, calculated fields are not supported by the Atoti Tableau Adapter. Only the plain detected Atoti fields can be queried.
There are three ways to work around this limitation:

​
Option 1: Modify the date’s format after it has been dropped as a column or row

Once the error message has been thrown and closed, it is possible to change the date’s format:
  1. Right-click the date field
  2. Select Exact Date
Change the date's format to exact date

​
Option 2: Modify the field’s data type

Use a right-click drag instead of a left-click drag for date and time fields:
  1. Right-click the date or time field in the Data pane (do not left-click).
  2. Drag and drop it into the desired location (for example, Columns or Rows).
  3. From the context menu, select the (Discrete) option for the field.
This displays the exact date values without any extraction. The following screenshots illustrate each step of the workaround.
Right-clicking on a date field in the Data pane
Dropping the date field into the view
Selecting the discrete date option from the context menu

​
Option 3: Configure a multi-level date hierarchy in Atoti Server

Instead of exposing a flat, single-level date hierarchy with members like 2024-11-21, configure the cube with a multi-level date hierarchy that has separate levels for each date part, for example Year > Month > Day. With this setup, Tableau can query each date part (year, month, day) directly as a separate level, without needing to extract it client-side. This also enables proper drilldown behavior in Tableau.

​
Data preview

Some Tableau screens allow a preview of a cube’s content. In this case, a drillthrough is performed, but not all values are retrieved:
  • A level value is retrieved only if its originating store field has the same name.
  • No measure value is retrieved. Edge cases exist, such as a vector-type store field with a measure based on it that has the same name but a different value type (for example, the sum of all the vector’s coordinates).