nodetool-rag-indexing

You help users build Retrieval-Augmented Generation (RAG) pipelines in NodeTool.

RAG Architecture

INDEXING:  Documents → Load → Split → Embed → Store (vector collection)
QUERY:     Question → Embed → Search → Format → LLM → Answer

Vector Store Backends

NodeTool's vector store (@nodetool-ai/vectorstore) is backend-pluggable. The workflow nodes are the same regardless of backend — you pick the backend via configuration.

There are no FAISS nodes; the backends above cover local and hosted use.

Vector Nodes (vector.*)

All RAG nodes live under the single vector.* namespace (not vector.chroma.* or vector.faiss.*).

Query nodes (QueryText, QueryImage, HybridSearch) output ids, documents, metadatas, and distances (HybridSearch also returns scores).

Document Loading & Splitting (nodetool.document.*, lib.os.*)

Chunk Size Guidance

Indexing — Workflow Pattern

ListFiles → LoadDocumentFile → SplitRecursively → IndexTextChunk(collection)

Pair every index/query node with a vector.Collection node (or a collection name) so they target the same store. Use the same embedding model for indexing and querying.

Indexing — HTTP API

# Index a file into a collection
curl -X POST http://localhost:7777/api/collections/<name>/index \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"file_path": "/path/to/document.pdf"}'

The server resolves the collection, runs its ingestion workflow if one is registered, otherwise falls back to split → embed → store.

Query — Workflow Pattern

ChatInput → HybridSearch(collection, top_k) → FormatText → Agent → Output

Complete RAG Example

Index

ListFiles("/docs/") → LoadDocumentFile → SplitRecursively(chunk_size=400, overlap=50)
                                                  ↓
                                  IndexTextChunk(collection="my-docs")

Query

ChatInput("What is...?") → HybridSearch(collection="my-docs", top_k=5)
                                  ↓
                         FormatText(template="Context:\n{documents}\n\nQuestion: {query}")
                                  ↓
                         Agent(model=gpt-5.4, system="Answer using only the context provided.")
                                  ↓
                         Output

Environment Variables

# ChromaDB backend (only when using Chroma — SQLite-vec needs no config)
CHROMA_URL=                          # Remote Chroma URL (empty = local)
CHROMA_PATH=~/.local/share/nodetool/chroma  # Local storage path
CHROMA_TOKEN=                        # Optional auth token

The embedding model is chosen on the index/query nodes via model selection (e.g. text-embedding-3-small, or a local sentence-transformers model).

Common Pitfalls

• Embedding model mismatch: use the same embedding model for indexing and search.
• Chunks too large: dilute the LLM context — keep to 200-500 tokens.
• Chunks too small: sentences get fragmented; use 10-20% overlap.
• Empty collection: index before querying — an unindexed collection returns nothing.
• Wrong node names: it's vector.IndexTextChunk / vector.QueryText / vector.HybridSearch, not IndexTextChunks / TextSearch, and there is no vector.chroma.*/vector.faiss.* namespace.
• No nodetool collections CLI: manage collections through the editor UI or the /api/collections/... endpoints.