[LLM] Neo4jGraph와 Cypher 쿼리

1. Neo4jGraph

 : Neo4j Python 드라이버를 감싼 래퍼(Wrapper) 클래스

• 역할

 - Cypher 쿼리 실행 : 읽기/쓰기 쿼리 실행, 결과를 list[dict]로 반환

 - 그래프 스키마 자동 조회 : 노드 레이블·관계 타입·속성 정보 자동으로 읽어 schema 속성에 저장

 - GraphRAG 파이프라인 연계 : GraphCypherQAChain, LLMGraphTransformer 등과 결합해 자연어 기반 그래프 질의응답 구성

 

• 객체 생성 파라미터  - 환경변수(.env)에 연결 정보 저장해두면 파라미터 없이 바로 생성 가능

파라미터	타입	기본값	설명
url	str | None	None	Neo4j 서버 URL(환경변수 NEO4J_URI 대체 가능)
username	str | None	None	인증 사용자명(NEO4J_USERNAME)
password	str | None	None	인증 패스워드(NEO4J_PASSWORD)
database	str | None	"neo4j"	접속할 DB 이름
refresh_schema	bool	True	생성 시 자동 스키마 조회 여부
enhanced_schema	bool	Fasle	True면 속성 실제 예시값까지 스키마에 포함

 

• 주요 메소드

메소드	기능
query(query, params={})	Cypher 실행 → List[Dict] 반환 params로 파라미터화 쿼리(SQL Injection 방지) 지원
refresh_schema()	DB로부터 스키마 정보 재조회·갱신
add_graph_documents(graph_documents)	GraphDocument(Node/Relationship 리스트)를 DB에 저장
close()	드라이버 연결 종료(with문 사용 시 자동 호출)

GraphDocument 구조

 - GraphDocument = list[Node] + list[Relationship]

 → Node : id(식별자), type(라벨), properties(속성 dict)

 → Relationship : source(시작 Node), target(끝 Node), type(관계 타입), properties(속성 dict)

 

• 주요 속성

속성	타입	설명
schema	str	LLM 프롬프트에 바로 넣을 수 있는 문자열 형태 스키마
structured_schema	dict	node_props, rel_props, relationships 키 포함한 구조화된 스키마

 

2. Cypher 기본 표기법

요소	표기
노드	( ), 라벨은 : 시작 - ex. (p: Person)
관계	[ ], 방향 필수(->, <-) - ex. -[r: KNOWS]->
속성	{ }, ex. (m {name: "Neo4j"})
주석	// (한 줄), /* */ (여러 줄)

- 방향 없는 관계 : CREATE에서 사용 불가. 노드·관계에 변수 할당해야 이후 참조 가능

 

3. CREATE - 노드/관계 생성

 -❗️ 동일 노드라도 중복 생성됨(중복 방지 : contraint or MERGE 사용)

// 노드 생성
CREATE (변수: 라벨 {속성키: 속성값, ...})

// 기존 노드 사이에 관계 생성
MATCH (a), (b) WHERE 조건
CREATE (a) -[:관계타입 {속성}]-> (b)

// 노드+관계 동시 생성
CREATE (a: Label1 {...}) -[:REL_TYPE]-> (b: Label2 {...})

 

4. MATCH / RETURN - 조회

 - 읽기 전용 절(≒ SQL의 SELECT). RETURN과 함께 사용해야 결과 노출

MATCH 패턴
[WHERE 조건]
RETURN ...
[ORDER BY 컬럼 ASC | DESC]

 • labels(n) : 노드의 라벨 조회

 • type(r) : 관계의 타입 조회

 • collect(x) : 여러 결과를 리스트로 묶음

 • RETURN DISTINCT : 중복 제거

 

4-1. ORDER BY / SKIP / LIMIT

RETURN ...
ORDER BY 컬럼1 [ASC | DESC], 컬럼2 [ASC | DESC]
SKIP N  // 앞 N개 건너뛰기(페이징)
LIMIT M  // 최대 M개만 반환

 

4-2. OPTIONAL MATCH

 : 매칭되지 않아도 행을 유지. 미매칭 변수는 null(≒ SQL의 LEFT OUTER JOIN)

 

5. MERGE - 조회 or 생성

 : "있으면 찾고, 없으면 만든다". 명시한 모든 속성이 매칭 키로 사용

- 매칭 키 외 속성은 ON CREATE SET으로 추가하는 것이 안전

MERGE (n: Label {key: value})

MATCH (a), (b) WHERE ...
MERGE (a) -[:REL]-> (b)

MERGE (n: Label {id: 1})
ON CREATE SET n.createAt = timestamp(), n.count = 1
ON MATCH SET n.updataAt = timestamp(), n.count = n.count + 1

 

6. SET - 속성/라벨 수정

 : 이미 조회된 데이터 변경

SET n.속성 = 값  // 단일 속성 변경/추가
SET n.속성1 = v1, n.속성2 = v2
SET n += {key: value, ...}  // 여러 속성 병합
SET n = {key: value, ...}  // 전체 교체(기존 속성 삭제)
SET n: NewLabel  // 라벨 추가

 

7. DELETE / DETACH DELETE - 삭제

 • DELETE : 관계 연결된 노드는 삭제 불가

 • DETACH DELETE : 노드와 연결된 모든 관계 함께 삭제

MATCH (a) -[r:REL]-> (b) DELETE r;  // 관계만 삭제
MATCH (n: Label) DELETE n;  // 노드만 삭제(관계 없을 때)
MATCH (n: Label) DETACH DELETE n;  // 노드+관계 삭제
MATCH (n) DETACH DELETE n;  // 전체 그래프 초기화

 

8. REMOVE - 속성/라벨 제거

MATCH (n) REMOVE n.속성명;  // 속성 삭제
MATCH (n) REMOVE n:라벨명;  // 라벨 삭제