Obsidian
Query databases with natural language from Obsidian and embed results in your notes.
The Obsidian plugin connects your Obsidian vault to an Atlas instance. Ask natural-language questions about your data through a modal or embedded code blocks, and insert the results directly into your notes as Markdown tables.
Unlike server-side interaction plugins (Slack, MCP), the Obsidian plugin is a standalone Obsidian community plugin that communicates with Atlas over HTTP. It does not require atlas.config.ts registration — just point it at your Atlas URL.
Installation
Manual Install
- Download
main.js,manifest.json, andstyles.cssfrom the latest release. - Create a folder at
<your-vault>/.obsidian/plugins/atlas/. - Copy the three files into that folder.
- Open Settings → Community Plugins and enable Atlas.
Build from Source
cd plugins/obsidian
bun install
bun run buildCopy the built main.js, manifest.json, and styles.css into your vault's plugin directory.
Configuration
Open Settings → Atlas in Obsidian:
| Setting | Description |
|---|---|
| Atlas URL | Base URL of your Atlas instance (e.g. https://api.example.com). Trailing slashes are stripped automatically. |
| API key | API key for authentication. Leave empty if your Atlas instance has auth disabled. The key is stored as a password field. |
The plugin communicates with your Atlas API over HTTP. Make sure your Atlas instance is reachable from your machine — for local development that's usually http://localhost:3001.
Usage
Query Modal
Open the query modal in one of two ways:
- Click the database icon in the left ribbon bar.
- Run Atlas: Ask a question from the command palette (
Ctrl/Cmd+P).
Type a natural-language question and click Ask (or press Ctrl/Cmd+Enter). The agent's response streams in real time — text appears as it's generated, and data tables render below.
Once the response completes, click Insert into note to paste the question, answer, and any data tables as Markdown at your cursor position.
Embedded Code Blocks
Embed live queries directly in your notes using fenced code blocks with the atlas language tag:
```atlas
Revenue by region last quarter
```In reading mode, the block renders with a Run query button. Click it to execute — the agent's answer and data tables appear inline. Results are cached for the current session. Click Refresh to re-run the query.
Each code block query runs independently — there is no conversation context between blocks. For multi-turn exploration, use the query modal.
Data Table Display
Both the modal and code blocks display query results as HTML tables. Tables are capped at 100 rows with an overflow indicator. In the query modal, click Insert into note to paste the full dataset as a Markdown table. Code block results are display-only.
How It Works
The plugin uses a lightweight streaming client (src/client.ts) that connects to the Atlas /api/chat endpoint. It parses a subset of the Vercel AI SDK data stream protocol — text deltas, tool results, errors, and finish signals — and emits typed events:
| Event | Description |
|---|---|
text | Text chunk from the agent's response |
result | Tabular data (columns + rows) from an executeSQL tool call |
error | Error message from the server |
finish | Stream complete |
Results are converted to Markdown tables using a built-in resultToMarkdown() helper that escapes pipe characters and newlines.
Troubleshooting
"Configure Atlas in Settings → Atlas"
The Atlas URL is not set. Open Settings → Atlas and enter your Atlas instance URL.
Connection failed
Verify your Atlas instance is running and reachable. For local development, ensure bun run dev is running and the URL is http://localhost:3001.
Authentication errors
If your Atlas instance requires authentication, make sure the API key in settings matches a valid key. Check the Atlas admin console for key management.