Tutoriel 1 : Créer une base de données, un schéma, une table et un entrepôt¶

Introduction¶

Dans ce tutoriel, vous apprendrez les principes fondamentaux de la gestion des objets de ressources Snowflake à l’aide de Snowflake Python APIs. Pour commencer avec l’API, vous créez et gérez une base de données, un schéma, une table et un entrepôt virtuel Snowflake.

Créer une base de données, un schéma et une table¶

Vous pouvez utiliser votre objet root pour créer une base de données, un schéma et une table dans votre compte Snowflake.

1. Pour créer une base de données, dans la cellule suivante de votre notebook, exécutez le code suivant :

   database = root.databases.create(
     Database(
       name="PYTHON_API_DB"),
       mode=CreateMode.or_replace
     )
   

   Copy

   Ce code, qui est fonctionnellement équivalent à la commande SQL CREATE OR REPLACE DATABASE PYTHON_API_DB, crée une base de données dans votre compte nommée PYTHON_API_DB. Ce code suit un modèle commun pour la gestion des objets dans Snowflake :

   • root.databases.create() crée une base de données dans Snowflake. Il accepte deux arguments : un objet Database et un mode.

   • Vous transmettez un objet Database en utilisant Database(name="PYTHON_API_DB"), et définissez le nom de la base de données en utilisant l’argument name. Rappelez-vous que vous avez importé Database à la ligne 3 du notebook.

   • Vous spécifiez le mode de création en transmettant l’argument mode. Dans ce cas, vous le définissez sur CreateMode.or_replace, mais les valeurs suivantes sont également valides :

     • CreateMode.if_not_exists : équivalent à CREATE IF NOT EXISTS en SQL.

     • CreateMode.error_if_exists : lève une exception si l’objet existe déjà dans Snowflake. Il s’agit de la valeur par défaut si aucun mode n’est spécifié.

   • Vous gérez la base de données par programmation en stockant une référence à la base de données dans un objet que vous avez créé nommé database.

2. Dans Snowsight, accédez à la section des bases de données de votre compte Snowflake. Si votre code a réussi, la base de données PYTHON_API_DB est répertoriée.

   Astuce

   Si vous utilisez VS Code, installez l”extension Snowflake pour explorer tous les objets Snowflake dans votre éditeur.

3. Pour créer un schéma dans la base de données PYTHON_API_DB, dans votre cellule suivante, exécutez le code suivant :

   schema = database.schemas.create(
     Schema(
       name="PYTHON_API_SCHEMA"),
       mode=CreateMode.or_replace,
     )
   

   Copy

   Notez que vous appelez .schemas.create() sur l’objet database que vous avez créé précédemment.

4. Pour créer une table dans le schéma que vous venez de créer, dans votre cellule suivante, exécutez le code suivant :

   table = schema.tables.create(
     Table(
       name="PYTHON_API_TABLE",
       columns=[
         TableColumn(
           name="TEMPERATURE",
           datatype="int",
           nullable=False,
         ),
         TableColumn(
           name="LOCATION",
           datatype="string",
         ),
       ],
     ),
   mode=CreateMode.or_replace
   )
   

   Copy

   Ce code crée une table dans le schéma PYTHON_API_SCHEMA avec deux colonnes et leurs types de données spécifiés : TEMPERATURE comme int, et LOCATION comme string.

   Ces deux derniers exemples de code devraient vous sembler familiers car ils suivent le modèle de la première étape où vous avez créé la base de données PYTHON_API_DB.

5. Pour confirmer que les objets ont été créés, revenez à votre compte Snowflake dans Snowsight.

Récupérer les données d’objet¶

Vous pouvez récupérer des métadonnées sur un objet dans Snowflake.

1. Pour récupérer des détails sur la table PYTHON_API_TABLE que vous avez créée précédemment, dans votre prochaine cellule de notebook, exécutez le code suivant :

   table_details = table.fetch()
   

   Copy

   fetch() renvoie un objet TableModel.

