Snowflake Python APIs : concepts généraux¶
Le modèle de programmation du Snowflake Python APIs est basé sur les ressources, ce qui signifie que les APIs se composent d’un ensemble d’objets qui représentent leurs homologues d’objets respectifs dans Snowflake. Voici quelques exemples de base de types d’objets de ressources Snowflake :
Bases de données
Schémas
Tables
Vues
Alertes
Canaux
Zones de préparation
Utilisateurs
Entrepôts virtuels
Pour chaque ressource prise en charge, l’API Python fournit trois classes distinctes avec lesquelles vous pouvez interagir :
Point d’entrée : l’objet Root¶
L’objet Root est le point d’entrée pour l’API Python. Vous créez une instance de Root qui est configurée avec le contexte Snowflake dans lequel il s’exécutera, en utilisant un objet de connecteur Python Connection ou un objet Session Snowpark.
Par exemple, le code suivant instancie un objet Root avec un objet Connection nommé my_connection :
from snowflake.core import Root
root = Root(my_connection)
Ou, vous pouvez instancier un objet Root avec un objet Session. Dans un environnement de Notebook ou une procédure stockée, vous récupérez la session en utilisant get_active_session() comme suit :
from snowflake.core import Root
from snowflake.snowpark.context import get_active_session
session = get_active_session()
root = Root(session)
Portées du compte, de la base de données et du schéma¶
Avec un objet Root, vous pouvez accéder aux collections d’objets de portée de compte, tels que les entrepôts (root.warehouses), bases de données (root.databases), et les volumes externes (root.external_volumes).
Vous pouvez accéder aux objets de portée de base de données sous un DatabaseResource, que vous pouvez ensuite récupérer via l’objet DatabaseCollection sous Root. Actuellement, SchemaCollection est le seul type d’objet disponible dans la portée de la base de données.
Vous pouvez accéder aux objets de portée de schéma, tels que les tables, les vues, les flux et les zones de préparation, via l’objet SchemaResource.
Par exemple, le code suivant accède à un StageCollection d’abord, et ensuite un StageResource :
root = Root(my_connection)
stages = root.databases["my_db"].schemas["my_schema"].stages
my_stage = stages["my_stage"] # Access the "my_stage" StageResource
diagramme de classe snowflake.core¶
Le diagramme suivant montre quelques classes de base dans le paquet snowflake.core et comment elles sont liées les unes aux autres, en commençant par l’objet Root.
Classe de collection¶
Les classes Collection correspondent aux classes nommées <SnowflakeObjectType>Collection.
Une classe Collection représente l’ensemble d’un type d’objet particulier visible dans le contexte donné. Pour les objets de portée de schéma (tels que les tables, les vues, les fonctions et les flux), la collection se compose de tous les objets de ce type dans le schéma donné qui sont visibles pour le rôle ou l’utilisateur actuel.
Les objets SchemaCollection sont limités à une base de données et les objets limités à un compte comme WarehouseCollection sont accessibles directement depuis l’instance Root.
En général, les collections vous permettent d’effectuer les opérations suivantes :
Créez un objet dans le schéma, la base de données ou le compte (selon la portée et le contexte comme décrit précédemment).
Parcourez l’ensemble des objets visibles dans cette portée.
Par exemple, le code suivant crée un nouvel entrepôt à l’aide d’un objet WarehouseCollection :
# my_wh is created from scratch
my_wh = Warehouse(name="my_wh", warehouse_size="X-Small")
root.warehouses.create(my_wh)
Récupération d’un objet Resource d’une collection¶
De plus, les collections fournissent un point d’entrée pour récupérer des objets Resource spécifiques dans la base de données Snowflake sous-jacente à laquelle l’API est connectée. Vous utilisez l’opérateur d’index entre crochets ([ ]) sur une collection pour « pointer » vers, ou obtenir une référence vers, un objet Snowflake dans cette collection.
Par exemple, le code suivant récupère une référence à un entrepôt existant nommé my_wh dans votre compte 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 modèle¶
Les classes de modèle portent simplement les mêmes noms que leurs ressources équivalentes dans Snowflake, telles que Warehouse pour les entrepôts et Table pour les tables.
Une classe de modèle représente un objet Snowflake ainsi que ses propriétés associées, telles que son nom, la base de données et le schéma auxquels il appartient (le cas échéant) et les attributs spécifiques à ce type d’objet. Par exemple, un modèle d’entrepôt indique les propriétés warehouse_size, type, et auto_resume pour cet objet d’entrepôt particulier.
Les objets de modèle contiennent un « sac de propriétés » (une collection de propriétés et de leurs valeurs) qui décrit collectivement l’objet. Vous pouvez utiliser ces propriétés pour décrire un objet existant dans Snowflake ou pour fournir la spécification de cette ressource afin de modifier un objet existant.
Récupération d’un objet modèle à partir d’un Resource¶
Pour renvoyer le sac de propriétés d’un objet tel qu’il existe actuellement dans votre base de données Snowflake, vous exécutez une opération fetch() sur l’objet Resource.
Par exemple, le code suivant illustre certaines opérations que vous pouvez effectuer à l’aide d’un objet de modèle :
# 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)
Note
Cette opération de récupération échoue si l’objet my_wh n’existe pas dans Snowflake.
Classe de ressources¶
Les classes Resource correspondent aux classes nommées <SnowflakeObjectType>Resource.
Vous pouvez envisager un objet Resource comme pointeur ou référence à un objet Snowflake sous-jacent. Alors que la classe de modèle est un simple sac de propriétés représentant les propriétés ou la spécification d’un objet, la classe Resource est une référence à l’objet réel dans votre base de données Snowflake.
Pour obtenir un objet Resource, vous y faites généralement référence par son nom correspondant Collection, en utilisant l’opérateur d’index entre crochets ([ ]). L’exemple de code suivant récupère un entrepôt existant nommé my_wh de la collection de l’entrepôt :
# 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()
Pour convertir un objet Resource en son modèle correspondant, effectuez une fetch() sur la ressource – cela récupère les propriétés de l’objet correspondant dans Snowflake. Notez que cette opération de récupération échoue si l’objet n’existe pas réellement dans Snowflake.
Exécution d’opérations spécifiques au type sur un objet Resource¶
La classe Resource implémente également les opérations d’API spécialisées de type d’objet. Par exemple, vous utilisez un objet WarehouseResource pour reprendre un entrepôt, ou un objet StageResource permettant de lister les fichiers sur une zone de préparation.
Les exemples de code suivants montrent comment effectuer ces opérations spécifiques au type en utilisant leurs objets 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)
Utilisation de l’API create_or_alter¶
Les objets Resource exposent également la méthode d’API create_or_alter si elle est prise en charge par la ressource. Cette méthode vous permet, comme son nom l’indique, de créer ou de modifier des objets Snowflake.
Note
L’API Python utilise ce mécanisme de création ou de modification (COA) des objets dans Snowflake. Le but de ce mécanisme est de garantir que le résultat d’une opération COA est le même, que cet objet particulier existe déjà ou non dans votre base de données Snowflake.
En d’autres termes, si l’objet n’existait pas auparavant, l’opération COA créerait un objet avec la spécification fournie ; s’il existait déjà, l’opération modifierait l’objet existant pour qu’il corresponde à la spécification demandée. Cette logique vous permet de créer ou de modifier des ressources en utilisant un seul morceau de code de manière idempotente et atomique.
Modèle de conception cohérent pour gérer les ressources¶
Les Snowflake Python APIs ont un modèle de conception cohérent que vous utilisez pour gérer les ressources dans Snowflake. Considérez un exemple de scénario dans lequel vous devez modifier un objet d’entrepôt existant dans votre compte. Les étapes suivantes décrivent comment vous travaillez généralement avec le modèle de conception de l’API pour ce faire, en utilisant les trois types de classe comme décrit précédemment.
1. Obtenez un WarehouseCollection depuis Root¶
Les entrepôts sont des objets de portée de compte auxquels vous pouvez accéder directement à partir de Root :
my_warehouses = root.warehouses # my_warehouses is a WarehouseCollection
2. Obtenez un objet WarehouseResource depuis WarehouseCollection¶
Pour récupérer un objet Resource, vous commencez généralement par sa collection. Les objets Collection fournissent un point d’entrée pour récupérer des ressources spécifiques dans la base de données Snowflake sous-jacente en utilisant l’opérateur d’index par crochets ([ ]) :
my_wh_ref = my_warehouses.warehouses["my_wh"] # my_wh_ref is a WarehouseResource
3. Récupérez le modèle Warehouse depuis WarehouseResource¶
En utilisant l’objet WarehouseResource , vous récupérez le modèle Warehouse correspondant et ses propriétés depuis Snowflake :
my_wh = my_wh_ref.fetch() # my_wh is a Warehouse model object
4. Modifiez une propriété dans le modèle Warehouse¶
Ensuite, vous modifiez une propriété, comme le warehouse_size, dans votre modèle d’entrepôt :
my_wh.warehouse_size = "X-Small"
5. Modifier l’objet d’entrepôt existant dans Snowflake¶
Enfin, en utilisant votre spécification de modèle d’entrepôt modifiée, vous modifiez l’objet d’entrepôt existant dans Snowflake (ou créez l’objet d’entrepôt s’il n’existe pas) :
my_wh_ref.create_or_alter(my_wh) # Use the WarehouseResource to perform create_or_alter
En utilisant cette référence my_wh_ref, vous pouvez également effectuer d’autres opérations sur l’objet dans Snowflake, comme le supprimer, si nécessaire.
Exemple de code complet¶
L’exemple de code suivant montre l’opération de création ou de modification d’entrepôt dans son intégralité, du début à la fin :
# 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