---
title: "Tableau data source plugin for Grafana"
description: "Tableau Server / Cloud datasource for Grafana. Query workbooks, views, data sources, users, groups, jobs, and extract tasks via the Tableau REST API."
---

> This is the Markdown version of https://grafana.com/grafana/plugins/crestdata-tableau-datasource/

# Tableau

- Developer: crestdata
- Version: 1.0.2
- [Installation](https://grafana.com/grafana/plugins/crestdata-tableau-datasource/installation.md)
- [Change log](https://grafana.com/grafana/plugins/crestdata-tableau-datasource/changelog.md)

![Onboarding](https://grafana.com/api/plugins/crestdata-tableau-datasource/versions/1.0.2/images/img/onboarding.png)

![Query Example](https://grafana.com/api/plugins/crestdata-tableau-datasource/versions/1.0.2/images/img/query.png)

![Dashboard: Tableau Site Overview](https://grafana.com/api/plugins/crestdata-tableau-datasource/versions/1.0.2/images/img/dashboard-TSO.png)

# Tableau Data Source Plugin for Grafana

## Description

The **Tableau DataSource Plugin** is a Grafana backend datasource plugin that enables on-demand querying and visualization of Tableau Server and Tableau Cloud content and operational data inside Grafana panels.

Tableau is a leading business intelligence and analytics platform. The plugin connects to the Tableau REST API to retrieve site information, projects, workbooks, views, published data sources, users, groups, background jobs, and extract refresh tasks.

### Features

- Query and visualize Tableau Server / Tableau Cloud data directly within Grafana

- Support for multiple data categories:

  - **Site Info**: Site metadata, storage quota, user quota, and usage counts
  - **Projects**: Project inventory with owner and content permissions
  - **Workbooks**: Published workbooks with owner, project, size, and tags
  - **Views**: Views across the site with optional usage hit counts
  - **Data Sources**: Published data sources with certification status and connection type
  - **Users**: Site users with role, authentication setting, and last login
  - **Groups**: Site groups with domain information
  - **Jobs**: Background job history with duration calculation
  - **Extract Tasks**: Scheduled extract refresh tasks with consecutive failure counts

- Filter expression support using Tableau REST API filter syntax

- Grafana time range picker integration — `from` is pushed to the Tableau API as a server-side filter, `to` is enforced as a post-filter in the backend

- Automatic pagination — all pages are fetched and merged transparently

- Built-in retry logic with exponential backoff for transient failures

- Personal Access Token (PAT) authentication with automatic session management and refresh

### Compatibility

| Component      | Version / Detail      |
| -------------- | --------------------- |
| Grafana        | >= 12.0.0             |
| Tableau Server | v2019.3+              |
| REST API       | 3.28                  |
| Authentication | Personal Access Token |

## Visuals

> **Onboarding**

![Onboarding](https://raw.githubusercontent.com/jignesh-crest/crestdata-grafana-plugin-artifacts/refs/heads/main/crestdata-tableau-datasource/onboarding.png)

---

> **Query Examples**

![Query Example](https://raw.githubusercontent.com/jignesh-crest/crestdata-grafana-plugin-artifacts/refs/heads/main/crestdata-tableau-datasource/query.png)

---

> **Added Dashboards**

![Dashboard: Tableau Site Overview](https://raw.githubusercontent.com/jignesh-crest/crestdata-grafana-plugin-artifacts/refs/heads/main/crestdata-tableau-datasource/dashboard-TSO.png)

## Installation

### Requirements

- Grafana >= 12.0.0
- Tableau Server v2019.3+ or Tableau Cloud
- A Personal Access Token (PAT) with appropriate site permissions
- Network connectivity to the Tableau Server or Tableau Cloud endpoint

### Obtain a Personal Access Token

1. Sign in to Tableau Server or Tableau Cloud.
2. Navigate to **My Account Settings → Personal Access Tokens**.
3. Click **Create new token**, provide a name, and copy both the token name and the secret — the secret is shown only once.

### Install the Plugin

Install the plugin from the [Grafana Plugin Catalog](https://grafana.com/grafana/plugins/) or using the Grafana CLI:

```bash
grafana cli plugins install crestdata-tableau-datasource
```

After installation, restart the Grafana server for the plugin to be loaded.

### Configure the Data Source

1. In Grafana, navigate to **Connections > Data Sources > Add data source**.
2. Search for **Tableau** and select it.
3. Fill in the required configuration fields:

| Name            | Type          | Required | Description                                                                     |
| --------------- | ------------- | -------- | ------------------------------------------------------------------------------- |
| Server Endpoint | String        | Yes      | The Tableau Server or Cloud URL (e.g., `https://use-east-1.online.tableau.com`) |
| Site Name       | String        | No       | The site content URL; leave blank for the default site                          |
| Token Name      | String        | Yes      | The Personal Access Token name                                                  |
| Token Secret    | Secure String | Yes      | The Personal Access Token secret (encrypted at rest)                            |

1. Click **Save & Test**. The health check will sign in and verify connectivity, returning the Tableau Server version and REST API version on success.

## Usage

### Query Editor

Once the data source is configured, you can create panels using the query editor with the following parameters:

| Parameter         | Type     | Options                                                                                 | Default   | Description                                                                 |
| ----------------- | -------- | --------------------------------------------------------------------------------------- | --------- | --------------------------------------------------------------------------- |
| Query Type        | Dropdown | Site Info, Projects, Workbooks, Views, Data Sources, Users, Groups, Jobs, Extract Tasks | Site Info | Select the data category to query                                           |
| Filter Expression | String   | Tableau filter syntax (`field:op:value`, comma-separated)                               | —         | Filter applied to Projects, Workbooks, Views, Data Sources, Users, and Jobs |

### Available Query Types

#### Site Info

Returns a single-row frame with site metadata: ID, name, content URL, admin mode, state, storage quota, user quota, number of users in use, storage in use, user usage percentage, and storage usage percentage.

#### Projects

Returns all projects on the site with ID, name, description, content permissions, owner ID, owner name, created at, and updated at. Supports filter expressions. The Grafana time range filters by `updatedAt`.

#### Workbooks

Returns published workbooks with ID, name, content URL, show tabs flag, size (MB), created at, updated at, encrypt extracts flag, project ID, project name, owner ID, owner name, and comma-separated tags. Supports filter expressions. The Grafana time range filters by `updatedAt`.

#### Views

Returns views across the site with ID, name, content URL, view URL name, workbook ID, workbook name, project ID, project name, owner ID, owner name, total view count, created at, and updated at. Supports filter expressions. The Grafana time range filters by `updatedAt`.

#### Data Sources

Returns published data sources with ID, name, content URL, connection type, certified flag, has extracts flag, size (MB), created at, updated at, project ID, project name, owner ID, owner name, and comma-separated tags. Supports filter expressions. The Grafana time range filters by `updatedAt`.

#### Users

Returns site users with ID, username, full name, email, site role, authentication setting, and last login. Supports filter expressions.

#### Groups

Returns site groups with ID, name, and domain name.

#### Jobs

Returns background job history with ID, status, job type, priority, finish code, created at, started at, ended at, and computed duration in minutes (nullable — null when start or end time is missing). Supports filter expressions. The Grafana time range filters by `createdAt`.

#### Extract Tasks

Returns scheduled extract refresh tasks with ID, task type, priority, consecutive failed count, schedule frequency, next run at, workbook ID, workbook name, data source ID, and data source name.

### Filter Expressions

Filter expressions use Tableau REST API filter syntax: `field:operator:value`. Multiple filters are comma-separated. The input is automatically normalized on blur — leading/trailing commas are stripped and spaces around commas are removed.

Examples:

- `name:eq:Sales` — exact name match
- `projectName:eq:Finance` — filter by project name
- `isCertified:eq:true` — certified data sources only
- `status:eq:Failed` — failed jobs only

Filters are supported on: Projects, Workbooks, Views, Data Sources, Users, and Jobs.

### Time Range

The Grafana time range picker is integrated for all query types that have a time field. The `from` bound is sent to the Tableau API as a server-side `gte` filter to minimize data transfer. The `to` bound is enforced as a post-filter in the backend after the data is received. This split approach is required because Tableau does not support two filters on the same field in a single request.

| Resource     | Time field used | `from` (API filter) | `to` (post-filter) |
| ------------ | --------------- | ------------------- | ------------------ |
| Projects     | `updatedAt`     | `updatedAt:gte:`    | drop rows after to |
| Workbooks    | `updatedAt`     | `updatedAt:gte:`    | drop rows after to |
| Views        | `updatedAt`     | `updatedAt:gte:`    | drop rows after to |
| Data Sources | `updatedAt`     | `updatedAt:gte:`    | drop rows after to |
| Jobs         | `createdAt`     | `createdAt:gte:`    | drop rows after to |

Query types without a time field (Site Info, Users, Groups, Extract Tasks) are unaffected by the time range picker.

The default time range for the bundled dashboard is **last 7 days**, which covers a typical Tableau job and content activity window.

### Error Handling and Retry Strategy

Retries are performed only for transient failures:

- HTTP 401 (session expired) — session is invalidated and a new one is obtained automatically
- HTTP 429 (rate limited)
- HTTP 5xx responses (500–599)

**Max retry attempts:** 3, with exponential backoff (base delay: 3 seconds).

Non-retryable: HTTP 400, 403, 404, and 405 errors are returned immediately.

## Resources Reference

| Resource      | Description                                                              | Supports Filter | Supports Time Range |
| ------------- | ------------------------------------------------------------------------ | --------------- | ------------------- |
| Site Info     | Site metadata, storage and user quota, usage counts and percentages      | No              | No                  |
| Projects      | Project inventory with owner and content permissions                     | Yes             | Yes (`updatedAt`)   |
| Workbooks     | Published workbooks with owner, project, size, and tags                  | Yes             | Yes (`updatedAt`)   |
| Views         | Views with optional usage hit counts                                     | Yes             | Yes (`updatedAt`)   |
| Data Sources  | Published data sources with certification and connection type            | Yes             | Yes (`updatedAt`)   |
| Users         | Site users with role, auth setting, and last login                       | Yes             | No                  |
| Groups        | Site groups with domain information                                      | No              | No                  |
| Jobs          | Background job history with computed duration                            | Yes             | Yes (`createdAt`)   |
| Extract Tasks | Scheduled extract refresh tasks with failure counts and schedule details | No              | No                  |

## Limitations and Recommendations

**API Considerations:**

- The plugin uses Tableau REST API version `3.28` internally; no user configuration is required
- Personal Access Tokens expire after 15 days of inactivity or when manually revoked; create a new token if authentication fails

**Performance tips:**

- Use filter expressions to reduce the volume of data returned for large sites
- Reduce dashboard refresh frequency if rate limit errors occur

## Support

For issues, questions, or feature requests, please open an issue in this repository.

## Roadmap

See the open issues for a list of proposed features and known issues.

## Contributing

Contributions are welcome! To get started with development:

```bash
cd crestdata-tableau-datasource

# Frontend
npm install
npm run dev        # development mode with watch
npm run build      # production build

# Backend
mage -v            # build backend binaries

# Tests
npm run test       # frontend tests (Jest)
npm run test:ci    # CI mode
go test ./...      # backend tests

# Linting
npm run lint
npm run lint:fix

# Local Grafana instance (Docker)
npm run server

# E2E tests (Playwright)
npm run e2e
```

Before submitting a pull request:

1. Run the linter and ensure all tests pass.
2. Validate the plugin using the [Grafana Plugin Validator](https://github.com/grafana/plugin-validator).
3. Ensure any changes to `plugin.json` are intentional — a Grafana server restart is required after such changes.

## Authors and Acknowledgment

Developed by [Crest Data](https://www.crestdata.ai/).

## License

This plugin is distributed under the Crest Data End User License Agreement (EULA). See the [LICENSE](https://gist.github.com/jignesh-crest/9021da50bc6625b6e06118d0f05e469d) file for details.

## References

- [Tableau Product Page](https://www.tableau.com/)
- [Tableau REST API Reference](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api.htm)
- [Grafana Plugin Development](https://grafana.com/developers/plugin-tools)
