Librerie client dell'API BigQuery

Questa pagina mostra come iniziare a utilizzare le librerie client di Cloud per l'API BigQuery. Le librerie client semplificano l'accesso alle APIGoogle Cloud da una lingua supportata. Sebbene tu possa utilizzare le APIGoogle Cloud effettuando direttamente delle richieste non elaborate al server, le librerie client forniscono semplificazioni che riducono notevolmente la quantità di codice da scrivere.

Scopri di più sulle librerie client di Cloud e sulle precedenti librerie client delle API di Google in Descrizione delle librerie client.

Installa la libreria client

C#

Install-Package Google.Cloud.BigQuery.V2 -Pre

Per ulteriori informazioni, vedi Configurazione di un ambiente di sviluppo C#.

Go

go get cloud.google.com/go/bigquery

Per ulteriori informazioni, vedi Configurazione di un ambiente di sviluppo Go.

Java

Se utilizzi Maven, aggiungi quanto segue al file pom.xml. Per saperne di più sulle BOM, consulta The Google Cloud Platform Libraries BOM.

<!--  Using libraries-bom to manage versions.
See https://github.com/GoogleCloudPlatform/cloud-opensource-java/wiki/The-Google-Cloud-Platform-Libraries-BOM -->
<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.google.cloud</groupId>
      <artifactId>libraries-bom</artifactId>
      <version>26.62.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<dependencies>
  <dependency>
    <groupId>com.google.cloud</groupId>
    <artifactId>google-cloud-bigquery</artifactId>
  </dependency>
</dependencies>

Se utilizzi Gradle, aggiungi quanto segue alle dipendenze:

implementation platform('com.google.cloud:libraries-bom:26.45.0')

implementation 'com.google.cloud:google-cloud-bigquery'

Se utilizzi sbt, aggiungi quanto segue alle dipendenze:

libraryDependencies += "com.google.cloud" % "google-cloud-bigquery" % "2.42.2"

Se utilizzi Visual Studio Code o IntelliJ, puoi aggiungere librerie client al tuo progetto utilizzando i seguenti plug-in IDE:

• Cloud Code for VS Code
• Cloud Code for IntelliJ

I plug-in forniscono funzionalità aggiuntive, come la gestione delle chiavi per i service account. Per informazioni dettagliate, consulta la documentazione di ogni plug-in.

Nota: le librerie client Cloud Java non supportano attualmente Android.

Per ulteriori informazioni, vedi Configurazione di un ambiente di sviluppo Java.

Node.js

npm install @google-cloud/bigquery

Per ulteriori informazioni, consulta Configurazione di un ambiente di sviluppo Node.js.

PHP

composer require google/cloud-bigquery

Per ulteriori informazioni, consulta Utilizzo di PHP su Google Cloud.

Python

pip install --upgrade google-cloud-bigquery

Per ulteriori informazioni, consulta Configurazione di un ambiente di sviluppo Python.

Ruby

gem install google-cloud-bigquery

Per ulteriori informazioni, vedi Configurazione di un ambiente di sviluppo Ruby.

Rust

Anteprima

Questa libreria è soggetta ai "Termini delle Offerte pre-GA" nella sezione Termini di servizio generali dei Termini specifici dei servizi. Le librerie pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per ulteriori informazioni, consulta le descrizioni della fase di lancio.

Nota: per richiedere assistenza o fornire un feedback su questa libreria, invia un'email all'indirizzo [e-mail].

cargo add google-cloud-bigquery

Per saperne di più, consulta la guida introduttiva a Rust.

Configura l'autenticazione

Per autenticare le chiamate alle API Google Cloud , le librerie client supportano il servizio Credenziali predefinite dell'applicazione (ADC). Le librerie cercano le credenziali in una serie di località definite e le utilizzano per autenticare le richieste all'API. Con le ADC, puoi rendere disponibili le credenziali per la tua applicazione in vari ambienti, ad esempio per lo sviluppo locale o la produzione, senza dover modificare il codice dell'applicazione.

