TABLEAU REST API: TABLEAU-API-LIB TUTORIALS

Building and publishing Tableau Hyper extracts with Python

A step-by-step guide to using Tableau’s Hyper API and REST API

Find more Devyx tutorial content on YouTube.

For more analytics and data engineering content: Substack.

Extracts are snapshots of data stored in flat files or database tables, typically generated by Tableau Server on a schedule defined by server administrators. For teams operating within complex environments, there may be a desire to build extracts on the fly based on a source like a Pandas DataFrame or a CSV file. One way to do this is using Python.

There are free tools out there that enable automating a significant portion of your Tableau Server workflows. For many people and teams, the struggle is carving out development time to put those tools to work.

Let’s get to the point: demonstrating how you can use Python to build a Hyper extract from scratch and publish it to Tableau Server or Tableau Online.

This tutorial walks through using the Python tableau-api-lib package and is part of a series on how to tap Tableau Server like a keg, giving you control over Tableau Server’s REST API.

These tutorials assume you have Python 3 installed already. If you do not have Python 3 yet, this will get you started: guide to install Python.

Setting the Stage

Tableau has made a number of APIs available to developers who want to automate workflows or build their own custom solutions within their Tableau ecosystems.

Two such APIs are: the Hyper API and the REST API.

The Hyper API is what you should be using if you are on Tableau Server 10.5 or higher and need custom control over generating Tableau extracts, particularly high-performing Hyper extracts. This API replaces older tools such as the Tableau SDK or the Extract API 2.0.

The REST API provides access to a number of endpoints granting you control over your Tableau Server / Tableau Online environments. It allows you to create users, projects, subscriptions, query metadata, publish or delete content, and much more.

In this tutorial we’ll put Tableau’s Hyper API and REST API to work for us in the context of building a Hyper extract and then publishing it to a Tableau site.

Step 1: make sure you have these PyPI packages installed

Even if you’re a pro at these tutorials, do yourself a favor and pull the latest versions of the libraries.

pip install --upgrade tableau-api-lib

pip install --upgrade tableauhyperapi

pip install --upgrade pandas

New to this Python stuff? Don’t sweat it, you’ll catch on quick. Follow this getting started tutorial. That tutorial also walks you through getting connected to Tableau Server using tableau-api-lib.

Step 2: configure your Tableau Server connection

Use the code below as a template for getting connected to your server. In later steps, we will build upon this boiler plate with additional lines of code. At the end of the article, you’ll find a consolidated block of code you can copy / paste for your convenience.

import pandas as pd

from tableauhyperapi import HyperProcess, Connection, TableDefinition, SqlType, Telemetry, Inserter, CreateMode, TableName
from tableauhyperapi import escape_string_literal

from tableau_api_lib import TableauServerConnection
from tableau_api_lib.utils.querying import get_projects_dataframe

tableau_server_config = {
        'my_env': {
                'server': 'https://YourTableauServer.com',
                'api_version': '<YOUR_API_VERSION>',
                'username': '<YOUR_USERNAME>',
                'password': '<YOUR_PASSWORD>',
                'site_name': '<YOUR_SITE_NAME>',
                'site_url': '<YOUR_SITE_CONTENT_URL>'
        }
}

conn = TableauServerConnection(tableau_server_config, env='my_env')
conn.sign_in()

Fun fact: you can also use personal access tokens, assuming you are on Tableau Server 2019.4 or newer. If you’re all about the access tokens, check out my article for details on how to use them.

Step 3: create a sample CSV file for our tutorial

Here is a screenshot of the CSV I created and will use throughout this article. Later on when we create a Hyper extract from a Pandas DataFrame, this CSV file will be the source of data for that DataFrame as well.

Step 4: store some file paths for later

Let’s define two file paths: one leading to our sample CSV file, and another pointing to the location where we will save our Hyper extract.

PATH_TO_CSV = 'sample_csv_for_hyper.csv'
PATH_TO_HYPER = 'test_hyper_extract_api.hyper'

Modify the file paths as desired for your own environment.

Step 5: generate a Hyper extract directly from a CSV

Use this GitHub gist as template code for generating a Hyper extract from a CSV file. I’m using a gist to provide the code because it’s much more presentable than the code blocks available on the Medium platform (where this article exists).

Step 6: generate a Hyper extract from a Pandas DataFrame

Pandas DataFrames are first class citizens in the Python world. Regardless of where your data is sourced from, you’ll be able to store that data in a Pandas DataFrame.

Use this GitHub gist as a template for turning your own Pandas DataFrame into a Hyper extract using the Hyper API.

Step 7: publish the hyper extract to Tableau Server or Tableau Online

Since we set up our connection to Tableau Server / Tableau Online in step 2, the line of code provided below can be used to publish the Hyper extract generated in the previous steps to Tableau Server or Tableau Online.

response = conn.publish_data_source(
datasource_file_path=PATH_TO_HYPER,
datasource_name='<ENTER_NAME_HERE>',
project_id='<DESTINATION_PROJECT_ID>'
)

You can call response.json() for the server’s JSON response to your API request to publish the extract if you’d like to verify that the extract was published successfully.

If you have no idea what your destination project ID value is, you can conveniently access all of your project names and project IDs using the following code:

from tableau_api_lib.utils.querying import get_projects_dataframe

projects_df = get_projects_dataframe(conn)
print(projects_df[['name', 'id']]

The output from the print statement will be a Pandas DataFrame with two columns. One column contains the names of your projects; the other column contains the ID values. If you see the project name matching the project you want the Hyper extract published to, use the corresponding ID value as the project ID used when publishing the extract.

Note that ‘conn’ is the Tableau Server / Tableau Online connection established in step 2 of this tutorial.

Step 8: verify that the extract has been published and is accessible

Having executed the code from our previous steps, I can verify that my extract was published to my Tableau Server site.

Wrapping it up

That’s it! We have used the Hyper API to create an extract, and we have used the REST API to publish that extract to Tableau Server.

Hopefully this ups your game in terms of automating workflows within your Tableau ecosystem.

Consolidated Code

Use this GitHub gist as a starting point for adapting the code in this tutorial for your own use. The gist linked here builds a Hyper extract using a Pandas DataFrame as the source of data and then publishes the extract to Tableau Server.