드라이버와 클라이언트 라이브러리
================================
.. toctree::
:hidden:
ai-integrations
AgensGraph는 PostgreSQL 통신 프로토콜을 쓰므로, **어떤 PostgreSQL 드라이버로도 접속해 Cypher를
실행할 수 있습니다.** 프로토콜이 보기에 Cypher 문장은 그저 문장 하나입니다. AgensGraph를 쓰는 데
그래프 전용 클라이언트가 필요하지 않습니다.
드라이버가 도움 없이 하지 못하는 것은 그래프 타입을 해석하는 일입니다. ``m.title`` 을 반환하는
쿼리는 모든 드라이버가 아는 ``jsonb`` 를 돌려주지만, ``m`` 을 반환하는 쿼리는 ``vertex`` 를, 경로
패턴의 ``p`` 는 ``graphpath`` 를 돌려줍니다. 보통의 드라이버는 그것들을 텍스트로 봅니다. AgensGraph를
위해 쓰인 드라이버는 타입 처리를 더하므로, 정점이 자기 레이블과 id와 속성을 지닌 객체로
도착합니다.
그래서 방법은 두 가지입니다:
**이미 쓰고 있는 PostgreSQL 드라이버를 쓰십시오.** 요소 전체가 아니라 속성을 반환하고, ``jsonb``
대신 평범한 스칼라를 원하는 곳에서는 Cypher를 SQL로 감싸십시오.
:doc:`../querying/combining-sql-and-cypher`\ 를 참고하십시오. 코드도 의존성도 가장 적고, Python이
아닌 언어에서는 이 길이 맞습니다.
정점과 간선과 경로를 네이티브 객체로 받고 싶을 때, 또는 AI 연동을 기반으로 만들 때는
**Python 드라이버를 쓰십시오.**
Python 드라이버
---------------
기반으로 삼을 드라이버는
`AgensGraph for Python `_\ 입니다.
psycopg 3 위에 그래프 타입 처리를 더하며, 모든 :doc:`AI 연동 `\ 이 이 드라이버
위에서 동작합니다. 설치와 사용법은 그 매뉴얼에 있습니다.
LangChain·LlamaIndex·LightRAG·cognee와 MCP 서버가 모두 이 드라이버를 기반으로 합니다.
:doc:`AI·LLM 연동 `\ 을 참고하십시오.
다른 언어
---------
Java·Node.js·Go에서는 보통의 PostgreSQL 드라이버 — pgjdbc, node-postgres, pgx — 를 쓰고, 위에서
말한 대로 요소 전체가 아니라 속성을 읽으십시오. 지금 기반으로 삼기에 알맞은 조합은 이것입니다.
그 세 언어를 위한 드라이버도 있기는 하며, 새로 시작하는 자리가 아니라 이미 쓰고 있는 프로젝트를
위해 여기에 남겨 둡니다:
* `Java / JDBC `_
:bdg-secondary-line:`legacy` — pgjdbc의 포크이며 2023년 1월에
``net.bitnine:agensgraph-jdbc:1.4.3`` 으로 배포됐습니다.
* `Node.js `_
:bdg-secondary-line:`legacy` — node-postgres를 감싸며 ``pg >= 6.1.2`` 를 대상으로 합니다. 2025년
9월에 ``@skaiworldwide/ag-driver`` 1.1.0으로 배포됐습니다.
* `Go `_
:bdg-secondary-line:`legacy` — ``lib/pq`` 위에 만들어졌고 태그 ``v0.1.1`` 의 Go 모듈로
배포됩니다.
접속과 매개변수
---------------
**접속에** ``graph_path`` **를 설정하십시오.** 세션별이므로, 풀에서 꺼내 주는 접속은 꺼낼 때마다
설정해야 합니다. 아니면 롤이나 데이터베이스에 한 번 설정하십시오:
.. code-block:: sql
ALTER ROLE appuser SET graph_path = moviekb;
Python 드라이버의 ``ConnectionPool`` 은 ``graph=`` 로 받은 그래프를 접속을 열 때 한 번만 설정하고
꺼내 줄 때마다 다시 설정하지는 않으므로, 접속을 빌려 간 쪽이 ``graph_path`` 를 바꾸고 커밋하면 그
값이 다음에 빌려 가는 쪽으로 넘어갑니다.
**Cypher 매개변수에는 타입을 주십시오.** 드라이버가 타입을 정해 주지 않은 매개변수는 JSON으로
파싱되므로, 평범한 문자열은 실패합니다:
.. code-block:: text
ERROR: invalid input syntax for type json
DETAIL: Token "The" is invalid.
CONTEXT: JSON data, line 1: The...
드라이버의 API로 매개변수의 타입을 선언하거나, 문장 안에서 형 변환하십시오:
.. code-block:: cypher
MATCH (m:movie {title: $1::text}) RETURN m.year;
형 변환이 이식성 있는 형태이고 비용도 들지 않습니다. 값이 어느 쪽으로도 읽힐 수 있는 곳에서 가장
중요합니다. 타입이 없으면 ``'123'`` 이 *숫자* 123으로 도착해, *문자열* ``"123"`` 을 담은 속성과
일치하지 않게 됩니다.
Python 드라이버는 타입을 대신 선언해 줍니다. 2.0부터는 Python ``str`` 을 ``text`` 로 보내므로
문자열 매개변수는 따로 형 변환할 필요가 없습니다. 다만 문자열을 다른 타입으로 받아야 하는
자리에서는 여전히 ``%s::date`` 처럼 형 변환해야 합니다.