Per gli ambienti di produzione, la modalità di configurazione delle credenziali ADC dipende dal servizio e dal contesto. Per ulteriori informazioni, consulta Configura le credenziali predefinite dell'applicazione.

Per un ambiente di sviluppo locale, puoi configurare come ADC le credenziali associate al tuo Account Google:

1. Installa Google Cloud CLI, quindi accedi a gcloud CLI con la tua identità federata. Dopo aver eseguito l'accesso, inizializza Google Cloud CLI eseguendo il comando seguente:

   gcloud init

2. Crea credenziali di autenticazione locali per il tuo account utente:

   gcloud auth application-default login

   Se viene restituito un errore di autenticazione e utilizzi un provider di identità (IdP) esterno, verifica di aver acceduto a gcloud CLI con la tua identità federata.

   Viene visualizzata una schermata di accesso. Dopo aver eseguito l'accesso, le tue credenziali vengono archiviate nel file delle credenziali locali utilizzato da ADC.

Utilizza la libreria client

L'esempio seguente mostra come inizializzare un client ed eseguire una query su un set di dati pubblico dell'API BigQuery.

Nota: JRuby non è supportato.

C#

using Google.Cloud.BigQuery.V2;
using System;

public class BigQueryQuery
{
    public void Query(
        string projectId = "your-project-id"
    )
    {
        BigQueryClient client = BigQueryClient.Create(projectId);
        string query = @"
            SELECT name FROM `bigquery-public-data.usa_names.usa_1910_2013`
            WHERE state = 'TX'
            LIMIT 100";
        BigQueryJob job = client.CreateQueryJob(
            sql: query,
            parameters: null,
            options: new QueryOptions { UseQueryCache = false });
        // Wait for the job to complete.
        job = job.PollUntilCompleted().ThrowOnAnyError();
        // Display the results
        foreach (BigQueryRow row in client.GetQueryResults(job.Reference))
        {
            Console.WriteLine($"{row["name"]}");
        }
    }
}

Go

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/bigquery"
	"google.golang.org/api/iterator"
)

// queryBasic demonstrates issuing a query and reading results.
func queryBasic(w io.Writer, projectID string) error {
	// projectID := "my-project-id"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	q := client.Query(
		"SELECT name FROM `bigquery-public-data.usa_names.usa_1910_2013` " +
			"WHERE state = \"TX\" " +
			"LIMIT 100")
	// Location must match that of the dataset(s) referenced in the query.
	q.Location = "US"
	// Run the query and print results when the query job is completed.
	job, err := q.Run(ctx)
	if err != nil {
		return err
	}
	status, err := job.Wait(ctx)
	if err != nil {
		return err
	}
	if err := status.Err(); err != nil {
		return err
	}
	it, err := job.Read(ctx)
	for {
		var row []bigquery.Value
		err := it.Next(&row)
		if err == iterator.Done {
			break
		}
		if err != nil {
			return err
		}
		fmt.Fprintln(w, row)
	}
	return nil
}

Java

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.FieldValueList;
import com.google.cloud.bigquery.Job;
import com.google.cloud.bigquery.JobId;
import com.google.cloud.bigquery.JobInfo;
import com.google.cloud.bigquery.QueryJobConfiguration;
import com.google.cloud.bigquery.TableResult;


public class SimpleApp {

  public static void main(String... args) throws Exception {
    // TODO(developer): Replace these variables before running the app.
    String projectId = "MY_PROJECT_ID";
    simpleApp(projectId);
  }

