Effectuer une migration depuis la bibliothèque cliente Python v0.27

La bibliothèque cliente BigQuery pour Python v0.28 apporte des modifications importantes dans la conception des bibliothèques clientes par rapport aux versions 0.27 et antérieures. Ces modifications peuvent être résumées comme suit :

  • Par défaut, les opérations de requête et de vue sont en dialecte SQL standard.
  • Les fonctions clientes liées aux tâches (par exemple, "exécuter des requêtes") déclenchent immédiatement les tâches.
  • Les fonctions permettant de créer, d'obtenir, de mettre à jour ou de supprimer des ensembles de données ou des tables sont déplacées vers la classe "Client".

Cette rubrique fournit des détails sur les modifications que vous devez apporter au code Python pour les bibliothèques clientes BigQuery afin d'utiliser la dernière version de ces bibliothèques.

Exécuter des versions précédentes de la bibliothèque cliente

La mise à niveau de la bibliothèque cliente Python vers la dernière version n'est pas obligatoire. Cependant, les nouvelles fonctionnalités de l'API BigQuery ne sont compatibles qu'avec les versions v0.28 et ultérieures.

Pour continuer à vous servir d'une version précédente de la bibliothèque cliente Python sans migrer le code, indiquez la version de bibliothèque cliente Python utilisée par l'application. Pour spécifier une version de bibliothèque, modifiez le fichier requirements.txt comme indiqué dans l'exemple suivant :

google-cloud-bigquery==0.27

Exécuter la dernière version de la bibliothèque cliente

Pour installer la dernière version de la bibliothèque cliente Python, utilisez la commande pip.

pip install --upgrade google-cloud-bigquery

Pour obtenir des instructions plus détaillées, consultez la section Bibliothèques clientes BigQuery.

Importer la bibliothèque et créer un client

L'importation de la bibliothèque cliente Python et la création d'un objet client sont identiques dans les versions précédentes et récentes de la bibliothèque.

from google.cloud import bigquery

client = bigquery.Client()

Interroger les modifications de code

Interroger les données en dialecte SQL standard

Les modifications apportées à partir des versions v0.28 sont les suivantes :

  • Le dialecte SQL par défaut est le langage SQL standard.
  • La classe QueryJobConfig permet de configurer la tâche de requête.
  • client.query() envoie une requête API pour démarrer immédiatement la requête.
  • L'ID de tâche est facultatif. Si vous ne spécifiez aucun ID, la bibliothèque cliente en génère un.

L'exemple suivant montre comment exécuter une requête.

Versions précédentes des bibliothèques clientes :

client = bigquery.Client()
query_job = client.run_async_query(str(uuid.uuid4()), query)

# Use standard SQL syntax.
query_job.use_legacy_sql = False

# Set a destination table.
dest_dataset = client.dataset(dest_dataset_id)
dest_table = dest_dataset.table(dest_table_id)
query_job.destination = dest_table

# Allow the results table to be overwritten.
query_job.write_disposition = 'WRITE_TRUNCATE'

query_job.begin()
query_job.result()  # Wait for query to finish.

rows = query_job.query_results().fetch_data()
for row in rows:
    print(row)

Jusqu'à la version 0.25.0 de la bibliothèque google-cloud-bigquery, au lieu de job.result(), il était nécessaire d'utiliser le code suivant pour attendre la fin de l'exécution des objets de tâche :

while True:
    job.reload()  # Refreshes the state via a GET request.
    if job.state == 'DONE':
        if job.error_result:
            raise RuntimeError(job.errors)
        return
    time.sleep(1)

Jusqu'à la version 0.25.0 de la bibliothèque google-cloud-bigquery, au lieu de job.query_results().fetch_data(), il était nécessaire d'utiliser le code suivant pour obtenir les lignes résultantes :

rows = query_job.results().fetch_data()

Dernière version de la bibliothèque cliente :

Par défaut, la bibliothèque cliente Python emploie désormais le langage SQL standard.

Python

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Python décrite dans le guide de démarrage rapide de BigQuery sur l'utilisation des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery en langage Python.

