DataGlass Product Guide

A comprehensive guide to DataGlass—the declarative visualization framework for Obsidian.

Executive Summary

DataGlass transforms YAML configurations into interactive charts within Obsidian notes. It bridges the gap between simple markdown and sophisticated data visualization, enabling knowledge workers to create publication-ready charts without writing code.

Core Philosophy: Configuration over code. A 5-line YAML block produces an interactive chart.

yaml

type: bar
data:
  source: '[{"category": "A", "value": 30}, {"category": "B", "value": 70}]'
x: category
y: value

Architecture Overview

Monorepo Structure

packages/
├── chart-renderer/      # Core engine (framework-agnostic, zero Obsidian deps)
├── dataglass-plugin/    # Obsidian integration layer
├── web/                 # Browser/web interface
├── markdown-it/         # Markdown processor plugin
├── chart-test-harness/  # Testing infrastructure
├── test-scenarios/      # 139 YAML test scenarios
└── wiki/                # Documentation site

Rendering Pipeline

YAML Config → Parse & Validate → Load Data → Transform → Select Engine → Render → Interactive SVG

Parse & Validate: Zod schemas with line/column error tracking
Load Data: CSV, JSON, Parquet, URLs, vault queries
Transform: Filter, aggregate, sort, pivot (9 transform types)
Engine Selection: Observable Plot (default) or D3
Render: SVG with optional interactions

Dual Engine Design

Observable Plot	D3 Engine
Simpler configuration	Advanced specialization
35+ mark types	31 chart types
Composable marks	Full chart implementations
Statistical transforms	Hierarchy drill-down
Default engine	`engine: d3` required

Feature Inventory

Chart Types (40+)

Basic Charts (both engines):

Bar, Line, Area, Scatter, Pie, Donut

Statistical Analysis (D3):

Boxplot, Histogram, Violin, Ridgeline, Contour, Heatmap, Bollinger Bands

Hierarchical (D3 with drill-down):

Treemap, Sunburst, Circle Packing, Dendrogram, Icicle, Tidy Tree

Network & Flow (D3):

Force-Directed Graph, Sankey Diagram, Chord Diagram, Arc Diagram, Edge Bundling, Parallel Sets

Time Series (D3):

Candlestick, Horizon Chart, Slope Chart

Radial (D3):

Radial Bar, Radial Area, Polar Area

Animated (D3):

Bar Race, Streamgraph

Observable Plot Marks (composable):

dot, line, area, bar, rect, text, rule, tick, link, arrow, vector, box, cell, hexbin, contour, density, regression, crosshair, waffle, frame, grid, axis

Data Sources

Source	Format	Example
Inline JSON	Array or object	`source: '[{"x":1}]'`
Inline CSV	Headers + rows	`source: 'a,b\n1,2'`
Markdown Table	Pipe syntax	`source: '\|a\|b\|\n\|1\|2\|'`
File	CSV, JSON, Parquet	`file: 'data/sales.csv'`
URL	Remote endpoint	`url: 'https://api.example.com/data.json'`
Vault Query	Obsidian-specific	`query: 'from:folder where:tag:#data'`
Heading Reference	Extract table	`file: '#Sales Data'`

Data Transformations (9 types)

yaml

transformations:
  - type: filter
    configuration:
      where: { status: { eq: "active" }, value: { gte: 100 } }

  - type: aggregate
    configuration:
      groupBy: ["category"]
      metrics: { total: { field: "value", op: "sum" } }

  - type: sort
    configuration:
      fields: [{ field: "total", direction: "desc" }]

  - type: limit
    configuration: { count: 10 }

Available transforms:

filter - WHERE clauses (eq, ne, gt, gte, lt, lte, in, contains, between)
aggregate - GROUP BY with metrics (sum, avg, min, max, count, first, last, concat)
sort - ORDER BY multiple fields
limit - LIMIT/OFFSET pagination
select - Column projection
rename - Column aliasing
derive - Computed columns
pivot - Reshape long to wide
sampling - Random/stratified sampling

Interactive Features

Tooltips:

yaml

interactions:
  tooltip:
    enabled: true
    template: "{category}: {value}"

Selection:

yaml

interactions:
  selection:
    mode: multiple
    highlightColor: "#ff6b6b"

Drill-Down (hierarchies):

yaml

interactions:
  drillDown:
    enabled: true
    breadcrumbs: true
    position: top-left

Hover Effects:

yaml

interactions:
  hover:
    enabled: true
    debounce: 50

Styling & Theming

Color Schemes:

category10, tableau10, accent, dark2, paired
pastel1, pastel2, set1, set2, set3
spectral, viridis, warm, cool, colorblind

Scale Types:

Linear, Log, Sqrt (quantitative)
Ordinal (categorical)
Time/UTC (temporal)
Diverging (with pivot point)

Theme Support:

Automatic dark/light mode detection
Custom color overrides
Obsidian CSS variable integration

Strengths

1. Declarative Simplicity

No JavaScript required. Complex visualizations from simple YAML:

yaml

