Haystack SnowflakeTableRetriever: SQL 기반 RAG 및 에이전트 파이프라인 통합 가이드

Haystack의 Snowflake 통합 컴포넌트인 SnowflakeTableRetriever를 사용하여 Snowflake 데이터 웨어하우스의 데이터를 SQL 쿼리를 통해 직접 RAG 및 에이전트 파이프라인으로 가져오는 방법을 알아봅니다.

컴포넌트 개요: 구조화된 데이터 검색 전문 Retriever

SnowflakeTableRetriever는 haystack_integrations.components.retrievers.snowflake.snowflake_table_retriever 모듈에 속하며, 별도의 snowflake-haystack 패키지로 제공됩니다. 이 컴포넌트는 일반적인 벡터 Retriever와는 달리, 의미론적 검색 대신 SQL 쿼리를 실행하여 Snowflake에서 구조화된 데이터를 직접 가져오는 데 특화되어 있습니다.

  • 입력: SQL 쿼리 문자열 (query).
  • 처리 과정: ADBC (Arrow Database Connectivity) 드라이버를 사용하여 Snowflake에 연결하고, Polars 라이브러리로 쿼리 결과를 읽어옵니다.
  • 출력: Polars DataFrame에서 변환된 Pandas DataFrame 및 해당 데이터의 Markdown 형식 문자열.

이 컴포넌트는 주로 PromptBuilder 또는 ChatPromptBuilder 컴포넌트 이전에 배치되어, 검색된 테이블 데이터를 LLM이 이해할 수 있는 형식으로 제공하는 역할을 합니다.

설치 및 기본 사용 예제

먼저, 필요한 통합 패키지를 설치합니다:


pip install snowflake-haystack

파이프라인에 통합하지 않고 독립적으로 컴포넌트를 사용하는 최소 예제는 다음과 같습니다:


from haystack.utils import Secret
from haystack_integrations.components.retrievers.snowflake import SnowflakeTableRetriever

# Snowflake 연결 설정 (환경 변수에서 API 키 로드)
snowflake_retriever = SnowflakeTableRetriever(
    user="",
    account="",
    api_key=Secret.from_env_var("SNOWFLAKE_API_KEY"),
    warehouse="",
    database="",
    db_schema="",
)

# SQL 쿼리 실행
query = "SELECT * FROM your_table_name LIMIT 5;"
results = snowflake_retriever.run(query=query)

# 결과 확인
print("DataFrame:\n", results["dataframe"])
print("\nMarkdown Table:\n", results["table"])

위 예제에서 api_key는 Haystack의 Secret 메커니즘을 통해 환경 변수 SNOWFLAKE_API_KEY에서 안전하게 로드됩니다. account는 Snowflake 계정 식별자이며, warehouse는 쿼리 실행에 사용될 가상 웨어하우스를 지정합니다.

세 가지 인증 방식: 비밀번호, 키 페어(JWT), OAuth

SnowflakeTableRetriever는 authenticator 매개변수를 통해 세 가지 주요 인증 방식을 지원합니다.

1. 비밀번호 인증 (authenticator="SNOWFLAKE")

사용자 이름과 비밀번호를 사용하여 로그인하는 가장 일반적인 방식입니다.


from haystack.utils import Secret
from haystack_integrations.components.retrievers.snowflake import SnowflakeTableRetriever

snowflake_retriever = SnowflakeTableRetriever(
    user="",
    account="",
    authenticator="SNOWFLAKE",
    api_key=Secret.from_env_var("SNOWFLAKE_API_KEY"),
    database="",
    db_schema="",
    warehouse="",
)
snowflake_retriever.warm_up() # 초기화 및 연결 테스트

2. 키 페어 인증 (authenticator="SNOWFLAKE_JWT")

Snowflake에서 생성한 RSA 개인 키 파일을 사용하여 JWT(JSON Web Token) 기반으로 인증합니다. 민감한 비밀번호 노출 없이 MFA(Multi-Factor Authentication) 정책과 함께 사용할 수 있습니다.


from haystack.utils import Secret
from haystack_integrations.components.retrievers.snowflake import SnowflakeTableRetriever

snowflake_retriever = SnowflakeTableRetriever(
    user="",
    account="",
    authenticator="SNOWFLAKE_JWT",
    private_key_file=Secret.from_env_var("SNOWFLAKE_PRIVATE_KEY_FILE"),
    private_key_file_pwd=Secret.from_env_var("SNOWFLAKE_PRIVATE_KEY_PWD", strict=False), # 비밀번호가 없는 경우 생략 가능
    database="",
    db_schema="",
    warehouse="",
)
snowflake_retriever.warm_up()

private_key_file은 개인 키 파일의 경로를, private_key_file_pwd는 파일 자체의 암호화를 해제하기 위한 비밀번호를 지정합니다.

3. OAuth 인증 (authenticator="OAUTH")

