nanograph operations
Operational guide for managing nanograph 1.2.x embedded graph databases — schema design, mutations, queries, CDC, embeddings, media, and maintenance. Teaches the defaults that prevent the usual agent mistakes: stale-schema writes, fragile raw CLI invocations, and obsolete manifest or WAL assumptions.
- Schema-first workflow with
.pgschemas and.gqqueries - Targeted mutations instead of export-edit-reload loops
lintfor query validation,migratefor schema changes,changesfor CDC- Gemini multimodal embeddings for text, images, audio, video, and PDFs
NamespaceLineagestorage, lineage-native CDC, andstorage migratefor legacy databases
Before doing anything
Run from the directory where nanograph.toml lives. nanograph resolves config from the current working directory and does not walk parent directories.
Inspect the database before operating on it:
nanograph describe --format json
nanograph doctordescribe --format json gives you type names, properties, key properties, edge summaries, row counts, and @description / @instruction annotations. Do not guess the schema from JSONL or query output.
Where to find guidance
Pick the reference that matches the task. Each file is focused so only the relevant context loads.
| Task | Reference |
|---|---|
Setting up a project (nanograph.toml, git, .env.nano, agent output conventions) | references/project-setup.md |
Changing data (mutations, @key, aliases, JSONL format) | references/data-changes.md |
Authoring or evolving schema (describe, doctor, annotations, lint, migrate) | references/schema.md |
| Embeddings and search (providers, traversal, backfill) | references/embeddings.md |
| Day-to-day ops (post-change checklist, CDC, compact, storage generation, common mistakes) | references/operations.md |
| Media, blobs, and multimodal Gemini embeddings | references/blobs.md |
For storage migration from legacy manifest/WAL databases to NamespaceLineage, use the nanograph-lance skill.
Full nanograph documentation: https://nanograph.io/docs.
Non-negotiable rules
These are the mistakes agents make most often. The references explain the *why*; here is the short list.
- Use mutation queries, not export-edit-reload. Reingestion destroys CDC continuity and Lance history. See data-changes.md.
- Put
@keyon every node type. Without it,update, edge wiring, andload --mode mergeall break. - Parameterize mutations. Never hardcode slugs, dates, or one-off values.
- Edge names in queries use camelCase.
HasMentorbecomeshasMentor. JSONL keeps PascalCase. - Use
--format jsonor--format jsonl. Never parsetableoutput. - Prefer aliases over raw
--query/--name/--param. Define them innanograph.tomlwith an explicitformat. - Never commit
.env.nano. It holds API keys.
Post-change workflow
After editing .pg or .gq files, follow this sequence every time:
- Edit
.pgand/or.gq. nanograph lint --query queries.gq- If the schema changed:
nanograph migrate(preview with--dry-run). - If
@embed(...)fields changed:nanograph embed --only-null. - Smoke test with
nanograph run <alias>.
Do not skip or reorder these steps — stale-schema writes, missing embeddings, and broken runtime behavior all come from shortcuts here.
Storage generation
nanograph 1.2.x uses NamespaceLineage for new graphs. Committed graph state, CDC windows, and managed blob storage live on Lance-native rails instead of the old graph.manifest.json + _wal.jsonl layout.
If a database is still on legacy storage, do not patch the old files manually. Run:
nanograph storage migrate --db <db>.nano --target lineage-nativeFor the full migration flow (verification, rollback, checklist), use the nanograph-lance skill.