PART 1 · Neo4j & Cypher

Neo4j 환경 구축

AuraDB 클라우드와 Neo4j Desktop, 두 가지 환경을 세팅하고 Python으로 연결하는 방법을 다룹니다.

1. 두 가지 선택지

Neo4j를 사용하는 방법은 크게 두 가지입니다.
클라우드(AuraDB)와 로컬(Neo4j Desktop).

AuraDB (클라우드)

Neo4j가 제공하는 무료 클라우드 서비스

설치 없이 웹 브라우저에서 바로 시작
무료 티어: 노드 20만 개, 관계 40만 개
학습용으로 충분한 용량

설치 불필요 · 5분 세팅

Neo4j Desktop (로컬)

로컬 PC에 설치하는 데스크톱 앱

인터넷 없이 사용 가능
플러그인(APOC, GDS) 설치 자유
대규모 데이터 처리 시 유리

로컬 설치 · 오프라인 가능

입문자에게는 AuraDB를 추천합니다.

설치 과정 없이 바로 Cypher를 연습할 수 있고,
나중에 필요하면 Desktop으로 전환하면 됩니다.

2. AuraDB 세팅

5분이면 끝나는 AuraDB 세팅 과정입니다.

  1. Neo4j AuraDB 접속
    neo4j.com/cloud/aura-free 에서 무료 계정 생성
    Google / GitHub 계정으로 소셜 로그인 가능
  2. New Instance 생성
    "Create Free Instance" 클릭
    인스턴스 이름 입력 (예: my-first-graph)
    리전 선택 (아시아 또는 미국)
  3. 비밀번호 저장
    생성 시 자동 생성된 비밀번호가 표시됨
    이 비밀번호는 다시 볼 수 없으므로 반드시 복사·저장
    Connection URI (bolt+s://xxxx.databases.neo4j.io)도 함께 저장
  4. Workspace 접속
    인스턴스 카드에서 "Open" 클릭 → Neo4j Workspace 열림
    좌측 Query 탭에서 Cypher 쿼리 실행 가능

반드시 기억할 것

AuraDB 무료 티어는 비활성 상태가 3일 지속되면 자동 일시정지됩니다.
다시 접속하면 자동으로 깨어나니 걱정하지 마세요.
단, 30일 이상 방치하면 삭제될 수 있으므로 주기적으로 접속하세요.

3. Neo4j Desktop 세팅

로컬 환경이 필요하거나, 플러그인을 자유롭게 사용하고 싶다면
Neo4j Desktop을 설치합니다.

  1. 다운로드
    neo4j.com/download 에서 Neo4j Desktop 다운로드
    Windows / macOS / Linux 지원
    설치 시 Activation Key가 자동 발급됨 (복사해두기)
  2. 프로젝트 & DBMS 생성
    앱 실행 후 "New Project" → "Add Database" → "Local DBMS"
    이름과 비밀번호 설정 (예: neo4j / password)
    Neo4j 버전 선택 (최신 5.x 권장)
  3. DBMS 시작 & Browser 열기
    "Start" 클릭 → DBMS 실행 (30초 정도 소요)
    "Open" → Neo4j Browser가 웹 브라우저에서 열림
    기본 접속 URL: bolt://localhost:7687
  4. 플러그인 설치 (선택)
    DBMS 카드 → Plugins 탭
    APOC: 데이터 가져오기, 유틸리티 함수 모음
    GDS: 그래프 알고리즘 라이브러리 (PageRank, Community Detection 등)
    토글을 켜면 자동 설치됨
4. Browser vs Workspace

Neo4j에는 두 가지 웹 인터페이스가 있습니다.
이름이 비슷해서 헷갈리기 쉬운데, 차이를 정리하면 이렇습니다.

비교 Neo4j Browser Neo4j Workspace
용도 쿼리 실행 · 시각화
전통적인 Neo4j UI		 쿼리 + 탐색 + 시각화 통합
차세대 UI (AuraDB 기본)
접속 방법 Desktop에서 "Open"
또는 localhost:7474		 AuraDB에서 "Open"
또는 workspace.neo4j.io
주요 기능 Cypher 실행
그래프 시각화
가이드 튜토리얼		 Query 탭: Cypher 실행
Explore 탭: 노코드 탐색
Import 탭: 데이터 가져오기
추천 대상 Desktop 사용자
기존 Neo4j 사용자		 AuraDB 사용자
입문자

어떤 걸 쓰든 상관없습니다.

둘 다 Cypher 쿼리를 실행하고 그래프를 시각화하는 도구입니다.
AuraDB를 쓰면 Workspace, Desktop을 쓰면 Browser를 자연스럽게 사용하게 됩니다.

5. Python 연결

Neo4j를 Python에서 프로그래밍적으로 사용하려면
공식 드라이버를 설치하고 연결합니다.

공식 neo4j 드라이버

Neo4j에서 직접 관리하는 공식 Python 드라이버입니다.

설치
pip install neo4j
기본 연결 코드
from neo4j import GraphDatabase

# AuraDB 연결
URI = "bolt+s://xxxx.databases.neo4j.io"
AUTH = ("neo4j", "your-password")

driver = GraphDatabase.driver(URI, auth=AUTH)

# 연결 테스트
driver.verify_connectivity()
print("Connected!")

# Cypher 쿼리 실행
records, summary, keys = driver.execute_query(
    "MATCH (n) RETURN count(n) AS count"
)
print(f"노드 수: {records[0]['count']}")

driver.close()

LangChain Neo4jGraph (GraphRAG용)

나중에 PART 4(GraphRAG)에서 사용할 LangChain 연동 방법입니다.
지금은 "이런 것도 있다" 정도만 알아두세요.

LangChain 연결 코드
from langchain_community.graphs import Neo4jGraph

graph = Neo4jGraph(
    url="bolt+s://xxxx.databases.neo4j.io",
    username="neo4j",
    password="your-password"
)

# 스키마 자동 탐지
print(graph.schema)

연결 정보 관리 팁

비밀번호와 URI를 코드에 직접 쓰지 마세요.
.env 파일에 저장하고, python-dotenv로 불러오는 것이 안전합니다.

NEO4J_URI=bolt+s://xxxx.databases.neo4j.io
NEO4J_PASSWORD=your-password

6. 핵심 정리

이 페이지에서 기억할 것

1. 두 가지 환경
AuraDB(클라우드, 무료, 설치 불필요) vs Neo4j Desktop(로컬, 플러그인 자유)

2. AuraDB 세팅 핵심
계정 생성 → 인스턴스 생성 → 비밀번호 반드시 저장 → Workspace에서 바로 시작

3. Desktop 세팅 핵심
다운로드 → 프로젝트 생성 → DBMS 시작 → Browser에서 쿼리 실행

4. Browser vs Workspace
둘 다 Cypher 실행 도구. Desktop은 Browser, AuraDB는 Workspace

5. Python 연결
neo4j 공식 드라이버로 연결. 비밀번호는 .env로 관리