Python과 Neo4j 환경 구축

1. 핵심 구성 요소 개관

Neo4j 기반 그래프 분석 환경은 네 가지 축으로 구성된다. 데이터베이스 엔진, 플러그인 라이브러리, 클라이언트 인터페이스, 언어 바인딩이 그것이다.

각 구성 요소는 독립적으로 교체 가능하다. 실행 환경(Desktop vs Aura), 플러그인의 활성화 여부, 접근 인터페이스(Browser vs Python)는 분석 목적에 따라 조합된다.

2. Cypher Query Language

Neo4j의 질의 언어는 Cypher이다. SQL이 테이블 기반 관계 대수를 표현하기 위해 설계된 것처럼, Cypher는 그래프 패턴 매칭을 표현하기 위해 설계되었다. 핵심 문법은 ASCII art 형태의 패턴 표현으로, 노드는 (), relationship은 -[]->로 표기한다.

// 노드 생성
CREATE (alice:Person {name: 'Alice', age: 30})

// 관계 패턴 매칭
MATCH (p:Person)-[:ACTED_IN]->(m:Movie)
WHERE m.released > 2000
RETURN p.name, m.title

// 다단계 traversal
MATCH (p:Person)-[:FRIEND]->(:Person)-[:FRIEND]->(fof:Person)
WHERE p.name = 'Alice'
RETURN DISTINCT fof.name

세 번째 예시는 그래프 DB의 강점을 단적으로 드러낸다. "친구의 친구"를 찾는 질의가 RDB에서는 self-join 두 번을 요구하지만, Cypher에서는 패턴 자체로 자연스럽게 표현된다. 이 표현력 차이가 multi-hop traversal이 빈번한 도메인에서 그래프 DB를 선택하게 만드는 핵심 근거이다.

3. GDS와 APOC: 두 가지 핵심 플러그인

기본 Neo4j 엔진은 그래프 저장과 Cypher 질의 실행을 담당한다. 그 위에서 데이터 분석과 운영 편의를 제공하는 두 라이브러리가 있다.

GDS는 분석가·데이터 과학자의 도구이고, APOC는 데이터 엔지니어의 도구라는 단순화된 구분이 가능하다. 다만 실무에서는 두 라이브러리를 함께 활성화하는 것이 일반적이다. 외부 데이터 소스로부터 그래프를 적재할 때 APOC가, 적재된 그래프 위에서 분석을 수행할 때 GDS가 동원되기 때문이다.

GraphRAG 맥락에서는 GDS의 임베딩 알고리즘(node2vec, FastRP)이 특히 중요하다. 그래프 구조를 벡터 공간으로 사용하여 vector similarity search와 결합하는 기반을 제공한다.

4. 실행 환경 선택: Desktop vs Aura

Neo4j는 두 가지 주된 실행 환경을 제공한다. 선택 기준은 학습 목적, 데이터 민감도, 운영 부담 수용 의지에 따라 갈린다.

학습 단계에서는 Desktop이 자유도가 높다. Cypher 콘솔에서 :play movies를 실행하면 People과 Movie를 node로, ACTED_IN·PRODUCED·DIRECTED를 relationship으로 가지는 예제 그래프가 생성되어 즉시 시각적 탐색이 가능하다. 반면 Aura는 환경 구성 부담 없이 바로 시작하려는 경우, 또는 노트북 자원이 제한된 경우 적합하다.

5. Python-Neo4j 연결과 Bolt Protocol

Python에서 Neo4j에 접근할 때는 graphdatascience 라이브러리를 통한 API 연결이 표준이다.

from graphdatascience import GraphDataScience

# Desktop 로컬 연결
URI = "bolt://localhost:7687"
AUTH = ("neo4j", "your_password")

gds = GraphDataScience(URI, auth=AUTH)

