feat(vx browse): add interactive SQL query tab

Adds a Query tab to the TUI browse mode with:
- SQL input with cursor navigation
- Paginated result display with LIMIT/OFFSET
- Column sorting (click header to cycle ASC/DESC/none)
- Uses shared DataFusion helper for query execution

Signed-off-by: Baris Palaska <[email protected]>

Author: palaska

vortex-tui/src/browse/app.rs

@@ -12,6 +12,7 @@ use vortex::dtype::DType;
 use vortex::error::VortexExpect;
 use vortex::error::VortexResult;
 use vortex::error::VortexUnwrap;
+use vortex::error::vortex_err;
 use vortex::file::Footer;
 use vortex::file::OpenOptionsSessionExt;
 use vortex::file::SegmentSpec;
@@ -24,6 +25,7 @@ use vortex::layout::segments::SegmentId;
 use vortex::layout::segments::SegmentSource;
 
 use crate::SESSION;
+use crate::browse::ui::QueryState;
 use crate::browse::ui::SegmentGridState;
 
 #[derive(Default, Copy, Clone, Eq, PartialEq)]
@@ -34,8 +36,9 @@ pub enum Tab {
 
     /// Show a segment map of the file
     Segments,
-    // TODO(aduffy): SQL query page powered by DF
-    // Query,
+
+    /// SQL query interface powered by DataFusion
+    Query,
 }
 
 /// A pointer into the `Layout` hierarchy that can be advanced.
@@ -199,6 +202,12 @@ pub struct AppState<'a> {
 
     /// Scroll offset for the encoding tree display in FlatLayout view
     pub tree_scroll_offset: u16,
+
+    /// State for the Query tab
+    pub query_state: QueryState,
+
+    /// File path for use in query execution
+    pub file_path: String,
 }
 
 impl AppState<'_> {
@@ -210,6 +219,11 @@ impl AppState<'_> {
 
 /// Create an app backed from a file path.
 pub async fn create_file_app<'a>(path: impl AsRef<Path>) -> VortexResult<AppState<'a>> {
+    let file_path = path
+        .as_ref()
+        .to_str()
+        .ok_or_else(|| vortex_err!("Path is not valid UTF-8"))?
+        .to_string();
     let vxf = SESSION.open_options().open(path.as_ref()).await?;
 
     let cursor = LayoutCursor::new(vxf.footer().clone(), vxf.segment_source());
@@ -225,5 +239,7 @@ pub async fn create_file_app<'a>(path: impl AsRef<Path>) -> VortexResult<AppStat
         segment_grid_state: SegmentGridState::default(),
         frame_size: Size::new(0, 0),
         tree_scroll_offset: 0,
+        query_state: QueryState::default(),
+        file_path,
     })
 }

vortex-tui/src/browse/mod.rs

@@ -19,6 +19,9 @@ use vortex::error::VortexExpect;
 use vortex::error::VortexResult;
 use vortex::layout::layouts::flat::FlatVTable;
 
+use crate::browse::ui::QueryFocus;
+use crate::browse::ui::SortDirection;
+
 mod app;
 mod ui;
 
@@ -47,10 +50,61 @@ enum HandleResult {
     Exit,
 }
 