기업 환경의 SSO(Single Sign-On) 시나리오에 적합하며, 클라이언트 자격 증명(Client Credentials) 또는 인증 코드(Authorization Code) 흐름을 지원합니다.


from haystack.utils import Secret
from haystack_integrations.components.retrievers.snowflake import SnowflakeTableRetriever

snowflake_retriever = SnowflakeTableRetriever(
    user="",
    account="",
    authenticator="OAUTH",
    oauth_client_id=Secret.from_env_var("SNOWFLAKE_OAUTH_CLIENT_ID"),
    oauth_client_secret=Secret.from_env_var("SNOWFLAKE_OAUTH_CLIENT_SECRET"),
    oauth_token_request_url="", # Client Credentials Flow용
    # oauth_authorization_url="", # Authorization Code Flow용
    database="",
    db_schema="",
    warehouse="",
)
snowflake_retriever.warm_up()

oauth_token_request_url은 토큰 요청 엔드포인트이며, oauth_authorization_url은 인증 코드 흐름 시 사용되는 권한 부여 엔드포인트입니다.

생명주기 메서드: warm_up(), run()

  • warm_up(): 인증 프로세스를 초기화하고 데이터베이스 연결을 테스트합니다. 파이프라인 실행 전에 호출하여 인증 관련 오류를 미리 감지하는 것이 좋습니다.
  • run(query: str, return_markdown: bool | None = None): 주어진 SQL 쿼리를 실행하고 결과를 반환합니다.
    • query: 실행할 SQL 문.
    • return_markdown: Markdown 형식의 테이블 문자열 반환 여부. 지정하지 않으면 초기화 시 설정된 값이 사용됩니다.
    반환값은 dataframe (Pandas DataFrame)과 table (Markdown 문자열)을 포함하는 딕셔너리입니다.

파이프라인에서의 활용: LLM이 테이블 데이터를 "읽도록" 만들기

SnowflakeTableRetriever는 LLM이 구조화된 데이터에 기반하여 답변을 생성하도록 하는 RAG 파이프라인에 이상적입니다.


from haystack import Pipeline
from haystack.utils import Secret
from haystack.components.builders import ChatPromptBuilder
from haystack.components.generators.chat import OpenAIChatGenerator
from haystack.dataclasses import ChatMessage
from haystack_integrations.components.retrievers.snowflake import SnowflakeTableRetriever

# Snowflake Retriever 컴포넌트 설정
snowflake_retriever = SnowflakeTableRetriever(
    user="",
    account="",
    api_key=Secret.from_env_var("SNOWFLAKE_API_KEY"),
    warehouse="",
    database="",
    db_schema="",
)

# Haystack 파이프라인 구성
pipeline = Pipeline()
pipeline.add_component("snowflake_retriever", snowflake_retriever)
pipeline.add_component(
    "prompt_builder",
    ChatPromptBuilder(
        template=[ChatMessage.from_user("Please analyze the following table data: \n{{ table }}")],
        required_variables=["table"],
    ),
)
pipeline.add_component("llm", OpenAIChatGenerator(model="gpt-4o"))

# 컴포넌트 연결
pipeline.connect("snowflake_retriever.table", "prompt_builder.table")
pipeline.connect("prompt_builder.prompt", "llm.messages")

# 파이프라인 실행 (SQL 쿼리를 데이터로 전달)
query_sql = "SELECT customer_id, order_total FROM orders WHERE order_date = '2023-10-26' LIMIT 10;"
result = pipeline.run(data={"query": query_sql})

print("LLM Response:", result["llm"]["replies"][0].content)

이 파이프라인은 Snowflake에서 데이터를 검색하여 Markdown 테이블로 변환한 후, 이를 ChatPromptBuilder를 통해 LLM에게 전달하여 분석을 요청합니다. SQL 쿼리는 파이프라인 실행 시 data 인자를 통해 동적으로 전달될 수 있습니다.

주요 사용 사례 및 고려 사항

  • 구조화된 데이터 기반 RAG: Snowflake의 최신 비즈니스 데이터를 LLM이 요약, 필터링 또는 비교 분석하는 데 활용됩니다.
  • Text-to-SQL 워크플로우: LLM이 생성한 SQL을 SnowflakeTableRetriever가 실행하고, 그 결과를 다시 LLM에게 제공하는 피드백 루프를 구축할 수 있습니다.
  • 보안: run() 메서드는 실제 SQL을 실행하므로, LLM이 생성한 SQL을 직접 사용하는 경우 데이터베이스 접근 권한을 최소화하고 실행 가능한 객체를 제한하는 등의 보안 조치가 필요합니다.
  • 자격 증명 관리: 모든 민감한 정보는 환경 변수와 Secret 객체를 통해 관리하여 파이프라인 직렬화 시 노출되지 않도록 합니다.

태그: Snowflake RAG SQL LLM haystack

11월 11일 20:24에 게시됨