# TODO(developer): Import the client library.
# from google.cloud import bigquery

# TODO(developer): Construct a BigQuery client object.
# client = bigquery.Client()

query = """
    SELECT name, SUM(number) as total_people
    FROM `bigquery-public-data.usa_names.usa_1910_2013`
    WHERE state = 'TX'
    GROUP BY name, state
    ORDER BY total_people DESC
    LIMIT 20
"""
query_job = client.query(query)  # Make an API request.

print("The query data:")
for row in query_job:
    # Row values can be accessed by field name or index.
    print("name={}, count={}".format(row[0], row["total_people"]))

Pour plus d'exemples sur l'exécution de requêtes avec la dernière version de la bibliothèque cliente Python, consultez les sections :

Télécharger des résultats de requête sous forme de DataFrame pandas

L'exemple suivant montre comment exécuter une requête et télécharger les résultats sous forme de DataFrame pandas.

Versions précédentes des bibliothèques clientes :

Les versions précédentes des bibliothèques clientes ne permettaient pas le téléchargement des résultats sur un objet DataFrame pandas.

Dernière version de la bibliothèque cliente :

Python

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Python décrite dans le guide de démarrage rapide de BigQuery sur l'utilisation des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery en langage Python.

# from google.cloud import bigquery
# client = bigquery.Client()

sql = """
    SELECT name, SUM(number) as count
    FROM `bigquery-public-data.usa_names.usa_1910_current`
    GROUP BY name
    ORDER BY count DESC
    LIMIT 10
"""

df = client.query(sql).to_dataframe()

Interroger des données en ancien SQL

L'exemple suivant montre comment exécuter une requête en ancien SQL.

Versions précédentes des bibliothèques clientes :

Par défaut, les versions précédentes des bibliothèques clientes employaient la syntaxe de l'ancien SQL. Pour plus d'informations sur la configuration et l'exécution d'une requête, voir l'exemple de requête.

Dernière version de la bibliothèque cliente :

Par défaut, la bibliothèque cliente emploie la syntaxe SQL standard. Définissez use_legacy_sql sur la valeur "true" pour utiliser l'ancien SQL. Pour en savoir plus sur la configuration et l'exécution d'une requête, consultez l'exemple de requête.

Interroger des données en mode synchrone

À partir de la version v0.28, il est recommandé d'utiliser la méthode Client.query() car elle permet d'accéder aux statistiques et aux autres propriétés de la requête dans QueryJob.

Versions précédentes des bibliothèques clientes :

query_results = client.run_sync_query(query)
query_results.use_legacy_sql = False

query_results.run()

# The query might not complete in a single request. To account for a
# long-running query, force the query results to reload until the query
# is complete.
while not query_results.complete:
  query_iterator = query_results.fetch_data()
  try:
     six.next(iter(query_iterator))
  except StopIteration:
      pass

rows = query_results.fetch_data()
for row in rows:
    print(row)

Dernière version de la bibliothèque cliente :

Python

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Python décrite dans le guide de démarrage rapide de BigQuery sur l'utilisation des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery en langage Python.

# TODO(developer): Import the client library.
# from google.cloud import bigquery

# TODO(developer): Construct a BigQuery client object.
# client = bigquery.Client()

query = """
    SELECT name, SUM(number) as total_people
    FROM `bigquery-public-data.usa_names.usa_1910_2013`
    WHERE state = 'TX'
    GROUP BY name, state
    ORDER BY total_people DESC
    LIMIT 20
"""
query_job = client.query(query)  # Make an API request.

print("The query data:")
for row in query_job:
    # Row values can be accessed by field name or index.
    print("name={}, count={}".format(row[0], row["total_people"]))

Modifications apportées au code de table

Références de table

Un objet TableReference permet de faire référence à une table sans propriétés supplémentaires. Un objet Table permet de faire référence à une ressource de table complète. Plusieurs propriétés qui employaient la classe Table utilisent désormais la classe TableReference à partir de la version v0.28. Exemple :

  • QueryJob.destination est désormais un objet TableReference.
  • client.dataset('mydataset').table('mytable') renvoie désormais un objet TableReference.