+#[allow(clippy::cognitive_complexity)]
 fn handle_normal_mode(app: &mut AppState, event: Event) -> HandleResult {
     if let Event::Key(key) = event
         && key.kind == KeyEventKind::Press
     {
+        // Check if we're in Query tab with SQL input focus - handle text input first
+        let in_sql_input =
+            app.current_tab == Tab::Query && app.query_state.focus == QueryFocus::SqlInput;
+
+        // Handle SQL input mode - most keys should type into the input
+        if in_sql_input {
+            match (key.code, key.modifiers) {
+                // These keys exit/switch even in SQL input mode
+                (KeyCode::Tab, _) => {
+                    app.current_tab = Tab::Layout;
+                }
+                (KeyCode::Esc, _) => {
+                    app.query_state.toggle_focus();
+                }
+                (KeyCode::Enter, _) => {
+                    // Execute the SQL query with COUNT(*) for pagination
+                    app.query_state.sort_column = None;
+                    app.query_state.sort_direction = SortDirection::None;
+                    let file_path = app.file_path.clone();
+                    app.query_state.execute_initial_query(&file_path);
+                    // Switch focus to results table after executing
+                    app.query_state.focus = QueryFocus::ResultsTable;
+                }
+                // Navigation keys
+                (KeyCode::Left, _) => app.query_state.move_cursor_left(),
+                (KeyCode::Right, _) => app.query_state.move_cursor_right(),
+                (KeyCode::Home, _) => app.query_state.move_cursor_start(),
+                (KeyCode::End, _) => app.query_state.move_cursor_end(),
+                // Control key shortcuts
+                (KeyCode::Char('a'), KeyModifiers::CONTROL) => app.query_state.move_cursor_start(),
+                (KeyCode::Char('e'), KeyModifiers::CONTROL) => app.query_state.move_cursor_end(),
+                (KeyCode::Char('u'), KeyModifiers::CONTROL) => app.query_state.clear_input(),
+                (KeyCode::Char('b'), KeyModifiers::CONTROL) => app.query_state.move_cursor_left(),
+                (KeyCode::Char('f'), KeyModifiers::CONTROL) => app.query_state.move_cursor_right(),
+                (KeyCode::Char('d'), KeyModifiers::CONTROL) => {
+                    app.query_state.delete_char_forward()
+                }
+                // Delete keys
+                (KeyCode::Backspace, _) => app.query_state.delete_char(),
+                (KeyCode::Delete, _) => app.query_state.delete_char_forward(),
+                // All other characters get typed into the input
+                (KeyCode::Char(c), KeyModifiers::NONE | KeyModifiers::SHIFT) => {
+                    app.query_state.insert_char(c);
+                }
+                _ => {}
+            }
+            return HandleResult::Continue;
+        }
+
+        // Normal mode handling for all other cases
         match (key.code, key.modifiers) {
             (KeyCode::Char('q'), _) => {
                 // Close the process down.
@@ -60,9 +114,25 @@ fn handle_normal_mode(app: &mut AppState, event: Event) -> HandleResult {
                 // toggle between tabs
                 app.current_tab = match app.current_tab {
                     Tab::Layout => Tab::Segments,
-                    Tab::Segments => Tab::Layout,
+                    Tab::Segments => Tab::Query,
+                    Tab::Query => Tab::Layout,
                 };
             }
+
+            // Query tab: Ctrl+h for previous page
+            (KeyCode::Char('h'), KeyModifiers::CONTROL) => {
+                if app.current_tab == Tab::Query {
+                    app.query_state.prev_page(&app.file_path.clone());
+                }
+            }
+
+            // Query tab: Ctrl+l for next page
+            (KeyCode::Char('l'), KeyModifiers::CONTROL) => {
+                if app.current_tab == Tab::Query {
+                    app.query_state.next_page(&app.file_path.clone());
+                }
+            }
+
             (KeyCode::Up | KeyCode::Char('k'), _) | (KeyCode::Char('p'), KeyModifiers::CONTROL) => {
                 // We send the key-up to the list state if we're looking at
                 // the Layouts tab.
@@ -75,6 +145,9 @@ fn handle_normal_mode(app: &mut AppState, event: Event) -> HandleResult {
                         }
                     }
                     Tab::Segments => app.segment_grid_state.scroll_up(10),
+                    Tab::Query => {
+                        app.query_state.table_state.select_previous();
+                    }
                 }
             }
             (KeyCode::Down | KeyCode::Char('j'), _)
@@ -87,6 +160,9 @@ fn handle_normal_mode(app: &mut AppState, event: Event) -> HandleResult {
                     }
                 }
                 Tab::Segments => app.segment_grid_state.scroll_down(10),
+                Tab::Query => {
+                    app.query_state.table_state.select_next();
+                }
             },
             (KeyCode::PageUp, _) | (KeyCode::Char('v'), KeyModifiers::ALT) => {
                 match app.current_tab {
@@ -98,6 +174,9 @@ fn handle_normal_mode(app: &mut AppState, event: Event) -> HandleResult {
                         }
                     }
                     Tab::Segments => app.segment_grid_state.scroll_up(100),
+                    Tab::Query => {
+                        app.query_state.prev_page(&app.file_path.clone());
+                    }
                 }
             }
             (KeyCode::PageDown, _) | (KeyCode::Char('v'), KeyModifiers::CONTROL) => {
@@ -110,25 +189,39 @@ fn handle_normal_mode(app: &mut AppState, event: Event) -> HandleResult {
                         }
                     }
                     Tab::Segments => app.segment_grid_state.scroll_down(100),
