The .totsum workspace file

When you save a workspace, Totsum writes one file with the .totsum extension. This page describes what is inside it, so that you can get your data back with ordinary tools, without Totsum, without a license key and without asking us. This page is the layout that commitment refers to.

What the file is

A .totsum file is an ordinary ZIP archive. Rename it to .zip, or open it with any archive tool, and you will find this layout:

metadata.json                 the workspace description (plain JSON, UTF-8)
database/
  <table name>.parquet        one Parquet file per table in the workspace

• database/*.parquet holds your data, one file per table, in the Apache Parquet format. Each file keeps the column names, types and values exactly as the table stood when you saved, empty cells included.
• metadata.json holds everything else that the workspace remembers. That is the format version, when it was saved, your description, the list of tables and where each was imported from, the questions and answers of the conversation, chart definitions, folders, table and column descriptions, and notes. It is plain JSON, and you can read it in a text editor.

The file holds no license key and no passphrase. The app has no feature that sends a workspace anywhere. It has no account, no sync, no telemetry and no update check.

The format version

metadata.json starts with a metadata block:

{
  "metadata": {
    "version": "1.2",
    "created_at": "2026-08-29T10:15:00",
    "description": "Q3 sales — first look",
    "totsum_version": "1.0.0"
  },
  "tables": [ ... ],
  ...
}

version is the version of the file layout, not of the application. The layout on this page is version 1.2. Totsum opens older layouts. A layout newer than the one your Totsum knows is opened too, with the fields it does not know left aside. Those fields are dropped if you save the file from the older build, so keep a copy first. If a future release changes the layout, this page changes with it and the version number moves.

Opening it without Totsum

With a spreadsheet or a data tool. Extract the archive. Each database/*.parquet file opens in any tool that reads Parquet, such as DuckDB, pandas, Polars, Apache Spark, R (arrow) and many desktop tools.

With Python (the pyarrow package):

import io, json, zipfile
import pyarrow.parquet as pq

with zipfile.ZipFile("my-workspace.totsum") as zf:
    description = json.loads(zf.read("metadata.json"))
    sales = pq.read_table(io.BytesIO(zf.read("database/sales.parquet")))

print(description["metadata"])
print(sales.to_pandas().head())

With DuckDB, after extracting the archive:

SELECT * FROM read_parquet('database/sales.parquet');

What is not in the file

• Your license key is not in the file. It lives in ~/.totsum/license.key (macOS) or %USERPROFILE%\.totsum\license.key (Windows), separately from any workspace.
• The AI model is not in the file. It is installed once on the machine, in ~/.totsum/models/, and it is not copied into workspaces.
• Exports you made, such as reports, images and data files, are ordinary files that you saved elsewhere. A workspace does not contain them.

Totsum’s own test suite includes a test that saves a workspace and reads the tables back with zipfile and pyarrow alone. The layout above is therefore checked on every build, not only described here.