2. Vous pouvez ensuite appeler .to_dict() sur l’objet résultant pour afficher ses informations détaillées.

   Pour imprimer les détails de la table, dans votre cellule suivante, exécutez le code suivant :

   table_details.to_dict()
   

   Copy

   Le notebook doit afficher un dictionnaire contenant des métadonnées sur la table PYTHON_API_TABLE, semblable à celui-ci :

   {
       "name": "PYTHON_API_TABLE",
       "kind": "TABLE",
       "enable_schema_evolution": False,
       "change_tracking": False,
       "data_retention_time_in_days": 1,
       "max_data_extension_time_in_days": 14,
       "default_ddl_collation": "",
       "columns": [
           {"name": "TEMPERATURE", "datatype": "NUMBER(38,0)", "nullable": False},
           {"name": "LOCATION", "datatype": "VARCHAR(16777216)", "nullable": True},
       ],
       "created_on": datetime.datetime(
           2024, 5, 9, 8, 59, 15, 832000, tzinfo=datetime.timezone.utc
       ),
       "database_name": "PYTHON_API_DB",
       "schema_name": "PYTHON_API_SCHEMA",
       "rows": 0,
       "bytes": 0,
       "owner": "ACCOUNTADMIN",
       "automatic_clustering": False,
       "search_optimization": False,
       "owner_role_type": "ROLE",
   }
   

   Copy

   Comme indiqué, ce dictionnaire contient des informations sur la table PYTHON_API_TABLE que vous avez créée précédemment, avec des informations détaillées sur columns, owner, database, schema, et plus encore.

Les métadonnées d’objet sont utiles lorsque vous créez une logique métier dans votre application. Par exemple, vous pouvez créer une logique qui s’exécute en fonction de certaines informations sur un objet. Vous pouvez utiliser fetch() pour récupérer les métadonnées des objets dans de tels scénarios.

Modifier une table par programmation¶

Vous pouvez ajouter par programmation une colonne à une table. La table PYTHON_API_TABLE comporte actuellement deux colonnes : TEMPERATURE et LOCATION. Dans ce scénario, vous souhaitez ajouter une nouvelle colonne nommée ELEVATION de type int et la définir comme clé primaire de la table.

1. Dans votre cellule suivante, exécutez le code suivant :

   table_details.columns.append(
       TableColumn(
         name="elevation",
         datatype="int",
         nullable=False,
         constraints=[PrimaryKey()],
       )
   )
   

   Copy

   Note

   Ce code ne crée pas la colonne. Au lieu de cela, cette définition de colonne est ajoutée au tableau qui représente les colonnes de la table dans TableModel. Pour afficher ce tableau, examinez la valeur de columns comme décrit dans les instructions pour afficher les métadonnées de la table.

2. Pour modifier la table et ajouter la colonne, dans votre cellule suivante, exécutez le code suivant :

   table.create_or_alter(table_details)
   

   Copy

   Dans cette ligne, vous appelez create_or_alter() sur l’objet représentant PYTHON_API_TABLE, et transmettez la valeur mise à jour de table_details. Cette ligne ajoute la colonne ELEVATION à PYTHON_API_TABLE.

3. Pour confirmer que la colonne a été ajoutée, dans votre cellule suivante, exécutez le code suivant :

   table.fetch().to_dict()
   

   Copy

   La sortie devrait ressembler à ce qui suit :

   {
       "name": "PYTHON_API_TABLE",
       "kind": "TABLE",
       "enable_schema_evolution": False,
       "change_tracking": False,
       "data_retention_time_in_days": 1,
       "max_data_extension_time_in_days": 14,
       "default_ddl_collation": "",
       "columns": [
           {"name": "TEMPERATURE", "datatype": "NUMBER(38,0)", "nullable": False},
           {"name": "LOCATION", "datatype": "VARCHAR(16777216)", "nullable": True},
           {"name": "ELEVATION", "datatype": "NUMBER(38,0)", "nullable": False},
       ],
       "created_on": datetime.datetime(
           2024, 5, 9, 8, 59, 15, 832000, tzinfo=datetime.timezone.utc
       ),
       "database_name": "PYTHON_API_DB",
       "schema_name": "PYTHON_API_SCHEMA",
       "rows": 0,
       "bytes": 0,
       "owner": "ACCOUNTADMIN",
       "automatic_clustering": False,
       "search_optimization": False,
       "owner_role_type": "ROLE",
       "constraints": [
           {"name": "ELEVATION", "column_names": ["ELEVATION"], "constraint_type": "PRIMARY KEY"}
       ]
   }
   

   Copy

   Examinez la valeur de columns et la valeur de constraints, qui incluent désormais toutes deux la colonne ELEVATION.

4. Pour confirmer l’existence de la nouvelle colonne, revenez à votre compte Snowflake dans Snowsight et inspectez la table.

Créer et gérer un entrepôt¶

Vous pouvez également gérer des entrepôts virtuels avec Snowflake Python APIs. Par exemple, vous devrez peut-être créer temporairement un autre entrepôt pour exécuter certaines requêtes. Dans ce scénario, vous pouvez utiliser l’API pour créer, suspendre ou supprimer un entrepôt.