+                    Tab::Query => {
+                        app.query_state.next_page(&app.file_path.clone());
+                    }
                 }
             }
             (KeyCode::Home, _) | (KeyCode::Char('<'), KeyModifiers::ALT) => match app.current_tab {
                 Tab::Layout => app.layouts_list_state.select_first(),
                 Tab::Segments => app.segment_grid_state.scroll_left(200),
+                Tab::Query => {
+                    app.query_state.table_state.select_first();
+                }
             },
             (KeyCode::End, _) | (KeyCode::Char('>'), KeyModifiers::ALT) => match app.current_tab {
                 Tab::Layout => app.layouts_list_state.select_last(),
                 Tab::Segments => app.segment_grid_state.scroll_right(200),
+                Tab::Query => {
+                    app.query_state.table_state.select_last();
+                }
             },
             (KeyCode::Enter, _) => {
-                if app.current_tab == Tab::Layout && app.cursor.layout().nchildren() > 0 {
-                    // Descend into the layout subtree for the selected child.
-                    let selected = app.layouts_list_state.selected().unwrap_or_default();
-                    app.cursor = app.cursor.child(selected);
+                match app.current_tab {
+                    Tab::Layout => {
+                        if app.cursor.layout().nchildren() > 0 {
+                            // Descend into the layout subtree for the selected child.
+                            let selected = app.layouts_list_state.selected().unwrap_or_default();
+                            app.cursor = app.cursor.child(selected);
 
-                    // Reset the list scroll state and tree scroll offset.
-                    app.layouts_list_state = ListState::default().with_selected(Some(0));
-                    app.tree_scroll_offset = 0;
+                            // Reset the list scroll state and tree scroll offset.
+                            app.layouts_list_state = ListState::default().with_selected(Some(0));
+                            app.tree_scroll_offset = 0;
+                        }
+                    }
+                    Tab::Query | Tab::Segments => {}
                 }
             }
             (KeyCode::Left | KeyCode::Char('h'), _)
@@ -142,17 +235,44 @@ fn handle_normal_mode(app: &mut AppState, event: Event) -> HandleResult {
                         app.tree_scroll_offset = 0;
                     }
                     Tab::Segments => app.segment_grid_state.scroll_left(20),
+                    Tab::Query => {
+                        app.query_state.horizontal_scroll =
+                            app.query_state.horizontal_scroll.saturating_sub(1);
+                    }
                 }
             }
             (KeyCode::Right | KeyCode::Char('l'), _) | (KeyCode::Char('b'), KeyModifiers::ALT) => {
                 match app.current_tab {
                     Tab::Layout => {}
                     Tab::Segments => app.segment_grid_state.scroll_right(20),
+                    Tab::Query => {
+                        let max_col = app.query_state.column_count().saturating_sub(1);
+                        if app.query_state.horizontal_scroll < max_col {
+                            app.query_state.horizontal_scroll += 1;
+                        }
+                    }
                 }
             }
 
             (KeyCode::Char('/'), _) | (KeyCode::Char('s'), KeyModifiers::CONTROL) => {
-                app.key_mode = KeyMode::Search;
+                if app.current_tab != Tab::Query {
+                    app.key_mode = KeyMode::Search;
+                }
+            }
+
+            (KeyCode::Char('s'), KeyModifiers::NONE) => {
+                if app.current_tab == Tab::Query {
+                    // Sort by selected column - modifies the SQL query
+                    let col = app.query_state.selected_column();
+                    app.query_state.apply_sort(col, &app.file_path);
+                }
+            }
+
+            (KeyCode::Esc, _) => {
+                if app.current_tab == Tab::Query {
+                    // Toggle focus in Query tab
+                    app.query_state.toggle_focus();
+                }
             }
 
             // Most events not handled

vortex-tui/src/browse/ui/mod.rs

@@ -2,9 +2,14 @@
 // SPDX-FileCopyrightText: Copyright the Vortex contributors
 
 mod layouts;
+mod query;
 mod segments;
 
 use layouts::render_layouts;
+pub use query::QueryFocus;
+pub use query::QueryState;
+pub use query::SortDirection;
+use query::render_query;
 use ratatui::prelude::*;
 use ratatui::widgets::Block;
 use ratatui::widgets::BorderType;
@@ -57,17 +62,13 @@ pub fn render_app(app: &mut AppState<'_>, frame: &mut Frame<'_>) {
     let selected_tab = match app.current_tab {
         Tab::Layout => 0,
         Tab::Segments => 1,
+        Tab::Query => 2,
     };
 
-    let tabs = Tabs::new([
-        "File Layout",
-        "Segments",
-        // TODO(aduffy): add SQL query interface
-        // "Query",
-    ])
-    .style(Style::default().bold().white())
-    .highlight_style(Style::default().bold().black().on_white())
-    .select(Some(selected_tab));
+    let tabs = Tabs::new(["File Layout", "Segments", "Query"])
+        .style(Style::default().bold().white())
+        .highlight_style(Style::default().bold().black().on_white())
+        .select(Some(selected_tab));
 
     frame.render_widget(tabs, tab_view);
 
@@ -77,5 +78,6 @@ pub fn render_app(app: &mut AppState<'_>, frame: &mut Frame<'_>) {
             render_layouts(app, app_view, frame.buffer_mut());
         }
         Tab::Segments => segments_ui(app, app_view, frame.buffer_mut()),
+        Tab::Query => render_query(app, app_view, frame.buffer_mut()),
     }
 }