Pour obtenir un exemple employant les classes TableReference et Table, consultez la section Créer une table.

Charger des données depuis un fichier local

L'exemple suivant montre comment charger un fichier local dans une table BigQuery.

Versions précédentes des bibliothèques clientes :

dataset = client.dataset(dataset_name)
table = dataset.table(table_name)

# Reload the table to get the schema.
table.reload()

with open(source_file_name, 'rb') as source_file:
    # This example uses CSV, but you can use other formats.
    # See https://cloud.google.com/bigquery/loading-data
    job = table.upload_from_file(
        source_file, source_format='text/csv')

# Wait for the load job to complete.
while True:
    job.reload()
    if job.state == 'DONE':
        if job.error_result:
            raise RuntimeError(job.errors)
        return
    time.sleep(1)

Dernière version de la bibliothèque cliente :

Python

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Python décrite dans le guide de démarrage rapide de BigQuery sur l'utilisation des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery en langage Python.

# from google.cloud import bigquery
# client = bigquery.Client()
# filename = '/path/to/file.csv'
# dataset_id = 'my_dataset'
# table_id = 'my_table'

dataset_ref = client.dataset(dataset_id)
table_ref = dataset_ref.table(table_id)
job_config = bigquery.LoadJobConfig()
job_config.source_format = bigquery.SourceFormat.CSV
job_config.skip_leading_rows = 1
job_config.autodetect = True

with open(filename, "rb") as source_file:
    job = client.load_table_from_file(source_file, table_ref, job_config=job_config)

job.result()  # Waits for table load to complete.

print("Loaded {} rows into {}:{}.".format(job.output_rows, dataset_id, table_id))

Pour en savoir plus, consultez la section Charger des données depuis une source de données locale.

Charger des données depuis un DataFrame pandas

L'exemple suivant montre comment importer un DataFrame pandas dans une table BigQuery.

Versions précédentes des bibliothèques clientes :

Les versions précédentes des bibliothèques clientes ne permettaient pas l'importation de données à partir d'un DataFrame pandas.

Dernière version de la bibliothèque cliente :

Python

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Python décrite dans le guide de démarrage rapide de BigQuery sur l'utilisation des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery en langage Python.

from google.cloud import bigquery

import pandas

# TODO(developer): Construct a BigQuery client object.
# client = bigquery.Client()

# TODO(developer): Set table_id to the ID of the table to create.
# table_id = "your-project.your_dataset.your_table_name"

records = [
    {"title": u"The Meaning of Life", "release_year": 1983},
    {"title": u"Monty Python and the Holy Grail", "release_year": 1975},
    {"title": u"Life of Brian", "release_year": 1979},
    {"title": u"And Now for Something Completely Different", "release_year": 1971},
]
dataframe = pandas.DataFrame(
    records,
    # In the loaded table, the column order reflects the order of the
    # columns in the DataFrame.
    columns=["title", "release_year"],
    # Optionally, set a named index, which can also be written to the
    # BigQuery table.
    index=pandas.Index(
        [u"Q24980", u"Q25043", u"Q24953", u"Q16403"], name="wikidata_id"
    ),
)
job_config = bigquery.LoadJobConfig(
    # Specify a (partial) schema. All columns are always written to the
    # table. The schema is used to assist in data type definitions.
    schema=[
        # Specify the type of columns whose type cannot be auto-detected. For
        # example the "title" column uses pandas dtype "object", so its
        # data type is ambiguous.
        bigquery.SchemaField("title", bigquery.enums.SqlTypeNames.STRING),
        # Indexes are written if included in the schema by name.
        bigquery.SchemaField("wikidata_id", bigquery.enums.SqlTypeNames.STRING),
    ],
    # Optionally, set the write disposition. BigQuery appends loaded rows
    # to an existing table by default, but with WRITE_TRUNCATE write
    # disposition it replaces the table with the loaded data.
    write_disposition="WRITE_TRUNCATE",
)

job = client.load_table_from_dataframe(
    dataframe, table_id, job_config=job_config
)  # Make an API request.
job.result()  # Wait for the job to complete.

