# Data Builder
> Build data-driven DenchClaw apps with full CRUD access to workspace objects (.object.yaml tables), DuckDB queries and mutations, data dashboards with Chart.js and D3.js, and interactive tools.
- Skill: `aspectrr/data-builder` (Agent Skill)
- Install (CLI): `npx skillmds@latest add aspectrr/data-builder`
- Raw SKILL.md: https://api.skillmd.com/api/skills/aspectrr/data-builder/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: aspectrr (https://skillmd.com/u/aspectrr)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/aspectrr/data-builder
---
# App Data Builder
This skill covers building data apps that interact with workspace objects and DuckDB. For core app structure and manifest basics, see the parent **app-builder** skill (`app-builder/SKILL.md`).
---
## Objects CRUD API (`objects` permission required)
The `window.dench.objects.*` API provides full CRUD access to workspace objects (`.object.yaml` tables). Add `objects` to your manifest permissions:
```yaml
permissions:
- objects
```
### List Entries
```javascript
const result = await dench.objects.list("people", {
search: "john",
filters: JSON.stringify([{ field: "Status", operator: "eq", value: "Active" }]),
sort: JSON.stringify({ field: "Full Name", direction: "asc" }),
page: 1,
pageSize: 50
});
// Returns { object, fields, entries, totalCount, statuses }
```
Filter operators: `eq`, `neq`, `contains`, `not_contains`, `starts_with`, `ends_with`, `gt`, `gte`, `lt`, `lte`, `is_empty`, `is_not_empty`.
### Get a Single Entry
```javascript
const entry = await dench.objects.get("people", "entry_id_here");
// Returns { entry: { id, fields: { "Full Name": "...", ... }, created_at, updated_at } }
```
### Create an Entry
```javascript
const { entryId } = await dench.objects.create("people", {
"Full Name": "Jane Doe",
"Email Address": "jane@example.com",
"Status": "Active"
});
```
### Update an Entry
```javascript
await dench.objects.update("people", entryId, {
"Status": "Lead"
});
```
### Delete an Entry
```javascript
await dench.objects.delete("people", entryId);
```
### Bulk Delete Entries
```javascript
await dench.objects.bulkDelete("people", [id1, id2, id3]);
```
### Get Object Schema
```javascript
const schema = await dench.objects.getSchema("people");
// Returns { object, fields, statuses }
```
### Get Relation Options
```javascript
const options = await dench.objects.getOptions("people", "jane");
// Returns filtered list of entries matching query
```
Use this for building relation dropdowns and autocomplete fields that reference entries in other objects.
---
## Database Access (`database` / `database:write` permissions)
The `database` permission grants read-only query access. The `database:write` permission grants full mutation access (INSERT, UPDATE, DELETE, CREATE TABLE, etc.).
```yaml
permissions:
- database # SELECT queries only
- database:write # SELECT + mutations
```
### Read Queries (`database` permission)
```javascript
const result = await dench.db.query("SELECT * FROM objects");
// Returns { rows: [...] }
```
### Mutations (`database:write` permission)
```javascript
await dench.db.execute("INSERT INTO game_scores (game, score) VALUES ('my-game', 1500)");
await dench.db.execute("CREATE TABLE IF NOT EXISTS app_data (key TEXT PRIMARY KEY, value TEXT)");
await dench.db.execute("UPDATE app_data SET value = 'new' WHERE key = 'setting1'");
await dench.db.execute("DELETE FROM app_data WHERE key = 'old'");
```
### DuckDB Workspace Schema
The workspace database uses an Entity-Attribute-Value (EAV) schema:
| Table | Columns | Description |
|-------|---------|-------------|
| `objects` | id, name, description, icon | Workspace object definitions |
| `fields` | id, object_id, name, type, required, position | Field definitions for each object |
| `entries` | id, object_id, created_at, updated_at | Row entries in each object |
| `entry_fields` | id, entry_id, field_id, value | Individual cell values (EAV) |
| `statuses` | id, object_id, name, color, position | Status options for status-type fields |
**PIVOT views** provide columnar access to object data:
```sql
SELECT * FROM v_people
-- Returns rows with columns like: id, "Full Name", "Email Address", "Status", ...
```
The view name is `v_{object_name}` where the object name is lowercased with spaces replaced by underscores.
### Common Queries
```javascript
// List all objects
const objects = await dench.db.query("SELECT * FROM objects");
// Get entries via PIVOT view
const people = await dench.db.query("SELECT * FROM v_people");
// Aggregate stats
const stats = await dench.db.query(`
SELECT o.name, COUNT(e.id) as count
FROM objects o LEFT JOIN entries e ON e.object_id = o.id
GROUP BY o.name ORDER BY count DESC
`);
// Get field definitions
const fields = await dench.db.query(
"SELECT * FROM fields WHERE object_id = (SELECT id FROM objects WHERE name = 'people')"
);
```
### Creating App-Specific Tables
Apps can create their own tables for storing app-specific data. Always use `CREATE TABLE IF NOT EXISTS` for idempotency:
```javascript
await dench.db.execute(`
CREATE TABLE IF NOT EXISTS app_settings (
key TEXT PRIMARY KEY, value TEXT,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
)
`);
```
---
## Data Dashboards & Visualization
### Chart.js Dashboard
```html
Chart Dashboard
Object Entries
```
### D3.js Visualization
```html
D3 Visualization
Workspace Overview
```
### CSS-Only Stat Cards
No charting library needed — use CSS grid and custom properties for simple metric displays:
```html
Total Records
—
+12% this week
```
```css
.stats-grid {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
gap: 16px;
padding: 24px;
}
.stat-card {
padding: 20px;
border-radius: 12px;
background: var(--app-surface);
border: 1px solid var(--app-border);
}
.stat-label {
font-size: 13px;
color: var(--app-text-muted);
margin-bottom: 8px;
}
.stat-value {
font-size: 36px;
font-weight: 700;
font-variant-numeric: tabular-nums;
}
.stat-change {
font-size: 12px;
margin-top: 4px;
}
.stat-change.positive { color: var(--app-success); }
.stat-change.negative { color: var(--app-error); }
```
---
## Interactive Tools & Utilities
### Form-Based Tools
Template for tools that collect input, process it, and display output:
```html
```
```css
.tool-container {
max-width: 720px;
margin: 0 auto;
padding: 24px;
}
.field { margin-bottom: 16px; }
.field label {
display: block;
font-size: 13px;
font-weight: 500;
color: var(--app-text-muted);
margin-bottom: 6px;
}
.field textarea, .field input, .field select {
width: 100%;
padding: 10px 12px;
border-radius: 8px;
border: 1px solid var(--app-border);
background: var(--app-surface);
color: var(--app-text);
font-size: 14px;
font-family: inherit;
resize: vertical;
}
.field textarea:focus, .field input:focus {
outline: none;
border-color: var(--app-accent);
box-shadow: 0 0 0 3px color-mix(in srgb, var(--app-accent) 20%, transparent);
}
button[type="submit"] {
padding: 10px 20px;
border: none;
border-radius: 8px;
background: var(--app-accent);
color: white;
font-size: 14px;
font-weight: 500;
cursor: pointer;
transition: background 0.15s;
}
button[type="submit"]:hover { background: var(--app-accent-hover); }
.output-box {
margin-top: 16px;
padding: 16px;
border-radius: 8px;
background: var(--app-surface);
border: 1px solid var(--app-border);
font-family: 'SF Mono', 'Fira Code', monospace;
font-size: 13px;
white-space: pre-wrap;
max-height: 400px;
overflow: auto;
}
```
### Kanban / Drag-and-Drop
Use SortableJS for draggable interfaces backed by workspace objects:
```html
```
```javascript
async function initKanban() {
const schema = await dench.objects.getSchema("tasks");
const statuses = schema.statuses || [];
const board = document.getElementById('board');
for (const status of statuses) {
const column = document.createElement('div');
column.className = 'kanban-column';
column.dataset.status = status.name;
column.innerHTML = `
${status.name}
`;
board.appendChild(column);
}
const result = await dench.objects.list("tasks", { pageSize: 200 });
for (const entry of result.entries) {
const status = entry.fields["Status"] || statuses[0]?.name;
const body = board.querySelector(`.column-body[data-status="${status}"]`);
if (body) {
const card = document.createElement('div');
card.className = 'kanban-card';
card.dataset.id = entry.id;
card.textContent = entry.fields["Title"] || entry.id;
body.appendChild(card);
}
}
document.querySelectorAll('.column-body').forEach(col => {
Sortable.create(col, {
group: 'tasks',
animation: 150,
ghostClass: 'drag-ghost',
onEnd: async (evt) => {
const entryId = evt.item.dataset.id;
const newStatus = evt.to.dataset.status;
try {
await dench.objects.update("tasks", entryId, { "Status": newStatus });
} catch (err) {
console.error('Failed to update status:', err);
}
},
});
});
}
```
---
## Patterns
### CRUD Form App Pattern
A complete pattern for a form that creates, reads, updates, and deletes entries in a workspace object:
```javascript
let currentEntries = [];
let editingId = null;
async function loadEntries() {
const result = await dench.objects.list("tasks", { pageSize: 100 });
currentEntries = result.entries;
renderTable(result.entries);
}
function renderTable(entries) {
const tbody = document.getElementById('entries-body');
tbody.innerHTML = entries.map(e => `
| ${e.fields["Title"] || ''} |
${e.fields["Status"] || ''} |
${new Date(e.created_at).toLocaleDateString()} |
|
`).join('');
}
async function createEntry(formData) {
try {
const { entryId } = await dench.objects.create("tasks", formData);
await loadEntries();
dench.ui.toast("Entry created", { type: "success" });
resetForm();
} catch (err) {
dench.ui.toast("Failed: " + err.message, { type: "error" });
}
}
async function updateEntry(id, formData) {
try {
await dench.objects.update("tasks", id, formData);
await loadEntries();
dench.ui.toast("Entry updated", { type: "success" });
resetForm();
} catch (err) {
dench.ui.toast("Failed: " + err.message, { type: "error" });
}
}
async function deleteEntry(id) {
if (!confirm('Delete this entry?')) return;
try {
await dench.objects.delete("tasks", id);
await loadEntries();
dench.ui.toast("Entry deleted", { type: "success" });
} catch (err) {
dench.ui.toast("Failed: " + err.message, { type: "error" });
}
}
function editEntry(id) {
const entry = currentEntries.find(e => e.id === id);
if (!entry) return;
editingId = id;
document.getElementById('title').value = entry.fields["Title"] || '';
document.getElementById('status').value = entry.fields["Status"] || '';
document.getElementById('submit-btn').textContent = 'Update';
}
function resetForm() {
editingId = null;
document.getElementById('task-form').reset();
document.getElementById('submit-btn').textContent = 'Create';
}
document.getElementById('task-form').addEventListener('submit', async (e) => {
e.preventDefault();
const formData = {
"Title": document.getElementById('title').value,
"Status": document.getElementById('status').value,
};
if (editingId) {
await updateEntry(editingId, formData);
} else {
await createEntry(formData);
}
});
loadEntries();
```
### Dashboard with Live Refresh
Pattern for an auto-refreshing dashboard that polls for updated data:
```javascript
const REFRESH_INTERVAL = 30000; // 30 seconds
let refreshTimer = null;
async function loadDashboard() {
try {
const stats = await dench.db.query(`
SELECT o.name, COUNT(e.id) as count
FROM objects o LEFT JOIN entries e ON e.object_id = o.id
GROUP BY o.name ORDER BY count DESC
`);
renderStats(stats.rows);
document.getElementById('last-updated').textContent =
'Updated: ' + new Date().toLocaleTimeString();
} catch (err) {
console.error('Refresh failed:', err);
}
}
function startAutoRefresh() {
loadDashboard();
refreshTimer = setInterval(loadDashboard, REFRESH_INTERVAL);
}
function stopAutoRefresh() {
if (refreshTimer) {
clearInterval(refreshTimer);
refreshTimer = null;
}
}
document.addEventListener('visibilitychange', () => {
if (document.hidden) {
stopAutoRefresh();
} else {
startAutoRefresh();
}
});
startAutoRefresh();
```
---
## Full Example: Data Dashboard
A complete workspace dashboard app with stat cards, theme support, and live data from DuckDB.
**`.dench.yaml`:**
```yaml
name: "Dashboard"
description: "Workspace overview dashboard"
icon: "layout-dashboard"
version: "1.0.0"
entry: "index.html"
runtime: "static"
permissions:
- database
```
**`index.html`:**
```html
Workspace Dashboard
Loading workspace data...
```