CSV Table

by Adam Coddington
5
4
3
2
1
Score: 75/100

Description

Category: Data Visualization

The CSV Table plugin is a powerful tool for rendering CSV data as tables within Obsidian notes. With this plugin, you can easily import and display your CSV files in a formatted table, complete with filtering, sorting, and column customization options. Simply place the plugin's code block in your note, specify the source CSV file, and configure the settings to suit your needs. The plugin supports various data types, including integers, booleans, and dates, making it easy to work with complex data sets. Additionally, you can use advanced filtering expressions and sorting options to refine your results. Whether you're working with large datasets or just want to easily display some CSV data in your notes, the CSV Table plugin is a valuable addition to your Obsidian toolkit.

Reviews

No reviews yet.

Stats

149
stars
39,369
downloads
11
forks
1,982
days
31
days
31
days
1
total PRs
0
open PRs
0
closed PRs
1
merged PRs
26
total issues
0
open issues
26
closed issues
18
commits

Latest Version

a month ago

Changelog

This is the first release since 2021. It rebuilds the plugin on current versions of csv-parse and filtrex, which brings working date handling and a few things that were quietly wrong in 1.2 (maxRows, failed filters), and it requires Obsidian 1.13.1 or newer. Existing csvtable blocks were checked expression by expression against 1.2's behaviour, so the differences you can see are the ones listed under Breaking changes at the end.

At a glance

Features

  • Dates — cast_date never reached the parser, so dates were always text and couldn't be compared as dates
  • Current csv-parse options — the Readme linked csv-parse's current docs, but the plugin ran a 2021 version that ignored newer option names
  • Numeric and date column names — a header like 2020 or 2021-01-01 couldn't be shown, filtered or sorted
  • Errors that name the option — a malformed block said "Could not parse CSV table spec" and nothing else

Bug fixes

  • maxRows counted the wrong rows — it limited rows read, not rows shown, and sorting ran on that prefix
  • A failed filter showed every row — an unknown function or a typo let the whole file through
  • Smaller fixes — byte order marks, empty files, short first rows, the stylesheet's width rule, the error box

Features

Dates: cast_date never reached the parser, so dates were always text

