Snowflake Python APIs: conceitos gerais¶
O modelo de programação do Snowflake Python APIs é baseado em recurso, o que significa que as APIs consistem em um conjunto de objetos que representam suas respectivas contrapartes de objeto no Snowflake. Alguns exemplos básicos de tipos de objeto de recurso do Snowflake incluem o seguinte:
Bancos de dados
Esquemas
Tabelas
Exibições
Alertas
Canais
Estágios
Usuários
Warehouses
Para cada recurso compatível, a API Python fornece três classes distintas com as quais você pode interagir:
Ponto de entrada: O objeto Root¶
O objeto Root é o ponto de entrada para a API Python. É possível criar uma instância de Root configurada com o contexto do Snowflake no qual ela será executada, usando um objeto Connection Python Connector ou um objeto Session Snowpark.
Por exemplo, o código a seguir instancia um objeto Root com um objeto Connection nomeado my_connection:
from snowflake.core import Root
root = Root(my_connection)
Ou você pode instanciar um objeto Root com um objeto Session. Em um ambiente de notebook ou procedimento armazenado, você pode recuperar a sessão usando get_active_session() da seguinte forma:
from snowflake.core import Root
from snowflake.snowpark.context import get_active_session
session = get_active_session()
root = Root(session)
Escopos de conta, banco de dados e esquema¶
Com um objeto Root, é possível acessar as coleções de objetos com escopo de conta, como warehouses (root.warehouses), bancos de dados (root.databases) e volumes externos (root.external_volumes).
É possível acessar objetos com escopo de banco de dados em um DatabaseResource, que, por sua vez, podem ser recuperados através do objeto DatabaseCollection em Root. Atualmente, SchemaCollection é o único tipo de objeto disponível no escopo do banco de dados.
É possível acessar objetos com escopo de esquema, como tabelas, exibições, fluxos e estágios, por meio do objeto SchemaResource.
Por exemplo, o código a seguir acessa primeiro um StageCollection e depois um StageResource:
root = Root(my_connection)
stages = root.databases["my_db"].schemas["my_schema"].stages
my_stage = stages["my_stage"] # Access the "my_stage" StageResource
Diagrama de classe snowflake.core¶
O diagrama a seguir mostra algumas classes básicas no pacote snowflake.core e como elas se relacionam entre si, começando com o objeto Root.
Classe de coleção¶
As classes Collection correspondem às classes nomeadas <SnowflakeObjectType>Collection.
Uma classe Collection representa o conjunto de um tipo de objeto específico visível dentro do contexto fornecido. Para objetos com escopo de esquema (como tabelas, exibições, funções e fluxos), a coleção consiste em todos os objetos desse tipo dentro do esquema fornecido que são visíveis para a função ou usuário atual.
Objetos SchemaCollection estão no escopo de um banco de dados, e objetos no escopo da conta, como WarehouseCollection, são acessíveis diretamente da instância Root.
Em geral, as coleções permitem que você faça o seguinte:
Crie um objeto no esquema, banco de dados ou conta (dependendo do escopo e do contexto, conforme descrito anteriormente).
Itere pelo conjunto de objetos visíveis nesse escopo.
Por exemplo, o código a seguir cria um novo warehouse usando um objeto WarehouseCollection:
# my_wh is created from scratch
my_wh = Warehouse(name="my_wh", warehouse_size="X-Small")
root.warehouses.create(my_wh)
Recuperação de um objeto Resource de uma coleção¶
Além disso, as coleções fornecem um ponto de entrada para recuperar objetos Resource específicos no banco de dados Snowflake subjacente ao qual a API está conectada. Use o operador de índice de colchetes ([ ]) em uma coleção para “apontar” ou obter uma referência a um objeto Snowflake dentro dessa coleção.
Por exemplo, o código a seguir recupera uma referência a um warehouse existente nomeado my_wh em sua conta Snowflake:
# 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"]
Classe de modelo¶
As classes de modelo simplesmente têm os mesmos nomes que seus recursos equivalentes no Snowflake, como Warehouse para warehouses e Table para tabelas.
Uma classe de modelo representa um objeto Snowflake junto com suas propriedades associadas, como seu nome, o banco de dados e o esquema ao qual ele pertence (se aplicável) e atributos específicos para esse tipo de objeto. Por exemplo, um modelo de warehouse indica as propriedades warehouse_size, type e auto_resume para aquele objeto de warehouse específico.
Objetos de modelo contêm um “conjunto de propriedades” (uma coleção de propriedades e seus valores) que descreve coletivamente o objeto. É possível usar essas propriedades para descrever um objeto existente no Snowflake ou para fornecer a especificação desse recurso para alterar um objeto existente.
Busca do objeto modelo de um Resource¶
Para retornar o conjunto de propriedades de um objeto como ele existe atualmente em seu banco de dados Snowflake, você executa uma operação fetch() no objeto Resource.
Por exemplo, o código a seguir demonstra algumas operações que é possível executar usando um objeto de modelo:
# 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)
Nota
Esta operação de busca falhará se o objeto my_wh não existir no Snowflake.
Classe de recurso¶
As classes Resource correspondem às classes nomeadas <SnowflakeObjectType>Resource.
É possível considerar um objeto Resource como um ponteiro ou referência para um objeto Snowflake subjacente. Enquanto a classe do modelo é um simples conjunto de propriedades que representa as propriedades ou especificações de um objeto, a classe Resource é uma referência ao objeto real em seu banco de dados Snowflake.
Para obter um objeto Resource, você normalmente se refere a ele pelo nome de sua Collection correspondente, usando o operador de índice de colchetes ([ ]). O exemplo de código a seguir recupera um warehouse existente nomeado my_wh da coleção de warehouse:
# 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()
Para converter um objeto Resource em seu modelo correspondente, execute um fetch() no recurso – isso recupera as propriedades do objeto correspondente no Snowflake. Observe que esta operação de busca falhará se o objeto não existir de fato no Snowflake.
Execução de operações específicas de tipo em um objeto Resource¶
A classe Resource também implementa as operações de API especializadas do tipo de objeto. Por exemplo, você usa um objeto WarehouseResource para retomar um warehouse ou um objeto StageResource para listar os arquivos em um estágio.
Os exemplos de código a seguir mostram como executar essas operações específicas de tipo usando seus respectivos objetos 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)
Como usar a API create_or_alter¶
Os objetos Resource também expõem o método da API create_or_alter se ele for compatível com o recurso. Este método permite que você, como o nome sugere, crie ou altere objetos Snowflake.
Nota
O API Python usa esse mecanismo de criar ou alterar (COA) para modificar objetos no Snowflake. O objetivo desse mecanismo é garantir que o resultado de uma operação COA seja o mesmo, independentemente de esse objeto específico já existir em seu banco de dados Snowflake.
Em outras palavras, se o objeto não existisse anteriormente, a operação COA criaria um com a especificação fornecida; se já existisse, a operação alteraria o objeto existente para corresponder à especificação solicitada. Essa lógica permite que você crie ou altere recursos usando um único trecho de código de maneira idempotente e atômica.
Padrão de design consistente para gerenciar recursos¶
O Snowflake Python APIs tem um padrão de design consistente que você usa para gerenciar recursos no Snowflake. Considere um cenário de exemplo em que você precisa alterar um objeto de warehouse existente em sua conta. As etapas a seguir descrevem como você normalmente trabalha com o padrão de design da API para fazer isso, usando todos os três tipos de classe conforme descrito anteriormente.
1. Obtenha uma WarehouseCollection de Root¶
Os warehouses são objetos com escopo de conta que você pode acessar diretamente de Root:
my_warehouses = root.warehouses # my_warehouses is a WarehouseCollection
2. Obtenha um objeto de WarehouseResource de WarehouseCollection¶
Para recuperar um objeto Resource, normalmente você começa com sua coleção. Os objetos Collection fornecem um ponto de entrada para recuperar recursos específicos no banco de dados Snowflake subjacente usando o operador de índice de colchetes ([ ]):
my_wh_ref = my_warehouses.warehouses["my_wh"] # my_wh_ref is a WarehouseResource
3. Obtenha o modelo de Warehouse de WarehouseResource¶
Usando o objeto WarehouseResource, você busca o modelo de Warehouse correspondente e suas propriedades do Snowflake:
my_wh = my_wh_ref.fetch() # my_wh is a Warehouse model object
4. Modifique uma propriedade no modelo Warehouse¶
Em seguida, você modifica uma propriedade, como warehouse_size, em seu modelo de warehouse:
my_wh.warehouse_size = "X-Small"
5. Altere o objeto de warehouse existente no Snowflake¶
Por fim, usando sua especificação de modelo de warehouse modificada, você altera o objeto de warehouse existente no Snowflake (ou cria o objeto de warehouse se ele não existir):
my_wh_ref.create_or_alter(my_wh) # Use the WarehouseResource to perform create_or_alter
Usando essa referência de my_wh_ref, também é possível executar outras operações no objeto no Snowflake, como descartá-lo, se necessário.
Exemplo de código completo¶
O exemplo de código a seguir mostra a operação de criar-ou-alterar do warehouse na íntegra:
# 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