data-explorer.nvim

Preview, Explore, and Query your data files (parquet, csv, tsv) directly inside Neovim

Powered by DuckDB and Telescope.

DataExplorer.mov

---

• Caution
• Motivation & Inspiration
• Requirements
• Features
• Installation
• Config
• API
  • DataExplorer
  • DataExplorerFile
• Usage Example
• Limitations
• Performances
• Architecture
• Future Plans
• Contribute & Bug Reports
• License

---

🚧 Caution

This plugin is still under active development. If you encounter issues, have ideas for improvements, or want to contribute — please open an issue or a pull request!

💪 Motivation & Inspiration

Exploring .parquet files directly in Neovim has always been a pain and required jumping between multiple tools.

While working on a separate side project, I constantly needed a quick, native way to preview, validate, and query these data files to confirm my assumptions and ensure data integrity-all.

So, I created data-explorer.nvim, inspired by: duckdb.yazi and his approach to using DuckDB.

Make this plugin allow me to better understand Neovim, which I've been using since August 2025, but there are still things I need to understand.

⚡️ Requirements

• Neovim ≥ 0.10
• DuckDB, installed and available in your PATH (duckdb command must be executable from your terminal)
• telescope.nvim
• fd

🎄 Features

Feature	Description
Supported Formats	.parquet, .csv, .tsv
SQL system	DuckDB
File Search	Find data files using Telescope
Metadata Display	Show column names, types, and other details
Table View	Display file contents in a formatted, colorized table
Pagination	Navigate large datasets page by page
Custom SQL Queries	Run SQL queries on your data, see results instantly
SQL Query History	History of executed SQL queries
Configurable	Limit, Layouts, mappings, colors, highlights
Commands	DataExplorer, DataExplorerFile

🔌 Installation

Example with lazy.nvim:

{
  "kyytox/data-explorer.nvim",
  dependencies = { "nvim-telescope/telescope.nvim" },
  config = function()
    require("data-explorer").setup()
  end,
}

Or with vim-plug:

Plug 'nvim-telescope/telescope.nvim'
Plug 'kyytox/data-explorer.nvim'

⚙️ Config

require("data-explorer").setup({
  use_storage_duckdb = false,
  limit = 40, -- Maximum number of rows to fetch per page
  layout = "vertical", -- Vertical or ----------
  files_types = {
    parquet = true,
    csv = true,
    tsv = true,
  },

  -- UI/Telescope options
  telescope_opts = {
    layout_strategy = "vertical",
    layout_config = {
      height = 0.7,
      width = 0.9,
      preview_cutoff = 1,
      preview_height = 0.6, -- Used for vertical layout
      preview_width = 0.4, -- Used for horizontal layout
    },
    finder = {
      include_hidden = false, -- Show hidden files
      exclude_dirs = { ".git", "node_modules", "__pycache__", "venv", ".venv", "miniconda3" },
    },
  },

  -- Floating window options for main display windows
  window_opts = {
    border = "rounded",
    max_height_metadata = 0.25,
    max_width_metadata = 0.25,
  },

  -- Query SQL
  query_sql = {
    history_size = 25, -- Number of queries to keep in history
  },

  -- Key mappings
  mappings = {
    quit = "q", -- Close the main UI
    back = "<BS>", -- Go back to file selection
    next_page = "J", -- Next page of data
    prev_page = "K", -- Previous page of data
    focus_meta = "1", -- Focus the metadata window
    focus_data = "2", -- Focus the data window
    toggle_sql = "3", -- Toggle the SQL query window
    rotate_layout = "r", -- Rotate the layout
    execute_sql = "e", -- Execute the SQL query
    prev_history = "<Up>", -- Previous query in history
    next_history = "<Down>", -- Next query in history
  },

  -- Highlight colors
  hl = {
    windows = {
      bg = "#151515",
      fg = "#cdd6f4",
      title = "#D97706",
      footer = "#F87171",
      sql_fg = "#3B82F6",
      sql_bg = "#1e1e2e",
      sql_err_fg = "#EF4444",
      sql_err_bg = "#3b1d2a",
    },
    buffer = {
      hl_enable = true,
      header = "white",
      col1 = "#EF4444",
      col2 = "#3B82F6",
      col3 = "#10B981",
      col4 = "#FBBF24",
      col5 = "#A78BFA",
      col6 = "#06B6D4",
      col7 = "#F59E0B",
      col8 = "#63A5F7",
      col9 = "#22C55E",
    },
  },
})

For more details on configuration options:

• Details Configurations: TXT file
• :help data-explorer.nvim-config: Neovim help

Parameter use_storage_duckdb

This option allows you to enable the storage of data from the read file in a DuckDB database file stored on disk (at the path ~/.cache/nvim/data_explorer/data_explorer.db).

