Tableau Hyper API for Python

0.0.24457 · active · verified Sat Apr 11

The Tableau Hyper API for Python allows developers to programmatically create, read, and update .hyper files, which are Tableau's high-performance data engine files. It provides direct interaction with the Hyper engine for efficient data management and integration with Tableau products. The current version is 0.0.24457, and it is actively maintained with frequent updates.

Warnings

gotcha Always use `with` statements for `HyperProcess` and `Connection` to ensure resources (file locks, server processes) are properly released, even if errors occur. Failing to do so can lead to file corruption, locked files, or orphaned Hyper processes.
Fix: Wrap `HyperProcess` and `Connection` in `with` statements (e.g., `with HyperProcess(...) as hyper: ...`) to automate resource cleanup.
gotcha Incorrect mapping between Python data types and Hyper's `SqlType` can lead to errors during insertion or unexpected data behavior (e.g., truncation, incorrect interpretation).
Fix: Carefully consult the `SqlType` documentation to ensure Python types (e.g., `int`, `str`, `float`, `datetime.datetime`) are mapped to their appropriate Hyper SQL equivalents (e.g., `SqlType.int()`, `SqlType.text()`, `SqlType.double()`, `SqlType.timestamp()`).
gotcha The `HyperProcess` may fail to start if the default port is already in use or if the underlying Hyper engine executable cannot be found or executed. This often manifests as connection errors or process termination.
Fix: Check for other running Hyper processes, specify a different port when initializing `HyperProcess` (e.g., `HyperProcess(endpoint=Endpoint(port=12345))`), and ensure system permissions allow the Hyper executable to run. Inspect Hyper process logs for detailed error messages.
gotcha When referencing tables, it's best practice to always specify both the schema and table name using `TableName('schema', 'table')` (e.g., `TableName('public', 'my_table')`). Omitting the schema can lead to ambiguity or unexpected behavior, especially in environments with multiple schemas.
Fix: Explicitly define `TableName` with both schema and table name, for example: `TableName('public', 'my_data')`.

Install

pip install tableauhyperapi Install latest version

Imports

HyperProcess

from tableauhyperapi import HyperProcess

Connection
```
from tableauhyperapi import Connection
```

TableDefinition

from tableauhyperapi import TableDefinition

TableDefinition.Column

from tableauhyperapi import TableDefinition, SqlType; column = TableDefinition.Column("name", SqlType.text())

SqlType
```
from tableauhyperapi import SqlType
```
TableName
```
from tableauhyperapi import TableName
```
Inserter
```
from tableauhyperapi import Inserter
```

Quickstart

This quickstart demonstrates how to initialize a HyperProcess, establish a connection to a .hyper file, define a table schema, create the table, and insert data into it. It emphasizes proper resource management using `with` statements to ensure connections and the Hyper process are correctly closed.

import os
from tableauhyperapi import HyperProcess, Connection, TableDefinition, TableName, SqlType, Inserter

# Define the path for the new Hyper file
hyper_file_path = 'my_first_hyper_file.hyper'

# Remove the file if it already exists to start fresh
if os.path.exists(hyper_file_path):
    os.remove(hyper_file_path)

# 1. Start the HyperProcess
with HyperProcess(telemetry_opt_out=True) as hyper:
    print(f"The HyperProcess has started on port {hyper.endpoint.port}.")

    # 2. Connect to the Hyper file (creates it if it doesn't exist)
    with Connection(endpoint=hyper.endpoint, database=hyper_file_path, create_mode=Connection.CreateMode.CREATE_AND_REPLACE) as connection:
        print("The connection to the Hyper file is open.")

        # 3. Define the table schema
        table_name = TableName('public', 'my_data_table')
        table_definition = TableDefinition(
            table_name,
            [
                TableDefinition.Column('id', SqlType.int()),
                TableDefinition.Column('name', SqlType.text()),
                TableDefinition.Column('value', SqlType.double()),
            ]
        )

        # 4. Create the table
        connection.catalog.create_table(table_definition)
        print(f"Table '{table_name}' created.")

        # 5. Insert data
        with Inserter(connection, table_definition) as inserter:
            inserter.add_row([1, 'Alpha', 10.5])
            inserter.add_row([2, 'Beta', 20.3])
            inserter.add_row([3, 'Gamma', 30.1])
            inserter.execute()
        print(f"{inserter.number_of_inserted_rows} rows inserted.")

    print("The connection to the Hyper file is closed.")
print("The HyperProcess is shut down.")

print(f"Hyper file '{hyper_file_path}' created successfully.")

view raw JSON →