Migrer à partir du package Python datalab

Le package Python datalab permet d'interagir avec les services Google Cloud via les notebooks Cloud Datalab. Le package Python datalab inclut des commandes magiques Jupyter et des modules Python, comme google.datalab.bigquery, qui sont compatibles avec un sous-ensemble de méthodes de l'API BigQuery.

La bibliothèque cliente BigQuery, google-cloud-bigquery, est la bibliothèque Python officielle utilisée pour les interactions avec BigQuery. La bibliothèque cliente fournit une commande de cellule magique Jupyter pour l'exécution des requêtes, des fonctions permettant d'envoyer et de récupérer des données à l'aide de DataFrames pandas, ainsi que la compatibilité avec toutes les fonctionnalités BigQuery. Les exemples de code suivants montrent comment effectuer des opérations BigQuery courantes à l'aide de la bibliothèque google-cloud-bigquery pour les développeurs qui connaissent déjà le package Python datalab.

Consultez le fichier requirements.txt pour afficher les versions des bibliothèques utilisées pour ces extraits de code.

Utiliser les commandes magiques Jupyter et les commandes shell

Les deux bibliothèques acceptent l'interrogation des données stockées dans BigQuery à l'aide d'une commande de cellule magique. Les principales différences entre les approches des deux bibliothèques à l'égard des commandes magiques sont les suivantes :

datalab google-cloud-bigquery
Nom des commandes magiques bq bigquery
Nom de l'extension Jupyter (utilisée pour charger les commandes magiques) google.datalab.kernel google.cloud.bigquery
Exécution de la requête La définition et l'exécution de la requête peuvent s'effectuer en plusieurs étapes. La requête est toujours exécutée immédiatement lors de l'exécution de la commande magique.
Fonctionnalité couverte par les commandes magiques Certaines fonctionnalités ne sont pas disponibles. Les commandes magiques ne s'appliquent qu'à l'exécution des requêtes. Pour les autres fonctionnalités de BigQuery, utilisez l'outil de ligne de commande ou les méthodes google.cloud.bigquery.Client.
Enregistrement des résultats de la requête Les résultats de la requête peuvent être enregistrés dans une table de destination via la commande magique de la requête, mais pas dans une variable. Pour les enregistrer dans une variable, utilisez Python au lieu des commandes magiques pour exécuter la requête (voir l'exemple). Les résultats de la requête peuvent être enregistrés dans une variable via la commande magique de la requête, mais pas dans une table de destination. Pour les enregistrer dans une table de destination, utilisez Python au lieu des commandes magiques pour exécuter la requête (voir l'exemple).

Installer la bibliothèque cliente Python

Pour installer la bibliothèque cliente BigQuery avec les dépendances requises pour l'utilisation des DataFrames pandas, saisissez la commande suivante dans votre notebook :

!pip install --upgrade 'google-cloud-bigquery[bqstorage,pandas]'

Redémarrez votre noyau après avoir installé le package.

Charger des commandes magiques

Les commandes magiques Jupyter sont des raccourcis spécifiques aux notebooks qui permettent d'exécuter des commandes avec une syntaxe minimale. Les notebooks Jupyter sont fournis préchargés avec de nombreuses commandes intégrées. Les packages Python datalab et google-cloud-python mettent en œuvre des commandes magiques supplémentaires que vous pouvez charger dans les notebooks Jupyter (y compris Datalab) pour interagir avec Google Cloud.

datalab

Les commandes magiques datalab sont préchargées dans les notebooks Datalab. Pour charger les commandes magiques dans un notebook Jupyter, exécutez la commande suivante :

%load_ext google.datalab.kernel

Vous trouverez d'autres options pour le chargement des commandes magiques dans le dépôt source de la bibliothèque datalab.

google-cloud-bigquery

Pour charger la commande magique BigQuery, exécutez la commande suivante :

%load_ext google.cloud.bigquery

La commande de cellule magique BigQuery fonctionne avec n'importe quel notebook sur lequel le package google-cloud-bigquery est installé.

Exécuter des requêtes

