Interroger des données Cloud Storage dans des tables externes

bq

La commande bq query permet d'interroger une table temporaire associée à une source de données externe à l'aide de l'option --external_table_definition. Lorsque vous utilisez l'outil de ligne de commande bq pour interroger une table temporaire associée à une source de données externe, vous pouvez spécifier le schéma de la table à l'aide de l'une des méthodes suivantes :

• Un fichier de définition de table (stocké sur l'ordinateur local)
• Une définition de schéma intégrée
• Un fichier de schéma JSON (stocké sur l'ordinateur local)

(Facultatif) Spécifiez l'option --location et définissez la valeur correspondant à votre emplacement.

Pour interroger une table temporaire associée à votre source de données externe à l'aide d'un fichier de définition de table, saisissez la commande suivante :

bq --location=LOCATION query \
--external_table_definition=TABLE::DEFINITION_FILE \
'QUERY'

Remplacez les éléments suivants :

• LOCATION : nom de votre emplacement. L'option --location est facultative ; Par exemple, si vous utilisez BigQuery dans la région de Tokyo, vous pouvez définir la valeur de cette option sur asia-northeast1. Vous pouvez définir une valeur par défaut correspondant à l'emplacement en utilisant le fichier .bigqueryrc ;
• TABLE : nom de la table temporaire que vous créez.
• DEFINITION_FILE : chemin d'accès au fichier de définition de table sur votre ordinateur local.
• QUERY: requête que vous soumettez à la table temporaire.

Par exemple, la commande suivante permet de créer et d'interroger une table temporaire nommée sales à l'aide du fichier de définition de table sales_def.

bq query \
--external_table_definition=sales::sales_def \
'SELECT
  Region,
  Total_sales
FROM
  sales'

Pour interroger une table temporaire associée à votre source de données externe à l'aide d'une définition de schéma intégrée, saisissez la commande suivante :

bq --location=LOCATION query \
--external_table_definition=TABLE::SCHEMA@SOURCE_FORMAT=BUCKET_PATH \
'QUERY'

Remplacez les éléments suivants :

• LOCATION : nom de votre emplacement. L'option --location est facultative ; Par exemple, si vous utilisez BigQuery dans la région de Tokyo, vous pouvez définir la valeur de cette option sur asia-northeast1. Vous pouvez définir une valeur par défaut correspondant à l'emplacement en utilisant le fichier .bigqueryrc ;
• TABLE : nom de la table temporaire que vous créez.
• SCHEMA : définition de schéma en ligne au format field:data_type,field:data_type.
• SOURCE_FORMAT : format de la source de données externe, par exemple CSV.

• BUCKET_PATH : chemin d'accès au bucket Cloud Storage contenant les données de la table, au format gs://bucket_name/[folder_name/]file_pattern.

  Vous pouvez sélectionner plusieurs fichiers dans le bucket en spécifiant un caractère générique astérisque (*) dans le file_pattern. Exemple : gs://mybucket/file00*.parquet. Pour en savoir plus, consultez la section Gestion des caractères génériques dans les URI Cloud Storage.

  Vous pouvez spécifier plusieurs buckets pour l'option uris en fournissant plusieurs chemins d'accès.

  Les exemples suivants montrent des valeurs uris valides :

  • gs://bucket/path1/myfile.csv
  • gs://bucket/path1/*.parquet
  • gs://bucket/path1/file1*, gs://bucket1/path1/*

  Lorsque vous spécifiez des valeurs uris qui ciblent plusieurs fichiers, tous ces fichiers doivent partager un schéma compatible.

  Pour en savoir plus sur l'utilisation des URI Cloud Storage dans BigQuery, consultez la page Chemin d'accès aux ressources Cloud Storage.

• QUERY : requête que vous soumettez à la table temporaire.

Par exemple, la commande suivante crée et interroge une table temporaire appelée sales qui est associée à un fichier CSV stocké dans Cloud Storage avec la définition de schéma suivante : Region:STRING,Quarter:STRING,Total_sales:INTEGER.

bq query \
--external_table_definition=sales::Region:STRING,Quarter:STRING,Total_sales:INTEGER@CSV=gs://mybucket/sales.csv \
'SELECT
  Region,
  Total_sales
FROM
  sales'

Pour interroger une table temporaire associée à votre source de données externe à l'aide d'un fichier de schéma JSON, saisissez la commande suivante :

bq --location=LOCATION query \
--external_table_definition=SCHEMA_FILE@SOURCE_FORMAT=BUCKET_PATH \
'QUERY'

Remplacez les éléments suivants :

• LOCATION : nom de votre emplacement. L'option --location est facultative ; Par exemple, si vous utilisez BigQuery dans la région de Tokyo, vous pouvez définir la valeur de cette option sur asia-northeast1. Vous pouvez définir une valeur par défaut correspondant à l'emplacement en utilisant le fichier .bigqueryrc ;
• SCHEMA_FILE : chemin d'accès au fichier de schéma JSON sur votre ordinateur local.
• SOURCE_FORMAT : format de la source de données externe, par exemple CSV.

• BUCKET_PATH : chemin d'accès au bucket Cloud Storage contenant les données de la table, au format gs://bucket_name/[folder_name/]file_pattern.

  Vous pouvez sélectionner plusieurs fichiers dans le bucket en spécifiant un caractère générique astérisque (*) dans le file_pattern. Exemple : gs://mybucket/file00*.parquet. Pour en savoir plus, consultez la section Gestion des caractères génériques dans les URI Cloud Storage.

  Vous pouvez spécifier plusieurs buckets pour l'option uris en fournissant plusieurs chemins d'accès.

  Les exemples suivants montrent des valeurs uris valides :

  • gs://bucket/path1/myfile.csv
  • gs://bucket/path1/*.parquet
  • gs://bucket/path1/file1*, gs://bucket1/path1/*

  Lorsque vous spécifiez des valeurs uris qui ciblent plusieurs fichiers, tous ces fichiers doivent partager un schéma compatible.

  Pour en savoir plus sur l'utilisation des URI Cloud Storage dans BigQuery, consultez la page Chemin d'accès aux ressources Cloud Storage.

• QUERY : requête que vous soumettez à la table temporaire.

Par exemple, la commande suivante crée et interroge une table temporaire appelée sales qui est associée à un fichier CSV stocké dans Cloud Storage à l'aide du fichier de schéma /tmp/sales_schema.json.

  bq query \
  --external_table_definition=sales::/tmp/sales_schema.json@CSV=gs://mybucket/sales.csv \
  'SELECT
      Region,
      Total_sales
    FROM
      sales'

API

Pour exécuter une requête à l'aide de l'API, procédez comme suit:

1. Créez un objet Job.
2. Renseignez la section configuration de l'objet Job avec un objet JobConfiguration.
3. Renseignez la section query de l'objet JobConfiguration avec un objet JobConfigurationQuery.
4. Renseignez la section tableDefinitions de l'objet JobConfigurationQuery avec un objet ExternalDataConfiguration.
5. Appeler la méthode jobs.insert pour exécuter la requête de manière asynchrone ou la méthode jobs.query pour exécuter la requête de manière synchrone, en transmettant l'objet Job.

Java

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.CsvOptions;
import com.google.cloud.bigquery.ExternalTableDefinition;
import com.google.cloud.bigquery.Field;
import com.google.cloud.bigquery.QueryJobConfiguration;
import com.google.cloud.bigquery.Schema;
import com.google.cloud.bigquery.StandardSQLTypeName;
import com.google.cloud.bigquery.TableResult;

// Sample to queries an external data source using a temporary table
public class QueryExternalGCSTemp {

  public static void runQueryExternalGCSTemp() {
    // TODO(developer): Replace these variables before running the sample.
    String tableName = "MY_TABLE_NAME";
    String sourceUri = "gs://cloud-samples-data/bigquery/us-states/us-states.csv";
    Schema schema =
        Schema.of(
            Field.of("name", StandardSQLTypeName.STRING),
            Field.of("post_abbr", StandardSQLTypeName.STRING));
    String query = String.format("SELECT * FROM %s WHERE name LIKE 'W%%'", tableName);
    queryExternalGCSTemp(tableName, sourceUri, schema, query);
  }

  public static void queryExternalGCSTemp(
      String tableName, String sourceUri, Schema schema, String query) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      // Skip header row in the file.
      CsvOptions csvOptions = CsvOptions.newBuilder().setSkipLeadingRows(1).build();

      // Configure the external data source and query job.
      ExternalTableDefinition externalTable =
          ExternalTableDefinition.newBuilder(sourceUri, csvOptions).setSchema(schema).build();
      QueryJobConfiguration queryConfig =
          QueryJobConfiguration.newBuilder(query)
              .addTableDefinition(tableName, externalTable)
              .build();

      // Example query to find states starting with 'W'
      TableResult results = bigquery.query(queryConfig);

      results
          .iterateAll()
          .forEach(row -> row.forEach(val -> System.out.printf("%s,", val.toString())));

      System.out.println("Query on external temporary table performed successfully.");
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Query not performed \n" + e.toString());
    }
  }
}

