How to use Tableau Adapter

This feature requires a license that enables the bi-adapter component.

Prerequisites

Atoti application: An active Atoti application with a cube available.
Atoti Tableau Adapter: Activated on the server.
Tableau: Tableau Desktop or Tableau Cloud access. Tableau Desktop is supported from version 2026.1 onwards.
PostgreSQL JDBC driver: Required for Tableau Desktop. The 42.7.7 version of the driver is the only one guaranteed to work with Atoti. This version may be upgraded in any bugfix release. However, if you have tested a more recent version and it does not work, please open a support ticket.

How to activate the Atoti Tableau Adapter

To activate the Atoti Tableau Adapter you need to follow these steps:

1. Add the SQL Bridge artifact to your project

Include the following dependency in your pom.xml file:

<dependency>
    <groupId>com.activeviam.activepivot</groupId>
    <artifactId>activepivot-server-sql-bridge</artifactId>
    <version>${project.version}</version>
</dependency>

2. Choose an appropriate listening port

By default, the server listens for SQL queries on port 5432. This port number can be modified by setting the atoti.server.sql-bridge.port property of your Atoti application.

How to connect Tableau to Atoti

This guide explains how to connect Tableau (Desktop or Cloud) to an Atoti server using the PostgreSQL JDBC driver. Only User/Password authentication is supported.

Connect using a Tableau data source file

Atoti can generate the Tableau data source file (.tds) of a cube. A .tds file holds no data: it only stores the connection information and the field metadata Tableau needs to open a data source, so it can be shared and reopened like a shortcut to the cube. See the Tableau documentation for the full description of the format. The file generated by Atoti declares Tableau multilevel hierarchies that mirror the cube’s own multilevel hierarchies, and therefore reproduces the cube’s structure in Tableau. This set up therefore skips both the manual connection steps and the manual hierarchy creation described in How to reproduce the cube’s structure. Atoti generates the file on request, through the BI adapter REST API. See that reference for the endpoint path, its parameters and its responses. The following command downloads the .tds file of the SALES_CUBE cube, specifying that Tableau should connect to my-atoti-host.

curl -u username:password \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"host":"my-atoti-host"}' \
  "http://<atoti-server-host>:<atoti-server-port>/activeviam/bi-adapter/rest/v1/tableau/tds/SALES_CUBE" \
  -o SALES_CUBE.tds

Server-side configuration The SQL port and the level-name mode are not request parameters. They are read from the following properties of your Atoti application:

Property	Default	Description
`atoti.server.sql-bridge.port`	`5432`	Port the SQL Bridge listens on. It is embedded in the generated file.
`atoti.server.sql-bridge.levelNameMode`	`SHORTEST`	How the exposed columns name the cube levels. `SHORTEST` uses the level name alone when no other level shares that name, and falls back to the complete `level@hierarchy@dimension` name otherwise. `COMPLETE` always uses the complete name.

Manual connection steps

Tableau Desktop
Tableau Cloud

Follow these steps to connect Tableau Desktop to an Atoti server:

Open Tableau Desktop and create a new file.
Click Connect to Data in the upper-left corner.
From the list of connectors, select PostgreSQL.
Fill in the required connection details:
- Address: IP address of the Atoti server.
- Port: Port used by the PostgreSQL wire protocol (default is 5432). If changed, refer to the atoti.server.sql-bridge.port property of your Atoti application.
- Database: Always set to atoti.
- Authentication: Choose your preferred authentication method.
Click Connect to establish the connection.

Monitoring

The Atoti BI adapter relies on BI tools sending SQL queries to Atoti Server: a component called the SQL Bridge translates each query and forwards it to the cube. That SQL layer is an implementation detail, but it shows up in logs and traces.

Logging

Two loggers are available:

atoti.server.query.sqlbridge: logs the query processing. This includes the logical and physical query plans built from the incoming SQL. It also includes the cube, levels, and measures targeted by each underlying query.
atoti.server.query.sqlbridge.protocol: logs the protocol exchange, including received and sent messages, session lifecycle, and authentication. It also logs any error encountered while handling a query.

Tracing

Tracing is used to provide insight into the SQL queries received from BI tools. Atoti Server tracing must be enabled and configured before SQL query traces become available. See Tracing for setup instructions. Every query received is wrapped in a Sql Bridge query span, tagged with:

sql-query: the raw SQL query text sent by the BI tool.
sql-query-params: the parameters bound to the query, when it is a parameterized (prepared) query.

Releases and upgrades

Getting started

Concepts

Step 1: Bring your data into Atoti

Step 2: Design your Cube

Step 3: Build an Atoti application

Step 4: Query an Atoti application

Configure Atoti

Secure Atoti

Operate Atoti

Reference

How to use Tableau Adapter

Prerequisites

How to activate the Atoti Tableau Adapter