Skip to content

Latest commit

 

History

History
139 lines (113 loc) · 5.31 KB

tui.md

File metadata and controls

139 lines (113 loc) · 5.31 KB

TUI Guide

The dft TUI (Text User Interface) is an IDE-like experience that allows you to query DataFusion in a local “database-like” environment. It includes built-in utilities for analyzing queries, exploring catalogs, benchmarking, and more.

SQL & FlightSQL Editor and Results Query History and Stats
image image
Filterable Logs DataFusion Session Context Details
image image

Key Features of the TUI

  • Multiple Tabs for organizing queries and results:
    • SQL Editor – execute queries locally or (optionally) against FlightSQL.
    • Query History – quickly review previously run queries.
    • Execution Context – inspect DataFusion session details.
    • Logs – filter logs from dft or DataFusion in real time.
  • Custom ObjectStore Support – easily query data from AWS S3, Azure (TODO), GCP (TODO), or local file systems.
  • TableProviderFactory Integrations – Delta Lake, Iceberg, Hudi, etc.
  • Preloading DDL – automatically run your configured DDL on startup, giving a “local DB” feel.
  • Benchmark & Analyze – quickly measure and analyze query performance.

Limitations

  • Horizontal Scrolling: The underlying terminal widget does not support horizontal scrolling well. For wide data sets, consider selecting only the columns you need until improved scrolling support arrives.

Starting the TUI

Once you have installed dft, simply run:

dft

This will launch the TUI in your terminal.

Key Mappings

The interface is split into several tabs and modes so that relevant information can be viewed and controlled in a clean and organized manner. When not writing a SQL query keys can be entered to navigate and control the interface.

SQL Tab

Editor for executing SQL with local DataFusion SessionContext.

  • Normal mode
    • Not editable
      • q => quit datafusion-tui
      • e => start editing SQL Editor in Edit mode
      • c => clear contents of SQL Editor
      • Enter => execute query
      • Enter the tab number in brackets after a tabs name to navigate to that tab
      • If query results are longer or wider than screen, you can use arrow keys to scroll
    • Editable
      • Character keys to write queries
      • Backspace / tab / enter work same as normal
      • Shift + Up/Down/Left/Right => Select text
      • Alt + Enter => execute query
      • esc to exit Edit mode and go back to Normal mode
  • DDL mode
    • Not editable
      • l => load configured DDL file into editor
      • enter => rerun configured DDL file
      • s => write editor contents to configured DDL file
    • Editable
      • Character keys to write queries
      • Backspace / tab / enter work same as normal
      • Shift + Up/Down/Left/Right => Select text
      • Alt + Enter => execute query
      • esc to exit Edit mode and go back to Normal mode

FlightSQL Tab

Same interface as SQL tab but sends SQL queries to FlightSQL server.

  • Normal mode
    • q => quit datafusion-tui
    • e => start editing SQL Editor in Edit mode
    • c => clear contents of SQL Editor
    • Enter => execute query
    • Enter the tab number in brackets after a tabs name to navigate to that tab
    • If query results are longer or wider than screen, you can use arrow keys to scroll
    • Edit mode
      • Character keys to write queries
      • Backspace / tab / enter work same as normal
      • Shift + Up/Down/Left/Right => Select text
      • Alt + Enter => execute query
      • esc to exit Edit mode and go back to Normal mode

History Tab

TODO

Logs Tab

  • Logging mode (coming from tui_logger)
    • h => Toggles target selector widget hidden/visible
    • f => Toggle focus on the selected target only
    • UP => Select previous target in target selector widget
    • DOWN => Select next target in target selector widget
    • LEFT => Reduce SHOWN (!) log messages by one level
    • RIGHT => Increase SHOWN (!) log messages by one level
    • - => Reduce CAPTURED (!) log messages by one level
    • + => Increase CAPTURED (!) log messages by one level
    • PAGEUP => Enter Page Mode and scroll approx. half page up in log history.
    • PAGEDOWN => Only in page mode: scroll 10 events down in log history.
    • ESCAPE => Exit page mode and go back to scrolling mode
    • SPACE => Toggles hiding of targets, which have logfilter set to off

Editor Settings

[tui.editor]
experimental_syntax_highlighting = true