type: treemap
engine: d3
data:
  file: data/org-structure.json
hierarchy:
  id: name
  parent: parentName
  value: size
interactions:
  drillDown:
    enabled: true
    breadcrumbs: true

2. Dual Engine Flexibility

Observable Plot: Quick charts, composable marks, statistical transforms
D3: Specialized charts, hierarchies with drill-down, network visualizations

3. Rich Data Pipeline

Load from 7+ source types
Transform with 9 operation types
Chain transformations sequentially

4. Framework-Agnostic Core

The chart-renderer package has zero Obsidian dependencies. It can be embedded in:

Web applications (@dataglass/web)
Markdown processors (@dataglass/markdown-it)
Any JavaScript environment

5. Production-Ready Quality

139 YAML test scenarios covering all chart types
6,400+ unit tests for comprehensive coverage
Zod validation with line/column error tracking
Performance monitoring with tiered budgets
Security measures (input limits, rate limiting, URL validation)

6. Intelligent Defaults

Domain inference: Preserves categorical order automatically
Scale detection: Temporal, quantitative, categorical auto-detected
Color schemes: Appropriate palettes based on data type
Responsive sizing: Charts adapt to container width

7. Deep Obsidian Integration

Native code block processing (dg, data-glass)
Vault query data sources
Heading table extraction
Canvas integration
Theme synchronization

8. Extensive Chart Library

40+ chart types across both engines
35+ composable Plot marks
Specialized visualizations (Sankey, Chord, Force-Directed)
Statistical charts (Boxplot, Violin, Ridgeline)

Limitations

1. Learning Curve

YAML configuration requires understanding:

Chart type options and when to use each
Data source formats and loading patterns
Transformation syntax and chaining
Engine-specific features

Mitigation: Comprehensive examples, cheat sheet, visual editor (POC)

2. Engine Feature Disparity

Not all features available in both engines:

Drill-down: D3 only
Statistical transforms: Plot only
Some chart types: Engine-specific

Mitigation: Clear documentation of engine capabilities, automatic engine suggestion

3. Large Dataset Performance

Charts with >10,000 points may experience:

Slower initial render
Browser memory pressure
Interaction lag

Mitigation: Built-in sampling, aggregation transforms, progressive rendering

4. Static Export Limitations

No native PNG/PDF export (requires external tools)
SVG export available but may need post-processing
Interactive features lost in static exports

5. Real-Time Data

No streaming data support
Manual refresh required for URL sources
No WebSocket integration

6. Collaboration

No shared chart editing
No comment/annotation layer
Single-user workflow assumed

7. Mobile Experience

Touch interactions limited
Small screen layouts not optimized
Obsidian mobile app constraints

Potential Improvements

Near-Term Enhancements

1. Visual Chart Builder Current POC exists. Full implementation would provide:

Drag-and-drop chart creation
Live YAML preview
Property panel for all options
Data preview and column picker

2. Chart Templates & Presets

yaml

template: sales-dashboard
data:
  file: "quarterly-sales.csv"

Pre-configured templates for common use cases.

3. Export Capabilities

PNG export via canvas rendering
PDF export for reports
Clipboard copy for presentations

4. Annotation Layer

Add notes to specific data points
Highlight regions of interest
Custom callouts and labels

Medium-Term Features

5. Real-Time Data

WebSocket data sources
Polling with configurable intervals
Delta updates for efficiency

6. AI-Assisted Charting

Chart type suggestions based on data
Automatic transformation recommendations
Natural language chart creation

7. Linked Charts

Cross-filtering between charts
Shared selections
Dashboard layouts

8. Custom Mark Plugins

User-defined mark types
Custom renderers
Third-party chart integration

Long-Term Vision

9. Standalone Library

NPM package for any web application
React/Vue/Svelte components
Framework bindings

10. WebGPU Rendering

GPU-accelerated large datasets
Smooth animations at scale
Real-time interactions with millions of points

11. Collaborative Features

Shared chart configurations
Team templates
Version history

Quick Start

Installation

Open Obsidian Settings
Go to Community Plugins
Search for "DataGlass"
Install and enable

Your First Chart

Create a new note and add:

markdown

```dg
type: bar
title: My First Chart
data:
  source: '[
    {"month": "Jan", "sales": 100},
    {"month": "Feb", "sales": 150},
    {"month": "Mar", "sales": 120}
  ]'
x: month
y: sales
```

Loading External Data

From a CSV file in your vault:

yaml

type: line
data:
  file: data/monthly-metrics.csv
x: date
y: value
color: category

Adding Interactivity

yaml

type: scatter
engine: d3
data:
  file: data/products.csv
x: price
y: rating
color: category
interactions:
  tooltip:
    enabled: true
    template: "{name}: ${price}"
  hover:
    enabled: true

Transforming Data

yaml

type: bar
data:
  file: data/transactions.csv
