Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 39 additions & 9 deletions website/docs/guides/hyper_file/optimize.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,15 +17,45 @@ To use a specific database file format version, you'll need to use the `default_
Using the latest available database file format version should lessen the need to manually defragment or otherwise optimize your file for size or performance.
However, for extremely fragmented files you might still benefit from manually optimizing your file.

## Rewrite your Hyper file in an optimized format {#rewrite-your-hyper-file-in-an-optimized-format}

If you have a Hyper file that has become fragmented or is still using an older file version, one simple solution is to create a new file and copy all the data into it.
There is a [script that does just that](https://github.com/tableau/hyper-api-samples/tree/main/Community-Supported/convert-hyper-file) available on Github.

The Python script uses the Hyper API to copy all the schemas and tables in an existing `.hyper` file and writes them into a new file in a continuous sequence, eliminating any fragmentation that might have occurred.
By creating the new `.hyper` file with the intended new file format version, you can upgrade / downgrade between the various Hyper file versions.

## Guidelines for avoid fragmentation
## Rewrite your Hyper file in an optimized format

If you have a Hyper file that has become fragmented or is still using an older file version where you want to take advantage of new version features, you can
update your existing Hyper databases by checking the version and updating the version prior to performing other operations on them. For instance the Python script
below does this while maintaining a backup of the old Hyper file.

```python
import os
from tableauhyperapi import HyperProcess, Connection, Telemetry, CreateMode

TARGET_DATABASE_VERSION = "2"

with HyperProcess(Telemetry.SEND_USAGE_DATA_TO_TABLEAU,
parameters = {"default_database_version": TARGET_DATABASE_VERSION}) as hyper:
should_update_version = False
with Connection(hyper.endpoint, 'existing.hyper', CreateMode.CREATE_IF_NOT_EXISTS) as connection:
# check the current version of the extract

version = connection.execute_scalar_query("SELECT database_version from pg_catalog.hyper_database")
if version < TARGET_DATABASE_VERSION:
print(f'found version {version}, upgrading to version {TARGET_DATABASE_VERSION}')
should_update_version = True

if should_update_version:
with Connection(hyper.endpoint) as connection:
connection.execute_command(f"""
CREATE DATABASE "updatedversion.hyper" WITH VERSION {TARGET_DATABASE_VERSION} FROM "existing.hyper"
""")
# make a backup of the existing hyper file - will overwrite any existing file
os.replace("existing.hyper", "existing.bak.hyper")

# rename the new file to match old database name
os.replace("updatedversion.hyper", "existing.hyper")
with Connection(hyper.endpoint, 'existing.hyper', CreateMode.CREATE_IF_NOT_EXISTS) as connection:
# perform normal operations on connection
...
```

## Guidelines for avoiding fragmentation

The level of file compression in a `.hyper` file depends both on the characteristics of the contained data but also on the insertion/deletion patterns that you use. If you expect to repeatedly delete, insert, or update rows of data, there are patterns that are more likely to achieve optimal file compression, and others that are more likely to result in file fragmentation.

Expand Down
2 changes: 1 addition & 1 deletion website/docs/hyper-api/hyper_process.md
Original file line number Diff line number Diff line change
Expand Up @@ -174,7 +174,7 @@ create new database files.
Every version builds on the improvements of the previous version(s) and
adds some new functionality, like new data types.

Default value: `0`
Default value: `2`

Accepted values: `0`, `1` (writing this version is deprecated in favor
of version 2 and will be removed in a future Hyper API release), `2`, `3`, and `4`.
Expand Down
6 changes: 6 additions & 0 deletions website/docs/releases.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,12 @@ In case you are wondering why all our releases start with `0.0`, read [this FAQ

:::

### 0.0.23576 [October 16 2025]
* The default_database_version is upgraded to version 2
* This version better supports UPDATE and DELETE on extracts
* All supported Tableau versions can read these files
* Updated OpenSSL version from 3.4.1 to 3.4.3

### 0.0.23135 [August 28 2025]
* This release adds three new regular expression functions:
* `regexp_substr` to extract substrings
Expand Down
2 changes: 1 addition & 1 deletion website/src/config.ts
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
const version_long = '0.0.23135.r60daa2a5';
const version_long = '0.0.23576.r0633e4a4';
const version_short = version_long.substr(0, version_long.lastIndexOf('.'));

const downloadBaseUrl = 'https://downloads.tableau.com/tssoftware/';
Expand Down