table = client.get_table(table_id)  # Make an API request.
print(
    "Loaded {} rows and {} columns to {}".format(
        table.num_rows, len(table.schema), table_id
    )
)

Charger des données depuis Cloud Storage

L'exemple suivant montre comment charger un fichier depuis Cloud Storage dans une table BigQuery.

Versions précédentes des bibliothèques clientes :

dataset = client.dataset(dataset_name)
table = dataset.table(table_name)
job_id = str(uuid.uuid4())

job = client.load_table_from_storage(
    job_id, table, 'gs://bucket_name/object_name')
job.begin()

# Wait for the load job to complete.
while True:
    job.reload()
    if job.state == 'DONE':
        if job.error_result:
            raise RuntimeError(job.errors)
        return
    time.sleep(1)

Dernière version de la bibliothèque cliente :

Python

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Python décrite dans le guide de démarrage rapide de BigQuery sur l'utilisation des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery en langage Python.

# from google.cloud import bigquery
# client = bigquery.Client()
# dataset_id = 'my_dataset'

dataset_ref = client.dataset(dataset_id)
job_config = bigquery.LoadJobConfig()
job_config.schema = [
    bigquery.SchemaField("name", "STRING"),
    bigquery.SchemaField("post_abbr", "STRING"),
]
job_config.skip_leading_rows = 1
# The source format defaults to CSV, so the line below is optional.
job_config.source_format = bigquery.SourceFormat.CSV
uri = "gs://cloud-samples-data/bigquery/us-states/us-states.csv"

load_job = client.load_table_from_uri(
    uri, dataset_ref.table("us_states"), job_config=job_config
)  # API request
print("Starting job {}".format(load_job.job_id))

load_job.result()  # Waits for table load to complete.
print("Job finished.")

destination_table = client.get_table(dataset_ref.table("us_states"))
print("Loaded {} rows.".format(destination_table.num_rows))

Pour en savoir plus, consultez la section Charger des données depuis Cloud Storage.

Extraire une table vers Cloud Storage

L'exemple suivant montre comment extraire une table vers Cloud Storage.

Versions précédentes des bibliothèques clientes :

dataset = client.dataset(dataset_name)
table = dataset.table(table_name)
job_id = str(uuid.uuid4())

job = client.extract_table_to_storage(
    job_id, table, 'gs://bucket_name/object_name')
job.begin()

# Wait for the job to complete.
while True:
    job.reload()
    if job.state == 'DONE':
        if job.error_result:
            raise RuntimeError(job.errors)
        return
    time.sleep(1)

Dernière version de la bibliothèque cliente :

Python

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Python décrite dans le guide de démarrage rapide de BigQuery sur l'utilisation des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery en langage Python.

# from google.cloud import bigquery
# client = bigquery.Client()
# bucket_name = 'my-bucket'
project = "bigquery-public-data"
dataset_id = "samples"
table_id = "shakespeare"

destination_uri = "gs://{}/{}".format(bucket_name, "shakespeare.csv")
dataset_ref = client.dataset(dataset_id, project=project)
table_ref = dataset_ref.table(table_id)

extract_job = client.extract_table(
    table_ref,
    destination_uri,
    # Location must match that of the source table.
    location="US",
)  # API request
extract_job.result()  # Waits for job to complete.

print(
    "Exported {}:{}.{} to {}".format(project, dataset_id, table_id, destination_uri)
)

Pour en savoir plus, consultez la section Exporter des données de table.

Copier une table

L'exemple suivant montre comment copier une table dans une autre.

Versions précédentes des bibliothèques clientes :

dataset = client.dataset(dataset_name)
table = dataset.table(table_name)
destination_table = dataset.table(new_table_name)

job_id = str(uuid.uuid4())
job = client.copy_table(job_id, destination_table, table)

job.create_disposition = (
        google.cloud.bigquery.job.CreateDisposition.CREATE_IF_NEEDED)
job.begin()

# Wait for the job to complete.
while True:
    job.reload()
    if job.state == 'DONE':
        if job.error_result:
            raise RuntimeError(job.errors)
        return
    time.sleep(1)

