Snowflake Search Tool

SnowflakeSearchTool은 CrewAI 에이전트가 Snowflake 데이터 웨어하우스에서 SQL 쿼리를 실행하고 시맨틱 검색을 수행할 수 있게 해주는 도구예요.

출처: 문서

본문

`SnowflakeSearchTool`

설명 (Description)

SnowflakeSearchTool은 Snowflake 데이터 웨어하우스에 연결해 연결 풀링, 재시도 로직, 비동기 실행과 같은 고급 기능으로 SQL 쿼리를 실행하도록 설계되었습니다. 이 도구는 CrewAI 에이전트가 Snowflake 데이터베이스와 상호작용할 수 있게 해주며, Snowflake에 저장된 엔터프라이즈 데이터에 접근해야 하는 데이터 분석, 리포팅, 비즈니스 인텔리전스 작업에 이상적입니다.

설치 (Installation)

이 도구를 사용하려면 필요한 의존성을 설치해야 합니다.

uv add cryptography snowflake-connector-python snowflake-sqlalchemy

또는 아래와 같이 할 수도 있습니다.

uv sync --extra snowflake

시작하기 (Steps to Get Started)

SnowflakeSearchTool을 효과적으로 사용하려면 다음 단계를 따르세요.

의존성 설치 (Install Dependencies): 위 명령어 중 하나로 필요한 패키지를 설치합니다.
Snowflake 연결 구성 (Configure Snowflake Connection): Snowflake 자격 증명으로 SnowflakeConfig 객체를 만듭니다.
도구 초기화 (Initialize the Tool): 필요한 구성으로 도구 인스턴스를 만듭니다.
쿼리 실행 (Execute Queries): 도구를 사용해 Snowflake 데이터베이스에 대해 SQL 쿼리를 실행합니다.

예시 (Example)

다음 예시는 SnowflakeSearchTool을 사용해 Snowflake 데이터베이스에서 데이터를 쿼리하는 방법을 보여줍니다.

from crewai import Agent, Task, Crew
from crewai_tools import SnowflakeSearchTool, SnowflakeConfig

# Create Snowflake configuration
config = SnowflakeConfig(
    account="your_account",
    user="your_username",
    password="your_password",
    warehouse="COMPUTE_WH",
    database="your_database",
    snowflake_schema="your_schema"
)

# Initialize the tool
snowflake_tool = SnowflakeSearchTool(config=config)

# Define an agent that uses the tool
data_analyst_agent = Agent(
    role="Data Analyst",
    goal="Analyze data from Snowflake database",
    backstory="An expert data analyst who can extract insights from enterprise data.",
    tools=[snowflake_tool],
    verbose=True,
)

# Example task to query sales data
query_task = Task(
    description="Query the sales data for the last quarter and summarize the top 5 products by revenue.",
    expected_output="A summary of the top 5 products by revenue for the last quarter.",
    agent=data_analyst_agent,
)

# Create and run the crew
crew = Crew(agents=[data_analyst_agent], 
            tasks=[query_task])
result = crew.kickoff()

추가 매개변수로 도구를 커스터마이즈할 수도 있습니다.

# Initialize the tool with custom parameters
snowflake_tool = SnowflakeSearchTool(
    config=config,
    pool_size=10,
    max_retries=5,
    retry_delay=2.0,
    enable_caching=True
)

매개변수 (Parameters)

SnowflakeConfig 매개변수 (SnowflakeConfig Parameters)

SnowflakeConfig 클래스는 다음 매개변수를 허용합니다.

account: 필수. Snowflake 계정 식별자입니다.
user: 필수. Snowflake 사용자 이름입니다.
password: 선택*. Snowflake 비밀번호입니다.
private_key_path: 선택*. 개인 키 파일의 경로입니다 (비밀번호 대안).
warehouse: 필수. Snowflake 웨어하우스 이름입니다.
database: 필수. 기본 데이터베이스입니다.
snowflake_schema: 필수. 기본 스키마입니다.
role: 선택. Snowflake 역할입니다.
session_parameters: 선택. 사전 형태의 커스텀 세션 매개변수입니다.

*password 또는 private_key_path 중 하나는 반드시 제공해야 합니다.

SnowflakeSearchTool 매개변수 (SnowflakeSearchTool Parameters)

SnowflakeSearchTool은 초기화 시 다음 매개변수를 허용합니다.

config: 필수. 연결 세부 정보를 담고 있는 SnowflakeConfig 객체입니다.
pool_size: 선택. 풀의 연결 수입니다. 기본값은 5입니다.
max_retries: 선택. 실패한 쿼리의 최대 재시도 횟수입니다. 기본값은 3입니다.
retry_delay: 선택. 재시도 사이의 지연(초)입니다. 기본값은 1.0입니다.
enable_caching: 선택. 쿼리 결과 캐싱을 활성화할지 여부입니다. 기본값은 True입니다.

