parqv 0.1.0

An interactive Python TUI for visualizing, exploring, and analyzing Parquet files directly in your terminal.

parqv

parqv is a Python-based interactive TUI (Text User Interface) tool designed to explore, analyze, and understand Parquet files directly within your terminal. Forget juggling multiple commands; parqv provides a unified, visual experience.

💻 Demo (Placeholder)

🤔 Why parqv?

1. Unified Interface: Launch parqv <file.parquet> to access metadata, schema, data preview, column statistics, and row group details all within a single, navigable terminal window. No more memorizing different commands.
2. Interactive Exploration:
   • 🖱️ Keyboard & Mouse Driven: Navigate using familiar keys (arrows, hjkl, Tab) or even your mouse (thanks to Textual).
   • 📜 Scrollable Views: Easily scroll through large schemas, data tables, or row group lists.
   • 🌲 Expandable Schema: Visualize and navigate complex nested structures (Structs, Lists) effortlessly.
   • 📊 Dynamic Stats: Select a column and instantly see its detailed statistics and distribution.
3. Enhanced Analysis & Visualization:
   • 🎨 Rich Display: Leverages rich and Textual for colorful, readable tables and syntax-highlighted schema.
   • 📈 Quick Stats: Go beyond min/max/nulls. See means, medians, quantiles, distinct counts, frequency distributions, and even text-based histograms.
   • 🔬 Row Group Deep Dive: Inspect individual row groups to understand compression, encoding, and potential data skew.

✨ Features (TUI Mode)

• Interactive TUI: Run parqv <file.parquet> to launch the main interface.
• Metadata Panel: Displays key file information (path, creator, total rows, row groups, compression, etc.).
• Schema Explorer:
  • Interactive, collapsible tree view for schemas.
  • Clearly shows column names, data types (including nested types), and nullability.
  • Syntax highlighting for better readability.
• Data Table Viewer:
  • Scrollable table preview of the file's data.
  • Handles large files by loading data pages on demand.
  • (Planned) Column selection/reordering.
• Row Group Inspector:
  • List all row groups with key stats (row count, compressed/uncompressed size).
  • Select a row group to view per-column details (encoding, size, stats within the group).

🚀 Getting Started

1. Prerequisites:

• Python: Version 3.10 or higher.
• pip: The Python package installer.

2. Install parqv:

• Open your terminal and run:

  pip install parqv
  

• Updating parqv:

  pip install --upgrade parqv
  

3. Run parqv:

• Point parqv to your Parquet file:

  parqv /path/to/your/data.parquet
  

• The interactive TUI will launch. Use your keyboard (and mouse, if supported by your terminal) to navigate:
  • Arrow Keys / h,j,k,l: Move focus within lists, tables, trees.
  • Tab / Shift+Tab: Cycle focus between different panes/widgets.
  • Enter: Select items, expand/collapse tree nodes.
  • View Switching Keys (Examples - check help): m (Metadata), s (Schema), d (Data), t (Stats), g (Row Groups).
  • PageUp / PageDown / Home / End: Scroll long lists or tables.
  • ?: Show help screen with keybindings.
  • q / Ctrl+C: Quit parqv.

---

📄 License

Licensed under the Apache License, Version 2.0. See LICENSE for the full license text.