# 연결 확인 및 Cypher 실행
result = gds.run_cypher("""
    MATCH (p:Person)-[:ACTED_IN]->(m:Movie)
    RETURN p.name AS actor, count(m) AS movie_count
    ORDER BY movie_count DESC
    LIMIT 5
""")
print(result)

URI에 사용된 Bolt protocol은 Neo4j 전용 binary protocol이다. HTTP/HTTPS 대비 두 가지 차별점이 있다. 첫째, 그래프 데이터 전송에 최적화된 binary 직렬화로 전송 효율이 높다. 둘째, TLS 암호화를 기본 지원하여 별도 설정 없이 보안 통신이 성립한다. Aura 환경에서는 neo4j+s:// 스키마가 사용되며 +s는 암호화 활성화를 의미한다.

연결이 성립하면 Python 측에서는 Neo4j를 사실상 원격 그래프 분석 엔진으로 활용할 수 있다. node·relationship의 CRUD, Cypher 질의 실행, GDS 알고리즘 호출이 모두 가능하다.

6. 한계와 트레이드오프

본 챕터의 환경 구성 자체에서 도출되는 한계는 다음과 같다.

Desktop 환경의 확장성 제약. 로컬 머신 자원에 직접적으로 종속된다. 수백만 노드 규모를 넘어서면 메모리·디스크 I/O 병목이 발생하며, 학습 목적을 넘어선 분석에는 부적합하다. 본 챕터에서도 on-premise·cloud 클러스터 구성은 책의 범위 밖으로 명시되어 있다.

Aura 무료 티어의 운영 한계. 관리형 환경의 편의성은 데이터 크기·연결 수·플러그인 가용성에 대한 제약과 교환된다. 특히 GDS의 일부 고급 알고리즘은 유료 티어에서만 활성화되는 경우가 있어, 분석 깊이를 추구하는 단계에서는 검토가 필요하다.

플러그인 의존성. GDS와 APOC는 사실상 필수에 가깝지만, Neo4j 코어와 분리된 라이브러리이다. Neo4j 버전 업그레이드 시 플러그인 호환성을 별도로 확인해야 하며, 클라우드와 로컬에서 사용 가능한 함수 집합이 미묘하게 다를 수 있다.

Bolt protocol의 락인. Bolt는 Neo4j 생태계에 특화된 protocol이다. 표준 SQL/HTTP 기반 도구체인과의 통합이 직접적이지 않으며, BI 도구나 오케스트레이션 시스템과 연결할 때 별도의 어댑터·드라이버가 요구된다.

7. 실무 적용 시 고려사항

환경 구성 단계에서 결정되는 사항이 이후 분석 흐름 전체에 영향을 미친다.

첫째, 학습과 운영 환경을 일찍부터 분리한다. Desktop에서 작성한 Cypher와 Python 스크립트가 Aura에서도 동작하는지를 초기에 검증해두면, 이후 운영 환경으로의 이행이 매끄럽다. URI 문자열만 환경 변수로 분리하는 것이 일반적인 패턴이다.

둘째, GDS·APOC를 처음부터 함께 활성화한다. 학습 단계에서는 코어 Cypher만으로 충분해 보이지만, GraphRAG로 진입하는 순간 임베딩 생성·외부 데이터 통합·배치 처리가 필요해진다. 사후에 플러그인을 추가하면 기존 데이터 구조를 재검토해야 하는 경우가 발생한다.

셋째, 자격 증명 관리를 코드 외부로 분리한다. URI·사용자명·비밀번호를 스크립트에 직접 작성하는 패턴은 학습용으로만 허용된다. .env 파일 또는 시크릿 매니저를 사용하는 습관이 운영 단계에서 필수가 된다.

결론: Desktop은 학습의 자유도, Aura는 운영의 편의를 제공하며 — 어느 쪽을 선택하든 GDS·APOC·Bolt라는 세 축이 이후 GraphRAG 실습의 공통 기반이 된다.

참고 자료

• Graph Data Science with Python and Neo4j. Chapter 2: Getting Started with Python and Neo4j.