{"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":"python","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,"search_vec":"'0.0.24457':53 'activ':57 'allow':12 'analyt':65 'api':3,9 'creat':16 'current':50 'data':29,42,64,69 'data-engin':68 'databas':66 'develop':13 'direct':34 'effici':41 'engin':30,39,70 'etl':67 'file':21,31 'frequent':60 'high':27 'high-perform':26 'hyper':2,8,20,38,62 'integr':45 'interact':35 'maintain':58 'manag':43 'perform':28 'product':48 'programmat':15 'provid':33 'python':5,11 'read':17 'tableau':1,7,24,47,63 'updat':19,61 'version':51","created_at":"2026-04-12T03:48:17.034739+00:00","updated_at":"2026-04-16T22:38:52.288667+00:00","problems":[{"fix":"pip install tableauhyperapi","cause":"The `tableauhyperapi` package is not installed in the Python environment where the script is being executed.","error":"ModuleNotFoundError: No module named 'tableauhyperapi'"},{"fix":"Verify the file path, check file permissions, ensure no other process (like Tableau Desktop) is accessing the file, and confirm the file is not corrupted.","cause":"The Hyper file cannot be accessed, possibly due to an incorrect file path, insufficient file permissions, the file being locked by another process, or corruption.","error":"TableauException: \"Cannot open hyper file '<path_to_file>.hyper'\""},{"fix":"Double-check the exact table name used and ensure the table schema has been properly defined and created in the Hyper file using `TableDefinition` and `create_table()`.","cause":"The specified table name does not exist within the Hyper file, often due to a typo in the table name or forgetting to explicitly create the table before attempting to interact with it.","error":"TableauException: \"The table with name 'Extract' does not exist.\""},{"fix":"Review the table's schema definition (e.g., `table_definition.add_column(...)`) and ensure the column name in your code exactly matches an existing column in the table.","cause":"The specified column name does not match any existing column in the target table's schema within the Hyper file, commonly caused by a typo or a mismatch with the table definition.","error":"TableauException: \"Column 'ID' does not exist in table 'Extract'.\""}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.0.26359","cli_name":"","cli_version":null,"type":"library","homepage":"https://tableau.github.io/hyper-db","github":null,"docs":null,"changelog":null,"pypi":"https://pypi.org/project/tableauhyperapi/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["database","data","aws"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-29","next_check":"2026-07-28","install_tag":null}}