The problem: The Readme said cells were cast "to an integer, boolean, or date object". Numbers were; dates were not. The plugin dropped the cast_date option before calling csv-parse, so csvOptions: {cast_date: true} did nothing, every date cell stayed text, and a filter like start >= "2021-10-28" only worked when the file happened to write its dates year-first (#4). csv-parse's own date casting, had it been reachable, reads a bare date as UTC midnight and a date with a time in local time, so start == "2021-10-28" would have failed west of UTC.

What's new: cast_date: true works. With it on, every cell JavaScript can read as a date becomes one, read in your local time zone whether or not it carries a time, so both sides of start >= "2021-10-28" mean the same instant. A date cell displays as 2021-01-11, or 2021-01-11 08:00 when it has a time, instead of a quoted ISO timestamp, and ~= matches against that same text. The header line is never cast. It stays off by default, as it effectively always was.

source: meetings.csv
csvOptions:
  cast_date: true
filter: start >= "2021-10-28"
sortBy: start

Without it, dates written year-first still filter and sort correctly as text, which is what 1.2 did.

Current csv-parse options: the Readme linked docs for a parser the plugin didn't run

The problem: The csvOptions section pointed at csv-parse's current documentation, but the plugin bundled csv-parse 4 from 2021. Options added or renamed since — relax_quotes, skip_records_with_error, group_columns_by_name — were silently ignored, and the camelCase spellings csv-parse accepts (castDate, skipEmptyLines) bypassed the plugin's own defaults.

What's new: The plugin runs csv-parse 7, so the options on csv.js.org work as written. The names csv-parse 4 used (relax, skip_lines_with_empty_values, skip_lines_with_error, columns_duplicates_to_array) still work too, and camelCase spellings are treated the same as snake_case ones. When a block gives both an old and a new name, the new one wins.

Numeric and date column names: a header like 2020 broke the table

The problem: csv-parse 4 refused a header cell it had cast to a number, so a CSV with a 2020 column didn't render at all. A header like 2021-01-01 rendered, but couldn't be named in columns, sortBy or columnVariables: YAML reads the unquoted form as a date, and the plugin threw on it.

What's new: Numeric headers render. In the block, a number or an unquoted date is read back as the column's name wherever a name goes (columns, columnVariables, and {name: …}), and where an expression goes (sortBy, expression: …) it is turned into filtrex's quoted-symbol form, '2020', so it reads the column rather than the constant. Any column whose name isn't a valid identifier — spaces, accents — can be written that way directly, 'Localité' == "Paris", which filtrex has always allowed and the Readme now says so (#7). A date with a time has to be quoted, since YAML can't hand it back as written.

Errors that name the option: a malformed block said only "Could not parse CSV table spec"

The problem: The block's YAML was used as-is. csvOptions written as a list rather than a mapping (#29), a filter given as a mapping, or maxRows: ten produced either a generic parse error or a table that silently ignored the option.

What's new: Each option is checked, and a wrong shape is reported by name: Parameter 'csvOptions' must be a mapping of csv-parse option names to values. A key left blank is treated as not given, as before. source also accepts a leading / or ./ and backslashes.

Bug fixes

maxRows limited the rows read, not the rows shown

The problem: maxRows cut the file off before filtering: the filter ran over the first N rows and the table showed however many of those passed. sortBy then sorted only that prefix. A block asking for the five most populous countries with sortBy: {expression: population, reversed: true} and maxRows: 5 got the first five rows of the file, in population order.

What's new: Rows are filtered, then sorted, then cut to maxRows, as the Readme always described. A block that combined maxRows with filter or sortBy will show different rows after upgrading; one that used maxRows alone is unaffected.

A failed filter expression showed every row

The problem: filtrex 2 reported a runtime error — an unknown function, a misspelled one — by returning the error object instead of throwing, and an error object is truthy. A filter like contains(name, "a") therefore matched every row, and a column expression that failed showed {} in every cell, with nothing to say anything had gone wrong.

What's new: A filter, column or sort expression that fails at runtime shows its error in place of the table, as a syntax error already did. Sort errors are reported as sort errors rather than being blamed on the filter.

Also fixed

  • A byte order mark at the start of a UTF-8 CSV (Excel writes one) became part of the first column's name, so that column couldn't be referenced. It's skipped by default; bom: false in csvOptions restores the old behaviour.
  • An empty CSV, or one with only a header line, threw "Cannot convert undefined or null to object" instead of rendering an empty table. Column names now come from the header line, so under relax_column_count a short first row no longer drops columns from the whole table.
  • styles.css has always set .csv-table { width: 100% }, but only the error block carried that class; tables are now rendered with it and fill the note's width.
  • The error block had ten lines of padding on every side of a one-line message. It has one.

Breaking changes and migration

What changed: The plugin requires Obsidian 1.13.1 or newer, and filtrex 3 replaces filtrex 2 for expressions. Its comparison and arithmetic operators have been made to behave as they did (text and numbers coerce as in JavaScript; a blank cell is zero in arithmetic; population == "50340000" still matches a numeric cell), but two differences could not be undone.

You are affected if you...

  • run Obsidian older than 1.13.1 — you'll stay on 1.2.0.
  • apply and, or or not to a column that isn't true or false: not retired on a text column, or name and population > 5. filtrex 3 requires boolean operands and won't let that be overridden, so the block now shows an error. Compare instead: not (population > 100000000), retired == false.
  • use a comparison as a column (columns: [population > 1000000]) — it displays true/false rather than 1/0. Arithmetic on it is unchanged.
  • combine maxRows with filter or sortBy — see the fix above; the rows shown change.
  • rely on tables not filling the note's width.

Not affected: blocks that use source, columns, columnVariables, filter and sortBy with plain comparisons — every example in the Readme — render as before.

No escape hatch for the operator change, and the previous version of the plugin is still installable from its release if you need to wait. The Readme's "Upgrading from 1.2" section has the full list.

README file from

Github

Obsidian CSV Table

Have data in a CSV file that you'd like to render as a table in Obsidian? Now you can.

Quickstart

Imagine you have the following CSV file named countries.csv:

name,capitol,population
United States of America,"Washington, DC",328200000
Colombia,Bogota,50340000
Russia,Moscow,144400000

The following code block:

```csvtable
source: countries.csv
```

will render a table like:

Options

  • source: (Required) Path (relative to your vault's root) to the csv file to render within your notes.
  • csvOptions: Options to use for decoding the referenced CSV file; see https://csv.js.org/parse/options/ for available options (the names csv-parse 4 used, such as relax, are accepted too). By default the plugin sets columns: true, trim: true, skip_empty_lines: true, bom: true and cast: true; anything you set here takes precedence.
  • columns: A list of columns to render. Each item may be either the name of a field to display or an expression (see "Expressions" below), and can be re-named. If unspecified, all columns in the referenced CSV will be rendered. See "Selecting particular columns" below for details.
  • filter: A list of filter expressions (see "Expressions" below) or a single filter expression to use for limiting which rows of the referenced CSV will be displayed. If unspecified, all rows of the referenced CSV will be rendered taking into account the value specified for maxRows below. See "Filtering displayed rows" for details.
  • sortBy: A list of sort expressions (see "Expressions" below) or a single sort expression to use for sorting the displayed rows. If unspecified, rows will be displayed in the order they appear in the referenced CSV. See "Sorting Rows" for details.
  • columnVariables: A mapping of variable name to column name allowing you to set a name for use in filter or columns above to reference the value of a field that is not a valid variable name.
  • maxRows: The maximum number of rows to display, counted after filter and sortBy have been applied. If unspecified, all rows matching your filter will be displayed.

Expressions

This library uses filtrex for expression evaluation; see their documentation to see more information about the expression syntax and what functions are available: https://github.com/m93a/filtrex#expressions.

See "Filtering displayed rows" for an example of a filter expression in action, but realistically they work exactly as you'd probably expect. A few details worth knowing:

  • and, or and not need true-or-false operands: write not (population > 100000000) or done == true rather than not population.
  • true and false can be written as-is, e.g. done == true.
  • Comparisons and arithmetic coerce the way JavaScript does: a number cell compared with text naming a number (population == "50340000") matches, and a blank cell counts as zero in -, *, / and mod (+ with a blank cell joins text, as in JavaScript). Multiplying text, or dividing zero by zero, gives a value that displays as null and is neither less nor greater than anything; dividing a positive number by zero gives one that displays as null but is greater than every number. in compares exactly. Write mod rather than %, which filtrex has deprecated.
  • Dates are text unless you set cast_date: true in csvOptions (see "Filtering displayed rows"). Text compares alphabetically, which puts year-first dates in order: start >= "2021-10-28". A date cell can be compared with another date cell, or with text naming a date; dates and times written without a time zone are read in your local time zone, on both sides of the comparison.
  • A column whose name isn't a valid identifier (letters, digits and underscores, not starting with a digit) can be written in single quotes, as in 'Country Name' == "Colombia", or given a usable name with columnVariables.
  • A column name that YAML reads as a date (2021-01-01) or a number (2020, 010) can be written unquoted anywhere in the block; the plugin reads it back as the name (010 becomes 10, which is also how csv-parse keys that header while cast is on). A date with a time must be quoted. Writing a number as a quoted string in sortBy or expression makes it a constant, not a column.

Selecting particular columns

You can use the columns field to control which columns of your CSV file to render, e.g:

```csvtable
columns:
- name
- population
source: my_csv_file.csv
```

It's also possible for you to set better names for your columns or use expressions:

```csvtable
columns:
- expression: name
  name: Country Name
- expression: population  / 1000000
  name: Population (Millions)
source: my_csv_file.csv
```

Filtering displayed rows

Maybe you would like to display only a subset of the rows of your CSV? If so, you can provide a filter expression to limit which rows are shown:

```csvtable
source: my_csv_file.csv
filter: population < 100000000
```

By default, cells holding a number are cast to numbers for use in your filter expressions; everything else, dates included, stays text. Text compares alphabetically, so dates written year-first (2021-10-28, 2021-10-28 12:00) can be filtered as they are:

```csvtable
source: meetings.csv
filter: start >= "2021-10-28"
```

If you set cast_date: true in csvOptions, every cell JavaScript can read as a date becomes one (including text like "March 5" or "meeting 5", so use it on files you know; the header line is left alone, and cast must stay on). A date cell is displayed as 2021-01-11, or 2021-01-11 08:00 when it has a time (with seconds, and milliseconds, when they aren't zero), in your local time zone, and compares with text naming a date, as described under "Expressions".

Also, note that your filter expression can also be provided as a list; those expressions will be and-ed together, e.g.:

```csvtable
source: my_csv_file.csv
filter:
- population < 100000000
- name == "Colombia"
```

Note that the filtering language requires that you use double-quoted strings in comparisons -- if you had entered name == 'Colombia' above, the filter would not have returned results.

Sorting Rows

If you would like to sort the rows of your displayed CSV, you can provide a sort expression:

```csvtable
source: my_csv_file.csv
sortBy: name
```

Additionally, you can specify your sortBy expression as a list; the document will be sorted by all specified fields in rank order:

```csvtable
source: my_csv_file.csv
sortBy:
- columnOne
- columnTwo
```

It's also possible for you to sort your displayed data in reverse order if you specify your sortBy expression using an extended format allowing you to specify both the expression and direction of sort:

```csvtable
source: my_csv_file.csv
sortBy:
- expression: name
  reversed: true
```

Upgrading from 1.2

Version 1.3 rebuilt the plugin on current tooling and newer versions of csv-parse and filtrex. Existing csvtable blocks should keep working, with these differences:

  • Requires Obsidian 1.13.1 or newer.
  • maxRows now counts the rows displayed, after filtering and sorting. It used to limit how many rows of the file were read before filtering, and sorting applied to that subset.
  • cast_date in csvOptions now takes effect (1.2 dropped that spelling before calling csv-parse, so dates were always text, whatever the old Readme said; the castDate spelling did reach csv-parse). It is off by default, as before. With it on, date cells are read, displayed (2021-01-11, 2021-01-11 08:00) and compared in your local time zone, where csv-parse's own casting read a bare date as UTC midnight.
  • csv-parse's relax, skip_lines_with_empty_values, skip_lines_with_error and columns_duplicates_to_array options were renamed in csv-parse 5; the old names still work here.
  • A byte order mark at the start of the file is skipped, so the first column of a CSV saved by Excel gets its proper name.
  • and, or and not require true-or-false operands; see "Expressions".
  • Expression errors that used to let every row through (an unknown function, for instance) now show as an error in place of the table.
  • A comparison used as a column expression (population > 1000000) displays as true/false rather than 1/0.
  • The table's columns come from the CSV's header line even when the first row is short (with relax_column_count); previously the short row decided.
  • Tables carry the csv-table class and so fill the width of the note, as the plugin's stylesheet always intended.

Similar Plugins

info
• Similar plugins are suggested based on the common tags between the plugins.
Excel to Markdown Table
5 years ago by Ganessh Kumar R P
An Obsidian plugin to paste data from Microsoft Excel, Google Sheets, Apple Numbers and LibreOffice Calc as Markdown tables in Obsidian editor.
AsciiDoc Blocks Plugin
5 years ago by Juracy Filho
A plugin to render asciidoc blocks in Obsidian, initially asciidoc tables
Table to CSV Exporter
4 years ago by Stefan Wolfrum
An Obsidian Plugin that allows to export tables from a pane in reading mode to CSV files.
Table Generator
4 years ago by Boninall
A plugin for generate markdown table quickly like Typora.
Any Block
4 years ago by LincZero
You can flexibility to create a 'Block' by many means. It also provides many useful features, like `list to table`. (obsidian/markdown-it/vuepress plugin/app)
Financial Doc
3 years ago by Studio Webux
Financial Documentation and Tracking using CSV format and Chart.js directly in Obsidian
Importer
3 years ago by Obsidian
Convert your data to Markdown files you can use in Obsidian. Works with Apple Notes, OneNote, Evernote, Notion, Google Keep, and many other formats.
Sheets Extended
3 years ago by NicoNekoru
Plugin that adds features to tables in obsidian including merging, vertical headers, and custom css
Markdown table checkboxes
3 years ago by DylanGiesberts
Obsidian plugin. Allows for the usage of checkboxes inside markdown tables.
CSV Codeblock
3 years ago by elrindir
Plugin for obsidian to render csv syntax in codeblocks.
JSON table
3 years ago by Dario Baumberger
Simply switch between JSON and tables in your Obsidian notes.
Enhanced tables
3 years ago by pistacchio
A plugin for Obsidian to add advanced controls (like sorting and filtering) to standard markup tables
Markmap to CSV
3 years ago by maxlee
obsidian plugin for conversion from markmap to csv
SQLSeal
2 years ago by hypersphere
Query your files using SQL directly from your Obsidian Vault
Account Viewer
2 years ago by Muaz Yediyüzkırkiki
Obsidian Plugin that automatically generate accounting tables from Markdown code blocks tagged with "accounting" alias.
Advanced Tables
6 years ago by Tony Grosinger
Improved table navigation, formatting, and manipulation in Obsidian.md
CSV Editor
6 years ago by death_au
Edit CSV Files in Obsidian
Table of Contents
6 years ago by hipstersmoothie
Create a tables of contents for a note.
Table Extended
6 years ago by AidenLx
Extend basic table in Obsidian with MultiMarkdown table syntax
Charts View
5 years ago by caronchen
Data visualization solution in Obsidian, support plots and graphs.
HTML checkboxes
2 years ago by Anareaty
CSV All-in-One
2 years ago by hihangeol
Sortable Tables
a year ago by filippov112
A plugin for Obsidian that adds the ability to interactively sort Markdown tables in preview mode.
List to table converter
a year ago by paddomanno
Table Checkbox Renderer
a year ago by Daniel Aguerrevere
Interactive checkboxes for Markdown tables in Obsidian. Toggle checkboxes in Reading Mode and instantly update your Markdown file. Supports multiple checkboxes per cell and any table layout.
Workout Planner
10 months ago by Rares Spatariu
Table Line Break Mobile
9 months ago by marcelflymark
Obsidian plugin: Insert a new line break inside a table cell using the <br> HTML element
JSON-CSV Importer
4 months ago by farling42
Plug-in for Obsidian.md which will create Notes from JSON files
Budget Planner
4 months ago by kalinichenko88
A minimalist budget planning tool for Obsidian. Create, track, and manage budgets using markdown code blocks directly in your notes.
Bases Toolbox
4 months ago by Grub Basket
Adds Quality of Life features to Obsidian Bases
Power Bases
4 months ago by Power Plugins
Add board, calendar, timeline, chart, gallery, and table views to Bases, with inline editing, colors, rollups, field types, formulas, and CSV import.
Power Tables
4 months ago by Power Plugins
Color, calculate, and sort Markdown tables in place: cell fills and text colors, live formulas that recalculate, and column sorting, all stored as plain Markdown.
Power Editor
4 months ago by Power Plugins
Format any note from a toolbar, selection bubble, or slash menu: WYSIWYG editing, block drag handles, image resizing, dictation, and AI edits, all staying plain Markdown.
TableTune
3 months ago by niizhou
Tune your Obsidian tables: drag column/row borders to resize; sizes remembered per table; content-aware defaults; clean single-scrollbar reading view.
Table Resize
2 months ago by lishuai1993
调整obsidian中表格宽度的插件
Vtable
a month ago by vmsimab
在 Obsidian 中创建增强表格,支持单元格合并、公式计算、一键图表与富文本实时渲染等众多功能。