Dernière version de la bibliothèque cliente :

Python

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Python décrite dans le guide de démarrage rapide de BigQuery sur l'utilisation des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery en langage Python.

# TODO(developer): Import the client library.
# from google.cloud import bigquery

# TODO(developer): Construct a BigQuery client object.
# client = bigquery.Client()

# TODO(developer): Set source_table_id to the ID of the original table.
# source_table_id = "your-project.source_dataset.source_table"

# TODO(developer): Set destination_table_id to the ID of the destination table.
# destination_table_id = "your-project.destination_dataset.destination_table"

job = client.copy_table(source_table_id, destination_table_id)
job.result()  # Wait for the job to complete.

print("A copy of the table created.")

Pour en savoir plus, consultez la section Copier une table.

Insérer des données en flux continu dans une table

L'exemple suivant montre comment écrire des lignes dans le tampon en flux continu d'une table.

Versions précédentes des bibliothèques clientes :

dataset = client.dataset(dataset_name)
table = dataset.table(table_name)

# Reload the table to get the schema.
table.reload()

rows = [('values', 'in', 'same', 'order', 'as', 'schema')]
errors = table.insert_data(rows)

if not errors:
    print('Loaded 1 row into {}:{}'.format(dataset_name, table_name))
else:
    do_something_with(errors)

Dernière version de la bibliothèque cliente :

Python

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Python décrite dans le guide de démarrage rapide de BigQuery sur l'utilisation des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery en langage Python.

# TODO(developer): Import the client library.
# from google.cloud import bigquery

# TODO(developer): Construct a BigQuery client object.
# client = bigquery.Client()

# TODO(developer): Set table_id to the ID of the model to fetch.
# table_id = "your-project.your_dataset.your_table"

table = client.get_table(table_id)  # Make an API request.
rows_to_insert = [(u"Phred Phlyntstone", 32), (u"Wylma Phlyntstone", 29)]

errors = client.insert_rows(table, rows_to_insert)  # Make an API request.
if errors == []:
    print("New rows have been added.")

Pour en savoir plus, consultez la section Insérer des données en streaming dans BigQuery.

Répertorier les tables

L'exemple suivant montre comment répertorier les tables d'un ensemble de données.

Versions précédentes des bibliothèques clientes :

dataset = client.dataset(dataset_name)
for table in dataset.list_tables():
    print(table.name)

Dernière version de la bibliothèque cliente :

Python

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Python décrite dans le guide de démarrage rapide de BigQuery sur l'utilisation des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery en langage Python.

# TODO(developer): Import the client library.
# from google.cloud import bigquery

# TODO(developer): Construct a BigQuery client object.
# client = bigquery.Client()

# TODO(developer): Set dataset_id to the ID of the dataset that contains
#                  the tables you are listing.
# dataset_id = 'your-project.your_dataset'

tables = client.list_tables(dataset_id)  # Make an API request.

print("Tables contained in '{}':".format(dataset_id))
for table in tables:
    print("{}.{}.{}".format(table.project, table.dataset_id, table.table_id))

Pour en savoir plus, consultez la section Répertorier des tables.

Obtenir une table

L'exemple suivant montre comment obtenir une table.

Versions précédentes des bibliothèques clientes :

dataset = client.dataset(dataset_name)
table = dataset.table(table_name)
table.reload()

Dernière version de la bibliothèque cliente :

Python

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Python décrite dans le guide de démarrage rapide de BigQuery sur l'utilisation des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery en langage Python.

# TODO(developer): Import the client library.
# from google.cloud import bigquery

# TODO(developer): Construct a BigQuery client object.
# client = bigquery.Client()

# TODO(developer): Set table_id to the ID of the model to fetch.
# table_id = 'your-project.your_dataset.your_table'

table = client.get_table(table_id)  # Make an API request.

# View table properties
print(
    "Got table '{}.{}.{}'.".format(table.project, table.dataset_id, table.table_id)
)
print("Table schema: {}".format(table.schema))
print("Table description: {}".format(table.description))
print("Table has {} rows".format(table.num_rows))

