Neo4j Document Import Skill

> **Status: Draft / WIP**

# neo4j-document-import-skill

Guides agents through importing unstructured documents into Neo4j as a knowledge graph: PDF/text chunking, LLM entity extraction (SimpleKGPipeline), LLM Graph Builder (no-code), apoc.load.json, and LangChain/LlamaIndex document loaders.

**Install:**
```bash
npx skills add https://github.com/neo4j-contrib/neo4j-skills --skill neo4j-document-import-skill
```

Or paste this link into your coding assistant:
https://github.com/neo4j-contrib/neo4j-skills/tree/main/neo4j-document-import-skill


# KG Construction — Extended Reference

Overflow from `SKILL.md` — load when detailed chunking strategy or entity resolution config needed.

---

## Chunking Strategy Comparison

| Strategy | How it splits | Best for | neo4j-graphrag class |
|---|---|---|---|
| Fixed-size | Token count with optional boundary respect | Dense technical docs; most use-cases | `FixedSizeSplitter(chunk_size, chunk_overlap)` |
| Sentence/paragraph | Natural language boundaries (`\n\n`, `.`) | Narrative text, news articles, course content | LangChain `CharacterTextSplitter(separator="\n\n")` |
| Semantic | Embedding similarity between adjacent sentences | Long-form documents with topic shifts | LangChain `SemanticChunker` (requires embedder) |
| N-gram | Overlapping windows of n words | Short snippets, keyword-dense text | Custom — not built into neo4j-graphrag |
| Structural | By section/heading/method (doc-specific) | API docs, legal contracts, structured PDFs | Custom — parse structure then chunk |

**Rule**: Start with `FixedSizeSplitter(chunk_size=512, chunk_overlap=50)`. Switch to paragraph-based when sentences must not break (courses, articles). Switch to semantic chunking only when topic coherence within chunks is critical and embedder calls during ingestion are affordable.

**Combination pattern** (course content model from GraphAcademy course):
```
Course → Module → Lesson → Paragraph
```
Split doc into structural units (Module/Lesson), then chunk each Lesson into Paragraphs (`\n\n`). Store both levels; query at Paragraph for vector search, traverse to Lesson for context. Pattern:
```python
from langchain_text_splitters import CharacterTextSplitter
splitter = CharacterTextSplitter(separator="\n\n", chunk_size=1500, chunk_overlap=200)
paragraphs = splitter.split_documents(lesson_docs)
```

LangChain `CharacterTextSplitter` behavior:
1. Split by `separator` (paragraph breaks)
2. Combine paragraphs up to `chunk_size` chars
3. If single paragraph > `chunk_size`: keep as-is (no mid-paragraph cut)
4. Add last paragraph of chunk N to start of chunk N+1 only if it's ≤ `chunk_overlap` chars

---

## Entity Resolver — Full Config

Resolvers merge duplicate entities after bulk ingest. All use APOC `refactor.mergeNodes` internally.

### Class Hierarchy

```
EntityResolver (base)
  ├── SinglePropertyExactMatchResolver  — exact name match
  ├── BasePropertySimilarityResolver (abstract)
  │     ├── FuzzyMatchResolver          — Levenshtein; pip install rapidfuzz
  │     └── SpaCySemanticMatchResolver  — cosine; pip install neo4j-graphrag[nlp]
  └── (custom subclass)
```

### SinglePropertyExactMatchResolver

```python
from neo4j_graphrag.experimental.components.resolver import SinglePropertyExactMatchResolver

resolver = SinglePropertyExactMatchResolver(
    driver=driver,
    filter_query="WHERE n:Organization OR n:Person",   # optional: narrow scope
    resolve_property="name",   # default: "name"
    neo4j_database="neo4j",    # optional
)
stats = asyncio.run(resolver.run())
# stats.number_of_nodes_to_resolve, stats.number_of_created_nodes
```

### FuzzyMatchResolver

```python
from neo4j_graphrag.experimental.components.resolver import FuzzyMatchResolver

resolver = FuzzyMatchResolver(
    driver=driver,
    resolve_properties=["name"],   # list of properties to concatenate + compare
    threshold=0.9,    # Levenshtein similarity 0–1; lower = more aggressive merging
    filter_query="WHERE n:Organization",
)
a