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 .pg schemas and .gq queries
• Targeted mutations instead of export-edit-reload loops
• lint for query validation, migrate for schema changes, changes for CDC
• Gemini multimodal embeddings for text, images, audio, video, and PDFs
• NamespaceLineage storage, lineage-native CDC, and storage migrate for 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 doctor

describe --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 @key on every node type. Without it, update, edge wiring, and load --mode merge all break.
• Parameterize mutations. Never hardcode slugs, dates, or one-off values.
• Edge names in queries use camelCase. HasMentor becomes hasMentor. JSONL keeps PascalCase.
• Use --format json or --format jsonl. Never parse table output.
• Prefer aliases over raw --query/--name/--param. Define them in nanograph.toml with an explicit format.
• Never commit .env.nano. It holds API keys.

Post-change workflow

After editing .pg or .gq files, follow this sequence every time:

1. Edit .pg and/or .gq.
2. nanograph lint --query queries.gq
3. If the schema changed: nanograph migrate (preview with --dry-run).
4. If @embed(...) fields changed: nanograph embed --only-null.
5. 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-native

For the full migration flow (verification, rollback, checklist), use the nanograph-lance skill.