Les exemples suivants montrent comment utiliser une commande de cellule magique pour exécuter une requête. Les deux exemples exécutent la requête et affichent les résultats sous la cellule d'entrée.

datalab

Les résultats de la requête sont affichés sous la cellule d'entrée.
%%bq query
SELECT word, SUM(word_count) as count
FROM `bigquery-public-data.samples.shakespeare`
GROUP BY word
ORDER BY count ASC
LIMIT 100

google-cloud-bigquery

Les résultats de la requête sont affichés sous la cellule d'entrée dans un DataFrame pandas.
%%bigquery
SELECT word, SUM(word_count) as count
FROM `bigquery-public-data.samples.shakespeare`
GROUP BY word
ORDER BY count ASC
LIMIT 100

Exécuter une requête et stocker les résultats dans une variable

L'exemple suivant montre comment exécuter une requête et stocker les résultats dans une variable nommée my_variable.

datalab

La commande magique de la requête datalab permet d'enregistrer une requête SQL sans l'exécuter en transmettant un nom à l'aide des options --name ou -n.
%%bq query -n my_query
SELECT name FROM `bigquery-public-data.usa_names.usa_1910_current`
WHERE state = "TX"
LIMIT 100
La requête enregistrée peut ensuite être exécutée séparément, les résultats étant stockés dans une variable.
import google.datalab.bigquery as bq

my_variable = my_query.execute().result().to_dataframe()

google-cloud-bigquery

%%bigquery my_variable
SELECT name FROM `bigquery-public-data.usa_names.usa_1910_current`
WHERE state = "TX"
LIMIT 100

Autres commandes

La bibliothèque datalab contient des commandes magiques pour de nombreux types d'opérations BigQuery, tandis que la bibliothèque google-cloud-bigquery propose une commande de cellule magique pour l'exécution de requêtes. Pour exécuter des commandes pour des opérations autres que des requêtes, utilisez l'outil de ligne de commande bq. Les exemples suivants montrent comment répertorier toutes les tables de l'ensemble de données samples du projet bigquery-public-data à l'aide d'une commande de cellule magique datalab ou d'une commande shell BigQuery.

datalab

%bq tables list --dataset bigquery-public-data.samples

Outil de ligne de commande bq

Pour commencer à utiliser l'outil de ligne de commande bq intégré à Google Cloud CLI, suivez les instructions d'installation de Google Cloud CLI. Notez que les commandes shell utilisées dans un notebook doivent être précédées d'un point d'exclamation (!). Une fois que l'outil de ligne de commande bq est configuré et disponible dans votre notebook, saisissez la commande suivante, qui équivaut à la commande de cellule magique datalab ci-dessus.

!bq ls bigquery-public-data:samples

Pour obtenir une liste complète des commandes, saisissez :

!bq help

Utiliser le code Python

Outre les commandes magiques Jupyter, vous pouvez effectuer des opérations BigQuery à l'aide de méthodes Python dans les packages datalab et google-cloud-bigquery.

Exécuter une requête

Les deux bibliothèques acceptent l'exécution de requêtes et le renvoi des résultats sous forme de DataFrame pandas.

datalab

import google.datalab.bigquery as bq

sql = """
    SELECT name FROM `bigquery-public-data.usa_names.usa_1910_current`
    WHERE state = "TX"
    LIMIT 100
"""
df = bq.Query(sql).execute().result().to_dataframe()

google-cloud-bigquery

from google.cloud import bigquery

client = bigquery.Client()
sql = """
    SELECT name FROM `bigquery-public-data.usa_names.usa_1910_current`
    WHERE state = "TX"
    LIMIT 100
"""
df = client.query(sql).to_dataframe()

Charger des données dans une table BigQuery

L'exemple suivant montre comment créer un ensemble de données et charger les données d'un fichier CSV dans une nouvelle table à partir de Cloud Storage.

datalab

import google.datalab.bigquery as bq

# Create the dataset
dataset_id = 'import_sample'
bq.Dataset(dataset_id).create()

