Instructions de langage de définition de données (LDD) en langage SQL standard

Les instructions de langage de définition de données (Data definition language, DDL) permettent de créer et de modifier des ressources BigQuery à l'aide de la syntaxe de requête SQL standard. Dans BigQuery, à l'heure actuelle, les commandes LDD vous permettent de :

Autorisations requises

Tous les utilisateurs ont besoin de l'autorisation bigquery.jobs.create pour créer une tâche et exécuter des instructions LDD. Chaque type d'instruction LDD nécessite également des autorisations spécifiques pour s'exécuter. Cette section décrit les rôles IAM (Identity and Access Management) qui fournissent ces autorisations et les autorisations requises pour chaque type d'instruction.

Rôles IAM

Les rôles IAM prédéfinis bigquery.user, bigquery.jobUser et bigquery.admin incluent l'autorisation bigquery.jobs.create requise.

Les rôles bigquery.admin et bigquery.dataOwner incluent toutes les autres autorisations requises pour l'exécution d'instructions LDD. Le rôle bigquery.dataEditor inclut certaines des autorisations requises, comme indiqué dans le tableau de la section suivante.

Pour en savoir plus sur les rôles IAM dans BigQuery, consultez la page Rôles prédéfinis et autorisations, ou la documentation de référence sur les autorisations IAM.

Autorisations d'exécuter des instructions LDD

Différents types d'instructions DDL nécessitent des autorisations différentes pour s'exécuter, comme indiqué dans le tableau suivant :

instruction SQL Autorisations Rôles IAM Détails des autorisations
CREATE EXTERNAL TABLE bigquery.tables.create bigquery.admin
bigquery.dataEditor
bigquery.dataOwner
Autorisations relatives aux tables
CREATE FUNCTION bigquery.routines.create bigquery.admin
bigquery.dataEditor
bigquery.dataOwner
CREATE MATERIALIZED VIEW bigquery.tables.create bigquery.admin
bigquery.dataEditor
bigquery.dataOwner
Autorisations d'affichage matérialisées
CREATE PROCEDURE bigquery.routines.create bigquery.admin
bigquery.dataEditor
bigquery.dataOwner
CREATE SCHEMA bigquery.datasets.create bigquery.admin
bigquery.dataEditor
bigquery.dataOwner
Autorisations d'ensemble de données
CREATE TABLE bigquery.tables.create bigquery.admin
bigquery.dataEditor
bigquery.dataOwner
Autorisations relatives aux tables
CREATE VIEW bigquery.tables.create bigquery.admin
bigquery.dataEditor
bigquery.dataOwner
Afficher les autorisations
ALTER COLUMN
DROP NOT NULL
bigquery.tables.get
bigquery.tables.update
bigquery.admin
bigquery.dataEditor
bigquery.dataOwner
Autorisations relatives aux tables
ALTER COLUMN
SET OPTIONS
bigquery.tables.get
bigquery.tables.update
bigquery.admin
bigquery.dataEditor
bigquery.dataOwner
Autorisations relatives aux tables
ALTER MATERIALIZED VIEW
SET OPTIONS
bigquery.tables.get
bigquery.tables.update
bigquery.admin
bigquery.dataEditor
bigquery.dataOwner
Autorisations d'affichage matérialisées
ALTER SCHEMA
SET OPTIONS
bigquery.datasets.get
bigquery.datasets.update
bigquery.admin
bigquery.dataOwner
Autorisations de mise à jour des ensembles de données
ALTER TABLE
ADD COLUMN
bigquery.tables.get
bigquery.tables.update
bigquery.admin
bigquery.dataEditor
bigquery.dataOwner
Gérer les autorisations concernant les tables
ALTER TABLE
RENAME TO
bigquery.tables.get
bigquery.tables.update
bigquery.admin
bigquery.dataEditor
bigquery.dataOwner
Gérer les autorisations concernant les tables
ALTER TABLE
SET OPTIONS
bigquery.tables.get
bigquery.tables.update
bigquery.admin
bigquery.dataEditor
bigquery.dataOwner
Gérer les autorisations concernant les tables
ALTER TABLE
DROP COLUMN
bigquery.tables.get
bigquery.tables.update
bigquery.admin
bigquery.dataEditor
bigquery.dataOwner
Gérer les autorisations concernant les tables
ALTER VIEW
SET OPTIONS
bigquery.tables.get
bigquery.tables.update
bigquery.admin
bigquery.dataEditor
bigquery.dataOwner
Gérer les autorisations concernant les tables
DROP EXTERNAL TABLE bigquery.tables.delete
bigquery.tables.get
bigquery.admin
bigquery.dataEditor
bigquery.dataOwner
Supprimer les autorisations concernant les tables
DROP FUNCTION bigquery.routines.delete bigquery.admin
bigquery.dataEditor
bigquery.dataOwner
DROP MATERIALIZED VIEW bigquery.tables.delete
bigquery.tables.get
bigquery.admin
bigquery.dataEditor
bigquery.dataOwner
Autorisations d'affichage matérialisées
DROP PROCEDURE bigquery.routines.delete
bigquery.routines.get
bigquery.admin
bigquery.dataEditor
bigquery.dataOwner
DROP SCHEMA bigquery.datasets.delete
bigquery.tables.delete
*

* Inutile en cas de schéma vide.
bigquery.admin
bigquery.dataOwner
Supprimer les autorisations concernant les schémas
DROP TABLE bigquery.tables.delete
bigquery.tables.get
bigquery.admin
bigquery.dataEditor
bigquery.dataOwner
Supprimer les autorisations concernant les tables
DROP VIEW bigquery.tables.get
bigquery.tables.update
bigquery.admin
bigquery.dataEditor
bigquery.dataOwner
Supprimer les autorisations concernant les tables

Exécuter des instructions LDD

Vous pouvez exécuter des instructions LDD en utilisant Cloud Console ou l'outil de ligne de commande bq, en appelant l'API REST jobs.query, ou de manière automatisée à l'aide des bibliothèques clientes de l'API BigQuery.

Console

  1. Accédez à la page "BigQuery" de Cloud Console.

    Accéder à BigQuery

  2. Cliquez sur Saisir une nouvelle requête.

    Saisissez une nouvelle requête.

  3. Saisissez l'instruction LDD dans la zone de texte de l'éditeur de requête. Exemple :

     CREATE TABLE mydataset.newtable ( x INT64 )
     

  4. Cliquez sur Exécuter.

bq

Saisissez la commande bq query et indiquez l'instruction LDD comme paramètre de requête. Définissez l'indicateur use_legacy_sql sur false.

bq query --use_legacy_sql=false \
  'CREATE TABLE mydataset.newtable ( x INT64 )'

API

Appelez la méthode jobs.query et indiquez l'instruction LDD dans la propriété query du corps de la requête.

La fonctionnalité LDD complète les informations renvoyées par une ressource de tâches. statistics.query.statementType inclut les valeurs supplémentaires suivantes pour la compatibilité LDD :

  • CREATE_TABLE
  • CREATE_TABLE_AS_SELECT
  • DROP_TABLE
  • CREATE_VIEW
  • DROP_VIEW

statistics.query comporte deux champs supplémentaires :

  • ddlOperationPerformed : opération LDD effectuée, éventuellement dépendante de l'existence de la cible LDD. Les valeurs actuelles incluent :
    • CREATE : la requête a créé la cible LDD.
    • SKIP : aucune opération. Exemples : l'instruction CREATE TABLE IF NOT EXISTS a été envoyée et la table existe. Ou l'instruction DROP TABLE IF EXISTS a été envoyée et la table n'existe pas.
    • REPLACE : la requête a remplacé la cible LDD. Exemple : l'instruction CREATE OR REPLACE TABLE a été envoyée et la table existe déjà.
    • DROP : la requête a supprimé la cible LDD.
  • ddlTargetTable : lorsque vous envoyez une instruction CREATE TABLE/VIEW ou une instruction DROP TABLE/VIEW, la table cible est renvoyée sous la forme d'un objet comportant trois champs :
    • "projectId" : chaîne
    • "datasetId" : chaîne
    • "tableId" : chaîne

Java

Appelez la méthode BigQuery.create() pour démarrer une tâche de requête. Appelez la méthode Job.waitFor() pour attendre la fin de la requête LDD.

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

// Sample to create a view using DDL
public class DDLCreateView {

  public static void runDDLCreateView() {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "MY_PROJECT_ID";
    String datasetId = "MY_DATASET_ID";
    String tableId = "MY_VIEW_ID";
    String ddl =
        "CREATE VIEW "
            + "`"
            + projectId
            + "."
            + datasetId
            + "."
            + tableId
            + "`"
            + " OPTIONS("
            + " expiration_timestamp=TIMESTAMP_ADD("
            + " CURRENT_TIMESTAMP(), INTERVAL 48 HOUR),"
            + " friendly_name=\"new_view\","
            + " description=\"a view that expires in 2 days\","
            + " labels=[(\"org_unit\", \"development\")]"
            + " )"
            + " AS SELECT name, state, year, number"
            + " FROM `bigquery-public-data.usa_names.usa_1910_current`"
            + " WHERE state LIKE 'W%'`";
    ddlCreateView(ddl);
  }