Node.js

// Import the Google Cloud client library and create a client
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();

async function queryExternalGCSTemp() {
  // Queries an external data source using a temporary table.

  const tableId = 'us_states';

  // Configure the external data source
  const externalDataConfig = {
    sourceFormat: 'CSV',
    sourceUris: ['gs://cloud-samples-data/bigquery/us-states/us-states.csv'],
    // Optionally skip header row.
    csvOptions: {skipLeadingRows: 1},
    schema: {fields: schema},
  };

  // Example query to find states starting with 'W'
  const query = `SELECT post_abbr
  FROM \`${tableId}\`
  WHERE name LIKE 'W%'`;

  // For all options, see https://cloud.google.com/bigquery/docs/reference/v2/tables#resource
  const options = {
    query,
    tableDefinitions: {[tableId]: externalDataConfig},
  };

  // 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:');
  console.log(rows);
}

Python

from google.cloud import bigquery

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

# Configure the external data source and query job.
external_config = bigquery.ExternalConfig("CSV")
external_config.source_uris = [
    "gs://cloud-samples-data/bigquery/us-states/us-states.csv"
]
external_config.schema = [
    bigquery.SchemaField("name", "STRING"),
    bigquery.SchemaField("post_abbr", "STRING"),
]
external_config.options.skip_leading_rows = 1
table_id = "us_states"
job_config = bigquery.QueryJobConfig(table_definitions={table_id: external_config})

# Example query to find states starting with 'W'.
sql = 'SELECT * FROM `{}` WHERE name LIKE "W%"'.format(table_id)

query_job = client.query(sql, job_config=job_config)  # Make an API request.

w_states = list(query_job)  # Wait for the job to complete.
print("There are {} states with names starting with W.".format(len(w_states)))