  public static void simpleApp(String projectId) {
    try {
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();
      QueryJobConfiguration queryConfig =
          QueryJobConfiguration.newBuilder(
                  "SELECT CONCAT('https://stackoverflow.com/questions/', "
                      + "CAST(id as STRING)) as url, view_count "
                      + "FROM `bigquery-public-data.stackoverflow.posts_questions` "
                      + "WHERE tags like '%google-bigquery%' "
                      + "ORDER BY view_count DESC "
                      + "LIMIT 10")
              // Use standard SQL syntax for queries.
              // See: https://cloud.google.com/bigquery/sql-reference/
              .setUseLegacySql(false)
              .build();

      JobId jobId = JobId.newBuilder().setProject(projectId).build();
      Job queryJob = bigquery.create(JobInfo.newBuilder(queryConfig).setJobId(jobId).build());

      // Wait for the query to complete.
      queryJob = queryJob.waitFor();

      // Check for errors
      if (queryJob == null) {
        throw new RuntimeException("Job no longer exists");
      } else if (queryJob.getStatus().getExecutionErrors() != null
          && queryJob.getStatus().getExecutionErrors().size() > 0) {
        // TODO(developer): Handle errors here. An error here do not necessarily mean that the job
        // has completed or was unsuccessful.
        // For more details: https://cloud.google.com/bigquery/troubleshooting-errors
        throw new RuntimeException("An unhandled error has occurred");
      }

      // Get the results.
      TableResult result = queryJob.getQueryResults();

      // Print all pages of the results.
      for (FieldValueList row : result.iterateAll()) {
        // String type
        String url = row.get("url").getStringValue();
        String viewCount = row.get("view_count").getStringValue();
        System.out.printf("%s : %s views\n", url, viewCount);
      }
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Simple App failed due to error: \n" + e.toString());
    }
  }
}

Node.js

// Import the Google Cloud client library using default credentials
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();
async function query() {
  // Queries the U.S. given names dataset for the state of Texas.

  const query = `SELECT name
    FROM \`bigquery-public-data.usa_names.usa_1910_2013\`
    WHERE state = 'TX'
    LIMIT 100`;

  // For all options, see https://cloud.google.com/bigquery/docs/reference/rest/v2/jobs/query
  const options = {
    query: query,
    // Location must match that of the dataset(s) referenced in the query.
    location: 'US',
  };

  // Run the query as a job
  const [job] = await bigquery.createQueryJob(options);
  console.log(`Job ${job.id} started.`);

  // Wait for the query to finish
  const [rows] = await job.getQueryResults();

  // Print the results
  console.log('Rows:');
  rows.forEach(row => console.log(row));
}

PHP

use Google\Cloud\BigQuery\BigQueryClient;
use Google\Cloud\Core\ExponentialBackoff;

/** Uncomment and populate these variables in your code */
// $projectId = 'The Google project ID';
// $query = 'SELECT id, view_count FROM `bigquery-public-data.stackoverflow.posts_questions`';

$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);
$jobConfig = $bigQuery->query($query);
$job = $bigQuery->startQuery($jobConfig);

$backoff = new ExponentialBackoff(10);
$backoff->execute(function () use ($job) {
    print('Waiting for job to complete' . PHP_EOL);
    $job->reload();
    if (!$job->isComplete()) {
        throw new Exception('Job has not yet completed', 500);
    }
});
$queryResults = $job->queryResults();

$i = 0;
foreach ($queryResults as $row) {
    printf('--- Row %s ---' . PHP_EOL, ++$i);
    foreach ($row as $column => $value) {
        printf('%s: %s' . PHP_EOL, $column, json_encode($value));
    }
}
printf('Found %s row(s)' . PHP_EOL, $i);

Python

from google.cloud import bigquery