Pour en savoir plus, consultez la section Obtenir des informations sur les tables.

Vérifier qu'une table existe

L'API BigQuery ne fournit pas de méthode exists native. Au lieu de cela, récupérez la ressource de table et vérifiez si la demande génère une erreur 404. Auparavant, la bibliothèque cliente proposait l'outil d'aide exists() pour effectuer cette vérification. Cet outil d'aide exists() permettait certains cas d'utilisation inefficaces, par exemple appeler la méthode exists() avant de tenter d'obtenir la ressource complète. Par conséquent, l'outil d'aide exists() a été supprimé de la bibliothèque cliente.

L'exemple suivant montre comment vérifier si une table existe.

Versions précédentes des bibliothèques clientes :

dataset = client.dataset(dataset_name)
table = dataset.table(table_name)
if table.exists():
    # do something
else:
    # do something else

Dernière version de la bibliothèque cliente :

Python

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Python décrite dans le guide de démarrage rapide de BigQuery sur l'utilisation des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery en langage Python.

from google.cloud.exceptions import NotFound

# TODO(developer): Set table_id to the ID of the table to determine existence.
# table_id = "your-project.your_dataset.your_table"

try:
    client.get_table(table_id)  # Make an API request.
    print("Table {} already exists.".format(table_id))
except NotFound:
    print("Table {} is not found.".format(table_id))

Créer une table

L'exemple suivant montre comment créer une table.

Versions précédentes des bibliothèques clientes :

dataset = client.dataset(dataset_name)
table = dataset.table(table_name)
table.create()

Dernière version de la bibliothèque cliente :

Python

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Python décrite dans le guide de démarrage rapide de BigQuery sur l'utilisation des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery en langage Python.

from google.cloud import bigquery

# TODO(developer): Construct a BigQuery client object.
# client = bigquery.Client()

# TODO(developer): Set table_id to the ID of the table to create.
# table_id = "your-project.your_dataset.your_table_name"

schema = [
    bigquery.SchemaField("full_name", "STRING", mode="REQUIRED"),
    bigquery.SchemaField("age", "INTEGER", mode="REQUIRED"),
]

table = bigquery.Table(table_id, schema=schema)
table = client.create_table(table)  # Make an API request.
print(
    "Created table {}.{}.{}".format(table.project, table.dataset_id, table.table_id)
)

Pour en savoir plus, consultez la section Créer une table.

Mettre à jour une table

L'exemple suivant montre comment mettre à jour une table.

Versions précédentes des bibliothèques clientes :

dataset = client.dataset(dataset_name)
table = dataset.table(table_name)
table.patch(description='new description')

Notez que dans les versions précédentes de la bibliothèque, les versions de la ressource de table ne sont pas vérifiées à l'aide de la propriété etag. Par conséquent, le cycle lecture-modification-écriture n'est pas sécurisé.

Dernière version de la bibliothèque cliente :

Python

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Python décrite dans le guide de démarrage rapide de BigQuery sur l'utilisation des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery en langage Python.

# from google.cloud import bigquery
# client = bigquery.Client()
# table_ref = client.dataset('my_dataset').table('my_table')
# table = client.get_table(table_ref)  # API request

assert table.description == "Original description."
table.description = "Updated description."

table = client.update_table(table, ["description"])  # API request

assert table.description == "Updated description."

Pour en savoir plus, consultez la section Mettre à jour les propriétés d'une table.

Supprimer une table

L'exemple suivant montre comment supprimer une table.

Versions précédentes des bibliothèques clientes :

dataset = client.dataset(dataset_name)
table = dataset.table(table_name)
table.delete()

Dernière version de la bibliothèque cliente :

Python

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Python décrite dans le guide de démarrage rapide de BigQuery sur l'utilisation des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery en langage Python.

# TODO(developer): Import the client library.
# from google.cloud import bigquery

# TODO(developer): Construct a BigQuery client object.
# client = bigquery.Client()

# TODO(developer): Set table_id to the ID of the table to fetch.
# table_id = 'your-project.your_dataset.your_table'

