Snowflake Python APIs: 일반 개념¶
Snowflake Python APIs 의 프로그래밍 모델은 리소스 기반 이며, 이는 APIs가 Snowflake에서 해당 오브젝트를 나타내는 오브젝트 집합으로 구성된다는 의미입니다. Snowflake 리소스 오브젝트 유형의 몇 가지 기본적인 예는 다음과 같습니다.
데이터베이스
스키마
테이블
뷰
경고
파이프
스테이지
사용자
웨어하우스
지원되는 각 리소스에 대해 Python API는 인터페이스할 수 있는 세 가지 클래스를 제공합니다.
진입점: Root
오브젝트¶
Root
오브젝트는 Python API의 진입점입니다. Python 커넥터 Connection
오브젝트 또는 Snowpark Session
오브젝트를 사용하여 실행할 Snowflake 컨텍스트로 구성된 Root
인스턴스를 생성합니다.
예를 들어, 다음 코드는 이름이 my_connection
인 Connection
오브젝트로 Root
오브젝트를 인스턴스화합니다.
from snowflake.core import Root
root = Root(my_connection)
또는 Session
오브젝트로 Root
오브젝트를 인스턴스화할 수 있습니다. 노트북 환경 또는 저장 프로시저에서는 다음과 같이 get_active_session()
을 사용하여 세션을 검색합니다.
from snowflake.core import Root
from snowflake.snowpark.context import get_active_session
session = get_active_session()
root = Root(session)
계정, 데이터베이스 및 스키마 범위¶
Root
오브젝트를 사용하면 웨어하우스(root.warehouses
), 데이터베이스(root.databases
), 외부 볼륨(root.external_volumes
)과 같은 계정 범위 지정 오브젝트의 컬렉션에 액세스할 수 있습니다.
DatabaseResource
아래에서 데이터베이스 범위 오브젝트에 액세스할 수 있으며, Root
아래에서 DatabaseCollection
오브젝트를 통해 검색할 수 있습니다. 현재, SchemaCollection
은 데이터베이스 범위에서 사용할 수 있는 유일한 오브젝트 유형입니다.
테이블, 뷰, 스트림, 스테이지와 같은 스키마 범위 지정 오브젝트에 SchemaResource
오브젝트를 통해 액세스할 수 있습니다.
예를 들어, 다음 코드는 StageCollection
에 먼저 액세스한 다음 StageResource
에 액세스합니다.
root = Root(my_connection)
stages = root.databases["my_db"].schemas["my_schema"].stages
my_stage = stages["my_stage"] # Access the "my_stage" StageResource
snowflake.core
클래스 다이어그램¶
다음 다이어그램은 snowflake.core
패키지의 몇 가지 기본 클래스와 이들이 서로 어떻게 연관되는지 Root
오브젝트부터 보여줍니다.
컬렉션 클래스¶
Collection
클래스는 이름이 <SnowflakeObjectType>Collection
인 클래스에 해당합니다.
Collection
클래스는 주어진 컨텍스트 내에서 표시되는 특정 오브젝트 유형의 집합을 나타냅니다. 스키마 범위 오브젝트(예: 테이블, 뷰, 함수, 스트림)의 경우 컬렉션은 현재 역할이나 사용자에게 표시되는 지정된 스키마 내의 해당 유형의 모든 오브젝트로 구성됩니다.
SchemaCollection
오브젝트는 데이터베이스에 범위가 지정되며, Root
같은 계정 범위 오브젝트는 WarehouseCollection
인스턴스에서 직접 액세스할 수 있습니다.
일반적으로 컬렉션을 사용하면 다음을 수행할 수 있습니다.
스키마, 데이터베이스 또는 계정에 오브젝트를 생성합니다(이전에 설명한 범위 및 컨텍스트에 따라 다름).
해당 범위에서 볼 수 있는 오브젝트 세트를 반복합니다.
예를 들어, 다음 코드는 WarehouseCollection
오브젝트를 사용하여 새 웨어하우스를 생성합니다.
# my_wh is created from scratch
my_wh = Warehouse(name="my_wh", warehouse_size="X-Small")
root.warehouses.create(my_wh)
컬렉션에서 Resource
오브젝트 검색하기¶
또한 컬렉션은 Resource
가 연결된 기본 Snowflake 데이터베이스에서 특정 API 오브젝트를 검색할 수 있는 진입점을 제공합니다. 컬렉션에서 대괄호 인덱스 연산자([ ]
)를 사용하여 해당 컬렉션 내의 Snowflake 오브젝트를 “가리키거나” 참조를 가져올 수 있습니다.
예를 들어, 다음 코드는 Snowflake 계정의 my_wh
라는 기존 웨어하우스에 대한 참조를 검색합니다.
# my_wh_ref is retrieved from an existing warehouse
# This returns a WarehouseResource object, which is a reference to a warehouse named "my_wh" in your Snowflake account
my_wh_ref = root.warehouses["my_wh"]
모델 클래스¶
모델 클래스의 이름은 단순히 웨어하우스의 경우 Warehouse
, 테이블의 경우 Table
같이 Snowflake에서 해당 리소스와 동일한 이름을 갖습니다.
모델 클래스는 이름, 해당 오브젝트가 속한 데이터베이스 및 스키마(해당되는 경우), 해당 오브젝트 유형에 특정한 특성 등 관련 속성과 함께 Snowflake 오브젝트를 나타냅니다. 예를 들어, 웨어하우스 모델은 특정 웨어하우스 오브젝트에 대한 warehouse_size
, type
, auto_resume
속성을 나타냅니다.
모델 오브젝트에는 오브젝트를 전체적으로 설명하는 “속성 백”(속성과 해당 값의 컬렉션)이 포함되어 있습니다. 이러한 속성을 사용하여 Snowflake의 기존 오브젝트를 설명하거나 기존 오브젝트를 변경할 해당 리소스의 사양을 제공할 수 있습니다.
Resource
에서 모델 오브젝트 가져오기¶
현재 Snowflake 데이터베이스에 존재하는 오브젝트의 속성 백을 반환하려면 Resource
오브젝트에 대해 fetch()
작업을 실행합니다.
예를 들어, 다음 코드는 모델 오브젝트를 사용하여 수행할 수 있는 일부 작업을 보여줍니다.
# my_wh is fetched from an existing warehouse
my_wh = root.warehouses["my_wh"].fetch()
print(my_wh.name, my_wh.auto_resume)
# my_wh is fetched from an existing warehouse
my_wh = root.warehouses["my_wh"].fetch()
my_wh.warehouse_size = "X-Small"
root.warehouses["my_wh"].create_or_alter(my_wh)
참고
이 가져오기 작업은 my_wh
오브젝트가 Snowflake에 존재하지 않으면 실패합니다.
리소스 클래스¶
Resource
클래스는 이름이 <SnowflakeObjectType>Resource
인 클래스에 해당합니다.
Resource
오브젝트를 기본 Snowflake 오브젝트에 대한 포인터 또는 참조로 간주할 수 있습니다. 모델 클래스는 오브젝트의 속성이나 사양을 나타내는 단순한 속성 모음인 반면, Resource
클래스는 Snowflake 데이터베이스의 실제 오브젝트에 대한 참조입니다.
Resource
오브젝트를 가져오려면 일반적으로 대괄호 인덱스 연산자([ ]
)를 사용하여 해당 Collection
에서 이름으로 참조합니다. 다음 코드 예제는 웨어하우스 컬렉션에서 my_wh
라는 이름의 기존 웨어하우스를 검색합니다.
# my_wh_ref is retrieved from an existing warehouse
# This returns a WarehouseResource object, which is a reference to a warehouse named "my_wh" in your Snowflake account
my_wh_ref = root.warehouses["my_wh"]
# Fetch returns the properties of the object (returns a "Model" Warehouse object that represents that warehouse's properties)
wh_properties = my_wh_ref.fetch()
Resource
오브젝트를 해당 모델로 변환하려면 리소스에서 fetch()
를 수행하면 Snowflake에서 해당 오브젝트의 속성을 검색할 수 있습니다. 오브젝트가 실제로 Snowflake에 존재하지 않으면 이 가져오기 작업은 실패합니다.
Resource
오브젝트에서 유형별 작업 수행하기¶
Resource
클래스는 오브젝트 타입의 특수한 API 작업도 구현합니다. 예를 들어, WarehouseResource
오브젝트를 사용하여 웨어하우스를 재개하거나 StageResource
오브젝트를 사용하여 스테이지에 있는 파일을 나열할 수 있습니다.
다음 코드 예제는 각각의 Resource
오브젝트를 사용하여 이러한 유형별 작업을 수행하는 방법을 보여줍니다.
# my_wh_ref is retrieved from an existing warehouse
my_wh_ref = root.warehouses["my_wh"]
# Resume a warehouse using a WarehouseResource object
my_wh_ref.resume()
# my_stage is fetched from an existing stage
stage_ref = root.databases["my_db"].schemas["my_schema"].stages["my_stage"]
# Print file names and their sizes on a stage using a StageResource object
for file in stage_ref.list_files():
print(file.name, file.size)
create_or_alter
API 사용하기¶
Resource
오브젝트는 리소스에서 지원하는 경우 create_or_alter
API 메서드도 노출합니다. 이름에서 알 수 있듯이 이 방법을 사용하면 Snowflake 오브젝트를 생성하거나 변경할 수 있습니다.
참고
Python API는 이 생성-또는-변경(COA) 메커니즘을 사용하여 Snowflake의 오브젝트를 수정합니다. 이 메커니즘의 목적은 특정 오브젝트가 Snowflake 데이터베이스에 이미 존재했는지 여부에 관계없이 COA 작업의 결과가 동일하도록 보장하는 것입니다.
즉, 오브젝트가 기존에 존재하지 않았다면 COA 작업은 제공된 사양으로 오브젝트를 생성하고, 이미 존재했다면 요청된 사양과 일치하도록 기존 오브젝트를 변경하는 작업입니다. 이 논리를 사용하면 멱등적이고 원자적인 방식으로 단일 코드를 사용하여 리소스를 생성하거나 변경할 수 있습니다.
리소스 관리를 위한 일관된 디자인 패턴¶
Snowflake Python APIs 에는 Snowflake에서 리소스를 관리하는 데 사용하는 일관된 디자인 패턴이 있습니다. 계정의 기존 웨어하우스 오브젝트를 변경해야 하는 예제 시나리오를 생각해 보겠습니다. 다음 단계는 앞서 설명한 세 가지 클래스 유형을 모두 사용하여 API의 디자인 패턴으로 작업하는 일반적인 방법을 간략하게 설명합니다.
1. Root
에서 WarehouseCollection
가져오기¶
웨어하우스는 Root
에서 직접 액세스할 수 있는 계정 범위의 오브젝트입니다.
my_warehouses = root.warehouses # my_warehouses is a WarehouseCollection
2. WarehouseCollection
에서 WarehouseResource
오브젝트 가져오기¶
Resource
오브젝트를 검색하려면 일반적으로 해당 컬렉션부터 시작합니다. Collection
오브젝트는 대괄호 인덱스 연산자([ ]
)를 사용하여 기본 Snowflake 데이터베이스에서 특정 리소스를 검색할 수 있는 진입점을 제공합니다.
my_wh_ref = my_warehouses.warehouses["my_wh"] # my_wh_ref is a WarehouseResource
3. WarehouseResource
에서 Warehouse
모델 가져오기¶
WarehouseResource
오브젝트를 사용하여 해당 Warehouse
모델과 해당 속성을 Snowflake에서 가져옵니다.
my_wh = my_wh_ref.fetch() # my_wh is a Warehouse model object
4. Warehouse
모델에서 속성 수정하기¶
그런 다음 웨어하우스 모델에서 warehouse_size
같은 속성을 수정합니다.
my_wh.warehouse_size = "X-Small"
5. Snowflake에서 기존 웨어하우스 오브젝트 변경¶
마지막으로 수정된 웨어하우스 모델 사양을 사용하여 Snowflake의 기존 웨어하우스 오브젝트를 변경합니다(웨어하우스 오브젝트가 없으면 새로 생성합니다).
my_wh_ref.create_or_alter(my_wh) # Use the WarehouseResource to perform create_or_alter
이 my_wh_ref
참조를 사용하여 필요한 경우 Snowflake의 오브젝트에 대해 삭제와 같은 다른 작업을 수행할 수도 있습니다.
전체 코드 예제¶
다음 코드 예제는 처음부터 끝까지의 전체 웨어하우스 생성 또는 변경 작업을 보여줍니다.
# my_wh is fetched from an existing warehouse
my_warehouses = root.warehouses # my_warehouses is a WarehouseCollection
my_wh_ref = my_warehouses.warehouses["my_wh"] # my_wh_ref is a WarehouseResource
my_wh = my_wh_ref.fetch() # my_wh is a Warehouse model object
my_wh.warehouse_size = "X-Small"
my_wh_ref.create_or_alter(my_wh) # Use the WarehouseResource perform create_or_alter