1. Pour récupérer la collection d’entrepôts associée à votre session, dans votre cellule suivante, exécutez le code suivant :

   warehouses = root.warehouses
   

   Copy

   Vous gérez les entrepôts dans votre session à l’aide de l’objet warehouses résultant.

2. Pour définir et créer un nouvel entrepôt, dans votre cellule suivante, exécutez le code suivant :

   python_api_wh = Warehouse(
       name="PYTHON_API_WH",
       warehouse_size="SMALL",
       auto_suspend=500,
   )
   
   warehouse = warehouses.create(python_api_wh,mode=CreateMode.or_replace)
   

   Copy

   Dans ce code, vous définissez un nouvel entrepôt en instanciant Warehouse et en spécifiant le nom, la taille et la politique de suspension automatique de l’entrepôt. Le délai de suspension automatique est exprimé en secondes. Dans ce cas, l’entrepôt sera suspendu après 8,33 minutes d’inactivité.

   Vous créez ensuite l’entrepôt en appelant create() sur votre collection d’entrepôt. Vous stockez la référence dans l’objet warehouse résultant.

3. Accédez à votre compte Snowflake dans Snowsight et confirmez que l’entrepôt a été créé.

4. Pour récupérer des informations sur l’entrepôt, dans votre cellule suivante, exécutez le code suivant :

   warehouse_details = warehouse.fetch()
   warehouse_details.to_dict()
   

   Copy

   Ce code devrait vous sembler familier car il suit le même modèle que celui que vous avez utilisé pour récupérer les métadonnées de la table à une étape précédente. Le résultat devrait être similaire à ceci :

   {
     'name': 'PYTHON_API_WH',
     'auto_suspend': 500,
     'auto_resume': 'true',
     'resource_monitor': 'null',
     'comment': '',
     'max_concurrency_level': 8,
     'statement_queued_timeout_in_seconds': 0,
     'statement_timeout_in_seconds': 172800,
     'tags': {},
     'warehouse_type': 'STANDARD',
     'warehouse_size': 'Small'
   }
   

   Copy

5. Facultatif : si vous avez plusieurs entrepôts dans votre session, utilisez l’API pour les parcourir ou pour rechercher un entrepôt spécifique.

   Dans votre cellule suivante, exécutez le code suivant :

   warehouse_list = warehouses.iter(like="PYTHON_API_WH")
   result = next(warehouse_list)
   result.to_dict()
   

   Copy

   Dans ce code, vous appelez iter() sur la collecte de l’entrepôt et transmettez l’argument like, qui renvoie tous les entrepôts dont les noms correspondent à la chaîne spécifiée. Dans ce cas, vous transmettez le nom de l’entrepôt que vous avez défini précédemment, mais cet argument est généralement une chaîne insensible à la casse qui fonctionne comme un filtre, avec prise en charge de caractères génériques SQL comme % et _.

   Après avoir exécuté la cellule, une sortie similaire au code suivant montre que vous avez renvoyé avec succès un entrepôt correspondant :

   {
     'name': 'PYTHON_API_WH',
     'auto_suspend': 500,
     'auto_resume': 'true',
     'resource_monitor': 'null',
     'comment': '',
     'max_concurrency_level': 8,
     'statement_queued_timeout_in_seconds': 0,
     'statement_timeout_in_seconds': 172800,
     'tags': {},
     'warehouse_type': 'STANDARD',
     'warehouse_size': 'Small'
   }
   

   Copy

6. Pour modifier par programmation l’entrepôt en modifiant sa taille sur LARGE, dans votre cellule suivante, exécutez le code suivant :

   warehouse = root.warehouses.create(Warehouse(
       name="PYTHON_API_WH",
       warehouse_size="LARGE",
       auto_suspend=500,
   ), mode=CreateMode.or_replace)
   

   Copy

7. Pour confirmer que la taille de l’entrepôt a été mise à jour sur LARGE, effectuez l’une des opérations suivantes :

   • Dans votre cellule suivante, exécutez le code suivant :

     warehouse.fetch().size
     

     Copy

   • Accédez à votre compte Snowflake dans Snowsight et confirmez le changement de taille de l’entrepôt.

8. Facultatif : si vous ne souhaitez pas continuer à utiliser l’entrepôt, supprimez-le. Dans votre cellule suivante, exécutez le code suivant :

   warehouse.drop()
   

   Copy

9. Pour confirmer la suppression de l’entrepôt, revenez à votre compte Snowflake dans Snowsight.

Quelle est la prochaine étape ?¶

Félicitations ! Dans ce tutoriel, vous avez appris les principes fondamentaux de la gestion des objets de ressources Snowflake à l’aide de Snowflake Python APIs.