# If the table does not exist, delete_table raises
# google.api_core.exceptions.NotFound unless not_found_ok is True.
client.delete_table(table_id, not_found_ok=True)  # Make an API request.
print("Deleted table '{}'.".format(table_id))

Pour en savoir plus, consultez la section Supprimer une table.

Modifications apportées au code d'ensemble de données

Références d'ensemble de données

Un objet DatasetReference permet de faire référence à un ensemble de données sans propriétés supplémentaires. Un objet Dataset permet de faire référence à une ressource d'ensemble de données complète. Certaines méthodes qui employaient la classe Dataset utilisent désormais la classe DatasetReference à partir des versions v0.28. Exemple :

  • client.dataset('mydataset') renvoie désormais un objet DatasetReference.

Pour obtenir un exemple employant les classes DatasetReference et Dataset, consultez la section Créer un ensemble de données.

Répertorier les ensembles de données

L'exemple suivant montre comment répertorier des ensembles de données dans un projet.

Versions précédentes des bibliothèques clientes :

for dataset in client.list_datasets():
    print(dataset.name)

Dernière version de la bibliothèque cliente :

Python

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Python décrite dans le guide de démarrage rapide de BigQuery sur l'utilisation des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery en langage Python.

# TODO(developer): Import the client library.
# from google.cloud import bigquery

# TODO(developer): Construct a BigQuery client object.
# client = bigquery.Client()

datasets = list(client.list_datasets())  # Make an API request.
project = client.project

if datasets:
    print("Datasets in project {}:".format(project))
    for dataset in datasets:
        print("\t{}".format(dataset.dataset_id))
else:
    print("{} project does not contain any datasets.".format(project))

Pour en savoir plus, consultez la section Répertorier des ensembles de données.

Obtenir un ensemble de données

L'exemple suivant montre comment obtenir un ensemble de données.

Versions précédentes des bibliothèques clientes :

dataset = client.dataset(dataset_name)
dataset.reload()

Dernière version de la bibliothèque cliente :

Python

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Python décrite dans le guide de démarrage rapide de BigQuery sur l'utilisation des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery en langage Python.

# TODO(developer): Import the client library.
# from google.cloud import bigquery

# TODO(developer): Construct a BigQuery client object.
# client = bigquery.Client()

# TODO(developer): Set dataset_id to the ID of the dataset to fetch.
# dataset_id = 'your-project.your_dataset'

dataset = client.get_dataset(dataset_id)  # Make an API request.

full_dataset_id = "{}.{}".format(dataset.project, dataset.dataset_id)
friendly_name = dataset.friendly_name
print(
    "Got dataset '{}' with friendly_name '{}'.".format(
        full_dataset_id, friendly_name
    )
)

# View dataset properties.
print("Description: {}".format(dataset.description))
print("Labels:")
labels = dataset.labels
if labels:
    for label, value in labels.items():
        print("\t{}: {}".format(label, value))
else:
    print("\tDataset has no labels defined.")

# View tables in dataset.
print("Tables:")
tables = list(client.list_tables(dataset))  # Make an API request(s).
if tables:
    for table in tables:
        print("\t{}".format(table.table_id))
else:
    print("\tThis dataset does not contain any tables.")

Pour en savoir plus, consultez la section Obtenir des informations sur les ensembles de données.

Vérifier qu'un ensemble de données existe

L'API BigQuery ne fournit pas de méthode exists native. Au lieu de cela, récupérez la ressource d'ensemble de données et vérifiez si la demande génère une erreur 404. Auparavant, la bibliothèque cliente proposait l'outil d'aide exists() pour effectuer cette vérification. Cet outil d'aide exists() permettait certains cas d'utilisation inefficaces, par exemple appeler la méthode exists() avant de tenter d'obtenir la ressource complète. Par conséquent, l'outil d'aide exists() a été supprimé de la bibliothèque cliente.

L'exemple suivant montre comment vérifier si un ensemble de données existe.

Versions précédentes des bibliothèques clientes :

dataset = client.dataset(dataset_name)
if dataset.exists():
    # do something