transformations:
  - type: filter
    configuration:
      where: { amount: { gte: 100 } }
  - type: aggregate
    configuration:
      groupBy: ["category"]
      metrics:
        total: { field: "amount", op: "sum" }
  - type: sort
    configuration:
      fields: [{ field: "total", direction: "desc" }]
  - type: limit
    configuration: { count: 10 }
x: category
y: total

Use Cases

Personal Knowledge Management

Reading tracker: Books read per month, genre distribution
Habit tracking: Streak visualization, completion rates
Finance: Expense categories, budget vs actual

Engineering & DevOps

System metrics: CPU, memory, latency over time
Deployment frequency: Release cadence visualization
Error rates: Error distribution by service

Data Analysis

Exploratory analysis: Quick visualization of datasets
Statistical summaries: Distribution shapes, outliers
Correlation discovery: Scatter plots with regression

Research & Academia

Experiment results: Treatment vs control comparisons
Survey analysis: Response distributions
Literature review: Citation networks, topic clusters

Business Intelligence

Sales dashboards: Revenue trends, regional performance
Customer analytics: Segmentation, cohort analysis
Product metrics: Feature usage, conversion funnels

Technical Specifications

Performance Budgets

Operation	Excellent	Good	Acceptable
Chart render	<100ms	<500ms	<1000ms
Data load	<50ms	<200ms	<500ms
Transformation	<20ms	<100ms	<300ms
Validation	<10ms	<50ms	<100ms

Security Limits

Limit	Value
Config size	10KB
Inline JSON	5KB
Data points	10,000
Chart dimensions	2000x2000px
Concurrent renders	5
Renders per minute	20

Browser Support

Chrome 90+
Firefox 88+
Safari 14+
Edge 90+

Dependencies

D3.js v7
Observable Plot v0.6
Zod v3
hyparquet (Parquet support)

Conclusion

DataGlass brings the power of professional data visualization to Obsidian through declarative YAML configuration. Its dual-engine architecture provides both simplicity for quick charts and depth for advanced visualizations.

Key Takeaways:

40+ chart types from simple YAML
Rich data pipeline with 9 transform types
Interactive features including drill-down navigation
Production-ready with extensive testing and security
Framework-agnostic core enables broader adoption

Whether you're tracking personal habits or analyzing complex datasets, DataGlass transforms your notes into an interactive data exploration environment.

Resources

Chart Gallery - Visual examples of all chart types
Cheat Sheet - Quick reference for common patterns
Examples - Real-world use cases with full configurations
YAML Schema - Complete configuration reference
D3 Chart Reference - Specialized D3 chart documentation

DataGlass Product Guide ​

Executive Summary ​

Architecture Overview ​

Monorepo Structure ​

Rendering Pipeline ​

Dual Engine Design ​

Feature Inventory ​

Chart Types (40+) ​

Data Sources ​

Data Transformations (9 types) ​

Interactive Features ​

Styling & Theming ​

Strengths ​

1. Declarative Simplicity ​

2. Dual Engine Flexibility ​

3. Rich Data Pipeline ​

4. Framework-Agnostic Core ​

5. Production-Ready Quality ​

6. Intelligent Defaults ​

7. Deep Obsidian Integration ​

8. Extensive Chart Library ​

Limitations ​

1. Learning Curve ​

2. Engine Feature Disparity ​

3. Large Dataset Performance ​

4. Static Export Limitations ​

5. Real-Time Data ​

6. Collaboration ​

7. Mobile Experience ​

Potential Improvements ​

Near-Term Enhancements ​

Medium-Term Features ​

Long-Term Vision ​

Quick Start ​

Installation ​

Your First Chart ​

Loading External Data ​

Adding Interactivity ​

Transforming Data ​

Use Cases ​

Personal Knowledge Management ​

Engineering & DevOps ​

Data Analysis ​

Research & Academia ​

Business Intelligence ​

Technical Specifications ​

Performance Budgets ​

Security Limits ​

Browser Support ​

Dependencies ​

Conclusion ​

Resources ​

DataGlass Product Guide

Executive Summary

Architecture Overview

Monorepo Structure

Rendering Pipeline

Dual Engine Design

Feature Inventory

Chart Types (40+)

Data Sources

Data Transformations (9 types)

Interactive Features

Styling & Theming

Strengths

1. Declarative Simplicity

2. Dual Engine Flexibility

3. Rich Data Pipeline

4. Framework-Agnostic Core

5. Production-Ready Quality

6. Intelligent Defaults

7. Deep Obsidian Integration

8. Extensive Chart Library

Limitations

1. Learning Curve

2. Engine Feature Disparity

3. Large Dataset Performance

4. Static Export Limitations

5. Real-Time Data

6. Collaboration

7. Mobile Experience

Potential Improvements

Near-Term Enhancements

Medium-Term Features

Long-Term Vision

Quick Start

Installation

Your First Chart

Loading External Data

Adding Interactivity

Transforming Data

Use Cases

Personal Knowledge Management

Engineering & DevOps

Data Analysis

Research & Academia

Business Intelligence

Technical Specifications

Performance Budgets

Security Limits

Browser Support

Dependencies

Conclusion

Resources