Pantab: Pandas DataFrames to Tableau Hyper Extracts

5.3.0 · active · verified Thu Apr 16

Pantab is a Python library that enables seamless conversion between pandas DataFrames and Tableau Hyper Extracts (.hyper files). It provides a high-performance way to get data into and out of Tableau's Hyper engine, which is used for data storage and querying within Tableau products. The current version is 5.3.0, and it generally follows a release cadence with minor versions every few months, often including bug fixes and Python version support updates.

Common errors

```
RuntimeError: hyper_error_code = 701: A table with name 'MyTable' already exists.
```
cause Attempting to write to a Hyper file with `table_mode='w'` (default for `to_hyper`) where the specified table name already exists in the file, and the file is not empty.

fix Use `table_mode='a'` to append, or `table_mode='w'` to overwrite the *entire file* if you intend to replace the whole content. If you only want to overwrite a specific table, you need to first delete the table or overwrite the file. The `table` argument in `to_hyper` and `frame_from_hyper` specifies the table within the Hyper file.
```
ModuleNotFoundError: No module named 'pantab'
```
cause The `pantab` library is not installed in the current Python environment.

fix Run `pip install pantab` to install the library.
```
tableauhyperapi.TableauHyperAPILibraryError: The Hyper API library could not be loaded. Please ensure that the Tableau Hyper API is installed and accessible.
```
cause The underlying `tableauhyperapi` library or its native components are missing or corrupted, or the environment is not set up correctly to find them.

fix Ensure `pantab` and `tableauhyperapi` are correctly installed: `pip install --upgrade pantab tableauhyperapi`. Sometimes, a fresh environment or system re-install of Hyper API dependencies might be needed if `pip` fails to resolve it.
```
TypeError: 'file_path' must be a Path or str, not NoneType
```
cause The `file_path` argument for `to_hyper` or `frame_from_hyper` was not provided or was `None`.

fix Ensure you pass a valid string or `pathlib.Path` object for the `file_path` argument, specifying the `.hyper` file you want to interact with.

Warnings

breaking Pantab v5.3.0 dropped support for Python 3.9 and 3.10. Users on these Python versions will need to upgrade to Python 3.11 or later to use the latest Pantab.
Fix: Upgrade your Python environment to 3.11 or newer, or pin your pantab version to <5.3.0.
breaking Pantab relies on `tableauhyperapi`, which periodically updates its minimum required version. Older `tableauhyperapi` versions can lead to `RuntimeError` or `ValueError`.
Fix: Ensure `tableauhyperapi` is updated to at least the minimum version required by your `pantab` installation. Running `pip install --upgrade pantab` usually resolves this by updating its dependencies.
gotcha Data type mapping between pandas and Hyper can have nuances. For instance, 8-bit integer columns in pandas will be stored as 16-bit integers in Hyper. Other types might also undergo conversions.
Fix: Review `pantab` documentation for specific data type mappings to ensure your data integrity and expected column types in Tableau. Test conversions with representative datasets.
gotcha Hyper files are single-writer, single-reader. Concurrent access or insufficient file permissions can lead to errors, especially on network drives or shared environments.
Fix: Ensure the process writing or reading the Hyper file has appropriate file system permissions. Avoid concurrent writes to the same Hyper file. Close file handlers properly if managing them manually (though `pantab` generally handles this).

Install

pip install pantab Install latest version

Imports

to_hyper
wrong:
```
import pantab.frame.to_hyper
```
correct:
```
from pantab import to_hyper
```
While 'pantab.frame.to_hyper' works, 'from pantab import to_hyper' is the recommended and more common direct import.
frame_from_hyper
wrong:
```
import pantab.frame.frame_from_hyper
```
correct:
```
from pantab import frame_from_hyper
```
Similar to 'to_hyper', direct import is preferred for convenience.

Quickstart

This quickstart demonstrates how to create a pandas DataFrame, write it to a Tableau Hyper file using `pantab.to_hyper`, and then read it back into a DataFrame using `pantab.frame_from_hyper`. It includes cleanup to remove the generated Hyper file.

import pandas as pd
import pantab as pt
import os

data = {
    'col1': [1, 2, 3],
    'col2': ['A', 'B', 'C'],
    'col3': [True, False, True]
}
df = pd.DataFrame(data)

hyper_file = 'my_data.hyper'
table_name = 'MyTable'

try:
    # Write DataFrame to Hyper file
    pt.to_hyper(df, hyper_file, table=table_name)
    print(f"DataFrame written to {hyper_file} successfully.")

    # Read DataFrame from Hyper file
    read_df = pt.frame_from_hyper(hyper_file, table=table_name)
    print(f"DataFrame read from {hyper_file} successfully:")
    print(read_df)

finally:
    # Clean up the generated file
    if os.path.exists(hyper_file):
        os.remove(hyper_file)
        print(f"Cleaned up {hyper_file}.")

view raw JSON →