사용법 (Usage)

SnowflakeSearchTool을 사용할 때 다음 매개변수를 제공해야 합니다.

query: 필수. 실행할 SQL 쿼리입니다.
database: 선택. 구성에 지정된 기본 데이터베이스를 재정의합니다.
snowflake_schema: 선택. 구성에 지정된 기본 스키마를 재정의합니다.
timeout: 선택. 쿼리 타임아웃(초)입니다. 기본값은 300입니다.

도구는 쿼리 결과를 사전 목록으로 반환하며, 각 사전은 컬럼 이름을 키로 하는 하나의 행을 나타냅니다.

# Example of using the tool with an agent
data_analyst = Agent(
    role="Data Analyst",
    goal="Analyze sales data from Snowflake",
    backstory="An expert data analyst with experience in SQL and data visualization.",
    tools=[snowflake_tool],
    verbose=True
)

# The agent will use the tool with parameters like:
# query="SELECT product_name, SUM(revenue) as total_revenue FROM sales GROUP BY product_name ORDER BY total_revenue DESC LIMIT 5"
# timeout=600

# Create a task for the agent
analysis_task = Task(
    description="Query the sales database and identify the top 5 products by revenue for the last quarter.",
    expected_output="A detailed analysis of the top 5 products by revenue.",
    agent=data_analyst
)

# Run the task
crew = Crew(
    agents=[data_analyst], 
    tasks=[analysis_task]
)
result = crew.kickoff()

고급 기능 (Advanced Features)

연결 풀링 (Connection Pooling)

SnowflakeSearchTool은 데이터베이스 연결을 재사용해 성능을 향상시키는 연결 풀링을 구현합니다. pool_size 매개변수로 풀 크기를 제어할 수 있습니다.

자동 재시도 (Automatic Retries)

도구는 지수 백오프(exponential backoff)로 실패한 쿼리를 자동으로 재시도합니다. max_retries와 retry_delay 매개변수로 재시도 동작을 구성할 수 있습니다.

쿼리 결과 캐싱 (Query Result Caching)

반복 쿼리의 성능을 향상시키기 위해 도구는 쿼리 결과를 캐시할 수 있습니다. 이 기능은 기본적으로 활성화되어 있으며 enable_caching=False로 설정하면 비활성화할 수 있습니다.

키-페어 인증 (Key-Pair Authentication)

비밀번호 인증에 더해 도구는 보안 강화를 위해 키-페어 인증을 지원합니다.

config = SnowflakeConfig(
    account="your_account",
    user="your_username",
    private_key_path="/path/to/your/private/key.p8",
    warehouse="COMPUTE_WH",
    database="your_database",
    snowflake_schema="your_schema"
)

오류 처리 (Error Handling)

SnowflakeSearchTool은 일반적인 Snowflake 문제에 대한 종합적인 오류 처리를 포함합니다.

연결 실패 (Connection failures)
쿼리 타임아웃 (Query timeouts)
인증 오류 (Authentication errors)
데이터베이스 및 스키마 오류 (Database and schema errors)

오류가 발생하면 도구는 (구성된 경우) 작업을 재시도하고 상세한 오류 정보를 제공합니다.

결론 (Conclusion)

SnowflakeSearchTool은 Snowflake 데이터 웨어하우스를 CrewAI 에이전트와 통합하는 강력한 방법을 제공합니다. 연결 풀링, 자동 재시도, 쿼리 캐싱과 같은 기능으로 엔터프라이즈 데이터에 효율적이고 안정적으로 접근할 수 있게 해줍니다. 이 도구는 Snowflake에 저장된 구조화된 데이터에 접근해야 하는 데이터 분석, 리포팅, 비즈니스 인텔리전스 작업에 특히 유용합니다.

Snowflake Search Tool

Snowflake Search Tool

본문

SnowflakeSearchTool

설명 (Description)

설치 (Installation)

시작하기 (Steps to Get Started)

예시 (Example)

매개변수 (Parameters)

SnowflakeConfig 매개변수 (SnowflakeConfig Parameters)

SnowflakeSearchTool 매개변수 (SnowflakeSearchTool Parameters)

사용법 (Usage)

고급 기능 (Advanced Features)

연결 풀링 (Connection Pooling)

자동 재시도 (Automatic Retries)

쿼리 결과 캐싱 (Query Result Caching)

키-페어 인증 (Key-Pair Authentication)

오류 처리 (Error Handling)

결론 (Conclusion)

더 알아보기 (Learn more)

`SnowflakeSearchTool`