  public static void ddlCreateView(String ddl) {
    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();

      QueryJobConfiguration config = QueryJobConfiguration.newBuilder(ddl).build();

      // create a view using query and it will wait to complete job.
      Job job = bigquery.create(JobInfo.of(config));
      job = job.waitFor();
      if (job.isDone()) {
        System.out.println("View created successfully");
      } else {
        System.out.println("View was not created");
      }
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("View was not created. \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 ddlCreateView() {
  // Creates a view via a DDL query

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const projectId = "my_project"
  // const datasetId = "my_dataset"
  // const tableId = "my_new_view"

  const query = `
  CREATE VIEW \`${projectId}.${datasetId}.${tableId}\`
  OPTIONS(
      expiration_timestamp=TIMESTAMP_ADD(
          CURRENT_TIMESTAMP(), INTERVAL 48 HOUR),
      friendly_name="new_view",
      description="a view that expires in 2 days",
      labels=[("org_unit", "development")]
  )
  AS SELECT name, state, year, number
      FROM \`bigquery-public-data.usa_names.usa_1910_current\`
      WHERE state LIKE 'W%'`;

  // For all options, see https://cloud.google.com/bigquery/docs/reference/rest/v2/jobs/query
  const options = {
    query: query,
  };

  // Run the query as a job
  const [job] = await bigquery.createQueryJob(options);

  job.on('complete', metadata => {
    console.log(`Created new view ${tableId} via job ${metadata.id}`);
  });
}

Python

Appelez la méthode Client.query() pour démarrer une tâche de requête. Appelez la méthode QueryJob.result() pour attendre la fin de la requête LDD.

# from google.cloud import bigquery
# project = 'my-project'
# dataset_id = 'my_dataset'
# table_id = 'new_view'
# client = bigquery.Client(project=project)

sql = """
CREATE VIEW `{}.{}.{}`
OPTIONS(
    expiration_timestamp=TIMESTAMP_ADD(
        CURRENT_TIMESTAMP(), INTERVAL 48 HOUR),
    friendly_name="new_view",
    description="a view that expires in 2 days",
    labels=[("org_unit", "development")]
)
AS SELECT name, state, year, number
    FROM `bigquery-public-data.usa_names.usa_1910_current`
    WHERE state LIKE 'W%'
""".format(
    project, dataset_id, table_id
)

job = client.query(sql)  # API request.
job.result()  # Waits for the query to finish.

print(
    'Created new view "{}.{}.{}".'.format(
        job.destination.project,
        job.destination.dataset_id,
        job.destination.table_id,
    )
)

Instruction CREATE SCHEMA

Crée un nouvel ensemble de données.

Syntaxe

CREATE SCHEMA [ IF NOT EXISTS ]
[project_name.]dataset_name
[OPTIONS(schema_option_list)]

Arguments

  • IF NOT EXISTS : si un ensemble de données portant le même nom existe, l'instruction CREATE n'a aucun effet. Ne peut pas s'afficher avec OR REPLACE.
  • project_name : nom du projet dans lequel vous créez l'ensemble de données. Sa valeur par défaut correspond au projet qui exécute cette requête LDD.

  • dataset_name : nom de l'ensemble de données à créer.

  • schema_option_list : liste des options de création de l'ensemble de données.

Détails

L'ensemble de données est créé à l'emplacement que vous spécifiez dans les paramètres de requête. Pour en savoir plus, consultez la page Spécifier votre zone.

Pour en savoir plus sur la création d'un ensemble de données, consultez la page Créer des ensembles de données. Pour plus d'informations sur les quotas, consultez la section Limites des ensembles de données.

schema_option_list

La liste d'options spécifie des options pour l'ensemble de données. Spécifiez les options au format suivant : NAME=VALUE, ...

Les options suivantes sont compatibles :

NAME VALUE Détails
default_kms_key_name STRING Spécifie la clé Cloud KMS par défaut pour le chiffrement des données de table de cet ensemble de données. Vous pouvez remplacer cette valeur lorsque vous créez une table.
default_partition_expiration_days FLOAT64 Spécifie le délai d'expiration par défaut, en jours, pour les partitions de tables de cet ensemble de données. Vous pouvez remplacer cette valeur lorsque vous créez une table.
default_table_expiration_days FLOAT64 Spécifie le délai d'expiration par défaut, en jours, pour les tables de cet ensemble de données. Vous pouvez remplacer cette valeur lorsque vous créez une table.
description STRING Description de l'ensemble de données.
friendly_name STRING Nom descriptif de l'ensemble de données.
labels <ARRAY<STRUCT<STRING, STRING>>> Tableau de libellés de l'ensemble de données, exprimé sous forme de paires clé/valeur.
location STRING Emplacement dans lequel créer l'ensemble de données. Si vous ne spécifiez pas cette option, l'ensemble de données est créé à l'emplacement où la requête est exécutée. Si vous spécifiez cette option et définissez explicitement l'emplacement de la tâche de requête, les deux valeurs doivent correspondre sans quoi la requête échoue.

Exemples

L'exemple suivant crée un ensemble de données avec un délai d'expiration de table par défaut et un ensemble d'étiquettes.

CREATE SCHEMA mydataset
OPTIONS(
  location="us",
  default_table_expiration_days=3.75,
  labels=[("label1","value1"),("label2","value2")]
  )

Instruction CREATE TABLE

Crée une table.

Syntaxe

CREATE [ OR REPLACE ] [ TEMP | TEMPORARY ] TABLE [ IF NOT EXISTS ]
table_name
[(
  column[, ...]
)]
[PARTITION BY partition_expression]
[CLUSTER BY clustering_column_list]
[OPTIONS(table_option_list)]
[AS query_statement]

Arguments

  • OR REPLACE : remplace toute table portant le même nom si elle existe. ne peut pas s'afficher avec IF NOT EXISTS.

  • TEMP | TEMPORARY : crée une table temporaire.

  • IF NOT EXISTS : si une table du même nom existe, l'instruction CREATE n'a aucun effet. Ne peut pas s'afficher avec OR REPLACE.

  • table_name : nom de la table à créer. Consultez la section Syntaxe du chemin d'accès à une table. Pour les tables temporaires, n'incluez pas le nom du projet ou de l'ensemble de données.

  • column : informations sur le schéma de la table.

Détails

Les instructions CREATE TABLE doivent respecter les règles suivantes :

  • Chaque requête ne peut contenir qu'une seule instruction CREATE.
  • La liste des colonnes ou la clause as query_statement ou bien les deux doivent être présentes.
  • Lorsque la liste des colonnes et la clause as query_statement sont toutes deux présentes, BigQuery ignore les noms dans la clause as query_statement et met les colonnes en correspondance avec leur position dans la liste des colonnes.
  • Lorsque seule la clause as query_statement est présente, BigQuery détermine le nom et le type des colonnes à l'aide de la clause as query_statement.
  • Les noms des colonnes doivent être spécifiés soit avec la liste des colonnes, soit à l'aide de la clause as query_statement ou du schéma de la table dans la clause LIKE.
  • Les noms de colonnes en double ne sont pas autorisés.
  • Lorsque la clause LIKE et la clause as query_statement sont toutes deux présentes, la liste des colonnes de l'instruction de requête doit correspondre aux colonnes de la table référencée par la clause LIKE.

Limites :

  • Il n'est pas possible de créer une table partitionnée par date d'ingestion à partir du résultat d'une requête. Au lieu de cela, créez la table avec une instruction LDD CREATE TABLE, puis insérez-y des données à l'aide d'une instruction LMD INSERT.
  • Il n'est pas possible de remplacer une table par un type de partitionnement différent à l'aide du modificateur OR REPLACE. Au lieu de cela, supprimez (DROP) la table, puis utilisez une instruction CREATE TABLE ... AS SELECT ... pour la recréer.

Cette instruction accepte les variantes suivantes :

  • CREATE TABLE LIKE : créez une table avec le même schéma qu'une table existante.
  • CREATE TABLE COPY : créez une table en copiant le schéma et les données d'une table existante.

column

(column_name column_schema[, ...]) contient les informations de schéma de la table dans une liste d'éléments séparés par une virgule.

column :=
  column_name column_schema

column_schema :=
   {
     simple_type [NOT NULL]
     | STRUCT<field_list> [NOT NULL]
     | ARRAY<array_element_schema>
   }
   [OPTIONS(column_option_list)]

field_list :=
  field_name column_schema [, ...]

array_element_schema :=
  { simple_type | STRUCT<field_list> }
  [NOT NULL]
  • column_name correspond au nom de la colonne. Un nom de colonne :

    • ne doit contenir que des lettres (a-z, A-Z), des chiffres (0-9) ou des traits de soulignement (_) ;
    • doit commencer par une lettre ou un trait de soulignement ;
    • Peut contenir jusqu'à 300 caractères.
  • column_schema : semblable à un type de données, mais il accepte une contrainte NOT NULL facultative pour les types autres que ARRAY. column_schema est également compatible avec des options sur les colonnes de premier niveau et sur les champs STRUCT.

    column_schema : ne peut être utilisé que dans la liste des définitions de colonnes des instructions CREATE TABLE. Il ne peut pas être utilisé comme type à l'intérieur des expressions. Par exemple, CAST(1 AS INT64 NOT NULL) n'est pas valide.

  • simple_type : tout type de données compatible en dehors de STRUCT et ARRAY.

  • field_list : représente les champs dans un objet "struct".

  • field_name : nom du champ "struct". Les noms de champs "struct" sont soumis aux mêmes restrictions que les noms de colonnes.

  • NOT NULL : Lorsque la contrainte NOT NULL est présente pour une colonne ou un champ, la colonne ou le champ sont créés avec le mode REQUIRED. Inversement, lorsque la contrainte NOT NULL est absente, la colonne ou le champ sont créés avec le mode NULLABLE.

    Les colonnes et les champs de type ARRAY ne sont pas compatibles avec le modificateur NOT NULL. Par exemple, un column_schema correspondant à ARRAY<INT64> NOT NULL n'est pas valide, car les colonnes ARRAY présentent le mode REPEATED et peuvent être vides, mais ne peuvent pas être NULL. Un élément de tableau dans une table ne peut jamais être NULL, que la contrainte NOT NULL soit spécifiée ou non. Par exemple, ARRAY<INT64> correspond à ARRAY<INT64 NOT NULL>.

    L'attribut NOT NULL du champ column_schema d'une table ne se propage pas dans le reste de la table via les requêtes. Par exemple, si la table T contient une colonne déclarée comme x INT64 NOT NULL, CREATE TABLE dataset.newtable AS SELECT x FROM T crée une table nommée dataset.newtable dans laquelle x est NULLABLE.

partition_expression

PARTITION BY est une clause facultative qui contrôle le partitionnement de table. partition_expression est une expression qui détermine comment partitionner la table. L'expression de partition peut contenir les valeurs suivantes :

  • _PARTITIONDATE. Partitionner par date d'ingestion avec des partitions quotidiennes. Cette syntaxe ne peut pas être utilisée avec la clause AS query_statement.
  • DATE(_PARTITIONTIME). Équivaut à _PARTITIONDATE. Cette syntaxe ne peut pas être utilisée avec la clause AS query_statement.
  • <date_column>. Partitionner en fonction d'une colonne DATE avec des partitions quotidiennes.
  • DATE({ <timestamp_column> | <datetime_column> }). Partitionner en fonction d'une colonne TIMESTAMP ou DATETIME avec des partitions quotidiennes.
  • DATETIME_TRUNC(<datetime_column>, { DAY | HOUR | MONTH | YEAR }). Partitionner en fonction d'une colonne DATETIME avec le type de partitionnement spécifié.
  • TIMESTAMP_TRUNC(<timestamp_column>, { DAY | HOUR | MONTH | YEAR }). Partitionner une colonne TIMESTAMP avec le type de partitionnement spécifié.
  • TIMESTAMP_TRUNC(_PARTITIONTIME, { DAY | HOUR | MONTH | YEAR }). Partitionner par date d'ingestion avec le type de partitionnement spécifié. Cette syntaxe ne peut pas être utilisée avec la clause AS query_statement.
  • DATE_TRUNC(<date_column>, { MONTH | YEAR }). Partitionner en fonction d'une colonne DATE avec le type de partitionnement spécifié.
  • RANGE_BUCKET(<int64_column>, GENERATE_ARRAY(<start>, <end>[, <interval>])). Partitionner en fonction d'une colonne d'entiers avec la plage spécifiée, où :

    • start est la valeur de début inclusive du partitionnement par plages.
    • end est la valeur de fin exclusive du partitionnement par plages.
    • interval est la largeur de chaque plage au sein de la partition. La valeur par défaut est 1.

clustering_column_list

CLUSTER BY est une clause facultative qui contrôle le clustering des tables. clustering_column_list est une liste d'éléments séparés par des virgules qui détermine la façon de procéder au clustering de la table. Cette liste peut contenir jusqu'à quatre noms de colonnes à mettre en cluster.

table_option_list

La liste d'options vous permet de définir des options de table, telles qu'un libellé et une date/heure d'expiration. Vous pouvez inclure plusieurs options dans une liste d'éléments séparés par des virgules.

Spécifiez les listes d'options de table au format suivant :

NAME=VALUE, ...

NAME et VALUE doivent être utilisées selon l'une des combinaisons suivantes :

NAME VALUE Détails
expiration_timestamp TIMESTAMP

Exemple : expiration_timestamp=TIMESTAMP "2025-01-01 00:00:00 UTC"

Cette propriété est équivalente à la propriété de ressource de table expirationTime.

partition_expiration_days

FLOAT64

Exemple : partition_expiration_days=7

Définit le délai d'expiration de la partition en jours. Pour en savoir plus, consultez la section Définir le délai d'expiration de la partition. Par défaut, les partitions n'expirent pas.

Cette propriété est équivalente à la propriété de ressource de table timePartitioning.expirationMs mais utilise des jours au lieu de millisecondes. Un jour équivaut à 86 400 000 millisecondes, soit 24 heures.

Cette propriété ne peut être définie que si la table est partitionnée.

require_partition_filter

BOOL

Exemple : require_partition_filter=true

Spécifie si les requêtes sur cette table doivent inclure un filtre de prédicat qui filtre la colonne de partitionnement. Pour en savoir plus, consultez la section Définir les exigences de filtrage des partitions. La valeur par défaut est false.

Cette propriété est équivalente à la propriété de ressource de table timePartitioning.requirePartitionFilter.

Cette propriété ne peut être définie que si la table est partitionnée.

kms_key_name

STRING

Exemple : kms_key_name="projects/project_id/locations/location/keyRings/keyring/cryptoKeys/key"

Cette propriété est équivalente à la propriété de ressource de table encryptionConfiguration.kmsKeyName.

En savoir plus sur la protection des données avec des clés Cloud KMS

friendly_name

STRING

Exemple : friendly_name="my_table"

Cette propriété est équivalente à la propriété de ressource de table friendlyName.

description

STRING

Exemple : description="a table that expires in 2025"

Cette propriété est équivalente à la propriété de ressource de table description.

labels

ARRAY<STRUCT<STRING, STRING>>

Exemple : labels=[("org_unit", "development")]

Cette propriété est équivalente à la propriété de ressource de table labels.

VALUE est une expression constante ne contenant que des littéraux, des paramètres de requête et des fonctions scalaires. Si l'expression constante renvoie la valeur null, l'option NAME correspondante est ignorée.

L'expression constante ne peut pas contenir les éléments suivants :

  • Une référence à une table
  • Des sous-requêtes ou des instructions SQL telles que SELECT, CREATE et UPDATE
  • Des fonctions définies par l'utilisateur, des fonctions d'agrégation ou des fonctions d'analyse
  • Les fonctions scalaires suivantes :
    • ARRAY_TO_STRING
    • REPLACE
    • REGEXP_REPLACE
    • RAND
    • FORMAT
    • LPAD
    • RPAD
    • REPEAT
    • SESSION_USER
    • GENERATE_ARRAY
    • GENERATE_DATE_ARRAY

column_option_list

Le paramètre column_option_list dans column_schema permet de spécifier des options de colonne ou de champ facultatives. Les options de colonnes ont la même syntaxe et les mêmes exigences que les options de tables, mais une liste différente de noms (NAME) et de valeurs (VALUE) :

NAME VALUE Détails
description

STRING

Exemple : description="a unique id"

Cette propriété est équivalente à la propriété de ressource de table schema.fields[].description.

Exemples

Créer une table

L'exemple suivant crée une table partitionnée nommée newtable dans mydataset :

CREATE TABLE mydataset.newtable
(
  x INT64 OPTIONS(description="An optional INTEGER field"),
  y STRUCT<
    a ARRAY<STRING> OPTIONS(description="A repeated STRING field"),
    b BOOL
  >
)
PARTITION BY _PARTITIONDATE
OPTIONS(
  expiration_timestamp=TIMESTAMP "2025-01-01 00:00:00 UTC",
  partition_expiration_days=1,
  description="a table that expires in 2025, with each partition living for 24 hours",
  labels=[("org_unit", "development")]
)

Si vous n'avez pas configuré de projet par défaut, ajoutez un ID de projet au nom de l'ensemble de données dans l'exemple SQL, et placez le nom entre accents graves si project_id contient des caractères spéciaux : `project_id.dataset.table`. Ainsi, au lieu de mydataset.newtable, le qualificatif de table peut être `myproject.mydataset.newtable`.

Si le nom de la table existe dans l'ensemble de données, l'erreur suivante est renvoyée :

Already Exists: project_id:dataset.table

La table est partitionnée à l'aide de la partition_expression suivante : PARTITION BY _PARTITIONDATE. Cette expression partitionne la table en utilisant la date figurant dans la pseudo-colonne _PARTITIONDATE.

Le schéma de la table contient deux colonnes :

  • x : un entier, avec la description "Un champ INTEGER facultatif"
  • y : un type de données STRUCT contenant deux colonnes :

    • a : un tableau de chaînes, avec la description "Un champ STRING répété"
    • b : une valeur booléenne

La liste d'options de table spécifie :

  • les date et heure d'expiration de la table : 1er janvier 2025 à 00:00:00 UTC ;
  • le délai d'expiration de la partition : un jour ;
  • Description : A table that expires in 2025
  • Libellé : org_unit = development

Créer une table à partir d'une table existante

L'exemple suivant crée une table nommée top_words dans mydataset à partir d'une requête :

CREATE TABLE mydataset.top_words
OPTIONS(
  description="Top ten words per Shakespeare corpus"
) AS
SELECT
  corpus,
  ARRAY_AGG(STRUCT(word, word_count) ORDER BY word_count DESC LIMIT 10) AS top_words
FROM bigquery-public-data.samples.shakespeare
GROUP BY corpus;

Si vous n'avez pas configuré de projet par défaut, ajoutez un ID de projet au nom de l'ensemble de données dans l'exemple SQL, et placez le nom entre accents graves si project_id contient des caractères spéciaux : `project_id.dataset.table`. Ainsi, au lieu de mydataset.top_words, le qualificatif de table peut être `myproject.mydataset.top_words`.

Si le nom de la table existe dans l'ensemble de données, l'erreur suivante est renvoyée :

Already Exists: project_id:dataset.table

Le schéma de la table contient deux colonnes :

  • corpus : nom d'un corpus de Shakespeare ;
  • top_words : un tableau (ARRAY) de structures (STRUCT) contenant deux champs : word (une chaîne STRING) et word_count (un type de données INT64 représentant le nombre de mots).

La liste d'options de table spécifie :

  • Description : Top ten words per Shakespeare corpus

Créer une table seulement si la table n'existe pas

L'exemple suivant crée une table nommée newtable dans mydataset uniquement si aucune table nommée newtable n'existe dans mydataset. Si ce nom de table existe dans l'ensemble de données, aucune erreur n'est renvoyée et aucune mesure n'est prise.

CREATE TABLE IF NOT EXISTS mydataset.newtable (x INT64, y STRUCT<a ARRAY<STRING>, b BOOL>)
OPTIONS(
  expiration_timestamp=TIMESTAMP "2025-01-01 00:00:00 UTC",
  description="a table that expires in 2025",
  labels=[("org_unit", "development")]
)

Si vous n'avez pas configuré de projet par défaut, ajoutez un ID de projet au nom de l'ensemble de données dans l'exemple SQL, et placez le nom entre accents graves si project_id contient des caractères spéciaux : `project_id.dataset.table`. Ainsi, au lieu de mydataset.newtable, le qualificatif de table peut être `myproject.mydataset.newtable`.

Le schéma de la table contient deux colonnes :

  • x : un entier
  • y : un type de données STRUCT contenant a (un tableau de chaînes) et b (une valeur booléenne)

La liste d'options de table spécifie :

  • les date et heure d'expiration : 1er janvier 2025 à 00:00:00 UTC ;
  • Description : A table that expires in 2025
  • Libellé : org_unit = development

Créer ou remplacer une table

L'exemple suivant crée une table nommée newtable dans mydataset. Si newtable existe déjà dans mydataset, elle est remplacée par une table vide.

CREATE OR REPLACE TABLE mydataset.newtable (x INT64, y STRUCT<a ARRAY<STRING>, b BOOL>)
OPTIONS(
  expiration_timestamp=TIMESTAMP "2025-01-01 00:00:00 UTC",
  description="a table that expires in 2025",
  labels=[("org_unit", "development")]
)

Si vous n'avez pas configuré de projet par défaut, ajoutez un ID de projet au nom de l'ensemble de données dans l'exemple SQL, et placez le nom entre accents graves si project_id contient des caractères spéciaux : `project_id.dataset.table`. Ainsi, au lieu de mydataset.newtable, le qualificatif de table peut être `myproject.mydataset.newtable`.

Le schéma de la table contient deux colonnes :

  • x : un entier
  • y : un type de données STRUCT contenant a (un tableau de chaînes) et b (une valeur booléenne)

La liste d'options de table spécifie :

  • les date et heure d'expiration : 1er janvier 2025 à 00:00:00 UTC ;
  • Description : A table that expires in 2025
  • Libellé : org_unit = development

Créer une table avec des colonnes REQUIRED

L'exemple suivant crée une table nommée newtable dans mydataset. Le modificateur NOT NULL dans la liste de définitions de colonnes d'une instruction CREATE TABLE indique qu'une colonne ou un champ est créé en mode REQUIRED.

CREATE TABLE mydataset.newtable (
  x INT64 NOT NULL,
  y STRUCT<
    a ARRAY<STRING>,
    b BOOL NOT NULL,
    c FLOAT64
  > NOT NULL,
  z STRING
)

Si vous n'avez pas configuré de projet par défaut, ajoutez un ID de projet au nom de l'ensemble de données dans l'exemple SQL, et placez le nom entre accents graves si project_id contient des caractères spéciaux : `project_id.dataset.table`. Ainsi, au lieu de mydataset.newtable, le qualificatif de table peut être `myproject.mydataset.newtable`.

Si le nom de la table existe dans l'ensemble de données, l'erreur suivante est renvoyée :

Already Exists: project_id:dataset.table

Le schéma de la table contient trois colonnes :

  • x : un entier REQUIRED
  • y : un type de données STRUCT REQUIRED contenant a (un tableau de chaînes), b (une valeur booléenne REQUIRED) et c (un nombre à virgule flottante NULLABLE)
  • z : une chaîne NULLABLE

Créer une table avec des types de données paramétrés

L'exemple suivant crée une table nommée newtable dans mydataset. Les paramètres entre parenthèses spécifient que la colonne contient un type de données paramétré. Pour plus d'informations sur les types paramétrés, consultez la section Types de données paramétrés

CREATE TABLE mydataset.newtable (
  x STRING(10),
  y STRUCT<
    a ARRAY<BYTES(5)>,
    b NUMERIC(15, 2),
    c FLOAT64
  >,
  z BIGNUMERIC(35)
)

Si vous n'avez pas configuré de projet par défaut, ajoutez un ID de projet au nom de l'ensemble de données dans l'exemple SQL, et placez le nom entre accents graves si project_id contient des caractères spéciaux : `project_id.dataset.table`. Au lieu de mydataset.newtable, le qualificatif de table doit être `myproject.mydataset.newtable`.

Si le nom de la table existe dans l'ensemble de données, l'erreur suivante est renvoyée :

Already Exists: project_id:dataset.table

Le schéma de la table contient trois colonnes :

  • x : chaîne paramétrée d'une longueur maximale de 10
  • y : un type de données STRUCT contenant a (un tableau d'octets paramétrés, avec une longueur maximale de 5), b (un paramètre NUMERIC avec une précision maximale de 15 et une échelle maximale de 2) et c (un nombre à virgule flottante)
  • z : BIGNUMERIC paramétré avec une précision maximale de 35 et une échelle maximale de 0

Créer une table partitionnée

L'exemple suivant crée une table partitionnée nommée newtable dans mydataset à l'aide d'une colonne DATE :

CREATE TABLE mydataset.newtable (transaction_id INT64, transaction_date DATE)
PARTITION BY transaction_date
OPTIONS(
  partition_expiration_days=3,
  description="a table partitioned by transaction_date"
)

Si vous n'avez pas configuré de projet par défaut, ajoutez un ID de projet au nom de l'ensemble de données dans l'exemple SQL, et placez le nom entre accents graves si project_id contient des caractères spéciaux : `project_id.dataset.table`. Ainsi, au lieu de mydataset.newtable, le qualificatif de table peut être `myproject.mydataset.newtable`.

Le schéma de la table contient deux colonnes :

  • transaction_id : un entier
  • date_transaction : une date

La liste d'options de table spécifie :

  • le délai d'expiration de la partition : trois jours ;
  • Description : A table partitioned by transaction_date

Créer une table partitionnée à partir d'un résultat de requête

L'exemple suivant crée une table partitionnée nommée days_with_rain dans mydataset à l'aide d'une colonne DATE :

CREATE TABLE mydataset.days_with_rain
PARTITION BY date
OPTIONS (
  partition_expiration_days=365,
  description="weather stations with precipitation, partitioned by day"
) AS
SELECT
  DATE(CAST(year AS INT64), CAST(mo AS INT64), CAST(da AS INT64)) AS date,
  (SELECT ANY_VALUE(name) FROM `bigquery-public-data.noaa_gsod.stations` AS stations
   WHERE stations.usaf = stn) AS station_name,  -- Stations can have multiple names
  prcp
FROM `bigquery-public-data.noaa_gsod.gsod2017` AS weather
WHERE prcp != 99.9  -- Filter unknown values
  AND prcp > 0      -- Filter stations/days with no precipitation

Si vous n'avez pas configuré de projet par défaut, ajoutez un ID de projet au nom de l'ensemble de données dans l'exemple SQL, et placez le nom entre accents graves si project_id contient des caractères spéciaux : `project_id.dataset.table`. Ainsi, au lieu de mydataset.days_with_rain, le qualificatif de table peut être `myproject.mydataset.days_with_rain`.

Le schéma de la table contient deux colonnes :

  • date : la DATE de collecte des données
  • station_name : le nom de la station météo sous forme de chaîne (STRING)
  • prcp : la quantité de précipitations en pouces, au format FLOAT64

La liste d'options de table spécifie :

  • le délai d'expiration de la partition : un an ;
  • Description : Weather stations with precipitation, partitioned by day

Créer une table en cluster

Exemple 1

L'exemple suivant crée une table en cluster nommée myclusteredtable dans mydataset. La table est une table partitionnée suivant une colonne TIMESTAMP et mise en cluster par une colonne STRING nommée customer_id.

CREATE TABLE mydataset.myclusteredtable
(
  timestamp TIMESTAMP,
  customer_id STRING,
  transaction_amount NUMERIC
)
PARTITION BY DATE(timestamp)
CLUSTER BY customer_id
OPTIONS (
  partition_expiration_days=3,
  description="a table clustered by customer_id"
)

Si vous n'avez pas configuré de projet par défaut, ajoutez un ID de projet au nom de l'ensemble de données dans l'exemple SQL, et placez le nom entre accents graves si project_id contient des caractères spéciaux : `project_id.dataset.table`. Ainsi, au lieu de mydataset.myclusteredtable, le qualificatif de table peut être `myproject.mydataset.myclusteredtable`.

Le schéma de la table contient trois colonnes :

  • timestamp : heure de la collecte des données sous forme d'horodatage (TIMESTAMP)
  • customer_id : ID client sous forme de chaîne (STRING)
  • transaction_amount : montant de la transaction au format numérique (NUMERIC)

La liste d'options de table spécifie :

  • le délai d'expiration de la partition : trois jours ;
  • Description : A table clustered by customer_id
Exemple 2

L'exemple suivant crée une table en cluster nommée myclusteredtable dans mydataset. La table est une table partitionnée par date d'ingestion.

CREATE TABLE mydataset.myclusteredtable
(
  customer_id STRING,
  transaction_amount NUMERIC
)
PARTITION BY DATE(_PARTITIONTIME)
CLUSTER BY
  customer_id
OPTIONS (
  partition_expiration_days=3,
  description="a table clustered by customer_id"
)

Si vous n'avez pas configuré de projet par défaut, ajoutez un ID de projet au nom de l'ensemble de données dans l'exemple SQL, et placez le nom entre accents graves si project_id contient des caractères spéciaux : `project_id.dataset.table`. Ainsi, au lieu de mydataset.myclusteredtable, le qualificatif de table peut être `myproject.mydataset.myclusteredtable`.

Le schéma de la table contient deux colonnes :

  • customer_id : ID client sous forme de chaîne (STRING)
  • transaction_amount : montant de la transaction au format numérique (NUMERIC)

La liste d'options de table spécifie :

  • le délai d'expiration de la partition : trois jours ;
  • Description : A table clustered by customer_id
Exemple 3

L'exemple suivant crée une table en cluster nommée myclusteredtable dans mydataset. La table n'est pas partitionnée.

CREATE TABLE mydataset.myclusteredtable
(
  customer_id STRING,
  transaction_amount NUMERIC
)
CLUSTER BY
  customer_id
OPTIONS (
  description="a table clustered by customer_id"
)

Si vous n'avez pas configuré de projet par défaut, ajoutez un ID de projet au nom de l'ensemble de données dans l'exemple SQL, et placez le nom entre accents graves si project_id contient des caractères spéciaux : `project_id.dataset.table`. Ainsi, au lieu de mydataset.myclusteredtable, le qualificatif de table peut être `myproject.mydataset.myclusteredtable`.

Le schéma de la table contient deux colonnes :

  • customer_id : ID client sous forme de chaîne (STRING)
  • transaction_amount : montant de la transaction au format numérique (NUMERIC)

La liste d'options de table spécifie :

  • Description : A table clustered by customer_id

Créer une table en cluster à partir d'un résultat de requête

Exemple 1

L'exemple suivant crée une table en cluster nommée myclusteredtable dans mydataset en utilisant le résultat d'une requête. La table est une table partitionnée suivant une colonne TIMESTAMP.

CREATE TABLE mydataset.myclusteredtable
(
  timestamp TIMESTAMP,
  customer_id STRING,
  transaction_amount NUMERIC
)
PARTITION BY DATE(timestamp)
CLUSTER BY
  customer_id
OPTIONS (
  partition_expiration_days=3,
  description="a table clustered by customer_id"
)
AS SELECT * FROM mydataset.myothertable

Si vous n'avez pas configuré de projet par défaut, ajoutez un ID de projet au nom de l'ensemble de données dans l'exemple SQL, et placez le nom entre accents graves si project_id contient des caractères spéciaux : `project_id.dataset.table`. Ainsi, au lieu de mydataset.myclusteredtable, le qualificatif de table peut être `myproject.mydataset.myclusteredtable`.

Le schéma de la table contient trois colonnes :

  • timestamp : heure de la collecte des données sous forme d'horodatage (TIMESTAMP)
  • customer_id : ID client sous forme de chaîne (STRING)
  • transaction_amount : montant de la transaction au format numérique (NUMERIC)

La liste d'options de table spécifie :

  • le délai d'expiration de la partition : trois jours ;
  • Description : A table clustered by customer_id
Exemple 2

L'exemple suivant crée une table en cluster nommée myclusteredtable dans mydataset en utilisant le résultat d'une requête. La table n'est pas partitionnée.

CREATE TABLE mydataset.myclusteredtable
(
  customer_id STRING,
  transaction_amount NUMERIC
)
CLUSTER BY
  customer_id
OPTIONS (
  description="a table clustered by customer_id"
)
AS SELECT * FROM mydataset.myothertable

Si vous n'avez pas configuré de projet par défaut, ajoutez un ID de projet au nom de l'ensemble de données dans l'exemple SQL, et placez le nom entre accents graves si project_id contient des caractères spéciaux : `project_id.dataset.table`. Ainsi, au lieu de mydataset.myclusteredtable, le qualificatif de table peut être `myproject.mydataset.myclusteredtable`.

Le schéma de la table contient deux colonnes :

  • customer_id : ID client sous forme de chaîne (STRING)
  • transaction_amount : montant de la transaction au format numérique (NUMERIC)

La liste d'options de table spécifie :

  • Description : A table clustered by customer_id

Créer une table temporaire

L'exemple suivant crée une table temporaire nommée Example et y insère des valeurs.

CREATE TEMP TABLE Example
(
  x INT64,
  y STRING
);

INSERT INTO Example
VALUES (5, 'foo');

INSERT INTO Example
VALUES (6, 'bar');

SELECT *
FROM Example;

Ce script renvoie le résultat suivant :

+-----+---+-----+
| Row | x | y   |
+-----+---|-----+
| 1   | 5 | foo |
| 2   | 6 | bar |
+-----+---|-----+

Instruction CREATE TABLE LIKE

Crée une table avec toutes les métadonnées d'une autre table.

Syntaxe

CREATE [ OR REPLACE ] TABLE [ IF NOT EXISTS ]
table_name
LIKE [[project_name.]dataset_name.]source_table_name
[PARTITION BY partition_expression]
[CLUSTER BY clustering_column_list]
[OPTIONS(table_option_list)]
[AS query_statement]

Détails

À l'exception de l'utilisation de la clause LIKE qui remplace une liste de colonnes, la syntaxe est identique à la syntaxe CREATE TABLE.

L'instruction CREATE TABLE LIKE ne copie que les métadonnées de la table source. Vous pouvez utiliser la clause as query_statement pour inclure des données dans la nouvelle table.

La nouvelle table n'a pas de relation avec la table source après sa création. Par conséquent, les modifications apportées à la table source ne seront pas répercutées dans la nouvelle table.

Par défaut, la nouvelle table hérite des métadonnées de partitionnement, de clustering et d'options de la table source. Vous pouvez personnaliser les métadonnées de la nouvelle table à l'aide des clauses facultatives de l'instruction SQL. Par exemple, si vous souhaitez spécifier un autre ensemble d'options pour la nouvelle table, incluez la clause OPTIONS avec une liste d'options et de valeurs. Ce comportement correspond à celui de ALTER TABLE SET OPTIONS.

Exemples

Exemple 1

L'exemple suivant crée une table nommée newtable dans mydataset avec les mêmes métadonnées que sourcetable :

CREATE TABLE mydataset.newtable
LIKE mydataset.newtable

Exemple 2

L'exemple suivant crée une table nommée newtable dans mydataset avec les mêmes métadonnées que sourcetable et avec les données de l'instruction SELECT :

CREATE TABLE mydataset.newtable
LIKE mydataset.soucetable
AS SELECT * FROM mydataset.myothertable

Instruction CREATE TABLE COPY

Crée une table avec les mêmes métadonnées et données qu'une autre table.

Syntaxe

CREATE [ OR REPLACE ] TABLE [ IF NOT EXISTS ] table_name
COPY source_table_name
[OPTIONS(table_option_list)]

Détails

À l'exception de l'utilisation de la clause COPY qui remplace une liste de colonnes, la syntaxe est identique à la syntaxe CREATE TABLE.

L'instruction CREATE TABLE COPY copie à la fois les métadonnées et les données de la table source.

La nouvelle table n'a pas de relation avec la table source après sa création. Par conséquent, les modifications apportées à la table source ne seront pas répercutées dans la nouvelle table.

La nouvelle table hérite du partitionnement et du clustering de la table source. Par défaut, les métadonnées des options de table de la table source sont également héritées. Bien que vous puissiez personnaliser les options de la nouvelle table à l'aide des clauses OPTIONS de l'instruction SQL. Le comportement équivaut à exécuter ALTER TABLE SET OPTIONS après la copie de la table.

Instruction CREATE SNAPSHOT TABLE

Crée un instantané de table d'une table standard ou crée une copie d'un instantané de table.

Syntaxe

CREATE SNAPSHOT TABLE [ IF NOT EXISTS ] table_snapshot_name
CLONE source_table_name
[FOR SYSTEM_TIME AS OF time_expression]
[OPTIONS(snapshot_option_list)]

Arguments

  • IF NOT EXISTS : si un instantané de table ou une autre ressource de table portant le même nom existe, l'instruction CREATE n'a aucun effet.

  • table_snapshot_name : nom de l'instantané de table que vous souhaitez créer. Le nom de l'instantané de table doit être unique pour chaque ensemble de données. Consultez la section Syntaxe du chemin d'accès à une table.

  • source_table_name : nom de la table dont vous souhaitez prendre un instantané ou de l'instantané de table que vous souhaitez copier. Consultez la section Syntaxe du chemin d'accès à une table.

    Si la table source est une table standard, BigQuery crée un instantané de la table source. Si la table source est un instantané de table, BigQuery crée une copie de l'instantané de table.

  • FOR SYSTEM_TIME AS OF : permet de sélectionner la version de la table à l'heure spécifiée par timestamp_expression. Elle ne peut être utilisée que lors de la création d'un instantané de table. Elle ne peut pas être utilisée lors de la copie d'un instantané de table.

  • snapshot_option_list : options de création d'instantanés de table supplémentaires, telles qu'un libellé et une date/heure d'expiration.

Détails

Les instructions CREATE SNAPSHOT TABLE doivent respecter les règles suivantes :

  • Chaque requête ne peut contenir qu'une seule instruction CREATE.
  • La table en cours de clonage doit être l'une des suivantes :
    • Une table standard (et non une vue ou une vue matérialisée)
    • Un instantané de table
  • La clause FOR SYSTEM_TIME AS OF ne peut être utilisée que lors de la création d'un instantané de table. Elle ne peut pas être utilisée lors de la copie d'un instantané de table.

snapshot_option_list

La liste d'options vous permet de définir des options d'instantané de table, telles qu'un libellé et un délai d'expiration. Vous pouvez inclure plusieurs options dans une liste d'éléments séparés par des virgules.

Spécifiez les listes d'options des instantanés de table au format suivant :

NAME=VALUE, ...

NAME et VALUE doivent être utilisées selon l'une des combinaisons suivantes :

NAME VALUE Détails
expiration_timestamp TIMESTAMP

Exemple : expiration_timestamp=TIMESTAMP "2025-01-01 00:00:00 UTC"

Cette propriété est équivalente à la propriété de ressource de table expirationTime.

friendly_name

STRING

Exemple : friendly_name="my_table_snapshot"

Cette propriété est équivalente à la propriété de ressource de table friendlyName.

description

STRING

Exemple : description="A table snapshot that expires in 2025"

Cette propriété est équivalente à la propriété de ressource de table description.

labels

ARRAY<STRUCT<STRING, STRING>>

Exemple : labels=[("org_unit", "development")]

Cette propriété est équivalente à la propriété de ressource de table labels.

VALUE est une expression constante qui ne contient que des littéraux, des paramètres de requête et des fonctions scalaires. Si l'expression constante renvoie la valeur null, l'option NAME correspondante est ignorée.

L'expression constante ne peut pas contenir les éléments suivants :

  • Une référence à une table
  • Des sous-requêtes ou des instructions SQL telles que SELECT, CREATE et UPDATE
  • Des fonctions définies par l'utilisateur, des fonctions d'agrégation ou des fonctions d'analyse
  • Les fonctions scalaires suivantes :
    • ARRAY_TO_STRING
    • REPLACE
    • REGEXP_REPLACE
    • RAND
    • FORMAT
    • LPAD
    • RPAD
    • REPEAT
    • SESSION_USER
    • GENERATE_ARRAY
    • GENERATE_DATE_ARRAY

Exemples

Créer un instantané de table : échec s'il existe déjà

L'exemple suivant crée un instantané de la table myproject.mydataset.mytable. L'instantané de la table est créé dans l'ensemble de données mydataset et s'appelle mytablesnapshot :

CREATE SNAPSHOT TABLE `myproject.mydataset.mytablesnapshot`
CLONE `myproject.mydataset.mytable`
OPTIONS(
  expiration_timestamp=TIMESTAMP_ADD(CURRENT_TIMESTAMP(), INTERVAL 48 HOUR),
  friendly_name="my_table_snapshot",
  description="A table snapshot that expires in 2 days",
  labels=[("org_unit", "development")]
)

Si le nom de l'instantané de table existe déjà dans l'ensemble de données, l'erreur suivante est renvoyée :

Already Exists: myproject.mydataset.mytablesnapshot

La liste d'options d'instantané de table spécifie les éléments suivants :

  • les date/heure d'expiration : 48 heures après la création de l'instantané de la table ;
  • Nom descriptif : my_table_snapshot
  • Description : A table snapshot that expires in 2 days
  • Libellé : org_unit = development

Créer un instantané de table : ignorer s'il existe déjà

L'exemple suivant crée un instantané de la table myproject.mydataset.mytable. L'instantané de la table est créé dans l'ensemble de données mydataset et s'appelle mytablesnapshot :

CREATE SNAPSHOT TABLE IF NOT EXISTS `myproject.mydataset.mytablesnapshot`
CLONE `myproject.mydataset.mytable`
OPTIONS(
  expiration_timestamp=TIMESTAMP_ADD(CURRENT_TIMESTAMP(), INTERVAL 48 HOUR),
  friendly_name="my_table_snapshot",
  description="A table snapshot that expires in 2 days"
  labels=[("org_unit", "development")]
)

La liste d'options d'instantané de table spécifie les éléments suivants :

  • les date/heure d'expiration : 48 heures après la création de l'instantané de la table ;
  • Nom descriptif : my_table_snapshot
  • Description : A table snapshot that expires in 2 days
  • Libellé : org_unit = development

Si ce nom d'instantané de table existe déjà dans l'ensemble de données, aucune action n'est effectuée et aucune erreur n'est renvoyée.

Pour en savoir plus sur la restauration des instantanés de table, consultez la section CREATE TABLE CLONE.

Pour en savoir plus sur la suppression des instantanés de table, consultez la section DROP SNAPSHOT TABLE.

Instruction CREATE TABLE CLONE

Restaure un instantané de table dans une table standard.

Syntaxe

CREATE [ OR REPLACE ] TABLE [ IF NOT EXISTS ] destination_table_name
CLONE table_snapshot_name
[OPTIONS(table_option_list)]

Arguments

  • OR REPLACE : remplace une table portant le même nom si elle existe. ne peut pas s'afficher avec IF NOT EXISTS.

  • IF NOT EXISTS : si le nom de la table de destination spécifié existe déjà, l'instruction CREATE n'a aucun effet. Ne peut pas s'afficher avec OR REPLACE.

  • destination_table_name : nom de la table que vous souhaitez créer. Consultez la section Syntaxe du chemin d'accès à une table. Le nom de la table doit être unique pour chaque ensemble de données.

  • table_snapshot_name : nom de l'instantané de table que vous souhaitez restaurer. Consultez la section Syntaxe du chemin d'accès à une table.

  • table_option_list : options de création de table supplémentaires, telles qu'un libellé et une date/heure d'expiration.

Détails

Les instructions CREATE TABLE CLONE doivent respecter les règles suivantes :

  • Chaque requête ne peut contenir qu'une seule instruction CREATE.
  • La table en cours de clonage doit être un instantané de table.

OPTIONS

Les options CREATE TABLE CLONE sont identiques aux options CREATE TABLE.

Exemples

Restaurer un instantané de table : échec si la table de destination existe déjà

L'exemple suivant crée la table myproject.mydataset.mytable à partir de l'instantané de table myproject.mydataset.mytablesnapshot :

CREATE TABLE `myproject.mydataset.mytable`
CLONE `myproject.mydataset.mytablesnapshot`
OPTIONS(
  expiration_timestamp=TIMESTAMP_ADD(CURRENT_TIMESTAMP(), INTERVAL 365 DAY),
  friendly_name="my_table",
  description="A table that expires in 1 year",
  labels=[("org_unit", "development")]
)

Si le nom de la table existe dans l'ensemble de données, l'erreur suivante est renvoyée :

Already Exists: myproject.mydataset.mytable.

La liste d'options de table spécifie :

  • les date/heure d'expiration : 365 jours après la création de la table ;
  • Nom descriptif : my_table
  • Description : A table that expires in 1 year
  • Libellé : org_unit = development

Restaurer un instantané de table : ignorer si une table de destination existe déjà

L'exemple suivant crée la table myproject.mydataset.mytable à partir de l'instantané de table myproject.mydataset.mytableshapshot :

CREATE TABLE IF NOT EXISTS `myproject.mydataset.mytable`
OPTIONS(
  expiration_timestamp=TIMESTAMP_ADD(CURRENT_TIMESTAMP(), INTERVAL 365 DAY),
  friendly_name="my_table",
  description="A table that expires in 1 year",
  labels=[("org_unit", "development")]
)
CLONE `myproject.mydataset.mytablesnapshot`

La liste d'options de table spécifie :

  • Date d'expiration : 365 jours après la création de la table
  • Nom descriptif : my_table
  • Description : A table that expires in 1 year
  • Libellé : org_unit = development

Si le nom de la table existe déjà dans l'ensemble de données, aucune action n'est effectuée et aucune erreur n'est renvoyée.

Pour en savoir plus sur la création d'instantanés de table, consultez la section CREATE SNAPSHOT TABLE.

Pour en savoir plus sur la suppression des instantanés de table, consultez la section DROP SNAPSHOT TABLE.

Instruction CREATE VIEW

Crée une vue.

Syntaxe

CREATE [ OR REPLACE ] VIEW [ IF NOT EXISTS ] view_name
[(view_column_name_list)]
[OPTIONS(view_option_list)]
AS query_expression

Arguments

  • OR REPLACE : remplace toute vue portant le même nom si elle existe. ne peut pas s'afficher avec IF NOT EXISTS.

  • IF NOT EXISTS : si une vue ou une autre ressource de table portant le même nom existe, l'instruction CREATE n'a aucun effet. Ne peut pas s'afficher avec OR REPLACE.

  • view_name : nom de la vue que vous créez. Consultez la section Syntaxe du chemin d'accès à une table.

  • view_column_name_list : permet de spécifier explicitement les noms des colonnes de la vue, qui peuvent être des alias des noms de colonnes dans la requête SQL sous-jacente.

  • view_option_list : options de création de vues supplémentaires, telles qu'un libellé et une date/heure d'expiration.

  • query_expression : expression de requête SQL standard utilisée pour définir la vue.

Détails

Les instructions CREATE VIEW doivent respecter les règles suivantes :

  • Chaque requête ne peut contenir qu'une seule instruction CREATE.

view_column_name_list

La liste des noms de colonnes d'une vue est facultative. Les noms doivent être uniques mais ne doivent pas nécessairement être identiques aux noms de colonnes de la requête SQL sous-jacente. Par exemple, si votre vue a été créée avec l'instruction suivante :

CREATE VIEW mydataset.age_groups(age, count) AS SELECT age, COUNT(*)
FROM mydataset.people
group by age;

Ensuite, vous pouvez l'interroger avec :

SELECT age, count from mydataset.age_groups;

Le nombre de colonnes de la liste des noms de colonnes doit correspondre au nombre de colonnes dans la requête SQL sous-jacente. Si les colonnes de la table de la requête SQL sous-jacente sont ajoutées ou supprimées, la vue n'est plus valide et doit être recréée. Par exemple, si la colonne age est supprimée de la table mydataset.people, la vue créée dans l'exemple précédent n'est plus valide.

view_option_list

La liste d'options vous permet de définir des options de vue, telles qu'un libellé et une date/heure d'expiration. Vous pouvez inclure plusieurs options dans une liste d'éléments séparés par des virgules.

Spécifiez les listes d'options de vue au format suivant :

NAME=VALUE, ...

NAME et VALUE doivent être utilisées selon l'une des combinaisons suivantes :

NAME VALUE Détails
expiration_timestamp TIMESTAMP

Exemple : expiration_timestamp=TIMESTAMP "2025-01-01 00:00:00 UTC"

Cette propriété est équivalente à la propriété de ressource de table expirationTime.

friendly_name

STRING

Exemple : friendly_name="my_view"

Cette propriété est équivalente à la propriété de ressource de table friendlyName.

description

STRING

Exemple : description="a view that expires in 2025"

Cette propriété est équivalente à la propriété de ressource de table description.

labels

ARRAY<STRUCT<STRING, STRING>>

Exemple : labels=[("org_unit", "development")]

Cette propriété est équivalente à la propriété de ressource de table labels.

VALUE est une expression constante ne contenant que des littéraux, des paramètres de requête et des fonctions scalaires. Si l'expression constante renvoie la valeur null, l'option NAME correspondante est ignorée.

L'expression constante ne peut pas contenir les éléments suivants :

  • Une référence à une table
  • Des sous-requêtes ou des instructions SQL telles que SELECT, CREATE et UPDATE
  • Des fonctions définies par l'utilisateur, des fonctions d'agrégation ou des fonctions d'analyse
  • Les fonctions scalaires suivantes :
    • ARRAY_TO_STRING
    • REPLACE
    • REGEXP_REPLACE
    • RAND
    • FORMAT
    • LPAD
    • RPAD
    • REPEAT
    • SESSION_USER
    • GENERATE_ARRAY
    • GENERATE_DATE_ARRAY

Projet par défaut dans le corps des vues

Si la vue est créée dans le même projet que celui utilisé pour exécuter l'instruction CREATE VIEW, l'expression de requête (query_expression) du corps de la vue peut référencer des entités sans spécifier le projet. Le projet par défaut est le projet propriétaire de la vue. Prenons l'exemple de requête ci-dessous.

CREATE VIEW myProject.myDataset.myView AS SELECT * FROM anotherDataset.myTable;

Après avoir exécuté la requête CREATE VIEW ci-dessus dans le projet myProject, vous pouvez exécuter la requête SELECT * FROM myProject.myDataset.myView. Quel que soit le projet avec lequel vous souhaitez exécuter cette requête SELECT, la table référencée anotherDataset.myTable est toujours résolue avec le projet myProject.

Si la vue n'est pas créée dans le même projet que celui utilisé pour exécuter l'instruction CREATE VIEW, toutes les références présentes dans l'expression de requête (query_expression) du corps de la vue doivent inclure les ID de projet. Ainsi, l'exemple de requête CREATE VIEW précédent n'est pas valide s'il s'exécute dans un projet différent de myProject.

Exemples

Créer une vue

L'exemple suivant crée une vue nommée newview dans mydataset :

CREATE VIEW `myproject.mydataset.newview`
OPTIONS(
  expiration_timestamp=TIMESTAMP_ADD(CURRENT_TIMESTAMP(), INTERVAL 48 HOUR),
  friendly_name="newview",
  description="a view that expires in 2 days",
  labels=[("org_unit", "development")]
)
AS SELECT column_1, column_2, column_3 FROM `myproject.mydataset.mytable`

Si le nom de la vue existe déjà dans l'ensemble de données, l'erreur suivante est renvoyée :

Already Exists: project_id:dataset.table

La vue est définie à l'aide de la requête SQL standard suivante :

SELECT column_1, column_2, column_3 FROM `myproject.mydataset.mytable`

La liste d'options de vue spécifie :

  • les date/heure d'expiration : 48 heures à partir de la création de la vue ;
  • Nom descriptif : newview
  • Description : A view that expires in 2 days
  • Libellé : org_unit = development

Créer une vue seulement si la vue n'existe pas déjà

L'exemple suivant crée une vue nommée newview dans mydataset uniquement si aucune vue nommée newview n'existe dans mydataset. Si le nom de la vue existe déjà dans l'ensemble de données, aucune erreur n'est renvoyée et aucune action n'est effectuée.

CREATE VIEW IF NOT EXISTS `myproject.mydataset.newview`
OPTIONS(
  expiration_timestamp=TIMESTAMP_ADD(CURRENT_TIMESTAMP(), INTERVAL 48 HOUR),
  friendly_name="newview",
  description="a view that expires in 2 days",
  labels=[("org_unit", "development")]
)
AS SELECT column_1, column_2, column_3 FROM `myproject.mydataset.mytable`

La vue est définie à l'aide de la requête SQL standard suivante :

SELECT column_1, column_2, column_3 FROM `myproject.mydataset.mytable`

La liste d'options de vue spécifie :

  • les date/heure d'expiration : 48 heures à partir de la création de la vue ;
  • Nom descriptif : newview
  • Description : A view that expires in 2 days
  • Libellé : org_unit = development

Créer ou remplacer une vue

L'exemple suivant crée une vue nommée newview dans mydataset. Si newview existe déjà dans mydataset, elle est remplacée à l'aide de l'expression de requête spécifiée.

CREATE OR REPLACE VIEW `myproject.mydataset.newview`
OPTIONS(
  expiration_timestamp=TIMESTAMP_ADD(CURRENT_TIMESTAMP(), INTERVAL 48 HOUR),
  friendly_name="newview",
  description="a view that expires in 2 days",
  labels=[("org_unit", "development")]
)
AS SELECT column_1, column_2, column_3 FROM `myproject.mydataset.mytable`

La vue est définie à l'aide de la requête SQL standard suivante :

SELECT column_1, column_2, column_3 FROM myproject.mydataset.mytable

La liste d'options de vue spécifie :

  • les date/heure d'expiration : 48 heures à partir de la création de la vue ;
  • Nom descriptif : newview
  • Description : A view that expires in 2 days
  • Libellé : org_unit = development

Instruction CREATE MATERIALIZED VIEW

Crée une vue matérialisée.

Syntaxe

CREATE MATERIALIZED VIEW [ IF NOT EXISTS ] materialized_view_name
[PARTITION BY partition_expression]
[CLUSTER BY clustering_column_list]
[OPTIONS(materialized_view_option_list)]
AS query_expression

Arguments

  • OR REPLACE : remplace toute vue matérialisée portant le même nom si elle existe. Ne peut pas s'afficher avec IF NOT EXISTS.

  • IF NOT EXISTS : si une vue matérialisée ou une autre ressource de table portant le même nom existe, l'instruction CREATE n'a aucun effet. Ne peut pas s'afficher avec OR REPLACE.

  • materialized_view_name : nom de la vue matérialisée que vous créez. Consultez la section Syntaxe du chemin d'accès à une table.

    Si project_name est omis dans le nom de la vue matérialisée ou s'il est identique au projet qui exécute cette requête LDD, ce dernier est également utilisé comme projet par défaut pour les références aux tables, fonctions et autres ressources dans query_expression. Le projet par défaut des références est fixe et ne dépend pas des futures requêtes qui appellent la nouvelle vue matérialisée. Dans le cas contraire, toutes les références dans l'expression de requête (query_expression) doivent spécifier des noms de projets.

    Le nom de la vue matérialisée doit être unique pour chaque ensemble de données.

  • partition_expression : expression qui détermine comment partitionner la table. Une vue matérialisée ne peut être partitionnée que de la même manière que la table dans query expression (la table de base est partitionnée).

  • clustering_column_list : liste des références de colonnes séparées par une virgule, qui déterminent la façon de procéder au clustering de la vue matérialisée.

  • materialized_view_option_list** vous permet de spécifier des options de vue matérialisée supplémentaires, telles que l'état d'activation de l'actualisation, l'intervalle d'actualisation, un libellé ou encore un délai d'expiration.

  • query_expression : expression de requête SQL standard utilisée pour définir la vue matérialisée.

Détails

Les instructions CREATE MATERIALIZED VIEW doivent respecter les règles suivantes :

  • Chaque requête ne peut contenir qu'une seule instruction CREATE.

Projet par défaut dans le corps des vues matérialisées

Si la vue matérialisée est créée dans le même projet que celui utilisé pour exécuter l'instruction CREATE MATERIALIZED VIEW, l'expression de requête (query_expression) du corps de la vue peut référencer des entités sans spécifier le projet. Le projet par défaut est le projet propriétaire de la vue matérialisée. Prenons l'exemple de requête ci-dessous.

CREATE MATERIALIZED VIEW myProject.myDataset.myView AS SELECT * FROM anotherDataset.myTable;

Après avoir exécuté la requête CREATE MATERIALIZED VIEW ci-dessus dans le projet myProject, vous pouvez exécuter la requête SELECT * FROM myProject.myDataset.myView. Quel que soit le projet avec lequel vous souhaitez exécuter cette requête SELECT, la table référencée anotherDataset.myTable est toujours résolue avec le projet myProject.

Si la vue matérialisée n'est pas créée dans le même projet que celui utilisé pour exécuter l'instruction CREATE VIEW, toutes les références présentes dans l'expression de requête (query_expression) du corps de la vue matérialisée doivent inclure les ID de projet. Ainsi, l'exemple de requête CREATE MATERIALIZED VIEW précédent n'est pas valide s'il s'exécute dans un projet différent de myProject.

materialized_view_option_list

La liste d'options vous permet de définir des options de vue matérialisée, telles que l'état de l'actualisation, l'intervalle d'actualisation, un libellé ou encore un délai d'expiration. Vous pouvez inclure plusieurs options dans une liste d'éléments séparés par des virgules.

Spécifiez les listes d'options de vue matérialisée au format suivant :

NAME=VALUE, ...

NAME et VALUE doivent être utilisées selon l'une des combinaisons suivantes :

NAME VALUE Détails
enable_refresh BOOLEAN

Exemple : enable_refresh=false

refresh_interval_minutes FLOAT64

Exemple : refresh_interval_minutes=20

expiration_timestamp TIMESTAMP

Exemple : expiration_timestamp=TIMESTAMP "2025-01-01 00:00:00 UTC"

Cette propriété est équivalente à la propriété de ressource de table expirationTime.

friendly_name

STRING

Exemple : friendly_name="my_mv"

Cette propriété est équivalente à la propriété de ressource de table friendlyName.

description

STRING

Exemple : description="a materialized view that expires in 2025"

Cette propriété est équivalente à la propriété de ressource de table description.

labels

ARRAY<STRUCT<STRING, STRING>>

Exemple : labels=[("org_unit", "development")]

Cette propriété est équivalente à la propriété de ressource de table labels.

Exemples

Créer une vue matérialisée

L'exemple suivant crée une vue matérialisée nommée new_mv dans mydataset :

CREATE MATERIALIZED VIEW `myproject.mydataset.new_mv`
OPTIONS(
  expiration_timestamp=TIMESTAMP_ADD(CURRENT_TIMESTAMP(), INTERVAL 48 HOUR),
  friendly_name="new_mv",
  description="a materialized view that expires in 2 days",
  labels=[("org_unit", "development")],
  enable_refresh=true,
  refresh_interval_minutes=20
)
AS SELECT column_1, SUM(column_2) AS sum_2, AVG(column_3) AS avg_3
FROM `myproject.mydataset.mytable`
GROUP BY column_1

Si le nom de la vue matérialisée existe déjà dans l'ensemble de données, l'erreur suivante est renvoyée :

Already Exists: project_id:dataset.materialized_view

Lorsque vous utilisez une instruction LDD pour créer une vue matérialisée, vous devez spécifier le projet, l'ensemble de données et la vue matérialisée au format suivant : `project_id.dataset.materialized_view` (en intégrant les accents graves si project_id contient des caractères spéciaux), par exemple, `myproject.mydataset.new_mv`.

La vue matérialisée est définie à l'aide de la requête SQL standard suivante :

SELECT column_1, column_2, column_3 FROM `myproject.mydataset.mytable`

La liste d'options de vue matérialisée spécifie :

  • les date/heure d'expiration : 48 heures à partir de la création de la vue matérialisée ;
  • Nom descriptif : new_mv
  • Description : A materialized view that expires in 2 days
  • Libellé : org_unit = development
  • l'état d'activation de l'actualisation : true ;
  • l'intervalle d'actualisation : 20 minutes.

Créer une vue matérialisée uniquement si la vue matérialisée n'existe pas

L'exemple suivant crée une vue matérialisée nommée new_mv dans mydataset uniquement si aucune vue matérialisée nommée new_mv n'existe dans mydataset. Si le nom de la vue matérialisée existe déjà dans l'ensemble de données, aucune erreur n'est renvoyée et aucune action n'est effectuée.

CREATE MATERIALIZED VIEW IF NOT EXISTS `myproject.mydataset.new_mv`
OPTIONS(
  expiration_timestamp=TIMESTAMP_ADD(CURRENT_TIMESTAMP(), INTERVAL 48 HOUR),
  friendly_name="new_mv",
  description="a view that expires in 2 days",
  labels=[("org_unit", "development")],
  enable_refresh=false
)
AS SELECT column_1, column_2, column_3 FROM `myproject.mydataset.mytable`

La vue matérialisée est définie à l'aide de la requête SQL standard suivante :

SELECT column_1, column_2, column_3 FROM `myproject.mydataset.mytable`

La liste d'options de vue matérialisée spécifie :

  • les date/heure d'expiration : 48 heures à partir de la création de la vue ;
  • Nom descriptif : new_mv
  • Description : A view that expires in 2 days
  • Libellé : org_unit = development
  • l'état d'activation de l'actualisation : false.

Créer une vue matérialisée avec partitionnement et clustering

L'exemple suivant crée une vue matérialisée nommée new_mv dans mydataset, partitionnée par la colonne col_datetime et mise en cluster par la colonne col_int :

CREATE MATERIALIZED VIEW `myproject.mydataset.new_mv`
PARTITION BY DATE(col_datetime)
CLUSTER BY col_int
AS SELECT col_int, col_datetime, COUNT(1) as cnt
   FROM `myproject.mydataset.mv_base_table`
   GROUP BY col_int, col_datetime

La table de base (mv_base_table) doit également être partitionnée par la colonne col_datetime. Pour en savoir plus, consultez la page Utiliser des tables partitionnées et en cluster.

Instruction CREATE EXTERNAL TABLE

Crée une table externe.

Les tables externes permettent à BigQuery d'interroger les données stockées en dehors de l'espace de stockage BigQuery. Pour plus d'informations sur les tables externes, consultez la page Présentation des sources de données externes.

Syntaxe

CREATE [ OR REPLACE ] EXTERNAL TABLE [ IF NOT EXISTS ] table_name
[(
  column_name column_schema,
  ...
)]
[WITH CONNECTION connection_name]
[WITH PARTITION COLUMNS
  [(
      partition_column_name partition_column_type,
      ...
  )]
]
OPTIONS (
  external_table_option_list,
  ...
);

Arguments

  • OR REPLACE : remplace toute table externe portant le même nom si elle existe. Ne peut pas s'afficher avec IF NOT EXISTS.

  • IF NOT EXISTS : si une table externe ou une autre ressource de table portant le même nom existe, l'instruction CREATE n'a aucun effet. Ne peut pas s'afficher avec OR REPLACE.

  • table_name : nom de la table externe. Consultez la section Syntaxe du chemin d'accès à une table.

  • column_name : nom d'une colonne de la table.

  • column_schema : spécifie le schéma de la colonne. Cette clause utilise la même syntaxe que la définition column_schema de l'instruction CREATE TABLE. Si vous ne l'incluez pas, BigQuery détecte automatiquement le schéma.

  • connection_name : spécifie une ressource de connexion qui dispose d'identifiants permettant d'accéder aux données externes. Spécifiez le nom de la connexion au format PROJECT_ID.LOCATION.CONNECTION_ID. Si l'ID ou l'emplacement du projet contient un tiret, placez le nom de la connexion entre accents graves (`).

  • partition_column_name : nom d'une colonne de partition. Incluez ce champ si vos données externes utilisent une configuration de partitionnement Hive. Pour en savoir plus, consultez la section Configurations de données compatibles.

  • partition_column_type : type de colonne de partition.

  • external_table_option_list : liste des options de création de la table externe.

Détails

L'instruction CREATE EXTERNAL TABLE ne permet pas de créer des tables externes temporaires.

Pour créer une table partitionnée en externe, utilisez la clause WITH PARTITION COLUMNS pour spécifier les détails du schéma de partition. BigQuery valide les définitions des colonnes en fonction de l'emplacement des données externes. La déclaration du schéma doit strictement respecter l'ordre des champs dans le chemin externe. Pour en savoir plus sur le partitionnement externe, consultez la page Interroger des données partitionnées en externe.

external_table_option_list

La liste d'options spécifie des options de création de la table externe. Les options format et uris sont obligatoires. Spécifiez la liste d'options au format suivant : NAME=VALUE, ....

Options
allow_jagged_rows

BOOL

Si la valeur est true, autorise les lignes auxquelles il manque des colonnes finales facultatives.

S'applique aux données CSV.

allow_quoted_newlines

BOOL

Si la valeur est true, autorise les sections de données entre guillemets contenant des caractères de retour à la ligne dans le fichier.

S'applique aux données CSV.

compression

STRING

Type de compression de la source de données. Valeur autorisée : GZIP. Si cette option n'est pas spécifiée, la source de données n'est pas compressée.

S'applique aux données CSV et JSON.

enable_logical_types

BOOL

Si la valeur est true, convertit les types logiques Avro en types SQL correspondants. Pour en savoir plus, consultez la section Types logiques.

S'applique aux données Avro.

encoding

STRING

Encodage des caractères des données. Valeurs autorisées : UTF8 (ou UTF-8), ISO_8859_1 (ou ISO-8859-1).

S'applique aux données CSV.

field_delimiter

STRING

Séparateur des champs dans un fichier CSV.

S'applique aux données CSV.

format

STRING

Format des données externes. Valeurs autorisées : AVRO, CSV, DATASTORE_BACKUP, GOOGLE_SHEETS, NEWLINE_DELIMITED_JSON (ou JSON), ORC, PARQUET.

La valeur JSON est équivalente à NEWLINE_DELIMITED_JSON.

decimal_target_types

ARRAY<STRING>

Détermine comment convertir un type Decimal. Équivaut à ExternalDataConfiguration.decimal_target_types.

Exemple : ["NUMERIC", "BIGNUMERIC"].

json_extension

STRING

Pour les données JSON, indique un format d'échange JSON particulier. Si ce n'est pas le cas, BigQuery lit les données sous forme d'enregistrements JSON génériques.

Les valeurs acceptées sont les suivantes :
GEOJSON (Bêta). Données GeoJSON. Pour en savoir plus, consultez la section Charger des données GeoJSON.

hive_partition_uri_prefix

STRING

Préfixe commun à tous les URI sources avant le début de l'encodage de la clé de partition. Ne s'applique qu'aux tables externes partitionnées avec Hive.

S'applique aux données Avro, CSV, JSON, Parquet et ORC.

Exemple : "gs://bucket/path".

ignore_unknown_values

BOOL

Si la valeur est true, ignore les valeurs supplémentaires qui ne sont pas représentées dans le schéma de la table, sans renvoyer d'erreur.

S'applique aux données CSV et JSON.

max_bad_records

INT64

Nombre maximal d'enregistrements incorrects à ignorer lors de la lecture des données.

S'applique aux données CSV, JSON et Sheets.

null_marker

STRING

Chaîne représentant les valeurs NULL dans un fichier CSV.

S'applique aux données CSV.

projection_fields

STRING

Liste des propriétés d'entité à charger.

S'applique aux données Datastore.

quote

STRING

Chaîne utilisée pour citer des sections de données dans un fichier CSV. Si vos données contiennent des caractères de retour à la ligne entre guillemets, définit également la propriété allow_quoted_newlines sur true.

S'applique aux données CSV.

require_hive_partition_filter

BOOL

Si la valeur est true, toutes les requêtes sur cette table nécessitent un filtre de partition pouvant être utilisé pour éliminer les partitions lors de la lecture des données. Ne s'applique qu'aux tables externes partitionnées avec Hive.

S'applique aux données Avro, CSV, JSON, Parquet et ORC.

sheet_range

STRING

Plage d'une feuille de calcul Sheets à interroger.

S'applique aux données Sheets.

Exemple : “sheet1!A1:B20”.

skip_leading_rows

INT64

Nombre de lignes en haut d'un fichier à ignorer lors de la lecture des données.

S'applique aux données CSV et Sheets.

uris

ARRAY<STRING>

Tableau d'URI complets pour les emplacements de données externes.

Exemple : ["gs://bucket/path/*"].

Exemples

L'exemple suivant crée une table externe à partir de plusieurs URI. Les données sont au format CSV. Cet exemple utilise la détection automatique de schéma.

CREATE EXTERNAL TABLE dataset.CsvTable OPTIONS (
  format = 'CSV',
  uris = ['gs://bucket/path1.csv', 'gs://bucket/path2.csv']
);

L'exemple suivant crée une table externe à partir d'un fichier CSV et spécifie explicitement le schéma. Il spécifie également le délimiteur de champ ('|') et définit le nombre maximal d'enregistrements incorrects autorisés.

CREATE OR REPLACE EXTERNAL TABLE dataset.CsvTable
(
  x INT64,
  y STRING
)
OPTIONS (
  format = 'CSV',
  uris = ['gs://bucket/path1.csv'],
  field_delimiter = '|',
  max_bad_records = 5
);

L'exemple suivant crée une table partitionnée en externe. Il utilise la détection automatique de schéma pour détecter à la fois le schéma du fichier et la configuration de partitionnement Hive.

Par exemple, si le chemin externe est gs://bucket/path/field_1=first/field_2=1/data.csv, les colonnes de partition sont field_1 (STRING) et field_2 (INT64).

CREATE EXTERNAL TABLE dataset.AutoHivePartitionedTable
WITH PARTITION COLUMNS
OPTIONS (
  uris=['gs://bucket/path/*'],
  format=csv,
  hive_partition_uri_prefix='gs://bucket/path'
);

L'exemple suivant crée une table partitionnée en externe en spécifiant explicitement les colonnes de partition. Cet exemple suppose que le chemin d'accès au fichier externe est au format gs://bucket/path/field_1=first/field_2=1/data.csv.

CREATE EXTERNAL TABLE dataset.CustomHivePartitionedTable
WITH PARTITION COLUMNS (
  field_1 STRING, -- column order must match the external path
  field_2 INT64
)
OPTIONS (
  uris=['gs://bucket/path/*'],
  format=csv,
  hive_partition_uri_prefix='gs://bucket/path'
);

Instruction CREATE FUNCTION

Elle crée une fonction définie par l'utilisateur (UDF). BigQuery est compatible avec les fonctions définies par l'utilisateur écrites en SQL ou JavaScript.

Syntaxe

Pour créer une fonction SQL définie par l'utilisateur, utilisez la syntaxe suivante :

CREATE [ OR REPLACE ] [ TEMPORARY | TEMP ] FUNCTION [ IF NOT EXISTS ]
    [[project_name.]dataset_name.]function_name
    ([named_parameter[, ...]])
     ([named_parameter[, ...]])
  [RETURNS data_type]
  AS (sql_expression)

named_parameter:
  param_name param_type

Pour créer une fonction JavaScript définie par l'utilisateur, utilisez la syntaxe suivante :

CREATE [OR REPLACE] [TEMPORARY | TEMP] FUNCTION [IF NOT EXISTS]
    [[project_name.]dataset_name.]function_name
    ([named_parameter[, ...]])
  RETURNS data_type
  [determinism_specifier]
  LANGUAGE js
  [OPTIONS (function_option_list)]
  AS javascript_code

named_parameter:
  param_name param_type

determinism_specifier:
  { DETERMINISTIC | NOT DETERMINISTIC }

Les noms de routines ne doivent comporter que des lettres, des chiffres et des traits de soulignement, et ne doivent pas contenir plus de 256 caractères.

Arguments

  • OR REPLACE : remplace toute fonction portant le même nom si elle existe. ne peut pas s'afficher avec IF NOT EXISTS.

  • IF NOT EXISTS : si un ensemble de données portant le même nom existe, l'instruction CREATE n'a aucun effet. Ne peut pas s'afficher avec OR REPLACE.

  • TEMP ou TEMPORARY : crée une fonction temporaire. En l'absence de la clause, l'instruction crée une fonction persistante définie par l'utilisateur. Vous pouvez réutiliser une fonction persistante définie par l'utilisateur dans plusieurs requêtes, alors qu'une fonction temporaire définie par l'utilisateur ne peut être utilisée que dans une requête, script ou procédure unique.

  • project_name. Pour les fonctions persistantes, nom du projet dans lequel vous créez la fonction. Sa valeur par défaut correspond au projet qui exécute la requête LDD. N'incluez pas le nom du projet pour les fonctions temporaires.

  • dataset_name. Pour les fonctions persistantes, nom de l'ensemble de données dans lequel vous créez la fonction. Sa valeur par défaut correspond à l'ensemble de données par défaut (defaultDataset) dans la requête. N'incluez pas le nom de l'ensemble de données pour les fonctions temporaires.

  • function_name. Nom de la fonction.

  • named_parameter : paire param_name/param_type séparée par une virgule. La valeur de param_type est un type de données BigQuery. Pour une fonction SQL UDF, la valeur de param_type peut également être ANY TYPE.

  • determinism_specifier : s'applique uniquement aux UDF JavaScript. La valeur indique à BigQuery si le résultat de la requête peut être mis en cache. Les valeurs possibles sont les suivantes :

    • DETERMINISTIC : la fonction renvoie toujours le même résultat lorsqu'elle est exécutée avec les mêmes arguments. Le résultat de la requête peut être mis en cache. Par exemple, si la fonction add_one(i) renvoie toujours i + 1, la fonction est déterministe.

    • NOT DETERMINISTIC : la fonction ne renvoie pas toujours le même résultat lorsqu'elle est exécutée avec les mêmes arguments. Elle n'est donc pas mise en cache. Par exemple, si la fonction add_random(i) renvoie i + rand(), la fonction n'est pas déterministe et BigQuery n'utilise pas les résultats mis en cache.

      Si toutes les fonctions appelées sont déterministes (DETERMINISTIC), BigQuery tente de mettre en cache le résultat. Il arrive toutefois que les résultats ne puissent pas être mis en cache pour d'autres raisons. Pour en savoir plus, consultez la page Utiliser les résultats de requête mis en cache.

  • data_type : type de données renvoyé par la fonction.

    • Si la fonction est définie en SQL, la clause RETURNS est facultative. Si la clause RETURNS est omise, BigQuery déduit le type renvoyé par votre fonction du corps de la fonction SQL lors des appels par une requête.
    • Si la fonction est définie en JavaScript, la clause RETURNS est obligatoire. Pour en savoir plus sur les valeurs autorisées pour data_type, consultez la section Types de données compatibles avec les fonctions JavaScript définies par l'utilisateur.
  • sql_expression : expression SQL qui définit la fonction.

  • function_option_list. Liste d'options pour la création de la fonction. S'applique uniquement aux fonctions JavaScript définies par l'utilisateur.

  • javascript_code : définition d'une fonction JavaScript. La valeur est un littéral de chaîne. Si le code inclut des guillemets et des barres obliques inverses, il doit faire l'objet d'un échappement ou être représenté sous forme de chaîne brute. Par exemple, le code return "\n"; peut être représenté comme suit :

    • Chaîne entre guillemets"return \"\\n\";". Les guillemets et les barres obliques inverses doivent faire l'objet d'un échappement.
    • Chaîne entre guillemets triples : """return "\\n";""". Les barres obliques inverses doivent faire l'objet d'un échappement, contrairement aux guillemets.
    • Chaîne brute : r"""return "\n";""". Aucun échappement n'est nécessaire.

function_option_list

La liste d'options spécifie les options de création d'une fonction définie par l'utilisateur. Les options suivantes sont compatibles :

NAME VALUE Détails
description

STRING

Description de la fonction définie par l'utilisateur.
library

ARRAY<STRING>

Tableau de bibliothèques JavaScript à inclure dans la définition de la fonction. S'applique uniquement aux fonctions JavaScript définies par l'utilisateur. Pour en savoir plus, consultez la section Inclure des bibliothèques JavaScript.

Exemple : ["gs://my-bucket/lib1.js", "gs://my-bucket/lib2.js"]

Exemples

Créer une fonction SQL définie par l'utilisateur

L'exemple suivant crée une fonction SQL persistante définie par l'utilisateur nommée multiplyInputs dans un ensemble de données nommé mydataset.

CREATE FUNCTION mydataset.multiplyInputs(x FLOAT64, y FLOAT64)
RETURNS FLOAT64
AS (x * y);

Créer une fonction JavaScript définie par l'utilisateur

L'exemple suivant crée une fonction JavaScript temporaire définie par l'utilisateur nommée multiplyInputs et l'appelle à partir d'une instruction SELECT.

CREATE TEMP FUNCTION multiplyInputs(x FLOAT64, y FLOAT64)
RETURNS FLOAT64
LANGUAGE js
AS r"""
  return x*y;
""";

SELECT multiplyInputs(a, b) FROM (SELECT 3 as a, 2 as b);

Instruction CREATE TABLE FUNCTION

Crée une fonction de table, également appelée fonction de valeur de table (table-valued function, TVF).

Syntaxe

CREATE [ OR REPLACE ] TABLE FUNCTION [ IF NOT EXISTS ]
  [[project_name.]dataset_name.]function_name
  ( [ function_parameter [, ...] ] )
  [RETURNS TABLE < column_declaration [, ...] > ]
  AS sql_query

function_parameter:
  parameter_name { data_type | ANY TYPE }

column_declaration:
  column_name data_type

Arguments

  • OR REPLACE : remplace toute fonction portant le même nom si elle existe. Ne peut pas s'afficher avec IF NOT EXISTS.
  • IF NOT EXISTS : si une fonction de table du même nom existe, l'instruction CREATE n'a aucun effet. Ne peut pas s'afficher avec OR REPLACE.
  • project_name : nom du projet dans lequel vous créez la fonction. Sa valeur par défaut correspond au projet qui exécute cette requête LDD.
  • dataset_name : nom de l'ensemble de données dans lequel vous créez la fonction.
  • function_name : nom de la fonction à créer.
  • function_parameter : paramètre de fonction, spécifié en tant que nom de paramètre et type de données. La valeur de data_type est un type de données BigQuery scalaire ou ANY TYPE.
  • RETURNS TABLE : schéma de la table renvoyée par la fonction, spécifié sous forme de liste de paires de noms de colonnes et de type de données séparées par une virgule. Si la valeur RETURNS TABLE est absente, BigQuery déduit le schéma de sortie de l'instruction de requête dans le corps de la fonction. Si RETURNS TABLE est inclus, les noms du type de table renvoyé doivent correspondre aux noms des colonnes de la requête SQL.
  • sql_query : spécifie la requête SQL à exécuter. La requête SQL doit inclure des noms pour toutes les colonnes.

Détails

Si nécessaire, BigQuery convertit (par coercition) des types d'arguments. Par exemple, si le type de paramètre est FLOAT64 et que vous transmettez une valeur INT64, BigQuery la convertit en FLOAT64.

Si le type d'un paramètre est ANY TYPE, la fonction accepte une entrée de n'importe quel type pour cet argument. Le type que vous transmettez à la fonction doit être compatible avec la définition de la fonction. Si vous transmettez un argument dont le type est incompatible, la requête renvoie une erreur. Si plusieurs paramètres ont le type ANY TYPE, BigQuery n'applique aucune relation entre ces types.

Exemples

La fonction de table suivante utilise un paramètre INT64 pour filtrer les résultats d'une requête :

CREATE OR REPLACE TABLE FUNCTION mydataset.names_by_year(y INT64)
AS
  SELECT year, name, SUM(number) AS total
  FROM `bigquery-public-data.usa_names.usa_1910_current`
  WHERE year = y
  GROUP BY year, name

L'exemple suivant spécifie le type TABLE de retour dans la clause RETURNS :

CREATE OR REPLACE TABLE FUNCTION mydataset.names_by_year(y INT64)
RETURNS TABLE<name STRING, year INT64, total INT64>
AS
  SELECT year, name, SUM(number) AS total
  FROM `bigquery-public-data.usa_names.usa_1910_current`
  WHERE year = y
  GROUP BY year, name

Instruction CREATE PROCEDURE

Crée une procédure qui consiste en un bloc d'instructions pouvant être appelées à partir d'autres requêtes.

Syntaxe

CREATE [OR REPLACE] PROCEDURE [IF NOT EXISTS]
[[project_name.]dataset_name.]procedure_name (procedure_argument[, ...] )
[OPTIONS(procedure_option_list)]
BEGIN
statement_list
END;

procedure_argument: [procedure_argument_mode] argument_name argument_type

procedure_argument_mode: IN | OUT | INOUT

Arguments

  • OR REPLACE : remplace toute procédure portant le même nom si elle existe. ne peut pas s'afficher avec IF NOT EXISTS.

  • IF NOT EXISTS : si une procédure portant le même nom existe, l'instruction CREATE n'a aucun effet. Ne peut pas s'afficher avec OR REPLACE.

  • project_name** : nom du projet dans lequel vous créez la procédure. Sa valeur par défaut correspond au projet qui exécute cette requête LDD. Si le nom du projet contient des caractères spéciaux tels que des signes deux-points, il doit être placé entre accents graves ` (exemple : `google.com:my_project`).

  • dataset_name : nom de l'ensemble de données dans lequel vous créez la procédure. Sa valeur par défaut correspond à l'ensemble de données par défaut (defaultDataset) dans la requête.

  • procedure_name : nom de la procédure à créer.

  • statement_list : liste d'instructions BigQuery. Une liste d'instructions est une série d'instructions se terminant toutes par un point-virgule. Les procédures peuvent s'appeler elles-mêmes de manière récursive.

  • argument_type : tout type BigQuery valide.

  • procedure_argument_mode : spécifie si un argument est une entrée, une sortie ou les deux.

procedure_option_list

Le paramètre procedure_option_list permet de spécifier des options de procédure. Les options de procédure ont la même syntaxe et les mêmes exigences que les options de table, mais une liste différente de noms (NAME) et de valeurs (VALUE) :

NAME VALUE Détails
strict_mode

BOOL

Exemple : strict_mode=FALSE

Si strict_mode correspond à TRUE, le corps de la procédure est soumis à des vérifications supplémentaires en cas d'erreurs, telles que des tables ou des colonnes inexistantes. L'instruction CREATE PROCEDURE échoue si l'une de ces vérifications du corps échoue.

Si strict_mode est utile pour intercepter de nombreux types d'erreurs courants, il n'est pas exhaustif. Une procédure créée avec strict_mode ne garantit pas son exécution correcte.

Si strict_mode correspond à FALSE, seule la syntaxe du corps de la procédure est vérifiée. Les procédures qui s'invoquent de manière récursive doivent être créées avec strict_mode=FALSE pour éviter les erreurs provoquées par une procédure encore inexistante lors de sa validation.

La valeur par défaut est TRUE.

Mode de l'argument

IN indique que l'argument n'est qu'une entrée de la procédure. Vous pouvez spécifier une expression de valeur ou une variable pour les arguments IN.

OUT indique que l'argument est une sortie de la procédure. Un argument OUT est initialisé sur NULL lorsque la procédure démarre. Vous devez spécifier une variable pour les arguments OUT.

INOUT indique que l'argument est à la fois une entrée et un résultat de la procédure. Vous devez spécifier une variable pour les arguments INOUT. Un argument INOUT peut être référencé dans le corps d'une procédure en tant que variable et se voir attribuer de nouvelles valeurs.

Si vous ne spécifiez pas IN, OUT ni INOUT, l'argument est traité comme un argument IN.

Champ d'application de la variable

Si une variable est déclarée en dehors d'une procédure, qu'elle est transmise en tant qu'argument INOUT ou OUT à une procédure et que cette procédure attribue une nouvelle valeur à cette variable, la nouvelle valeur est visible en dehors de la procédure.

Les variables déclarées dans une procédure ne sont pas visibles en dehors de la procédure, et inversement.

Une valeur peut être attribuée à un argument OUT ou INOUT à l'aide de SET. Dans ce cas, la valeur modifiée est visible en dehors de la procédure. Si la procédure se termine correctement, la valeur de l'argument OUT ou INOUT est la dernière valeur attribuée à cette variable INOUT.

Les tables temporaires existent pendant toute la durée d'exécution du script. Ainsi, si une procédure crée une table temporaire, l'appelant de la procédure pourra également référencer la table temporaire.

Projet par défaut dans le corps des procédures

Les corps de procédure peuvent référencer des entités sans spécifier le projet. Le projet par défaut est celui auquel appartient la procédure, qui n'est pas forcément celui utilisé pour exécuter l'instruction CREATE PROCEDURE. Prenons l'exemple de requête ci-dessous.

CREATE PROCEDURE myProject.myDataset.QueryTable()
BEGIN
  SELECT * FROM anotherDataset.myTable;
END;

Après avoir créé la procédure ci-dessus, vous pouvez exécuter la requête CALL myProject.myDataset.QueryTable(). Quel que soit le projet avec lequel vous souhaitez exécuter cette requête CALL, la table référencée anotherDataset.myTable est toujours résolue avec le projet myProject.

Exemples

L'exemple suivant crée une procédure qui prend x comme argument d'entrée et renvoie x comme résultat. Comme aucun mode d'argument n'est défini pour l'argument delta, il est considéré comme un argument d'entrée. La procédure consiste en un bloc contenant une instruction unique, qui attribue la somme des deux arguments d'entrée à x.

CREATE PROCEDURE mydataset.AddDelta(INOUT x INT64, delta INT64)
BEGIN
  SET x = x + delta;
END;

L'exemple suivant appelle la procédure AddDelta de l'exemple ci-dessus, en lui transmettant la variable accumulator deux fois. Comme les modifications apportées à x dans AddDelta sont visibles en dehors de AddDelta, ces appels de procédure incrémentent accumulator par un total de huit.

DECLARE accumulator INT64 DEFAULT 0;
CALL mydataset.AddDelta(accumulator, 5);
CALL mydataset.AddDelta(accumulator, 3);
SELECT accumulator;

Cela renvoie le résultat suivant :

+-------------+
| accumulator |
+-------------+
|           8 |
+-------------+

L'exemple suivant crée la procédure SelectFromTablesAndAppend, qui prend target_date comme argument d'entrée et renvoie rows_added comme résultat. La procédure crée une table temporaire DataForTargetDate à partir d'une requête, puis calcule le nombre de lignes dans DataForTargetDate et affecte le résultat à rows_added. Ensuite, elle insère une nouvelle ligne dans TargetTable, en transmettant la valeur de target_date comme l'un des noms de colonnes. Enfin, elle supprime la table DataForTargetDate et renvoie rows_added.

CREATE PROCEDURE mydataset.SelectFromTablesAndAppend(
  target_date DATE, OUT rows_added INT64)
BEGIN
  CREATE TEMP TABLE DataForTargetDate AS
  SELECT t1.id, t1.x, t2.y
  FROM dataset.partitioned_table1 AS t1
  JOIN dataset.partitioned_table2 AS t2
  ON t1.id = t2.id
  WHERE t1.date = target_date
    AND t2.date = target_date;

  SET rows_added = (SELECT COUNT(*) FROM DataForTargetDate);

  SELECT id, x, y, target_date  -- note that target_date is a parameter
  FROM DataForTargetDate;

  DROP TABLE DataForTargetDate;
END;

L'exemple suivant déclare une variable rows_added, puis la transmet en tant qu'argument à la procédure SelectFromTablesAndAppend de l'exemple précédent, avec la valeur de CURRENT_DATE. Un message indiquant le nombre de lignes ajoutées est ensuite renvoyé.

DECLARE rows_added INT64;
CALL mydataset.SelectFromTablesAndAppend(CURRENT_DATE(), rows_added);
SELECT FORMAT('Added %d rows', rows_added);

Instruction CREATE ROW ACCESS POLICY

Crée une règle d'accès au niveau des lignes. Les règles d'accès au niveau des lignes d'une table doivent porter des noms uniques.

Syntaxe

CREATE [ OR REPLACE ] ROW ACCESS POLICY [ IF NOT EXISTS ]
row_access_policy_name ON table_name
[GRANT TO (grantee_list)]
FILTER USING (filter_expression);

Arguments

  • IF NOT EXISTS : si une règle d'accès au niveau d'une ligne porte le même nom, l'instruction CREATE n'a aucun effet. Ne peut pas s'afficher avec OR REPLACE.

  • row_access_policy_name : Nom de la règle d'accès au niveau des lignes que vous créez. Le nom de la règle d'accès au niveau des lignes doit être unique pour chaque table. Le nom de la règle d'accès au niveau des lignes peut contenir les éléments suivants :

    • Jusqu'à 256 caractères
    • Lettres (majuscules ou minuscules), chiffres et traits de soulignement Doit commencer par une lettre.
  • table_name : Nom de la table pour laquelle vous souhaitez créer une règle d'accès au niveau des lignes. Le tableau doit déjà exister.

  • GRANT TO grantee_list : clause facultative qui spécifie les membres initiaux avec lesquels la règle d'accès au niveau de la ligne doit être créée.

    grantee_list est une liste d'utilisateurs ou de groupes iam_member. Les chaînes doivent être des comptes principaux IAM valides, ou membres, en suivant le format d'un membre de la liaison de stratégie IAM et elles doivent être entre guillemets. Les types de valeurs suivants sont acceptés :

    Types grantee_list
    user:{emailid}

    Adresse e-mail qui représente un compte Google spécifique.

    Exemple : user:alice@example.com

    serviceAccount:{emailid}

    Adresse e-mail qui représente un compte de service.

    Exemple : serviceAccount:my-other-app@appspot.gserviceaccount.com

    group:{emailid}

    Adresse e-mail qui représente un groupe Google.

    Exemple : group:admins@example.com

    domain:{domain}

    Le domaine Google Workspace (principal) qui représente tous les utilisateurs de ce domaine.

    Exemple : domain:example.com

    allAuthenticatedUsers Identifiant spécial qui représente tous les comptes de service et tous les internautes qui se sont authentifiés avec un compte Google. Cet identifiant inclut les comptes qui ne sont pas associés à un domaine Google Workspace ou Cloud Identity, tels que des comptes personnels Gmail. Les utilisateurs non authentifiés, tels que les visiteurs anonymes, ne sont pas pris en compte.
    allUsers Un identifiant spécial qui représente toute personne ayant accès à Internet, y compris les utilisateurs authentifiés et non authentifiés. Étant donné que BigQuery nécessite une authentification avant qu'un utilisateur puisse accéder au service, allUsers n'inclut que les utilisateurs authentifiés.

    Vous pouvez combiner des séries de valeurs iam_member, à condition de les séparer par des virgules et de les placer entre guillemets séparément. Exemple : "user:alice@example.com","group:admins@example.com","user:sales@example.com".

  • filter_expression : Définit le sous-ensemble de lignes de la table à n'afficher que pour les membres de la liste grantee_list. La clause filter_expression est semblable à la clause WHERE dans une requête SELECT.

    Les fonctions suivantes sont valides dans l'expression de filtre :

    • Fonctions scalaires SQL standards de BigQuery, fonctions d'agrégation et fonctions d'analyse.
    • SESSION_USER(), pour limiter l'accès aux lignes appartenant à l'utilisateur exécutant la requête. Si aucune des règles d'accès au niveau des lignes n'est applicable à l'utilisateur demandeur, celui-ci n'a pas accès aux données de la table.

    L'expression de filtre ne peut pas contenir les éléments suivants :

    • Une référence à une table
    • Des sous-requêtes ou des instructions SQL telles que SELECT, CREATE ou UPDATE.
    • Fonctions définies par l'utilisateur

Exemples

Créer une règle d'accès aux lignes, puis modifier ultérieurement les bénéficiaires

   CREATE ROW ACCESS POLICY My_apac_filter
   ON project.dataset.My_table
   GRANT TO ("user:abc@example.com")
   FILTER USING (region = "apac");
   CREATE OR REPLACE ROW ACCESS POLICY My_apac_filter
   ON project.dataset.My_table
   GRANT TO ("user:xyz@example.com")
   FILTER USING (region = "apac");

Créer une règle d'accès aux lignes avec plusieurs bénéficiaires

   CREATE ROW ACCESS POLICY My_us_filter
   ON project.dataset.My_table
   GRANT TO ("user:john@example.com", "group:sales-us@example.com", "group:sales-managers@example.com")
   FILTER USING (region = "us");

Créer une règle d'accès aux lignes avec allAuthenticatedUsers comme bénéficiaires

   CREATE ROW ACCESS POLICY My_us_filter
   ON project.dataset.My_table
   GRANT TO ("allAuthenticatedUsers")
   FILTER USING (region = "us");

Créer une règle d'accès aux lignes avec un filtre basé sur l'utilisateur actuel

   CREATE ROW ACCESS POLICY My_row_filter
   ON dataset.My_table
   GRANT TO ("domain:example.com")
   FILTER USING (email = SESSION_USER());

Créer une règle d'accès aux lignes avec un filtre sur une colonne de type ARRAY

   CREATE ROW ACCESS POLICY My_reports_filter
   ON project.dataset.My_table
   GRANT TO ("domain:example.com")
   FILTER USING (SESSION_USER() IN UNNEST(reporting_chain));

Instruction ALTER SCHEMA SET OPTIONS

Définit les options sur un ensemble de données.

L'instruction s'exécute à l'emplacement de l'ensemble de données si celui-ci existe, sauf si vous spécifiez un emplacement dans les paramètres de la requête. Pour en savoir plus, consultez la page Spécifier votre zone.

Syntaxe

ALTER SCHEMA [IF EXISTS]
[project_name.]dataset_name
SET OPTIONS(schema_set_options_list)

Arguments

  • IF EXISTS : si aucun ensemble de données du même nom n'existe, l'instruction n'a aucun effet.

  • project_name : nom du projet qui contient l'ensemble de données. Sa valeur par défaut correspond au projet qui exécute cette instruction LDD.

  • dataset_name : nom de l'ensemble de données.

  • schema_set_options_list : liste des options à définir.

schema_set_options_list

La liste d'options spécifie des options pour l'ensemble de données. Spécifiez les options au format suivant : NAME=VALUE, ...

Les options suivantes sont compatibles :

NAME VALUE Détails
default_kms_key_name STRING Spécifie la clé Cloud KMS par défaut pour le chiffrement des données de table de cet ensemble de données. Vous pouvez remplacer cette valeur lorsque vous créez une table.
default_partition_expiration_days FLOAT64 Spécifie le délai d'expiration par défaut, en jours, pour les partitions de tables de cet ensemble de données. Vous pouvez remplacer cette valeur lorsque vous créez une table.
default_table_expiration_days FLOAT64 Spécifie le délai d'expiration par défaut, en jours, pour les tables de cet ensemble de données. Vous pouvez remplacer cette valeur lorsque vous créez une table.
description STRING Description de l'ensemble de données.
friendly_name STRING Nom descriptif de l'ensemble de données.
labels <ARRAY<STRUCT<STRING, STRING>>> Tableau de libellés de l'ensemble de données, exprimé sous forme de paires clé/valeur.
location STRING Emplacement dans lequel créer l'ensemble de données. Si vous ne spécifiez pas cette option, l'ensemble de données est créé à l'emplacement où la requête est exécutée. Si vous spécifiez cette option et définissez explicitement l'emplacement de la tâche de requête, les deux valeurs doivent correspondre sans quoi la requête échoue.

Exemple

L'exemple suivant définit le délai d'expiration par défaut des tables.

ALTER SCHEMA mydataset
SET OPTIONS(
  default_table_expiration_days=3.75
  )

Instruction ALTER TABLE SET OPTIONS

Définit les options d'une table.

Syntaxe

ALTER TABLE [IF EXISTS] table_name
SET OPTIONS(table_set_options_list)

Arguments

Détails

Cette instruction n'est pas compatible avec les tables externes.

table_set_options_list

La liste d'options vous permet de définir des options de table, telles qu'un libellé et une date/heure d'expiration. Vous pouvez inclure plusieurs options dans une liste d'éléments séparés par des virgules.

Spécifiez les listes d'options de table au format suivant :

NAME=VALUE, ...

NAME et VALUE doivent être utilisées selon l'une des combinaisons suivantes :

NAME VALUE Détails
expiration_timestamp TIMESTAMP

Exemple : expiration_timestamp=TIMESTAMP "2025-01-01 00:00:00 UTC"

Cette propriété est équivalente à la propriété de ressource de table expirationTime.

partition_expiration_days

FLOAT64

Exemple : partition_expiration_days=7

Définit le délai d'expiration de la partition en jours. Pour en savoir plus, consultez la section Définir le délai d'expiration de la partition. Par défaut, les partitions n'expirent pas.

Cette propriété est équivalente à la propriété de ressource de table timePartitioning.expirationMs mais utilise des jours au lieu de millisecondes. Un jour équivaut à 86 400 000 millisecondes, soit 24 heures.

Cette propriété ne peut être définie que si la table est partitionnée.

require_partition_filter

BOOL

Exemple : require_partition_filter=true

Spécifie si les requêtes sur cette table doivent inclure un filtre de prédicat qui filtre la colonne de partitionnement. Pour en savoir plus, consultez la section Définir les exigences de filtrage des partitions. La valeur par défaut est false.

Cette propriété est équivalente à la propriété de ressource de table timePartitioning.requirePartitionFilter.

Cette propriété ne peut être définie que si la table est partitionnée.

kms_key_name

STRING

Exemple : kms_key_name="projects/project_id/locations/location/keyRings/keyring/cryptoKeys/key"

Cette propriété est équivalente à la propriété de ressource de table encryptionConfiguration.kmsKeyName.

En savoir plus sur la protection des données avec des clés Cloud KMS

friendly_name

STRING

Exemple : friendly_name="my_table"

Cette propriété est équivalente à la propriété de ressource de table friendlyName.

description

STRING

Exemple : description="a table that expires in 2025"

Cette propriété est équivalente à la propriété de ressource de table description.

labels

ARRAY<STRUCT<STRING, STRING>>

Exemple : labels=[("org_unit", "development")]

Cette propriété est équivalente à la propriété de ressource de table labels.

VALUE est une expression constante ne contenant que des littéraux, des paramètres de requête et des fonctions scalaires. Si l'expression constante renvoie la valeur null, l'option NAME correspondante est ignorée.

L'expression constante ne peut pas contenir les éléments suivants :

  • Une référence à une table
  • Des sous-requêtes ou des instructions SQL telles que SELECT, CREATE et UPDATE
  • Des fonctions définies par l'utilisateur, des fonctions d'agrégation ou des fonctions d'analyse
  • Les fonctions scalaires suivantes :
    • ARRAY_TO_STRING
    • REPLACE
    • REGEXP_REPLACE
    • RAND
    • FORMAT
    • LPAD
    • RPAD
    • REPEAT
    • SESSION_USER
    • GENERATE_ARRAY
    • GENERATE_DATE_ARRAY

Lorsque l'option VALUE est définie, la valeur existante de cette option de table est remplacée, le cas échéant. Si l'option VALUE est définie sur NULL, la valeur de la table qui correspondait à cette option est effacée.

Exemples

Définir l'horodatage d'expiration et la description d'une table

L'exemple suivant définit l'horodatage d'expiration d'une table à sept jours à compter de l'heure d'exécution de l'instruction ALTER TABLE, et définit également la description de la table :

ALTER TABLE mydataset.mytable
SET OPTIONS (
  expiration_timestamp=TIMESTAMP_ADD(CURRENT_TIMESTAMP(), INTERVAL 7 DAY),
  description="Table that expires seven days from now"
)

Définir l'attribut de filtrage de partition requis sur une table partitionnée

L'exemple suivant définit l'attribut timePartitioning.requirePartitionFilter sur une table partitionnée :

ALTER TABLE mydataset.mypartitionedtable
SET OPTIONS (require_partition_filter=true)

Les requêtes faisant référence à cette table doivent utiliser un filtre sur la colonne de partitionnement, faute de quoi BigQuery renvoie une erreur. En définissant cette option sur true, vous pouvez éviter d'interroger par erreur davantage de données que vous ne l'aviez prévu :

Effacer l'horodatage d'expiration sur une table

L'exemple suivant efface l'horodatage d'expiration sur une table afin qu'elle n'expire jamais :

ALTER TABLE mydataset.mytable
SET OPTIONS (expiration_timestamp=NULL)

Instruction ALTER TABLE ADD COLUMN

Ajoute une ou plusieurs nouvelles colonnes à un schéma de table existant.

Syntaxe

ALTER TABLE table_name
ADD COLUMN [IF NOT EXISTS] column_name column_schema [, ...]

Arguments

  • table_name : nom de la table. Consultez la section Syntaxe du chemin d'accès à une table.

  • IF EXISTS : si le nom de colonne existe déjà, l'instruction n'a aucun effet.

  • column_name : nom de la colonne à ajouter.

  • column_schema : schéma de la colonne. Ce schéma utilise la même syntaxe que le schéma de colonne de l'instruction CREATE TABLE.

Détails

Vous ne pouvez pas utiliser cette instruction pour créer les colonnes suivantes :

  • Colonnes partitionnées
  • Colonnes en cluster
  • Colonnes imbriquées dans les champs RECORD existants

Vous ne pouvez pas ajouter une colonne REQUIRED à un schéma de table existant. Toutefois, vous pouvez créer une colonne REQUIRED imbriquée dans un nouveau champ RECORD.

Cette instruction n'est pas compatible avec les tables externes.

Sans la clause IF NOT EXISTS, si la table contient déjà une colonne portant ce nom, l'instruction renvoie une erreur. Si la clause IF NOT EXISTS est incluse et que le nom de colonne existe déjà, aucune erreur n'est renvoyée et aucune mesure n'est prise.

La valeur de la nouvelle colonne pour les lignes existantes est définie sur l'une des valeurs suivantes :

  • NULL si la nouvelle colonne a été ajoutée avec le mode NULLABLE. Il s'agit du mode par défaut.
  • Une valeur ARRAY vide si la nouvelle colonne a été ajoutée avec le mode REPEATED.

Pour en savoir plus sur les modifications de schéma dans BigQuery, consultez la page Modifier des schémas de table.

Exemples

Ajouter des colonnes

L'exemple suivant ajoute les colonnes suivantes à une table existante nommée mytable :

  • Colonne A de type STRING
  • Colonne B de type GEOGRAPHY
  • Colonne C de type NUMERIC avec le mode REPEATED
  • Colonne D de type DATE avec une description
ALTER TABLE mydataset.mytable
  ADD COLUMN A STRING,
  ADD COLUMN IF NOT EXISTS B GEOGRAPHY,
  ADD COLUMN C ARRAY<NUMERIC>,
  ADD COLUMN D DATE OPTIONS(description="my description")

Si l'une des colonnes nommées A, C ou D existe déjà, l'instruction échoue. Si la colonne B existe déjà, l'instruction réussit en raison de la clause IF NOT EXISTS.

Ajouter une colonne RECORD

L'exemple suivant ajoute une colonne nommée A de type STRUCT qui contient les colonnes imbriquées suivantes :

  • Colonne B de type GEOGRAPHY
  • Colonne C de type INT64 avec le mode REPEATED
  • Colonne D de type INT64 avec le mode REQUIRED
  • Colonne E de type TIMESTAMP avec une description
ALTER TABLE mydataset.mytable
   ADD COLUMN A STRUCT<
       B GEOGRAPHY,
       C ARRAY<INT64>,
       D INT64 NOT NULL,
       E TIMESTAMP OPTIONS(description="creation time")
       >

La requête échoue si la table contient déjà une colonne nommée A, même si cette colonne ne contient aucune des colonnes imbriquées spécifiées.

La nouvelle colonne STRUCT nommée A peut être vide, mais la colonne imbriquée D dans A est requise pour toute valeur STRUCT de A.

Instruction ALTER TABLE RENAME TO

Renomme une table.

Syntaxe

ALTER TABLE [IF EXISTS] table_name
RENAME TO new_table_name

Arguments

  • IF EXISTS : si aucune table du même nom n'existe, l'instruction n'a aucun effet.

  • table_name : nom de la table à renommer. Consultez la section Syntaxe du chemin d'accès à une table.

  • new_table_name : nouveau nom de la table. Le nouveau nom ne peut pas être un nom de table existant.

Détails

  • Cette instruction n'est pas compatible avec les tables externes.
  • Si vous modifiez les règles de table ou d'accès au niveau de la ligne lorsque vous renommez la table, ces modifications peuvent ne pas être effectives.
  • Si vous souhaitez renommer une table contenant du streaming de données, vous devez arrêter la diffusion et attendre que BigQuery indique que le streaming n'est pas utilisé.

Exemples

Renommer une table

L'exemple suivant renomme la table mydataset.mytable en mydataset.mynewtable :

ALTER TABLE mydataset.mytable RENAME TO mynewtable

Instruction ALTER TABLE DROP COLUMN

Supprime une ou plusieurs colonnes d'un schéma de table existant.

Syntaxe

ALTER TABLE table_name
DROP COLUMN [IF EXISTS] column_name [, ...]

Arguments

  • table_name : nom de la table à modifier. Consultez la section Syntaxe du chemin d'accès à une table. La table doit déjà exister et posséder un schéma.

  • IF EXISTS : si la colonne spécifiée n'existe pas, l'instruction n'a aucun effet.

  • column_name : nom de la colonne à supprimer.

Détails

Elle ne libère pas immédiatement l'espace de stockage associé à la colonne supprimée. La déclaration en arrière-plan de l'espace de stockage reste effective pendant sept jours à compter de la date de suppression d'une colonne.

Pour en savoir plus sur la récupération immédiate d'un espace de stockage, consultez la section Supprimer une colonne d'un schéma de table.

Vous ne pouvez pas utiliser cette instruction pour supprimer les éléments suivants :

  • Colonnes partitionnées
  • Colonnes en cluster
  • Colonnes imbriquées dans des champs RECORD existants

Cette instruction n'est pas compatible avec les tables externes.

Sans la clause IF EXISTS, si la table ne contient pas de colonne portant ce nom, l'instruction renvoie une erreur. Si la clause IF EXISTS est incluse et que le nom de colonne n'existe pas, aucune erreur n'est renvoyée et aucune mesure n'est prise.

Cette instruction ne fait que supprimer la colonne du tableau. Tous les objets faisant référence à la colonne, tels que les vues ou les vues matérialisées, doivent être mis à jour ou recréés séparément.

Pour en savoir plus sur les modifications de schéma dans BigQuery, consultez la page Modifier des schémas de table.

Exemples

Supprimer des colonnes

L'exemple suivant supprime les colonnes ci-après d'une table existante nommée mytable :

  • Colonne A
  • Colonne B
ALTER TABLE mydataset.mytable
  DROP COLUMN A,
  DROP COLUMN IF EXISTS B

Si la colonne A n'existe pas, l'instruction échoue. Si la colonne B n'existe pas, l'instruction aboutit tout de même, du fait de la clause IF EXISTS.

Instruction ALTER COLUMN SET OPTIONS

Définit les options telles que la description de colonne sur une colonne d'une table dans BigQuery.

Syntaxe

ALTER TABLE [IF EXISTS] table_name
ALTER COLUMN [IF EXISTS] column_name SET OPTIONS(column_set_options_list)

Arguments

  • (ALTER TABLE) IF EXISTS : si aucune table du même nom n'existe, l'instruction n'a aucun effet.

  • table_name : nom de la table à modifier. Consultez la section Syntaxe du chemin d'accès à une table.

  • (ALTER COLUMN) IF EXISTS : si la colonne spécifiée n'existe pas, l'instruction n'a aucun effet.

  • column_name : nom de la colonne de premier niveau que vous modifiez. La modification des sous-champs, tels que les colonnes imbriquées dans STRUCT, n'est pas possible.

  • column_set_options_list : liste des options à définir sur la colonne.

Détails

Cette instruction n'est pas compatible avec les tables externes.

column_set_options_list

Spécifiez les listes d'options de colonne au format suivant :

NAME=VALUE, ...

NAME et VALUE doivent être utilisées selon l'une des combinaisons suivantes :

NAME VALUE Détails
description

STRING

Exemple : description="a table that expires in 2025"

VALUE est une expression constante ne contenant que des littéraux, des paramètres de requête et des fonctions scalaires. Si l'expression constante renvoie la valeur null, l'option NAME correspondante est ignorée.

L'expression constante ne peut pas contenir les éléments suivants :

  • Une référence à une table
  • Des sous-requêtes ou des instructions SQL telles que SELECT, CREATE et UPDATE
  • Des fonctions définies par l'utilisateur, des fonctions d'agrégation ou des fonctions d'analyse
  • Les fonctions scalaires suivantes :
    • ARRAY_TO_STRING
    • REPLACE
    • REGEXP_REPLACE
    • RAND
    • FORMAT
    • LPAD
    • RPAD
    • REPEAT
    • SESSION_USER
    • GENERATE_ARRAY
    • GENERATE_DATE_ARRAY

Lorsque l'option VALUE est définie, la valeur existante de cette option de colonne est remplacée, le cas échéant. Si l'option VALUE est définie sur NULL, la valeur de la colonne qui correspondait à cette option est effacée.

Exemples

L'exemple suivant définit une nouvelle description sur une colonne appelée price :

ALTER TABLE mydataset.mytable
ALTER COLUMN price
SET OPTIONS (
  description="Price per unit"
)

Instruction ALTER COLUMN DROP NOT NULL

Supprime une contrainte NOT NULL d'une colonne d'une table dans BigQuery.

Syntaxe

ALTER TABLE [IF EXISTS] table_name
ALTER COLUMN [IF EXISTS] column DROP NOT NULL

Arguments

  • (ALTER TABLE) IF EXISTS : si aucune table du même nom n'existe, l'instruction n'a aucun effet.

  • table_name : nom de la table à modifier. Consultez la section Syntaxe du chemin d'accès à une table.

  • (ALTER COLUMN) IF EXISTS : si la colonne spécifiée n'existe pas, l'instruction n'a aucun effet.

  • column_name : nom de la colonne de premier niveau que vous modifiez. La modification des sous-champs n'est pas disponible.

Détails

Si une colonne ne présente pas de contrainte NOT NULL, la requête renvoie une erreur.

Cette instruction n'est pas compatible avec les tables externes.

Exemples

L'exemple suivant supprime la contrainte NOT NULL d'une colonne appelée mycolumn :

ALTER TABLE mydataset.mytable
ALTER COLUMN mycolumn
DROP NOT NULL

Instruction ALTER COLUMN SET DATA TYPE

Remplace le type de données d'une colonne d'une table dans BigQuery par un type de données moins restrictif. Par exemple, un type de données NUMERIC peut être remplacé par un type BIGNUMERIC, mais pas l'inverse.

Syntaxe

ALTER TABLE [IF EXISTS] table_name
ALTER COLUMN [IF EXISTS] column_name SET DATA TYPE data_type

Arguments

  • (ALTER TABLE) IF EXISTS : si aucune table du même nom n'existe, l'instruction n'a aucun effet.

  • table_name : nom de la table à modifier. Consultez la section Syntaxe du chemin d'accès à une table.

  • column_name : nom de la colonne de premier niveau que vous modifiez. La modification des sous-champs n'est pas disponible.

  • data_type : type vers lequel vous convertissez la colonne.

Détails

Pour obtenir un tableau des coercitions de types de données valides, comparez la colonne "De type" à la colonne "Coercition vers" de la page Règles de conversion en SQL standard.

Voici des exemples de coercitions de types de données valides :

  • INT64 vers NUMERIC, BIGNUMERIC, FLOAT64
  • NUMERIC vers BIGNUMERIC, FLOAT64

Cette instruction n'est pas compatible avec les tables externes.

Sans la clause IF EXISTS, si la table ne contient pas de colonne portant ce nom, l'instruction renvoie une erreur. Si la clause IF EXISTS est incluse et que le nom de colonne n'existe pas, aucune erreur n'est renvoyée et aucune action n'est effectuée.

Vous pouvez également modifier un type de données plus restrictif en un type de données paramétrées moins restrictif. Par exemple, vous pouvez augmenter la longueur maximale d'un type de chaîne, ou encore la précision ou l'échelle d'un type numérique.

Voici des exemples de modifications de type de données paramétrées valides :

  • NUMERIC(6,10) vers NUMERIC(8,12)
  • NUMERIC vers BIGNUMERIC(40, 20)
  • STRING(5) vers STRING(7)

Exemples

L'exemple suivant modifie le type de données de la colonne c1 de INT64 vers NUMERIC :

CREATE TABLE dataset.table(c1 INT64);

ALTER TABLE dataset.table ALTER COLUMN c1 SET DATA TYPE NUMERIC;

L'exemple suivant modifie le type de données de l'un des champs de la colonne s1 :

CREATE TABLE dataset.table(s1 STRUCT<a INT64, b STRING>);

ALTER TABLE dataset.table ALTER COLUMN s1
SET DATA TYPE STRUCT<a NUMERIC, b STRING>;

L'exemple suivant modifie la précision d'une colonne de type de données paramétrées :

CREATE TABLE dataset.table (pt NUMERIC(7,2));

ALTER TABLE dataset.table
ALTER COLUMN pt
SET DATA TYPE NUMERIC(8,2);

Instruction ALTER VIEW SET OPTIONS

Définit les options sur une vue.

Syntaxe

ALTER VIEW [IF EXISTS] view_name
SET OPTIONS(view_set_options_list)

Arguments

view_set_options_list

La liste d'options vous permet de définir des options de vue, telles qu'un libellé et une date/heure d'expiration. Vous pouvez inclure plusieurs options dans une liste d'éléments séparés par des virgules.

Spécifiez les listes d'options de vue au format suivant :

NAME=VALUE, ...

NAME et VALUE doivent être utilisées selon l'une des combinaisons suivantes :

NAME VALUE Détails
expiration_timestamp TIMESTAMP

Exemple : expiration_timestamp=TIMESTAMP "2025-01-01 00:00:00 UTC"

Cette propriété est équivalente à la propriété de ressource de table expirationTime.

friendly_name

STRING

Exemple : friendly_name="my_view"

Cette propriété est équivalente à la propriété de ressource de table friendlyName.

description

STRING

Exemple : description="a view that expires in 2025"

Cette propriété est équivalente à la propriété de ressource de table description.

labels

ARRAY<STRUCT<STRING, STRING>>

Exemple : labels=[("org_unit", "development")]

Cette propriété est équivalente à la propriété de ressource de table labels.

VALUE est une expression constante ne contenant que des littéraux, des paramètres de requête et des fonctions scalaires. Si l'expression constante renvoie la valeur null, l'option NAME correspondante est ignorée.

L'expression constante ne peut pas contenir les éléments suivants :

  • Une référence à une table
  • Des sous-requêtes ou des instructions SQL telles que SELECT, CREATE et UPDATE
  • Des fonctions définies par l'utilisateur, des fonctions d'agrégation ou des fonctions d'analyse
  • Les fonctions scalaires suivantes :
    • ARRAY_TO_STRING
    • REPLACE
    • REGEXP_REPLACE
    • RAND
    • FORMAT
    • LPAD
    • RPAD
    • REPEAT
    • SESSION_USER
    • GENERATE_ARRAY
    • GENERATE_DATE_ARRAY

Lorsque l'option VALUE est définie, la valeur existante de cette option de vue est remplacée, le cas échéant. Si l'option VALUE est définie sur NULL, la valeur de la vue qui correspondait à cette option est effacée.

Exemples

Définir l'horodatage d'expiration et la description d'une vue

L'exemple suivant définit l'horodatage d'expiration d'une vue à sept jours à compter de l'heure d'exécution de l'instruction ALTER VIEW, et définit également la description de la table :

ALTER VIEW mydataset.myview
SET OPTIONS (
  expiration_timestamp=TIMESTAMP_ADD(CURRENT_TIMESTAMP(), INTERVAL 7 DAY),
  description="View that expires seven days from now"
)

Instruction ALTER MATERIALIZED VIEW SET OPTIONS

Définit les options sur une vue matérialisée.

Syntaxe

ALTER MATERIALIZED VIEW [IF EXISTS] materialized_view_name
SET OPTIONS(materialized_view_set_options_list)

Arguments

materialized_view_set_options_list

La liste d'options vous permet de définir des options de vue matérialisée, telles que l'état de l'actualisation, l'intervalle d'actualisation, un libellé ou encore un délai d'expiration. Vous pouvez inclure plusieurs options dans une liste d'éléments séparés par des virgules.

Spécifiez les listes d'options de vue matérialisée au format suivant :

NAME=VALUE, ...

NAME et VALUE doivent être utilisées selon l'une des combinaisons suivantes :

NAME VALUE Détails
enable_refresh BOOLEAN

Exemple : enable_refresh=false

refresh_interval_minutes FLOAT64

Exemple : refresh_interval_minutes=20

expiration_timestamp TIMESTAMP

Exemple : expiration_timestamp=TIMESTAMP "2025-01-01 00:00:00 UTC"

Cette propriété est équivalente à la propriété de ressource de table expirationTime.

friendly_name

STRING

Exemple : friendly_name="my_mv"

Cette propriété est équivalente à la propriété de ressource de table friendlyName.

description

STRING

Exemple : description="a materialized view that expires in 2025"

Cette propriété est équivalente à la propriété de ressource de table description.

labels

ARRAY<STRUCT<STRING, STRING>>

Exemple : labels=[("org_unit", "development")]

Cette propriété est équivalente à la propriété de ressource de table labels.

Lorsque l'option VALUE est définie, la valeur existante de cette option de vue matérialisée est remplacée, le cas échéant. Si l'option VALUE est définie sur NULL, la valeur de la vue qui correspondait à cette option est effacée.

Exemples

Définir l'état et l'intervalle d'actualisation sur une vue matérialisée

L'exemple suivant active l'actualisation avec un intervalle de 20 minutes sur une vue matérialisée :

ALTER MATERIALIZED VIEW mydataset.my_mv
SET OPTIONS (
  enable_refresh=true,
  refresh_interval_minutes=20
)

Instruction DROP SCHEMA

Supprime un ensemble de données.

Syntaxe

DROP SCHEMA [IF EXISTS]
[project_name.]dataset_name
[ CASCADE | RESTRICT ]

Arguments

  • IF EXISTS : si aucun ensemble de données du même nom n'existe, l'instruction n'a aucun effet.

  • project_name : nom du projet qui contient l'ensemble de données. Sa valeur par défaut correspond au projet qui exécute cette instruction LDD.

  • dataset_name : nom de l'ensemble de données à supprimer.

  • CASCADE : supprime l'ensemble de données et toutes les ressources qu'il contient, telles que les tables, les vues et les fonctions. Vous devez avoir l'autorisation de supprimer les ressources, sinon l'instruction renvoie une erreur. Pour obtenir la liste des autorisations BigQuery, consultez la page Rôles et autorisations prédéfinis.

  • RESTRICT : ne supprime l'ensemble de données que s'il est vide. Sinon, elle renvoie une erreur. Si vous ne spécifiez pas CASCADE ou RESTRICT, le comportement par défaut est RESTRICT.

Détails

L'instruction s'exécute à l'emplacement de l'ensemble de données si celui-ci existe, sauf si vous spécifiez un emplacement dans les paramètres de la requête. Pour en savoir plus, consultez la page Spécifier votre zone.

Exemples

L'exemple suivant permet de supprimer l'ensemble de données nommé mydataset. Si l'ensemble de données n'existe pas ou n'est pas vide, l'instruction renvoie une erreur.

DROP SCHEMA mydataset

L'exemple suivant supprime l'ensemble de données nommé mydataset et toutes les ressources qu'il contient. Si l'ensemble de données n'existe pas, aucune erreur n'est renvoyée.

DROP SCHEMA IF EXISTS mydataset CASCADE

Instruction DROP TABLE

Supprime une table.

Syntaxe

DROP TABLE [IF EXISTS] table_name

Arguments

Exemples

Supprimer une table

L'exemple suivant supprime une table nommée mytable dans mydataset :

DROP TABLE mydataset.mytable

Si ce nom de table n'existe pas déjà dans l'ensemble de données, l'erreur suivante est renvoyée :

Error: Not found: Table myproject:mydataset.mytable

Supprimer une table seulement si cette table existe déjà

L'exemple suivant supprime une table nommée mytable dans mydataset uniquement si la table existe déjà. Si ce nom de table n'existe pas déjà dans l'ensemble de données, aucune erreur n'est renvoyée et aucune action n'est effectuée.

DROP TABLE IF EXISTS mydataset.mytable

Instruction DROP SNAPSHOT TABLE

Supprime un instantané de table.

Syntaxe

DROP SNAPSHOT TABLE [IF EXISTS] table_snapshot_name

Arguments

  • IF EXISTS : si aucun instantané de table du même nom n'existe, l'instruction n'a aucun effet.

  • table_snapshot_name : nom de l'instantané de table à supprimer. Consultez la section Syntaxe du chemin d'accès à une table.

Exemples

Supprimer un instantané de table : échec s'il n'existe pas

L'exemple suivant supprime l'instantané de table nommé mytablesnapshot dans l'ensemble de données mydataset :

DROP SNAPSHOT TABLE mydataset.mytablesnapshot

Si l'instantané de table n'existe pas dans l'ensemble de données, l'erreur suivante est renvoyée :

Error: Not found: Table snapshot myproject:mydataset.mytablesnapshot

Supprimer un instantané de table : ignorer s'il n'existe pas

L'exemple suivant supprime l'instantané de table nommé mytablesnapshot dans l'ensemble de données mydataset.

DROP SNAPSHOT TABLE IF EXISTS mydataset.mytablesnapshot

Si l'instantané de table n'existe pas dans l'ensemble de données, aucune action n'est effectuée et aucune erreur n'est renvoyée.

Pour en savoir plus sur la création d'instantanés de table, consultez la section CREATE SNAPSHOT TABLE.

Pour en savoir plus sur la restauration d'instantanés de table, consultez la section CREATE TABLE CLONE.

Instruction DROP EXTERNAL TABLE

Supprime une table externe.

Syntaxe

DROP EXTERNAL TABLE [IF EXISTS] table_name

Arguments

  • IF EXISTS : si aucune table externe du même nom n'existe, l'instruction n'a aucun effet.

  • table_name : nom de la table externe à supprimer. Consultez la section Syntaxe du chemin d'accès à une table.

Détails

Si table_name existe, mais n'est pas une table externe, l'instruction renvoie l'erreur suivante :

Cannot drop table_name which has type TYPE. An external table was expected.

L'instruction DROP EXTERNAL ne supprime que la définition de la table externe de BigQuery. Les données stockées dans l'emplacement externe ne sont pas concernées.

Exemples

L'exemple suivant supprime la table externe nommée external_table de l'ensemble de données mydataset. Il renvoie une erreur si la table externe n'existe pas.

DROP EXTERNAL TABLE mydataset.external_table

L'exemple suivant supprime la table externe nommée external_table de l'ensemble de données mydataset. Si la table externe n'existe pas, aucune erreur n'est renvoyée.

DROP EXTERNAL TABLE IF EXISTS mydataset.external_table

Instruction DROP VIEW

Supprime une vue.

Syntaxe

DROP VIEW [IF EXISTS] view_name

Arguments

Exemples

Supprimer une vue

L'exemple suivant crée une vue nommée myview dans mydataset :

DROP VIEW mydataset.myview

Si ce nom de vue n'existe pas déjà dans l'ensemble de données, l'erreur suivante est renvoyée :

Error: Not found: Table myproject:mydataset.myview

Supprimer une vue seulement si cette vue existe déjà

L'exemple suivant supprime une vue nommée myview dans mydataset uniquement si la vue existe déjà. Si ce nom de vue n'existe pas déjà dans l'ensemble de données, aucune erreur n'est renvoyée et aucune action n'est effectuée.

DROP VIEW IF EXISTS mydataset.myview

Instruction DROP MATERIALIZED VIEW

Supprime une vue matérialisée.

Syntaxe

DROP MATERIALIZED VIEW [IF EXISTS] mv_name

Arguments

  • IF EXISTS : si aucune vue matérialisée du même nom n'existe, l'instruction n'a aucun effet.

  • mv_name : nom de la vue matérialisée à supprimer. Consultez la section Syntaxe du chemin d'accès à une table.

Exemples

Supprimer une vue matérialisée

L'exemple suivant supprime une vue matérialisée nommée my_mv dans mydataset :

DROP MATERIALIZED VIEW mydataset.my_mv

Si ce nom de vue matérialisée n'existe pas dans l'ensemble de données, l'erreur suivante est renvoyée :

Error: Not found: Table myproject:mydataset.my_mv

Si vous supprimez une vue matérialisée dans un autre projet, vous devez spécifier le projet, l'ensemble de données et la vue matérialisée au format suivant : `project_id.dataset.materialized_view` (en intégrant les accents graves si project_id contient des caractères spéciaux), par exemple, `myproject.mydataset.my_mv`.

Supprimer une vue matérialisée uniquement si elle existe

L'exemple suivant supprime une vue matérialisée nommée my_mv dans mydataset uniquement si la vue matérialisée existe déjà. Si ce nom de vue matérialisée n'existe pas dans l'ensemble de données, aucune erreur n'est renvoyée et aucune action n'est effectuée.

DROP MATERIALIZED VIEW IF EXISTS mydataset.my_mv

Si vous supprimez une vue matérialisée dans un autre projet, vous devez spécifier le projet, l'ensemble de données et la vue matérialisée au format suivant : `project_id.dataset.materialized_view`, (en intégrant les accents graves si project_id contient des caractères spéciaux), par exemple, `myproject.mydataset.my_mv`.

Instruction DROP FUNCTION

Supprime une fonction persistante définie par l'utilisateur.

Syntaxe

DROP FUNCTION [IF EXISTS] [[project_name.]dataset_name.]function_name

Arguments

  • IF EXISTS : si aucune fonction du même nom n'existe, l'instruction n'a aucun effet.

  • project_name : nom du projet contenant la fonction à supprimer. Sa valeur par défaut correspond au projet qui exécute cette requête LDD. Si le nom du projet contient des caractères spéciaux tels que des signes deux-points, il doit être placé entre accents graves ` (exemple : `google.com:my_project`).

  • dataset_name : nom de l'ensemble de données contenant la fonction à supprimer. Sa valeur par défaut correspond à l'ensemble de données par défaut (defaultDataset) dans la requête.

  • function_name : nom de la fonction que vous supprimez.

Exemples

L'exemple d'instruction suivant supprime la fonction parseJsonAsStruct contenue dans l'ensemble de données mydataset.

DROP FUNCTION mydataset.parseJsonAsStruct;

L'exemple d'instruction suivant supprime la fonction parseJsonAsStruct de l'ensemble de données sample_dataset dans le projet other_project.

DROP FUNCTION `other_project`.sample_dataset.parseJsonAsStruct;

DROP TABLE FUNCTION

Supprime une fonction de table.

Syntaxe

DROP TABLE FUNCTION [IF EXISTS] [[project_name.]dataset_name.]function_name

Arguments

  • IF EXISTS : si aucune fonction de table ne porte ce nom, l'instruction n'a aucun effet.

  • project_name : nom du projet contenant la fonction de table à supprimer. Sa valeur par défaut correspond au projet qui exécute cette requête LDD.

  • dataset_name : nom de l'ensemble de données contenant la fonction de table à supprimer.

  • function_name : nom de la fonction de table à supprimer.

Exemple

L'exemple suivant supprime une fonction de table nommée my_table_function :

DROP TABLE FUNCTION mydataset.my_table_function;

Instruction DROP PROCEDURE

Supprime une procédure stockée.

Syntaxe

DROP PROCEDURE [IF EXISTS] [[project_name.]dataset_name.]procedure_name

Arguments

  • IF EXISTS : si aucune procédure du même nom n'existe, l'instruction n'a aucun effet.

  • project_name : nom du projet contenant la procédure à supprimer. Sa valeur par défaut correspond au projet qui exécute cette requête LDD. Si le nom du projet contient des caractères spéciaux tels que des signes deux-points, il doit être placé entre accents graves ` (exemple : `google.com:my_project`).

  • dataset_name : nom de l'ensemble de données contenant la procédure à supprimer. Sa valeur par défaut correspond à l'ensemble de données par défaut (defaultDataset) dans la requête.

  • procedure_name : nom de la procédure que vous supprimez.

Exemples

L'exemple d'instruction suivant supprime la procédure myprocedure contenue dans l'ensemble de données mydataset.

DROP PROCEDURE mydataset.myProcedure;

L'exemple d'instruction suivant supprime la procédure myProcedure contenue dans l'ensemble de données sample_dataset dans le projet other_project.

DROP PROCEDURE `other-project`.sample_dataset.myprocedure;

Instruction DROP ROW ACCESS POLICY

Supprime une règle d'accès au niveau de la ligne.

Syntaxe

DROP [ IF EXISTS ]
row_access_policy_name ON table_name;
DROP ALL ROW ACCESS POLICIES ON table_name;

Arguments

  • IF EXISTS : si aucune règle d'accès au niveau d'une ligne portant le même nom n'existe, l'instruction n'a aucun effet.

  • row_access_policy_name : Nom de la règle d'accès au niveau des lignes que vous supprimez. Chaque règle d'accès au niveau des lignes d'une table possède un nom unique.

  • table_name : Nom de la table avec la ou les règles d'accès au niveau des lignes que vous souhaitez supprimer.

Exemples

Supprimer une règle d'accès au niveau des lignes d'une table

   DROP ROW ACCESS POLICY My_row_filter ON project.dataset.My_table;

Supprimer toutes les règles d'accès au niveau des lignes d'une table

   DROP ALL ROW ACCESS POLICIES ON project.dataset.My_table;

Syntaxe du chemin d'accès à une table

Utilisez la syntaxe suivante lorsque vous spécifiez le chemin d'une ressource de table, y compris les tables standards, les vues, les vues matérialisées, les tables externes et les instantanés de table.

table_path :=
  [[project_name.]dataset_name.]table_name
  • project_name : nom du projet contenant la ressource de table. Sa valeur par défaut correspond au projet qui exécute la requête LDD. Si le nom du projet contient des caractères spéciaux tels que des signes deux-points, il doit être placé entre accents graves ` (exemple : `google.com:my_project`).

  • dataset_name : nom de l'ensemble de données contenant la ressource de table. Sa valeur par défaut correspond à l'ensemble de données par défaut (defaultDataset) dans la requête.

  • table_name : nom de la ressource de table.

Lorsque vous créez une table dans BigQuery, le nom de la table doit être unique pour chaque ensemble de données. Le nom de la table peut :

  • contenir jusqu'à 1 024 caractères ;
  • contenir des caractères Unicode des catégories L (lettre), M (marque), N (nombre), Pc (ponctuation de type connecteur, y compris trait de soulignement), Pd (ponctuation de type tiret), Zs (espace). Pour en savoir plus, consultez la section décrivant les catégories générales.

Par exemple, tous les noms de table suivants sont valides : table 01, ग्राहक, 00_お客様, étudiant-01.

Certains noms de tables et préfixes de noms de tables sont réservés. Si vous recevez une erreur indiquant que le nom ou le préfixe de votre table est réservé, sélectionnez-en un autre et réessayez.