else:
    # do something else

Dernière version de la bibliothèque cliente :

Python

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Python décrite dans le guide de démarrage rapide de BigQuery sur l'utilisation des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery en langage Python.

from google.cloud.exceptions import NotFound

# TODO(developer): Set dataset_id to the ID of the dataset to determine existence.
# dataset_id = "your-project.your_dataset"

try:
    client.get_dataset(dataset_id)  # Make an API request.
    print("Dataset {} already exists".format(dataset_id))
except NotFound:
    print("Dataset {} is not found".format(dataset_id))

Créer un ensemble de données

L'exemple suivant montre comment créer un ensemble de données.

Versions précédentes des bibliothèques clientes :

dataset = client.dataset(dataset_name)
dataset.create()

Dernière version de la bibliothèque cliente :

Python

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Python décrite dans le guide de démarrage rapide de BigQuery sur l'utilisation des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery en langage Python.

from google.cloud import bigquery

# TODO(developer): Construct a BigQuery client object.
# client = bigquery.Client()

# TODO(developer): Set dataset_id to the ID of the dataset to create.
# dataset_id = "{}.your_dataset".format(client.project)

# Construct a full Dataset object to send to the API.
dataset = bigquery.Dataset(dataset_id)

# TODO(developer): Specify the geographic location where the dataset should reside.
dataset.location = "US"

# Send the dataset to the API for creation.
# Raises google.api_core.exceptions.Conflict if the Dataset already
# exists within the project.
dataset = client.create_dataset(dataset)  # Make an API request.
print("Created dataset {}.{}".format(client.project, dataset.dataset_id))

Pour en savoir plus, consultez la section Créer des ensembles de données.

Mettre à jour un ensemble de données

L'exemple suivant montre comment mettre à jour un ensemble de données.

Versions précédentes des bibliothèques clientes :

dataset = client.dataset(dataset_name)
dataset.patch(description='new description')

Notez que dans les versions précédentes de la bibliothèque, les versions de la ressource d'ensemble de données ne sont pas vérifiées à l'aide de la propriété etag. Par conséquent, le cycle lecture-modification-écriture n'est pas sécurisé.

Dernière version de la bibliothèque cliente :

Python

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Python décrite dans le guide de démarrage rapide de BigQuery sur l'utilisation des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery en langage Python.

# TODO(developer): Import the client library.
# from google.cloud import bigquery

# TODO(developer): Construct a BigQuery client object.
# client = bigquery.Client()

# TODO(developer): Set dataset_id to the ID of the dataset to fetch.
# dataset_id = 'your-project.your_dataset'

dataset = client.get_dataset(dataset_id)  # Make an API request.
dataset.description = "Updated description."
dataset = client.update_dataset(dataset, ["description"])  # Make an API request.

full_dataset_id = "{}.{}".format(dataset.project, dataset.dataset_id)
print(
    "Updated dataset '{}' with description '{}'.".format(
        full_dataset_id, dataset.description
    )
)

Pour en savoir plus, consultez la section Mettre à jour les propriétés d'un ensemble de données.

Supprimer un ensemble de données

L'exemple suivant montre comment supprimer un ensemble de données.

Versions précédentes des bibliothèques clientes :

dataset = client.dataset(dataset_name)
dataset.delete()

Dernière version de la bibliothèque cliente :

Python

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Python décrite dans le guide de démarrage rapide de BigQuery sur l'utilisation des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery en langage Python.

# TODO(developer): Import the client library.
# from google.cloud import bigquery

# TODO(developer): Construct a BigQuery client object.
# client = bigquery.Client()

# TODO(developer): Set model_id to the ID of the model to fetch.
# dataset_id = 'your-project.your_dataset'

# Use the delete_contents parameter to delete a dataset and its contents.
# Use the not_found_ok parameter to not receive an error if the dataset has already been deleted.
client.delete_dataset(
    dataset_id, delete_contents=True, not_found_ok=True
)  # Make an API request.

print("Deleted dataset '{}'.".format(dataset_id))

Pour en savoir plus, consultez la section Supprimer des ensembles de données.