# Create the table
schema = [
    {'name': 'name', 'type': 'STRING'},
    {'name': 'post_abbr', 'type': 'STRING'},
]
table = bq.Table(
    '{}.us_states'.format(dataset_id)).create(schema=schema)
table.load(
    'gs://cloud-samples-data/bigquery/us-states/us-states.csv',
    mode='append',
    source_format='csv',
    csv_options=bq.CSVOptions(skip_leading_rows=1)
)  # Waits for the job to complete

google-cloud-bigquery

from google.cloud import bigquery

client = bigquery.Client(location='US')

# Create the dataset
dataset_id = 'import_sample'
dataset = client.create_dataset(dataset_id)

# Create the table
job_config = bigquery.LoadJobConfig(
    schema=[
        bigquery.SchemaField('name', 'STRING'),
        bigquery.SchemaField('post_abbr', 'STRING')
    ],
    skip_leading_rows=1,
    # The source format defaults to CSV, so the line below is optional.
    source_format=bigquery.SourceFormat.CSV
)
load_job = client.load_table_from_uri(
    'gs://cloud-samples-data/bigquery/us-states/us-states.csv',
    dataset.table('us_states'),
    job_config=job_config
)
load_job.result()  # Waits for table load to complete.

Pour consulter plus d'exemples d'utilisation de la bibliothèque cliente Python de BigQuery, consultez les pages Charger des données par lots et Insérer des données en flux continu dans BigQuery.

Charger un objet DataFrame pandas dans une table BigQuery

L'exemple suivant montre comment créer un ensemble de données et charger les données d'un DataFrame pandas dans une nouvelle table.

Certaines opérations BigQuery, comme la création d'un ensemble de données, nécessitent de fournir des emplacements. Si un emplacement est fourni à un client google-cloud-bigquery lors de l'initialisation, il constituera l'emplacement par défaut pour l'intégralité des tâches, des ensembles de données et des tables créés avec ce client. La bibliothèque datalab ne permet pas de spécifier des emplacements pour les ensembles de données ou les tâches, ce qui peut entraîner un comportement inattendu. Pour en savoir plus, consultez la page Emplacement des ensembles de données.

datalab

La bibliothèque datalab effectue une insertion en flux continu lors du chargement des données d'un DataFrame pandas dans une table BigQuery. De ce fait, les données peuvent ne pas être immédiatement disponibles pour les requêtes. Pour en savoir plus, consultez la page Importer des données dans BigQuery.
import google.datalab.bigquery as bq
import pandas

# Create the dataset
dataset_id = 'import_sample'
bq.Dataset(dataset_id).create()

# Create the table and load the data
dataframe = pandas.DataFrame([
    {'title': 'The Meaning of Life', 'release_year': 1983},
    {'title': 'Monty Python and the Holy Grail', 'release_year': 1975},
    {'title': 'Life of Brian', 'release_year': 1979},
    {
        'title': 'And Now for Something Completely Different',
        'release_year': 1971
    },
])
schema = bq.Schema.from_data(dataframe)
table = bq.Table(
    '{}.monty_python'.format(dataset_id)).create(schema=schema)
table.insert(dataframe)  # Starts steaming insert of data

google-cloud-bigquery

La bibliothèque cliente BigQuery convertit le DataFrame pandas au format Parquet et effectue une tâche de chargement (contrairement à une insertion en flux continu). Les données sont immédiatement disponibles dès la fin de l'opération de chargement.
from google.cloud import bigquery
import pandas

client = bigquery.Client(location='US')

dataset_id = 'import_sample'
dataset = client.create_dataset(dataset_id)

# Create the table and load the data
dataframe = pandas.DataFrame([
    {'title': 'The Meaning of Life', 'release_year': 1983},
    {'title': 'Monty Python and the Holy Grail', 'release_year': 1975},
    {'title': 'Life of Brian', 'release_year': 1979},
    {
        'title': 'And Now for Something Completely Different',
        'release_year': 1971
    },
])
table_ref = dataset.table('monty_python')
load_job = client.load_table_from_dataframe(dataframe, table_ref)
load_job.result()  # Waits for table load to complete.