graphclient

graphclient는 XML 계약을 기준으로 Neo4j와 Memgraph에 Cypher를 실행하는 그래프 데이터베이스 모듈입니다. API 형태와 계약 refresh 흐름은 dbclient와 비슷하지만, 데이터 원본과 파라미터 바인딩은 그래프 데이터베이스에 맞춰 동작합니다.

책임 범위

• GraphDataSource 설정에서 그래프 연결 정보를 읽어 Bolt 계열 연결을 구성합니다.
• XML statement 계약을 로드하고 ApplicationID|ProjectID|TransactionID|StatementID 기준으로 실행합니다.
• Cypher named parameter를 요청 파라미터와 매핑합니다.
• Json, Scalar, NonQuery, SchemeOnly, CodeHelp 반환 형식을 처리합니다.
• transact에서 CommandType=G로 들어온 거래를 그래프 쿼리 실행으로 변환합니다.

주요 API

메서드	경로	용도
GET	/graphclient/api/query/has	쿼리 계약 존재 여부를 확인합니다.
GET	/graphclient/api/query/refresh	계약 파일을 다시 로드합니다.
GET	/graphclient/api/query/retrieve	계약 원문 또는 상세 정보를 조회합니다.
GET	/graphclient/api/query/meta	입력/출력 메타 정보를 반환합니다.
GET	/graphclient/api/query/reports	계약 기반 보고용 정보를 조회합니다.
POST	/graphclient/api/query/execute	Cypher 계약을 실행합니다.

핵심 구현

• Areas/graphclient/Controllers/QueryController.cs: query API 진입점입니다.
• DataClient/GraphDataClient.cs: 그래프 연결, 파라미터 바인딩, 실행 결과 변환을 담당합니다.
• Extensions/GraphMapper.cs: XML 계약과 그래프 데이터 원본 매핑을 관리합니다.
• Events/GraphClientRequestHandler.cs: 모듈 내부 MediatR 실행 요청을 처리합니다.
• Events/ManagedRequestHandler.cs: 운영 화면이나 관리 기능에서 전달되는 데이터 원본 변경 요청을 반영합니다.

계약과 식별자

계약은 기본적으로 다음 위치에 둡니다.

contracts/graphclient/{ApplicationID}/{ProjectID}/{TransactionID}.xml

쿼리 ID는 다음 형식입니다.

ApplicationID|ProjectID|TransactionID|StatementID

statement에는 사용할 DataSourceID, 반환 형식, Cypher 본문, 입력 파라미터를 선언합니다. Cypher 안에서는 $name 형태의 named parameter를 사용합니다.

주요 설정

설정	설명
GraphDataSource	애플리케이션/프로젝트별 그래프 데이터 원본입니다.
DefaultDataSourceID	계약에서 데이터 원본이 생략될 때 사용할 기본 ID입니다.
Security.AllowedGraphHosts	연결 가능한 그래프 호스트 allowlist입니다.
Security.MaxCommandTimeout	계약이 지정할 수 있는 최대 실행 시간입니다.
DefaultCommandTimeout	statement timeout이 없을 때 적용되는 기본값입니다.
IsProfileLogging	그래프 요청/응답 프로파일 로그 기록 여부입니다.
SubscribeAction	기본 수신 이벤트는 graphclient.Events.GraphClientRequest, graphclient.Events.ManagedRequest입니다.

GraphDataSource 예시는 다음과 같습니다.

{
  "ApplicationID": "HDS",
  "ProjectID": "*",
  "DataSourceID": "GRAPH01",
  "GraphProvider": "Neo4j",
  "ConnectionString": "bolt://localhost:7687",
  "UserName": "neo4j",
  "Password": "<password>",
  "Database": "neo4j",
  "IsEncryption": "N"
}

transact 연동

transact 거래 계약에서는 CommandType을 G로 둡니다.

{
  "ServiceID": "GQ010",
  "CommandType": "G",
  "ReturnType": "Json"
}

라우팅 예시는 다음과 같습니다.

{
  "HDS|*|G|D": "http://localhost:8421/graphclient/api/query",
  "HDS|*|G|P": "http://localhost:8421/graphclient/api/query",
  "HDS|*|G|T": "http://localhost:8421/graphclient/api/query"
}

운영 주의사항

• 그래프 DB 계정은 계약별 필요한 권한만 부여합니다.
• AllowedGraphHosts와 timeout 정책을 운영 환경에서 반드시 검토합니다.
• 쿼리 결과가 크면 Json 반환이 네트워크와 메모리에 직접 영향을 주므로 조회 범위를 계약에 명시합니다.
• 연결 문자열, 사용자명, 비밀번호는 공개 문서나 소스에 실제 값으로 남기지 않습니다.