By default, this option is set to false, meaning that the data is loaded directly into DuckDB's in-memory database. This is generally faster for most operations, especially for smaller files. But keep in mind that with each page change and custom query execution, the target file is reread each time.

If you enable this option by setting it to true, the data from the read file will be stored in a .db file on disk. But thanks to this, the file is read only once, so page changes and custom query executions will be faster, especially for larger files. However, this approach may consume more disk space and could be slower for initial loading compared to in-memory operations (cf. performance table below).

🚀 API

DataExplorer

Search for and preview supported data files:

:lua require("data-explorer").DataExplorer()

:DataExplorer

vim.keymap.set("n", "<leader>fd", function()
  require("data-explorer").DataExplorer()
end, { noremap = true, silent = true, desc = "Open Data Explorer" })

Telescope will show a list of supported data files in your current working directory. Selecting a file opens it in the DataExplorer view with metadata and a table view.

DataExplorerFile

Open the currently edited file in DataExplorer (if supported):

:lua require("data-explorer").DataExplorerFile()

:DataExplorerFile

vim.keymap.set("n", "<leader>fD", function()
  require("data-explorer").DataExplorerFile()
end, { noremap = true, silent = true, desc = "Open Data Explorer for current file" })

This bypasses Telescope and directly loads the file into the explorer.

🧠 Usage Example

1. Run :DataExplorer to open the Telescope file picker.
2. Select a file
3. Explore the file:

• 1 → focus Metadata
• 2 → focus Data Table
• 3 → toggle SQL editor

4. Write SQL queries using f as the table name.
5. Press e to execute and view results instantly.
6. Press q to quit the explorer.

⚠️ Limitations

• The larger the file, the more time it will take to display the metadata and data.
• Emojis and certain special characters (not all) in data may not render correctly (small column shifts).
• Minimal SQL editor — no autocomplete or highlighting.
• SQL errors don't provide detailed messages because the query is encapsulated in a select limit offset query (for page management) (feature to improve).

📏 Performances

The following table shows approximate load and query times. The file is a copy of nasa-exoplanet archive data with a lot of lines duplicated.

With a PC:

• CPU: AMD Ryzen™ 7 7700X
• RAM: 32 GB
• DuckDB version: 1.4.1

Their tests are made with the option use_storage_duckdb = false and true with a limit between 50 and 1000 rows. The difference in the limit (50 or 1000) doesn't really impact performance (0.02 s difference) unless you're displaying 20,000 lines.

File Type	File Size	Total Rows	Avg Time (use_storage_duckdb = False)	Avg Time (use_storage_duckdb = True)
Parquet	9 MB	500 000	0.021 s	2.11 s
Parquet	19 MB	1 003 391	0.031 s	4.25 s
CSV	31 MB	38 170	0.336 s	0.534 s
CSV	84 MB	101 553	0.798 s	1.2 s
TSV	31 MB	38 170	0.294 s	0.498 s
TSV	84 MB	101 553	0.729 s	1.60 s

⛩️ Architecture

                        ┌────────────┐
                   ┌────┼  Commands  ┼────┐
                   │    └────────────┘    │
                   │                      │
         ┌─────────▼──────────┐  ┌────────▼───────┐
         │  DataExplorerFile  │  │  DataExplorer  ├───────┐
         └─────────────┬──────┘  └────────────────┘       │
                       │                                  │
                       └─────┐                     ┌──────▼──────┐
                             │                ┌────┤  Telescope  │
                       ┌─────▼──────────┐     │    └───▲─────────┘
                       │ ┌────────────┐ │     │        │
                       │ │  Metadata  │ │     │        │
    ┌─────────────┐    │ │  Metadata  │ ◄─────┘        │
    │  SQL Error  │    │ └────────────┘ │              │
    └──────▲──────┘    │ ┌────────────┐ │              │
           │           │ │    Data    │ │              │Back
           │           │ │            │ │              │to Files
           │           │ │    Data    │ │              │Selection
    ┌──────┴──────┐    │ │            │ │              │
    │  SQL Query  ◄────┤ │    Data    │ ├──────────────┘
    │    Prompt   │    │ │            │ │
    └──────┬──────┘    │ │    Data    │ │
           │           │ └────────────┘ │
           │           └────────▲───────┘
           │                    │
           └────────────────────┘                                 ```

📜 Future Plans

• Support for more formats (.json, .sqlite, etc.)
• Smarter preview caching
• Metadata personalization
• Better SQL Error handling

🫵🏼 Contribute & Bug Reports

PRs and feedback are welcome! If you want to help improve performance, extend support for new formats, or enhance the UI — please open a PR or issue.

📜 License

MIT License © 2025 Kyytox