{"id":4272,"library":"tableauhyperapi","title":"Tableau Hyper API for Python","description":"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.","status":"active","version":"0.0.24457","language":"en","source_language":"en","source_url":"https://github.com/tableau/hyper-api-python-client","tags":["hyper","tableau","data","analytics","database","etl","data-engineering"],"install":[{"cmd":"pip install tableauhyperapi","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"symbol":"HyperProcess","correct":"from tableauhyperapi import HyperProcess"},{"symbol":"Connection","correct":"from tableauhyperapi import Connection"},{"symbol":"TableDefinition","correct":"from tableauhyperapi import TableDefinition"},{"symbol":"TableDefinition.Column","correct":"from tableauhyperapi import TableDefinition, SqlType; column = TableDefinition.Column(\"name\", SqlType.text())"},{"symbol":"SqlType","correct":"from tableauhyperapi import SqlType"},{"symbol":"TableName","correct":"from tableauhyperapi import TableName"},{"symbol":"Inserter","correct":"from tableauhyperapi import Inserter"}],"quickstart":{"code":"import os\nfrom tableauhyperapi import HyperProcess, Connection, TableDefinition, TableName, SqlType, Inserter\n\n# Define the path for the new Hyper file\nhyper_file_path = 'my_first_hyper_file.hyper'\n\n# Remove the file if it already exists to start fresh\nif os.path.exists(hyper_file_path):\n    os.remove(hyper_file_path)\n\n# 1. Start the HyperProcess\nwith HyperProcess(telemetry_opt_out=True) as hyper:\n    print(f\"The HyperProcess has started on port {hyper.endpoint.port}.\")\n\n    # 2. Connect to the Hyper file (creates it if it doesn't exist)\n    with Connection(endpoint=hyper.endpoint, database=hyper_file_path, create_mode=Connection.CreateMode.CREATE_AND_REPLACE) as connection:\n        print(\"The connection to the Hyper file is open.\")\n\n        # 3. Define the table schema\n        table_name = TableName('public', 'my_data_table')\n        table_definition = TableDefinition(\n            table_name,\n            [\n                TableDefinition.Column('id', SqlType.int()),\n                TableDefinition.Column('name', SqlType.text()),\n                TableDefinition.Column('value', SqlType.double()),\n            ]\n        )\n\n        # 4. Create the table\n        connection.catalog.create_table(table_definition)\n        print(f\"Table '{table_name}' created.\")\n\n        # 5. Insert data\n        with Inserter(connection, table_definition) as inserter:\n            inserter.add_row([1, 'Alpha', 10.5])\n            inserter.add_row([2, 'Beta', 20.3])\n            inserter.add_row([3, 'Gamma', 30.1])\n            inserter.execute()\n        print(f\"{inserter.number_of_inserted_rows} rows inserted.\")\n\n    print(\"The connection to the Hyper file is closed.\")\nprint(\"The HyperProcess is shut down.\")\n\nprint(f\"Hyper file '{hyper_file_path}' created successfully.\")","lang":"python","description":"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."},"warnings":[{"fix":"Wrap `HyperProcess` and `Connection` in `with` statements (e.g., `with HyperProcess(...) as hyper: ...`) to automate resource cleanup.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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()`).","message":"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).","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Explicitly define `TableName` with both schema and table name, for example: `TableName('public', 'my_data')`.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}