O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Executar consultas parametrizadas

O BigQuery suporta parâmetros de consulta para ajudar a evitar a injeção SQL quando as consultas são criadas com a entrada do utilizador. Esta funcionalidade só está disponível com a sintaxe GoogleSQL. Os parâmetros de consulta podem ser usados como substitutos de expressões arbitrárias. Não é possível usar parâmetros como substitutos de identificadores, nomes de colunas, nomes de tabelas ou outras partes da consulta.

Para especificar um parâmetro com nome, use o caráter @ seguido de um identificador, como @param_name. Em alternativa, use o valor do marcador de posição ? para especificar um parâmetro posicional. Tenha em atenção que uma consulta pode usar parâmetros posicionais ou com nome, mas não ambos.

Quando usa um parâmetro, o valor fornecido em si não é registado nos registos do BigQuery para proteger informações potencialmente confidenciais.

Pode executar uma consulta parametrizada no BigQuery das seguintes formas:

O comando bq query da ferramenta de linhas de comando bq
a API
as bibliotecas cliente

O exemplo seguinte mostra como transmitir valores de parâmetros a uma consulta parametrizada:

Consola

As consultas parametrizadas não são suportadas pela Google Cloud consola.

bq

In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell

At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

Use --parameter para fornecer valores para parâmetros no formulário name:type:value. Um nome vazio produz um parâmetro posicional. O tipo pode ser omitido para assumir STRING.

A flag --parameter tem de ser usada em conjunto com a flag --use_legacy_sql=false para especificar a sintaxe do GoogleSQL.

(Opcional) Especifique a sua localização através da flag --location.

bq query \
   --use_legacy_sql=false \
   --parameter=corpus::romeoandjuliet \
   --parameter=min_word_count:INT64:250 \
   'SELECT
     word,
     word_count
   FROM
     `bigquery-public-data.samples.shakespeare`
   WHERE
     corpus = @corpus
   AND
     word_count >= @min_word_count
   ORDER BY
     word_count DESC;'

API

Para usar parâmetros com nome, defina parameterMode como NAMED na configuração da tarefa query.

Preencha queryParameters com a lista de parâmetros na configuração do trabalho query. Defina o name de cada parâmetro com o @param_name usado na consulta.

Ative a sintaxe GoogleSQL definindo useLegacySql como false.

{
  "query": "SELECT word, word_count FROM `bigquery-public-data.samples.shakespeare` WHERE corpus = @corpus AND word_count >= @min_word_count ORDER BY word_count DESC;",
  "queryParameters": [
    {
      "parameterType": {
        "type": "STRING"
      },
      "parameterValue": {
        "value": "romeoandjuliet"
      },
      "name": "corpus"
    },
    {
      "parameterType": {
        "type": "INT64"
      },
      "parameterValue": {
        "value": "250"
      },
      "name": "min_word_count"
    }
  ],
  "useLegacySql": false,
  "parameterMode": "NAMED"
}

Experimente no Explorador de APIs Google.

Para usar parâmetros posicionais, defina parameterMode como POSITIONAL na configuração da tarefa query.

C#

Antes de experimentar este exemplo, siga as C#instruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API C# BigQuery documentação de referência.

Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.

Para usar parâmetros com nome:


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

public class BigQueryQueryWithNamedParameters
{
    public void QueryWithNamedParameters(string projectId = "your-project-id")
    {
        var corpus = "romeoandjuliet";
        var minWordCount = 250;

        // Note: Standard SQL is required to use query parameters.
        var query = @"
            SELECT word, word_count
            FROM `bigquery-public-data.samples.shakespeare`
            WHERE corpus = @corpus
            AND word_count >= @min_word_count
            ORDER BY word_count DESC";

        // Initialize client that will be used to send requests.
        var client = BigQueryClient.Create(projectId);

        var parameters = new BigQueryParameter[]
        {
            new BigQueryParameter("corpus", BigQueryDbType.String, corpus),
            new BigQueryParameter("min_word_count", BigQueryDbType.Int64, minWordCount)
        };

        var job = client.CreateQueryJob(
            sql: query,
            parameters: parameters,
            options: new QueryOptions { UseQueryCache = false });
        // Wait for the job to complete.
        job = job.PollUntilCompleted().ThrowOnAnyError();
        // Display the results
        foreach (BigQueryRow row in client.GetQueryResults(job.Reference))
        {
            Console.WriteLine($"{row["word"]}: {row["word_count"]}");
        }
    }
}

Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.

Para usar parâmetros posicionais:


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

public class BigQueryQueryWithPositionalParameters
{
    public void QueryWithPositionalParameters(string projectId = "project-id")
    {
        var corpus = "romeoandjuliet";
        var minWordCount = 250;

        // Note: Standard SQL is required to use query parameters.
        var query = @"
                SELECT word, word_count
                FROM `bigquery-public-data.samples.shakespeare`
                WHERE corpus = ?
                AND word_count >= ?
                ORDER BY word_count DESC;";

        // Initialize client that will be used to send requests.
        var client = BigQueryClient.Create(projectId);

        // Set the name to None to use positional parameters.
        // Note that you cannot mix named and positional parameters.
        var parameters = new BigQueryParameter[]
        {
            new BigQueryParameter(null, BigQueryDbType.String, corpus),
            new BigQueryParameter(null, BigQueryDbType.Int64, minWordCount)
        };

        var job = client.CreateQueryJob(
            sql: query,
            parameters: parameters,
            options: new QueryOptions
            {
                UseQueryCache = false,
                ParameterMode = BigQueryParameterMode.Positional
            });
        // Wait for the job to complete.
        job = job.