# 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
"""
rows = client.query_and_wait(query)  # Make an API request.

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

Ruby

require "google/cloud/bigquery"

def query
  bigquery = Google::Cloud::Bigquery.new
  sql = "SELECT name FROM `bigquery-public-data.usa_names.usa_1910_2013` " \
        "WHERE state = 'TX' " \
        "LIMIT 100"

  # Location must match that of the dataset(s) referenced in the query.
  results = bigquery.query sql do |config|
    config.location = "US"
  end

  results.each do |row|
    puts row.inspect
  end
end

Rust

Anteprima

Questa libreria è soggetta ai "Termini delle Offerte pre-GA" nella sezione Termini di servizio generali dei Termini specifici dei servizi. Le librerie pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per ulteriori informazioni, consulta le descrizioni della fase di lancio.

Nota: per richiedere assistenza o fornire un feedback su questa libreria, invia un'email all'indirizzo [e-mail].

use google_cloud_bigquery::client::BigQuery;

pub async fn sample(project_id: &str) -> anyhow::Result<()> {
    let client = BigQuery::builder().build().await?;

    let mut rows = client
        .query(
            "SELECT \
        name FROM `bigquery-public-data.usa_names.usa_1910_2013` \
        WHERE state = 'TX' \
        LIMIT 100",
        )
        .with_project_id(project_id)
        .set_location("US")
        .until_done()
        .await?
        .read();

    while let Some(row) = rows.next().await.transpose()? {
        let name: String = row.get("name")?;
        println!("Name: {name}");
    }
    Ok(())
}

Risorse aggiuntive

C#

Il seguente elenco contiene link ad altre risorse relative alla libreria client per C#:

• Riferimento API
• Best practice per le librerie client
• Issue Tracker
• google-bigquery su Stack Overflow
• Codice sorgente

Go

Il seguente elenco contiene link ad altre risorse relative alla libreria client per Go:

• Riferimento API
• Best practice per le librerie client
• Issue Tracker
• google-bigquery su Stack Overflow
• Codice sorgente

Java

Il seguente elenco contiene link ad altre risorse relative alla libreria client per Java:

• Riferimento API
• Best practice per le librerie client
• Issue Tracker
• google-bigquery su Stack Overflow
• Codice sorgente

Node.js

Il seguente elenco contiene link ad altre risorse relative alla libreria client per Node.js:

• Riferimento API
• Best practice per le librerie client
• Issue Tracker
• google-bigquery su Stack Overflow
• Codice sorgente

PHP

Il seguente elenco contiene link ad altre risorse relative alla libreria client per PHP:

• Riferimento API
• Best practice per le librerie client
• Issue Tracker
• google-bigquery su Stack Overflow
• Codice sorgente

Python

Il seguente elenco contiene link ad altre risorse relative alla libreria client per Python:

• Riferimento API
• Best practice per le librerie client
• Issue Tracker
• google-bigquery su Stack Overflow
• Codice sorgente

Ruby

Il seguente elenco contiene link ad altre risorse relative alla libreria client per Ruby:

• Riferimento API
• Best practice per le librerie client
• Issue Tracker
• google-bigquery su Stack Overflow
• Codice sorgente

Rust

Il seguente elenco contiene link ad altre risorse relative alla libreria client per Rust:

• Riferimento API
• Best practice per le librerie client
• Issue Tracker
• google-bigquery su Stack Overflow
• Codice sorgente

Librerie Python open source

Per l'analisi dei dati, il machine learning e le operazioni DataFrame in Python, l'API BigQuery offre librerie Python open source specifiche. Per un confronto dettagliato ed esempi di utilizzo in tutte e tre le librerie, consulta Utilizzare le librerie Python open source.

Raccolta	Pacchetto	Descrizione
BigQuery DataFrames	bigframes	API Pythonic DataFrame e ML (bigframes.pandas e bigframes.ml) basate sul motore dell'API BigQuery. Implementa le API pandas e scikit-learn utilizzando il pushdown delle query lato server. Per la documentazione, consulta Introduzione a BigQuery DataFrames e la documentazione di riferimento.
pandas-gbq	pandas-gbq	Interfaccia per l'esecuzione di query e lo spostamento di dati tra l'API BigQuery e i DataFrame pandas lato client in memoria. Per la documentazione, consulta la documentazione di pandas-gbq.
google-cloud-bigquery	google-cloud-bigquery	Libreria client Python di base che esegue il wrapping di tutte le API BigQuery per il deployment, l'amministrazione e le query SQL generali. Per la documentazione, consulta il riferimento della libreria client.

Librerie client API BigQuery di terze parti

Oltre alle librerie client supportate da Google elencate nelle tabelle precedenti, è disponibile un insieme di librerie di terze parti.

Lingua	Raccolta
Python	ibis (tutorial)
R	bigrquery, BigQueryR
Scala	spark-bigquery-connector

Passaggi successivi

• Visualizza gli esempi di codice BigQuery disponibili.
• Esegui una query su un set di dati pubblico con le librerie client dell'API BigQuery.
• Visualizza i dati pubblici dell'API BigQuery utilizzando un blocco note Jupyter.