tableau-lineage

Extract Tableau workbook internals into clean, AI-ready JSON.

One command. One output. Everything an AI agent needs to understand a Tableau workbook.

uv run python parse.py --input dashboard.twbx --output nested.json

That's it. The output is a clean, hierarchical JSON with datasources, fields, calculated fields, worksheets, dashboards, filters, and parameters — optimized for AI context windows (81% smaller than the raw internal format).

Why This Exists

Tableau workbooks (.twb/.twbx) contain rich metadata: calculated field formulas, filter logic, worksheet configurations, dashboard layouts, and parameter definitions. But this data is buried in XML, verbose with internal IDs, and impossible for AI agents to reason about directly.

This tool extracts all that into a single nested JSON — no querying, no back-and-forth. Feed the entire output to an AI agent and it has everything it needs in one shot.

Output Format

{
  "workbook": "my_dashboard.twbx",
  "export_version": "0.1.0",
  "counts": {
    "datasources": 3,
    "fields": 232,
    "calculated_fields": 181,
    "worksheets": 42,
    "dashboards": 12,
    "parameters": 3
  },
  "datasources": [
    {
      "name": "federated.xxx",
      "source": "[schema].[table]",
      "fields": [
        {"name": "[customer_id]", "datatype": "integer", "role": "dimension"}
      ],
      "calculated_fields": [
        {
          "name": "[Total Revenue]",
          "formula": "SUM([order_amount])",
          "depends_on": ["[order_amount]"]
        }
      ]
    }
  ],
  "worksheets": [
    {
      "name": "Sales Bar Chart",
      "mark_type": "Bar",
      "rows": ["[region]"],
      "cols": ["[Total Revenue]"],
      "filters": [
        {"field": "[order_date]", "type": "relative-date", "period_type": "month"}
      ],
      "datasource": "federated.xxx"
    }
  ],
  "dashboards": [
    {
      "name": "Main Dashboard",
      "worksheets": ["Sales Bar Chart", "Customer Table"]
    }
  ],
  "parameters": [
    {"name": "Top N", "datatype": "integer", "current_value": "10", "domain_type": "range"}
  ]
}

What Gets Captured

Layer	Data	Use Case
Datasources	Source tables, all fields with types, calculated fields with formulas and dependencies	Understand data structure
Worksheets	Mark type (bar/line/pie), rows, columns, filters with values, datasource references	Recreate visualization logic
Dashboards	Which worksheets appear in which dashboard	Rebuild layout
Parameters	User-configurable values, types, and defaults	Understand interactive controls

Why Nested Instead of Flat?

Metric	Flat JSON	Nested JSON	Reduction
File size	1.6 MB	313 KB	81%
Lines	39,900	2,600	93%
IDs	Verbose (calc::federated.xxx::[Calculation_123])	Human-readable ([Total Revenue])	—
Redundancy	Every field repeated with full IDs	Grouped by datasource	—

The flat format has its uses (graph traversal, edge analysis). Use --flat to get it.

Usage

Basic (nested output — default)

uv run python parse.py --input myworkbook.twbx --output nested.json

Flat output (verbose internal format with all IDs)

uv run python parse.py --input myworkbook.twbx --output flat.json --flat

Supported input formats

Format	Description
.twb	Tableau workbook (XML)
.twbx	Packaged workbook (ZIP containing .twb)

Direct Python usage (standalone export)

If you already have a flat lineage JSON and want to convert it to nested format:

uv run python export_nested.py --input flat.json --output nested.json

Converting to TOON Format

The nested JSON output is already optimized for AI context windows, but if you want to reduce token usage even further, you can convert it to TOON (Token-Oriented Object Notation). TOON combines YAML-like indentation with CSV-style tabular arrays, achieving ~40% fewer tokens than JSON while remaining human-readable.

# Convert nested JSON to TOON using the TOON CLI
npx @toon-format/cli nested.json -o output.toon

This is outside the scope of this project — TOON conversion is a separate step you can add to your pipeline if token savings matter for your use case.

Project Structure

tableau-lineage/
├── parse.py              # Main CLI: .twb/.twbx → nested JSON
├── export_nested.py      # Nested export module (called by parse.py)
├── tests/
│   ├── test_parse.py
│   ├── test_export_nested.py
│   └── fixtures/
│       ├── minimal.twb
│       ├── complete.twb
│       └── sample_lineage.json
├── examples/
│   └── sample_workbook.twb
├── pyproject.toml
├── .python-version
├── README.md
├── AGENTS.md
├── CONTRIBUTING.md
└── LICENSE

Requirements

• Python 3.8 or higher
• uv (brew install uv or pip install uv)

No external dependencies. Both scripts use only the Python standard library.

Complementary Tools

This tool complements (does NOT replace) the official tableau-mcp:

Feature	tableau-lineage	tableau-mcp (official)
Local TWB/WBX parsing	✅	❌
Formula extraction	✅	❌
Filter detection	✅	❌
Nested AI-ready export	✅	❌
Query live data	❌	✅
Get view images	❌	✅

License

MIT License — see LICENSE for details.