Python 커넥터 API¶

상수¶

apilevel¶

지원되는 API 레벨을 나타내는 문자열 상수입니다. 커넥터는 API "2.0" 을 지원합니다.

threadsafety¶

인터페이스에서 지원되는 스레드 안전 레벨을 나타내는 정수 상수입니다. Python용 Snowflake 커넥터는 레벨 2 를 지원하며, 이는 스레드가 모듈 및 연결을 공유함을 나타냅니다.

paramstyle¶

인터페이스에서 요구되는 매개 변수 마커 형식의 타입을 나타내는 문자열 상수입니다. 커넥터는 기본적으로 "pyformat" 타입을 지정하며, 이는 Python 확장 형식 코드(예: ...WHERE name=%s 또는 ...WHERE name=%(name)s)에 적용됩니다. Connection.connect 는 paramstyle 을 재정의하여 바인딩 변수 형식을 "qmark" 또는 "numeric" 으로 변경하며, 여기서 변수는 각각 ? 또는 :N 입니다.

예:

format: .execute("... WHERE my_column = %s", (value,))
pyformat: .execute("... WHERE my_column = %(name)s", {"name": value})
qmark: .execute("... WHERE my_column = ?", (value,))
numeric: .execute("... WHERE my_column = :1", (value,))

Copy

참고

바인딩 변수는 paramstyle 이 "pyformat" 또는 "format" 인 경우에는 클라이언트 측에서 그리고 "qmark" 또는 "numeric" 인 경우에는 서버 측에서 발생합니다. 커넥터는 SQL 텍스트를 컴파일한 후 다중 실행을 지원하지 않으므로, 현재 성능 또는 기능의 측면에서 이러한 옵션 사이에는 커다란 차이가 없습니다. 대신, "qmark" 및 "numeric" 옵션은 다른 드라이버(즉, JDBC, ODBC, Go Snowflake Driver)의 쿼리 텍스트와 호환되며, 이는 ? 또는 :N 변수 형식을 사용한 서버측 바인딩을 지원합니다.

함수¶

connect(parameters...)¶

목적:

데이터베이스로의 연결을 생성하기 위한 생성자로, Connection 오브젝트를 반환합니다.

자동 커밋 모드는 기본적으로 활성화됩니다 (즉, 연결이 종료되면 모든 변경 사항이 커밋됨). 트랜잭션이 필요한 경우, BEGIN 명령을 사용하여 트랜잭션을 시작하고 COMMIT 또는 ROLLBACK 명령을 사용하여 변경 사항을 커밋하거나 롤백합니다.

매개 변수:

유효한 입력 매개 변수:

