Obsidian SQLSeal

SQLSeal allows you to treat your Obsidian vault as a queryable database. You can use standard SQL syntax to select, join, and filter data from your notes, files, and tags. The engine uses SQLite under the hood, providing full SQL capabilities.

SELECT * FROM files
ORDER BY modified_at DESC
LIMIT 10

SQLSeal provides built-in tables to query your Obsidian vault content. You can use these tables to retrieve information about files, tags, tasks, and links based on their properties (frontmatter) and associations.

Available tables:

• files: Information about files in the vault.
• tags: Information about tags associated with files.
• tasks: Information about tasks.
• links: Information about links within the vault.

In SQLSeal, tags exist in two distinct contexts with different structures:

1. Frontmatter Tags: These are defined in the YAML metadata at the top of your Obsidian files (e.g., tags: [project, todo]). In SQLSeal, these are treated as a plain list of values associated with a file and are accessed via the files table.
2. The tags Table: This is a specialized table that provides a row-based view of every tag in your vault. Each row represents a single tag instance, linking a specific tag value to a specific file path. This is useful for a granular, relational view of tag usage across the entire vault.

You can control how SQLSeal handles updates to underlying data sources using the REFRESH or NO REFRESH statements.

• REFRESH: The query automatically re-executes whenever the underlying data changes. SQLSeal only listens to changes in the specific tables used within the query.
• NO REFRESH: The query executes exactly once and stops listening for changes. Use this for expensive queries where you want manual control over when data is re-processed.

TABLE data = file(data.csv)

NO REFRESH

SELECT * FROM data

SQLSeal allows you to use properties to make queries dynamic and reusable across different files or templates. To reference a property within a query, prepend the property name with the @ symbol (e.g., @year refers to the year property).

SELECT * FROM files WHERE path = @path

You can use the ecStat:clustering transform within a dataset to cluster data into separate buckets. This is useful for identifying underlying complexity or patterns in your data.

To implement clustering, you add a second dataset object to your configuration that uses the transform property. This transform takes the source data and calculates cluster assignments, which can then be used to drive visual properties like color via a visualMap or series encoding.

// Example of a clustering transform configuration
{
  transform: {
    type: 'ecStat:clustering',
    print: true,
    config: {
      clusterCount: 6,
      outputType: 'single',
      outputClusterIndexDimension: 2
    }
  }
}

When using JSONL files where different lines contain different keys (sparse schemas), SQLSeal automatically constructs a table schema using the union of all keys found across all lines.

If a specific row is missing a key that exists elsewhere in the file, that field will be returned as NULL for that row.

-- If events.jsonl contains lines with varying keys like 'amount'
TABLE events = file(events.jsonl)

SELECT event, user, amount FROM events WHERE amount IS NOT NULL

When using SQLSeal in your notes:

• You can define multiple tables within a single sqlseal codeblock.
• You can reference tables defined in different snippets, provided they are within the same note.
• Note: Currently, tables are local to the file they are defined in.

SQLSeal Charts is an expansion for the plugin that provides full visualization tools for your query results.

Note: As of the current documentation, SQLSeal Charts is undergoing review by Obsidian. Full documentation will be released once approved.

SQLSeal is not intended as a direct replacement for Dataview, but rather as a complementary tool. While Dataview uses its own Dataview Query Language (DQL) and supports JavaScript, SQLSeal uses standard SQL (with full SQLite compatibility).

Key advantages of SQLSeal over Dataview include:

• SQL Compatibility: Uses standard SQL instead of DQL.
• CSV Support: Ability to both query and edit data from CSV files.
• Relational Power: Supports joining tables, which Dataview does not.
• Inline Queries: Supports inline queries using the S> prefix (whereas Dataview uses =).

Both plugins support querying vault data (files, tags, tasks), filtering, and mobile support.