매개 변수	필수	설명
account	예	사용자의 계정 식별자입니다. 계정 식별자에는 snowflakecomputing.com 접미사가 포함되지 않습니다. . . 자세한 정보는 예는 이 항목의 사용법 노트 를 참조하십시오.
user	예	사용자의 로그인 이름입니다.
password	예	사용자의 비밀번호입니다.
application		연결을 시도하는 애플리케이션을 식별하는 이름입니다.
region		더 이상 사용되지 않음 이 매개 변수 설명은 이전 버전과의 호환성만을 위해서 제공됩니다.
host		호스트 이름입니다.
port		포트 번호(기본값은 443)입니다.
database		사용할 기본 데이터베이스의 이름입니다. 로그인한 후에는 USE DATABASE 를 사용하여 데이터베이스를 변경할 수 있습니다.
schema		데이터베이스에서 사용할 기본 스키마의 이름입니다. 로그인한 후에는 USE SCHEMA 를 사용하여 스키마를 변경할 수 있습니다.
role		사용할 기본 역할의 이름입니다. 로그인한 후에는 USE ROLE 를 사용하여 역할을 변경할 수 있습니다.
warehouse		사용할 기본 웨어하우스의 이름입니다. 로그인한 후에는 USE WAREHOUSE 를 사용하여 웨어하우스를 변경할 수 있습니다.
passcode_in_password		기본적으로 False 입니다. MFA(다단계 인증) 암호가 로그인 암호에 포함된 경우 이 값을 True 로 설정합니다.
passcode		로그인에서 MFA(다단계 인증)를 사용할 때 Duo에서 제공되는 암호입니다.
private_key		인증에서 사용할 개인 키입니다. 자세한 내용은 키 페어 인증 및 키 페어 순환 사용하기 섹션을 참조하십시오.
private_key_file		지정된 사용자에 대한 개인 키 파일의 경로를 지정합니다. 키 페어 인증 및 키 페어 순환 사용하기 섹션을 참조하십시오.
private_key_file_pwd		지정된 사용자의 개인 키 파일을 해독하기 위한 암호 구문을 지정합니다. 키 페어 인증 및 키 페어 순환 사용하기 섹션을 참조하십시오.
autocommit		기본적으로 None 이며, Snowflake 매개 변수 AUTOCOMMIT 을 따릅니다. 세션에서 자동 커밋 모드를 활성화 또는 비활성화하려면 각각 True 또는 False 로 설정합니다.
client_prefetch_threads		결과 세트를 다운로드하기 위해 사용되는 스레드 수(기본적으로 4)입니다. 값을 늘리면 페치 성능이 향상되지만 메모리가 더 많이 필요합니다.
client_session_keep_alive		세션을 무한대로 활성으로 유지하려면(사용자의 활동이 없는 경우에도) 이 값을 True 로 설정합니다. 이 값을 True 로 설정하면 close 메서드가 호출되어 스레드가 올바르게 종료됩니다. 그렇지 않으면, 프로세스가 중단될 수 있습니다. 기본값은 사용 중인 커넥터의 버전에 따라 다릅니다. 버전 2.4.6 이상: 기본적으로 None 입니다. . 값이 None 인 경우 CLIENT_SESSION_KEEP_ALIVE 세션 매개 변수가 우선 순위를 갖습니다. . . 세션 매개 변수를 재정의하려면 이 인자에 True 또는 False 를 전달합니다. 버전 2.4.5 이전: 기본적으로 False 입니다. . 이 값이 False (값을 명시적으로 지정하거나 인자를 생략하여)인 경우 CLIENT_SESSION_KEEP_ALIVE 세션 매개 변수가 우선 순위를 갖습니다. . . connect 메서드에 client_session_keep_alive=False 를 전달해도 CLIENT_SESSION_KEEP_ALIVE 세션 매개 변수의 값 TRUE 를 재정의하지 않습니다.
login_timeout		로그인의 시간 제한(초)입니다. 기본적으로 60초입니다. HTTP 응답이 “성공”인 경우 시간 제한 길이 이후에는 로그인 요청이 수행되지 않습니다.
network_timeout		기타 모든 작업의 시간 제한(초)입니다. 기본적으로 없음/무한대입니다. HTTP 응답이 “성공”이 아닌 경우 시간 제한 길이 이후에는 일반 요청이 수행되지 않습니다.
ocsp_response_cache_filename		OCSP 응답 캐시 파일에 대한 URI입니다. 기본적으로 OCSP 응답 캐시 파일은 다음 캐시 디렉터리에 생성됩니다. Linux: ~/.cache/snowflake/ocsp_response_cache macOS: ~/Library/Caches/Snowflake/ocsp_response_cache Windows: %USERPROFILE%AppDataLocalSnowflakeCachesocsp_response_cache 다른 디렉터리에서 파일을 찾으려면, URI 에 경로와 파일 이름을 지정합니다(예: file:///tmp/my_ocsp_response_cache.txt).
authenticator		Snowflake용 인증자: 내부 Snowflake 인증자를 사용하려면 snowflake (기본값). 웹 브라우저 및 Okta, AD FS 또는 계정에 정의된 기타 모든 SAML 2.0 규격 ID 공급자(IdP)를 사용하여 인증하려면 externalbrowser. 기본 Okta를 통해 인증하려면 https://<okta_계정_이름>.okta.com (즉, Okta 계정의 URL 엔드포인트). OAuth를 사용하여 인증하려면 oauth. token 매개 변수를 지정하고 값을 OAuth 액세스 토큰으로 지정해야 합니다. MFA 토큰 캐싱을 사용하여 인증하려면 username_password_mfa. 자세한 내용은 MFA 토큰 캐싱을 사용하여 인증 도중 프롬프트 수 최소화하기 — 선택 사항 섹션을 참조하십시오. OAuth 2.0 Authorization Code 흐름을 사용하기 위한 OAUTH_AUTHORIZATION_CODE. OAuth 2.0 Client Credentials 흐름을 사용하기 위한 OAUTH_CLIENT_CREDENTIALS 이 값이 snowflake 가 아닌 경우, 사용자 및 비밀번호 매개 변수는 IdP의 로그인 자격 증명이어야 합니다.
validate_default_parameters		기본적으로 False 입니다. True 인 경우: 지정된 데이터베이스, 스키마 또는 웨어하우스가 없으면 예외가 발생합니다. 유효하지 않은 인자 이름 또는 잘못된 데이터 타입의 인자 값이 전달되면 stderr에 경고가 표시됩니다.
paramstyle		클라이언트측 바인딩의 경우 기본적으로 pyformat 입니다. qmark 또는 numeric 를 지정하여 서버측 바인딩의 바인딩 변수 형식을 변경합니다.
timezone		기본적으로 None 이며, Snowflake 매개 변수 TIMEZONE 을 따릅니다. 유효한 타임존(예: America/Los_Angeles)을 설정하여 세션 타임존을 설정합니다.
arrow_number_to_decimal		기본적으로 False 이며, 즉 NUMBER 열 값은 배정밀도 부동 소수점 숫자(float64)로 반환됩니다. . . fetch_pandas_all() 및 fetch_pandas_batches() 메서드를 호출할 때 DECIMAL 열 값을 10진수(decimal.Decimal)로 반환하려면 이 값을 True 로 설정합니다. . . 이 매개 변수는 Python용 Snowflake 커넥터의 2.4.3 버전에서 도입되었습니다.
socket_timeout		소켓 수준 읽기 및 연결 요청에 대한 시간 제한(초)입니다. 자세한 내용은 연결 시간 제한 관리하기 섹션을 참조하십시오.
backoff_policy		재시도 간 대기 시간을 정의하는 생성기 함수의 이름입니다. 자세한 내용은 재시도에 대한 연결 백오프 정책 관리하기 섹션을 참조하십시오.
enable_connection_diag		연결 진단 보고서를 생성하지 여부. 기본값은 False 입니다.
connection_diag_log_path		진단 보고서 위치에 대한 절대 경로입니다. enable_connection_diag 가 True 인 경우에만 사용됩니다. 기본값은 운영 체제의 기본 임시 디렉터리(예: Linux 또는 Mac의 경우 /tmp)입니다.
connection_diag_allowlist_path		SYSTEM$ALLOWLIST() 또는 SYSTEM$ALLOWLIST_PRIVATELINK() 의 출력이 포함된 JSON 파일의 절대 경로입니다. 연결에 정의된 사용자에게 시스템 허용 목록 함수를 실행할 권한이 없거나 계정 URL에 연결이 실패한 경우에만 필요합니다.
iobound_tpe_limit		preprocess_tpe 및 postprocess TPE(threadpool executor)의 크기입니다. 기본적으로 값은 파일 수와 CPU 코어 수 중 작은 쪽으로 설정됩니다.
unsafe_file_write		GET 명령을 사용하여 스테이지에서 다운로드한 파일에 할당할 파일 권한을 지정합니다. False (기본값)로 지정하면 파일 권한을 600 으로 설정하여 소유자만 파일에 액세스할 수 있습니다. True 를 지정하면 권한을 644 로 설정하여 소유자에게 읽기 및 쓰기 권한을 부여하고, 그 외 모든 사용자에게는 읽기 전용 권한을 부여할 수 있습니다. 자세한 내용은 데이터 다운로드하기 섹션을 참조하십시오.
oauth_client_id		client id 의 값은 Snowflake 통합을 위해 ID 공급자가 제공한 것입니다(Snowflake 보안 통합 메타데이터).
oauth_client_secret		client secret 의 값은 Snowflake 통합을 위해 ID 공급자가 제공한 것입니다(Snowflake 보안 통합 메타데이터).
oauth_authorization_url		드라이버에 인증 코드를 제공하는 ID 공급자 엔드포인트입니다. Snowflake를 ID 공급자로 사용하는 경우 이 값은 server 또는 account 매개 변수에서 파생됩니다.
oauth_token_request_url		드라이버에 액세스 토큰을 제공하는 ID 공급자 엔드포인트입니다. Snowflake를 ID 공급자로 사용하는 경우 이 값은 server 또는 account 매개 변수에서 파생됩니다.
oauth_scope		ID 공급자 승인 요청에서 요청된 범위입니다. 기본적으로 역할에서 파생됩니다. 여러 범위가 요구되는 경우 값은 공백으로 구분된 여러 범위의 목록이어야 합니다.
oauth_redirect_uri		인증 코드 리디렉션에 사용하는 URI (Snowflake 보안 통합 메타데이터)입니다. 기본값: http://127.0.0.1:{randomAvailablePort}/.
oauth_disable_pkce:		악의적인 공격자가 인증 코드를 가로채더라도 유효한 액세스 토큰으로 변경할 수 없도록 하는 보안 개선 사항인 PKCE (Proof Key for Code Exchange)를 비활성화합니다.
oauth_enable_refresh_token:		실제 액세스 토큰이 오래되었을 때 자동 재인증을 활성화합니다(인증 서버에서 지원되고 client_store_temporary_credential 이 True 로 설정되어 있는 경우).
oauth_enable_single_use_refresh_tokens:		일회용 새로 고침 토큰 시맨틱에 옵트인할지 여부입니다.

속성¶

Error, Warning, ...

Python 데이터베이스 API 표준에 의해 정의되는 모든 예외 클래스입니다. Python용 Snowflake 커넥터는 msg, errno, sqlstate, sfqid 및 raw_msg 속성을 제공합니다.

account 매개 변수에 대한 사용법 노트(connect 메서드용)¶

필수 account 매개 변수의 경우, 계정 식별자 를 지정합니다.

계정 식별자에는 snowflakecomputing.com 도메인 이름이 포함되지 않는다는 점에 유의하십시오. 연결을 생성할 때 Snowflake가 이 값을 자동으로 추가합니다.

다음 예에서는 조직 myorganization 의 계정 myaccount 에 대한 식별자로 계정 이름 을 사용합니다.

ctx = snowflake.connector.connect(
    user='<user_name>',
    password='<password>',
    account='myorganization-myaccount',
    ... )

다음 예에서는 계정 로케이터 xy12345 를 계정 식별자로 사용합니다.

ctx = snowflake.connector.connect(
    user='<user_name>',
    password='<password>',
    account='xy12345',
    ... )

이 예에서는 AWS US 서부(오레곤) 리전의 계정을 사용함에 유의하십시오. 계정이 다른 리전에 있거나 계정이 다른 클라우드 공급자를 사용하는 경우 계정 로케이터 다음에 추가 세그먼트를 지정 해야 합니다.

메서드¶

autocommit(True|False)¶

목적:

자동 커밋 모드를 활성화하거나 비활성화합니다. 기본적으로 자동 커밋은 활성화(True)됩니다.

close()¶

목적:

연결을 종료합니다. 연결이 종료되었을 때에도 여전히 트랜잭션이 연결되어 있으면 변경 사항이 롤백됩니다.

연결을 명시적으로 종료하면 서버에서 활성 세션이 제거되며, 그렇지 않으면 서버에서 삭제될 때까지 활성 세션이 유지되어, 동시 쿼리의 수가 제한됩니다.

예:

# context manager ensures the connection is closed
with snowflake.connector.connect(...) as con:
    con.cursor().execute(...)

# try & finally to ensure the connection is closed.
con = snowflake.connector.connect(...)
try:
    con.cursor().execute(...)
finally:
    con.close()

Copy

commit()¶

목적:

자동 커밋이 비활성화되면 현재 트랜잭션이 커밋됩니다. 자동 커밋이 활성화되면 이 메서드가 무시됩니다.

rollback()¶

목적:

자동 커밋이 비활성화되면 현재 트랜잭션이 롤백됩니다. 자동 커밋이 활성화되면 이 메서드가 무시됩니다.

cursor()¶

목적:

Cursor 오브젝트를 생성하기 위한 생성자입니다. fetch*() 호출의 반환 값은 단일 시퀀스 또는 시퀀스의 목록입니다.

cursor(snowflake.connector.DictCursor)

목적:

DictCursor 오브젝트를 생성하기 위한 생성자입니다. fetch*() 호출의 반환 값은 단일 dict 또는 dict 오브젝트의 목록입니다. 이 메서드는 결과에서 열 이름을 기준으로 값을 가져올 때 유용합니다.

execute_string(sql_text, remove_comments=False, return_cursors=True)¶

목적:

문자열로 전달되는 1개 이상의 SQL 문을 실행합니다. remove_comments 가 True 로 설정된 경우 쿼리에서 설명이 제거됩니다. return_cursors 가 True 로 설정된 경우 이 메서드는 실행 순서로 Cursor 오브젝트의 시퀀스를 반환합니다.

예:

이 예에서는 단일 문자열에서의 다중 명령 실행 및 반환되는 커서의 시퀀스 사용을 보여줍니다.

cursor_list = connection1.execute_string(
    "SELECT * FROM testtable WHERE col1 LIKE 'T%';"
    "SELECT * FROM testtable WHERE col2 LIKE 'A%';"
    )

for cursor in cursor_list:
   for row in cursor:
      print(row[0], row[1])

Copy

참고

단일 문자열에서 여러 SQL 문을 허용하는 execute_string() 등의 메서드는 SQL 삽입 공격에 취약합니다. 사용자 데이터의 유효성을 검사한 경우를 제외하고 사용자가 제공한 데이터와 SQL을 결합하여 SQL 문을 동적으로 구성하려면, 문자열 연결 또는 Python의 format() 등의 함수를 사용하지 마십시오. 아래 예는 문제를 보여줍니다.

# "Binding" data via the format() function (UNSAFE EXAMPLE)
value1_from_user = "'ok3'); DELETE FROM testtable WHERE col1 = 'ok1'; select pi("
sql_cmd = "insert into testtable(col1) values('ok1'); "                  \
          "insert into testtable(col1) values('ok2'); "                  \
          "insert into testtable(col1) values({col1});".format(col1=value1_from_user)
# Show what SQL Injection can do to a composed statement.
print(sql_cmd)

connection1.execute_string(sql_cmd)

Copy

동적으로 구성된 문은 다음과 같습니다(가독성을 위해 줄 바꿈이 추가됨).

insert into testtable(col1) values('ok1');
insert into testtable(col1) values('ok2');
insert into testtable(col1) values('ok3');
DELETE FROM testtable WHERE col1 = 'ok1';
select pi();

Copy

신뢰할 수 없는 사용자가 입력한 문자열과 SQL 문을 결합하는 경우에는 문자열을 구성하는 대신 데이터를 문에 바인딩하는 것이 안전합니다. execute_string() 메서드에서는 바인딩 매개 변수가 사용되지 않으므로 Cursor.execute() 또는 Cursor.executemany() 를 사용하여 매개 변수를 바인딩합니다.

execute_stream(sql_stream, remove_comments=False)¶

목적:

스트림 오브젝트로 전달된 1개 이상의 SQL 문을 실행합니다. remove_comments 가 True 로 설정된 경우 쿼리에서 설명이 제거됩니다. 이 생성기에서는 SQL 문이 실행될 때 각 Cursor 오브젝트가 생성됩니다.

sql_stream 이 주석 줄로 끝나는 경우 다음과 유사하게 remove_comments 를 True 로 설정해야 합니다.

sql_script = """
-- This is first comment line;
select 1;
select 2;
-- This is comment in middle;
-- With some extra comment lines;
select 3;
-- This is the end with last line comment;
"""
sql_stream = StringIO(sql_script)
with con.cursor() as cur:
        for result_cursor in con.execute_stream(sql_stream,remove_comments=True):
            for result in result_cursor:
                print(f"Result: {result}")

Copy

get_query_status(query_id)¶

목적:

쿼리의 상태를 반환합니다.

매개 변수:

query_id

쿼리의 ID입니다. Snowflake 쿼리 ID 검색하기 섹션을 참조하십시오.

반환:

쿼리의 상태를 나타내는 QueryStatus 오브젝트를 반환합니다.

예:

쿼리 상태 확인하기 섹션을 참조하십시오.

get_query_status_throw_if_error(query_id)¶

목적:

쿼리의 상태를 반환합니다. 쿼리 결과에 오류가 있는 경우 이 메서드에서는 ProgrammingError 가 발생합니다(execute() 메서드에서와 같이).

매개 변수:

query_id

쿼리의 ID입니다. Snowflake 쿼리 ID 검색하기 섹션을 참조하십시오.

반환:

쿼리의 상태를 나타내는 QueryStatus 오브젝트를 반환합니다.

예:

쿼리 상태 확인하기 섹션을 참조하십시오.

is_valid()¶

목적:

연결이 쿼리를 수신할 수 있을 만큼 안정적이면 True 를 반환합니다.

is_still_running(query_status)¶

목적:

쿼리 상태가 쿼리가 아직 완료되지 않음 또는 아직 진행 중으로 표시되면 True 가 반환됩니다.

매개 변수:

query_status

쿼리의 상태를 나타내는 QueryStatus 오브젝트입니다. 쿼리에 대한 이 오브젝트를 가져오려면, 쿼리 상태 확인하기 를 참조하십시오.

예:

쿼리 상태 확인하기 섹션을 참조하십시오.

is_an_error(query_status)¶

목적:

쿼리 상태가 쿼리에서 오류가 발생함으로 표시되면 True 가 반환됩니다.

매개 변수:

query_status

쿼리의 상태를 나타내는 QueryStatus 오브젝트입니다. 쿼리에 대한 이 오브젝트를 가져오려면, 쿼리 상태 확인하기 를 참조하십시오.

예:

쿼리 상태 확인하기 섹션을 참조하십시오.

속성¶

expired¶

연결의 마스터 토큰이 만료되었는지 여부를 추적합니다.

messages¶

이 연결에 대한 기본 데이터베이스로부터 수신된 모든 메시지에 대한 시퀀스(예외 클래스, 예외 값)를 포함하는 목록 오브젝트입니다.

목록은 메서드를 호출하면 자동으로 삭제됩니다.

errorhandler¶

오류 조건이 충족될 때 호출할 오류 처리기를 참조하는 읽기/쓰기 속성입니다.

이 처리기는 다음 인자를 허용하고 Python에서 호출할 수 있어야 합니다.

errorhandler(connection, cursor, errorclass, errorvalue)

Error, Warning, ...

Python 데이터베이스 API 표준에 의해 정의되는 모든 예외 클래스입니다.

메서드¶

close()

목적:

커서 오브젝트를 닫습니다.

describe(command [, parameters][, timeout][, file_stream])¶

목적:

데이터베이스 명령을 실행하지 않고 결과 세트에 대한 메타데이터를 반환합니다. 미 메서드는 쿼리를 실행한 후 description 속성에서 사용할 수 있는 동일한 메타데이터를 반환합니다.

이 메서드는 Python용 Snowflake 커넥터의 2.4.6 버전에서 도입되었습니다.

매개 변수:

execute() 메서드에 대한 매개 변수를 참조하십시오.

반환:

결과 세트의 열을 설명하는 ResultMetadata 오브젝트의 목록을 반환합니다.

예:

열 메타데이터 검색하기 섹션을 참조하십시오.

execute(command [, parameters][, timeout][, file_stream])¶

목적:

데이터베이스 명령을 준비하여 실행합니다.

매개 변수:

command

실행할 SQL 문이 포함된 문자열입니다.

parameters

(선택 사항) SQL 문에서 데이터 바인딩 을 위해 매개 변수를 사용한 경우, 이 값을 해당 매개 변수에 바인딩해야 하는 변수의 목록 또는 딕셔너리로 설정합니다.

변수에 대한 Python 데이터 타입을 해당 열의 SQL 데이터 타입으로 매핑하는 방법에 대한 자세한 내용은 qmark 및 numeric 바인딩용 데이터 타입 매핑 을 참조하십시오.

timeout

(선택 사항) 쿼리가 완료될 때까지 대기해야 하는 시간(초)입니다. 이 시간에 경과한 후에 쿼리가 완료되지 않으면 쿼리가 중단되어야 합니다.

file_stream

(선택 사항) PUT 명령을 실행할 때 이 매개 변수를 사용하여 파일 시스템의 파일이 아닌 인메모리 파일과 유사한 오브젝트(예: Python open() 함수에서 반환된 I/O 오브젝트)를 업로드할 수 있습니다. 이 매개 변수를 해당 I/O 오브젝트로 설정합니다.

PUT 명령에서 데이터 파일의 URI를 지정할 때:

• 사용자는 디렉터리 경로를 사용할 수 있습니다. URI에 지정하는 디렉터리 경로는 무시됩니다.

• 스테이지에서 생성해야 하는 파일의 이름을 파일 이름에 지정합니다.

예를 들어, 파일 스트림에서 다음 이름의 파일로 파일을 업로드하려면:

@mystage/myfile.csv

Copy

다음 호출 사용:

cursor.execute(
    "PUT file://this_directory_path/is_ignored/myfile.csv @mystage",
    file_stream=<io_object>)

Copy

반환:

Cursor 오브젝트의 참조를 반환합니다.

executemany(command, seq_of_parameters)¶

목적:

데이터베이스 명령을 준비하고 seq_of_parameters 의 모든 매개 변수 시퀀스에 대하여 실행합니다. 이 메서드를 사용하여 일괄 삽입 작업을 수행할 수 있습니다.

매개 변수:

command

명령은 실행될 코드가 포함된 문자열입니다. 문자열에는 데이터 바인딩하기 에 대한 1개 이상의 자리 표시자(예: 물음표)가 포함되어야 합니다.

예:

"insert into testy (v1, v2) values (?, ?)"

Copy

seq_of_parameters

이 매개 변수는 목록 또는 튜플의 시퀀스(목록 또는 튜플)여야 합니다. 예시 시퀀스는 아래의 예시 코드를 참조하십시오.

반환:

Cursor 오브젝트의 참조를 반환합니다.

예:

# This example uses qmark (question mark) binding, so
# you must configure the connector to use this binding style.
from snowflake import connector
connector.paramstyle='qmark'

stmt1 = "create table testy (V1 varchar, V2 varchar)"
cs.execute(stmt1)

# A list of lists
sequence_of_parameters1 = [ ['Smith', 'Ann'], ['Jones', 'Ed'] ]
# A tuple of tuples
sequence_of_parameters2 = ( ('Cho', 'Kim'), ('Cooper', 'Pat') )

stmt2 = "insert into testy (v1, v2) values (?, ?)"
cs.executemany(stmt2, sequence_of_parameters1)
cs.executemany(stmt2, sequence_of_parameters2)

Copy

내부적으로 여러 execute 메서드를 호출할 수 있으며 마지막 execute 호출의 결과 세트가 유지됩니다.

참고

executemany 메서드만을 사용하여 매개 변수가 있는 단일 SQL 문을 실행하고 여러 바인딩 값을 전달할 수 있습니다.

1개의 execute 호출에서 세미콜론으로 구분된 여러 SQL 문을 실행하는 기능은 지원되지 않습니다. 대신, 각 문에 별도의 execute 호출을 수행해야 합니다.

execute_async(...)¶

목적:

비동기 실행을 위한 데이터베이스 명령을 준비하여 제출해야 합니다. 비동기 쿼리 수행하기 섹션을 참조하십시오.

매개 변수:

이 메서드에서는 execute() 메서드와 동일한 매개 변수가 사용됩니다.

반환:

Cursor 오브젝트의 참조를 반환합니다.

예:

비동기 쿼리의 예 섹션을 참조하십시오.

fetch_arrow_all()¶

목적:

이 메서드는 커서에서 모든 행을 가져와 PyArrow 테이블로 로딩합니다.

매개 변수:

없습니다.

반환:

결과 세트에서 모든 행이 포함된 PyArrow 테이블을 반환합니다.

행이 없으면 None이 반환됩니다.

예:

Python용 Snowflake 커넥터로 결과를 가져오는 워크로드 분산하기 섹션을 참조하십시오.

fetch_arrow_batches()¶

목적:

이 메서드는 커서에서 행의 하위 세트를 가져와 PyArrow 테이블로 전달합니다.

매개 변수:

없습니다.

반환:

결과 세트에서 하위 세트가 포함된 PyArrow 테이블을 반환합니다.

가져올 행이 더 이상 없는 경우 None이 반환됩니다.

예:

Python용 Snowflake 커넥터로 결과를 가져오는 워크로드 분산하기 섹션을 참조하십시오.

get_result_batches()¶

목적:

결과 세트에서 행의 하위 세트를 가져오는 데 사용할 수 있는 ResultBatch 오브젝트의 목록을 반환합니다.

매개 변수:

없습니다.

반환:

ResultBatch 오브젝트의 목록을 반환하거나 쿼리가 실행을 마치지 않았다면 None 을 반환합니다.

예:

Python용 Snowflake 커넥터로 결과를 가져오는 워크로드 분산하기 섹션을 참조하십시오.

get_results_from_sfqid(query_id)¶

목적:

비동기 쿼리 도는 이전에 제출한 비동기 쿼리의 결과를 검색합니다.

매개 변수:

query_id

쿼리의 ID입니다. Snowflake 쿼리 ID 검색하기 섹션을 참조하십시오.

예:

쿼리 ID를 사용하여 쿼리 결과 검색하기 섹션을 참조하십시오.

fetchone()¶

목적:

쿼리 결과 세트의 다음 행을 가져오고 더 이상 사용할 수 있는 데이터가 없는 경우 단일 시퀀스/dict 또는 None 을 반환합니다.

fetchmany([size=cursor.arraysize])¶

목적:

쿼리 결과 세트의 다음 행을 가져오고 시퀀스/dict의 목록을 반환합니다. 사용할 수 있는 행이 더 이상 없는 경우에는 빈 시퀀스가 반환됩니다.

fetchall()¶

목적:

쿼리 결과 세트의 모든 또는 나머지 행을 가져오고 시퀀스/dict의 목록을 반환합니다.

fetch_pandas_all()¶

목적:

이 메서드는 커서에서 모든 행을 가져와 pandas DataFrame으로 로드합니다.

매개 변수:

없습니다.

반환:

결과 세트에서 모든 행이 포함된 DataFrame을 반환합니다.

pandas 데이터 프레임에 대한 자세한 내용은 pandas DataFrame 설명서를 참조하십시오.

행이 없으면 None 이 반환됩니다.

사용법 노트:

• 이 메서드는 pandas의 read_sql() 메서드를 완전하게 대체하지 않으며, 이 메서드를 사용하면 SELECT 쿼리에서 데이터를 가져와 데이터를 pandas DataFrame에 저장하는 작업을 빠르게 수행할 수 있습니다.

• 현재 이 메서드는 SELECT 문에서만 작동합니다.

예:

ctx = snowflake.connector.connect(
          host=host,
          user=user,
          password=password,
          account=account,
          warehouse=warehouse,
          database=database,
          schema=schema,
          protocol='https',
          port=port)

# Create a cursor object.
cur = ctx.cursor()

# Execute a statement that will generate a result set.
sql = "select * from t"
cur.execute(sql)

# Fetch the result set from the cursor and deliver it as the pandas DataFrame.
df = cur.fetch_pandas_all()

# ...

Copy

fetch_pandas_batches()¶

목적:

이 메서드는 커서에서 행의 하위 세트를 가져와 pandas DataFrame으로 전달합니다.

매개 변수:

없습니다.

반환:

결과 세트에서 하위 세트가 포함된 DataFrame을 반환합니다.

pandas 데이터 프레임에 대한 자세한 내용은 pandas DataFrame 설명서를 참조하십시오.

가져올 행이 더 이상 없는 경우 None 이 반환됩니다.

사용법 노트:

• 결과 세트의 행 수 및 메서드 호출에 지정된 행 수에 따라, 이 메서드를 두 번 이상 호출해야 하거나 모두 적합한 경우 단일 일괄 처리에서 모든 행을 반환해야 할 수 있습니다.

• 이 메서드는 pandas의 read_sql() 메서드를 완전하게 대체하지 않으며, 이 메서드를 사용하면 SELECT 쿼리에서 데이터를 가져와 데이터를 pandas DataFrame에 저장하는 작업을 빠르게 수행할 수 있습니다.

• 현재 이 메서드는 SELECT 문에서만 작동합니다.

예:

ctx = snowflake.connector.connect(
          host=host,
          user=user,
          password=password,
          account=account,
          warehouse=warehouse,
          database=database,
          schema=schema,
          protocol='https',
          port=port)

# Create a cursor object.
cur = ctx.cursor()

# Execute a statement that will generate a result set.
sql = "select * from t"
cur.execute(sql)

# Fetch the result set from the cursor and deliver it as the pandas DataFrame.
for df in cur.fetch_pandas_batches():
    my_dataframe_processing_function(df)

# ...

Copy

__iter__()¶

커서가 반복 프로토콜과 호환될 수 있도록 자체를 반환합니다.

속성¶

description¶

결과 세트의 열에 대한 메타데이터를 반환하는 읽기 전용 속성입니다.

이 속성은 쿼리를 실행하기 위해 execute() 메서드를 호출한 후에 설정됩니다. (2.4.6 이상 버전에서는 쿼리를 실행하지 않고 describe() 메서드를 호출하여 이 메타데이터를 가져올 수 있습니다.)

이 속성은 다음 중 하나로 설정됩니다.

• 2.4.5 이하 버전: 이 속성은 튜플의 목록으로 설정됩니다.

• 2.4.6 이상 버전: 이 속성은 ResultMetadata 오브젝트의 목록으로 설정됩니다.

각 튜플 또는 ResultMetadata 오브젝트에는 결과 세트의 열을 설명하는 메타데이터가 포함됩니다. 사용자는 인덱스를 기준으로 메타데이터에 액세스하거나 2.4.6 이상 버전의 경우 ResultMetadata 오브젝트 속성을 기준으로 액세스할 수 있습니다.

값의 인덱스	ResultMetadata 속성	설명
0	name	열 이름.
1	type_code	내부 타입 코드.
2	display_size	(사용되지 않음. 내부_크기와 동일.)
3	internal_size	내부 데이터 크기.
4	precision	숫자 데이터의 전체 자릿수.
5	scale	숫자 데이터의 소수 자릿수입니다.
6	is_nullable	열 또는 False 에서 NULL 값이 허용되는 경우 True.

이 속성을 가져오는 예는 열 메타데이터 검색하기 를 참조하십시오.

rowcount¶

생성된 마지막 execute 에서 행의 수를 반환하는 읽기 전용 속성입니다. execute 가 실행되지 않은 경우 값은 -1 또는 None 입니다.

sfqid¶

실행된 마지막 execute 또는 execute_async 에서 Snowflake 쿼리 ID를 반환하는 읽기 전용 속성입니다.

arraysize¶

fetchmany() 를 사용하여 한 번에 가져올 행의 수를 지정하는 읽기/쓰기 속성입니다. 기본값을 1 입니다. 즉, 한 번에 1개의 행을 가져옵니다.

connection¶

커서가 생성된 Connection 오브젝트에 대한 참조를 반환하는 읽기 전용 속성입니다.

messages

커서에 대한 기본 데이터베이스로부터 수신된 모든 메시지에 대한 시퀀스를 포함하는 오브젝트(예외 클래스, 예외 값)를 나열합니다.

fetch*() 호출을 제외하고 목록은 메서드를 호출하면 자동으로 삭제됩니다.

errorhandler

오류 조건이 충족될 때 호출할 오류 처리기를 참조하는 읽기/쓰기 속성입니다.

이 처리기는 다음 인자를 허용하고 Python에서 호출할 수 있어야 합니다.

errorhandler(connection, cursor, errorclass, errorvalue)

유형 코드¶

Cursor 오브젝트에서 description 속성 및 describe() 메서드는 결과 세트의 열을 설명하는 튜플의 목록(또는 2.4.6 이상 버전의 경우 ResultMetadata 오브젝트)을 제공합니다.

튜플에서 인덱스 1 의 값(ResultMetadata 오브젝트의 type_code 속성)은 열 데이터 타입을 나타냅니다. Python용 Snowflake 커넥터에서 타입 코드에 따라 문자열 표현을 가져오기 위해 사용하는 매핑은 다음과 같습니다.

qmark 및 numeric 바인딩용 데이터 타입 매핑¶

paramstyle 이 "qmark" 또는 "numeric" 인 경우에는 Python에서 Snowflake 데이터 타입으로 다음과 같은 기본 매핑이 사용됩니다.

다른 Snowflake 타입으로 매핑(예: datetime 을 TIMESTAMP_LTZ 로)해야 하는 경우에는 Snowflake 데이터 타입 다음에 값이 오는 형식으로 구성된 튜플로 Snowflake 데이터 타입을 지정합니다. 예는 TIMESTAMP를 사용한 날짜/시간 바인딩 을 참조하십시오.

메서드¶

Exception 오브젝트용으로 사용할 수 있는 메서드는 없습니다.

속성¶

errno¶

Snowflake DB 오류 코드입니다.

msg¶

오류 코드, SQL 상태 코드 및 쿼리 ID 등의 오류 메시지입니다.

raw_msg¶

오류 메시지입니다. 오류 코드, SQL 상태 코드 또는 쿼리 ID가 포함되지 않습니다.

sqlstate¶

ANSI 규격 SQL 상태 코드입니다

sfqid

Snowflake 쿼리 ID입니다.

속성¶

메서드¶

to_arrow()¶

목적:

이 메서드는 ResultBatch 오브젝트의 행을 포함하는 PyArrow 테이블을 반환합니다.

매개 변수:

없습니다.

반환:

ResultBatch 오브젝트에서 행을 포함하는 PyArrow 테이블을 반환합니다.

행이 없으면 None이 반환됩니다.

to_pandas()¶

목적:

이 메서드는 ResultBatch 오브젝트의 행을 포함하는 pandas DataFrame을 반환합니다.

매개 변수:

없습니다.

반환:

ResultBatch 오브젝트에서 행을 포함하는 pandas DataFrame을 반환합니다.

행이 없으면 빈 pandas DataFrame을 반환합니다.

메서드¶

없습니다.

속성¶

name¶

열의 이름

type_code¶

내부 타입 코드.

display_size¶

사용되지 않습니다. 내부_크기와 동일합니다.

internal_size¶

내부 데이터 크기.

precision¶

숫자 데이터의 전체 자릿수.

scale¶

숫자 데이터의 소수 자릿수입니다.

is_nullable¶

열 또는 False 에서 NULL 값이 허용되는 경우 True.

열거형¶

class QueryStatus¶

비동기 쿼리의 상태를 나타냅니다. 이 열거형에 포함되는 상수는 다음과 같습니다.

열거형 상수	설명
RUNNING	쿼리를 아직 실행하는 중입니다.
ABORTING	서버 측에서 쿼리를 중단하는 중입니다.
SUCCESS	쿼리가 성공적으로 종료되었습니다.
FAILED_WITH_ERROR	쿼리가 종료되었지만 실패했습니다.
QUEUED	실행을 위해 쿼리가 큐에서 대기 중이며(즉, 아직 실행이 시작되지 않음), 이러한 일반적인 이유는 리소스를 대기 중이기 때문입니다.
DISCONNECTED	세션의 연결이 끊겼습니다. 쿼리의 상태가 곧 “FAILED_WITH_ERROR”로 변경됩니다.
RESUMING_WAREHOUSE	웨어하우스가 시작되었지만 아직 쿼리가 실행 중이 아닙니다.
BLOCKED	문이 다른 문이 잠근 리소스를 대기하고 있습니다.
NO_DATA	문에 대한 데이터를 아직 사용할 수 없습니다. 이러한 일반적인 이유는 문의 실행이 아직 시작되지 않았기 때문입니다.

함수¶

write_pandas(parameters...)¶

목적:

pandas DataFrame을 Snowflake 데이터베이스의 테이블에 작성합니다.

데이터를 테이블에 작성하려면, 이 함수는 데이터를 Parquet 파일에 저장하고 PUT 명령을 사용하여 이러한 파일을 임시 스테이지에 업로드하며 COPY INTO <테이블> 명령을 사용하여 파일에서 테이블로 데이터를 복사합니다. 일부 함수 매개 변수를 사용하여 PUT 및 COPY INTO <테이블 > 문의 실행 방법을 제어할 수 있습니다.

매개 변수:

유효한 입력 매개 변수:

매개 변수	필수	설명
conn	예	Snowflake 데이터베이스로의 연결을 유지하는 Connection 오브젝트입니다.
df	예	테이블로 복사될 데이터가 포함된 pandas.DataFrame 오브젝트입니다.
table_name	예	데이터를 복사할 테이블의 이름입니다.
database		테이블이 포함된 데이터베이스의 이름입니다. 기본적으로 이 함수는 현재 세션에서 사용 중인 데이터베이스에 작성합니다. 참고: 이 매개 변수를 지정하면 schema 매개 변수도 지정해야 합니다.
schema		테이블이 포함된 스키마의 이름입니다. 기본적으로 이 함수는 현재 세션에서 사용 중인 스키마에 테이블을 작성합니다.
chunk_size		한 번에 삽입할 요소의 이름입니다. 기본적으로 이 함수는 1개 청크에 한 번에 모든 요소를 삽입합니다.
compression		Parquet 파일에서 사용할 압축 알고리즘입니다. 압축을 향상하기 위해 "gzip" 을 지정하거나 빠른 압축을 위해 "snappy" 를 지정할 수 있습니다. 기본적으로, 이 함수에서는 "gzip" 을 사용합니다.
on_error		오류가 처리되는 방법을 지정합니다. ON_ERROR 복사 옵션 에 설명된 문자열 값 중 1개로 이 값을 설정합니다. 기본적으로, 이 함수에서는 "ABORT_STATEMENT" 를 사용합니다.
parallel		Parquet 파일을 임시 스테이지로 업로드할 때 사용할 스레드의 개수입니다. 사용되는 스레드의 기본 개수와 스레드 개수를 선택할 때의 지침은 PUT 명령의 병렬 매개 변수 를 참조하십시오.
quote_identifiers		False 인 경우, 커넥터는 식별자를 큰따옴표로 묶지 않고 식별자를 서버로 전송합니다. 기본적으로 커넥터는 식별자를 큰따옴표로 묶습니다.

반환:

(success, num_chunks, num_rows, output) 의 튜플을 반환합니다. 여기서,

• 함수에서 데이터를 테이블에 작성하는 데 성공하면 success 은 True 입니다.

• num_chunks 는 함수에서 복사한 데이터 청크의 수입니다.

• num_rows 는 함수에서 삽입한 행의 수입니다.

• output 은 COPY INTO <테이블> 명령의 출력입니다.

예:

다음 예에서는 pandas DataFrame에서 ‘고객’ 테이블로 데이터를 작성합니다.

import pandas
from snowflake.connector.pandas_tools import write_pandas

# Create the connection to the Snowflake database.
cnx = snowflake.connector.connect(...)

# Create a DataFrame containing data about customers
df = pandas.DataFrame([('Mark', 10), ('Luke', 20)], columns=['name', 'balance'])

# Write the data from the DataFrame to the table named "customers".
success, nchunks, nrows, _ = write_pandas(cnx, df, 'customers')

Copy

pd_writer(parameters...)¶

목적:

pd_writer 는 데이터를 Snowflake 데이터베이스로 삽입하기 위한 insertion 메서드입니다.

pandas.DataFrame.to_sql 을 호출할 때, method=pd_writer 를 전달하여 pd_writer 를 데이터 삽입 방법으로 사용하도록 지정합니다. (코드에서 pd_writer 를 호출할 필요가 없습니다. to_sql 메서드는 pd_writer 를 호출하며 필요한 입력 매개 변수를 제공합니다.)

자세한 내용은 다음을 참조하십시오.

• 삽입 메서드 설명서.

• pandas 설명서.

참고

pandas DataFrame 의 열 이름에 소문자만 포함된 경우 열 이름을 큰따옴표로 묶어야 합니다. 그렇지 않으면 커넥터가 ProgrammingError 를 발생시킵니다.

snowflake-sqlalchemy 라이브러리는 테이블을 생성할 때 소문자 열 이름을 따옴표로 묶지 않는 반면, pd_writer 는 기본적으로 열 이름을 따옴표로 묶습니다. COPY INTO 명령에서 열 이름이 당연히 따옴표로 묶일 것으로 예상하기 때문에 이 문제가 발생합니다.

향후 개선 사항은 snowflake-sqlalchemy 라이브러리에서 제공할 예정입니다.

예:

import pandas as pd
from snowflake.connector.pandas_tools import pd_writer

sf_connector_version_df = pd.DataFrame([('snowflake-connector-python', '1.0')], columns=['NAME', 'NEWEST_VERSION'])

# Specify that the to_sql method should use the pd_writer function
# to write the data from the DataFrame to the table named "driver_versions"
# in the Snowflake database.
sf_connector_version_df.to_sql('driver_versions', engine, index=False, method=pd_writer)

# When the column names consist of only lower case letters, quote the column names
sf_connector_version_df = pd.DataFrame([('snowflake-connector-python', '1.0')], columns=['"name"', '"newest_version"'])
sf_connector_version_df.to_sql('driver_versions', engine, index=False, method=pd_writer)

Copy

pd_writer 함수에서는 write_pandas() 함수를 사용하여 DataFrame의 데이터를 Snowflake 데이터베이스로 작성합니다.

매개 변수:

유효한 입력 매개 변수:

매개 변수	필수	설명
table	예	테이블을 위한 pandas.io.sql.SQLTable 오브젝트입니다.
conn	예	Snowflake 데이터베이스로 연결하기 위해 사용된 sqlalchemy.engine.Engine 또는 sqlalchemy.engine.Connection 오브젝트입니다.
keys	예	삽입할 데이터에 대한 테이블 열의 이름입니다.
data_iter	예	삽입할 데이터가 포함된 행의 반복기입니다.

예:

다음 예에서는 method=pd_writer 를 pandas.DataFrame.to_sql 메서드로 전달하고, 이 메서드는 pd_writer 함수를 호출하여 pandas DataFrame의 데이터를 Snowflake 데이터베이스에 작성합니다.

import pandas
from snowflake.connector.pandas_tools import pd_writer

# Create a DataFrame containing data about customers
df = pandas.DataFrame([('Mark', 10), ('Luke', 20)], columns=['name', 'balance'])

# Specify that the to_sql method should use the pd_writer function
# to write the data from the DataFrame to the table named "customers"
# in the Snowflake database.
df.to_sql('customers', engine, index=False, method=pd_writer)

Copy

데이터 가져오기¶

날짜 및 시간 데이터를 가져올 때 Snowflake 데이터 타입이 Python 데이터 타입으로 변환됩니다.

데이터 업데이트하기¶

날짜 및 시간 데이터를 업데이트할 때 Python 데이터 타입이 Snowflake 데이터 타입으로 변환됩니다.