Parametrisierte Abfragen ausführen

In diesem Dokument erfahren Sie, wie Sie in BigQuery parametrisierte Abfragen ausführen. Hinweis: Einige der in diesem Dokument verlinkten Inhalte sind nur auf Englisch verfügbar.

Parametrisierte Abfragen ausführen

BigQuery unterstützt Abfrageparameter, um eine SQL-Injection zu verhindern, wenn Abfragen über Nutzereingaben erstellt werden. Diese Funktion ist nur in Verbindung mit der Standard-SQL-Abfragesyntax verfügbar. Abfrageparameter können als Ersatz für beliebige Ausdrücke dienen. Es ist jedoch nicht möglich, Parameter anstelle von Kennzeichnungen, Spaltennamen, Tabellennamen oder anderen Teilen der Abfrage zu nutzen.

Verwenden Sie zum Angeben eines benannten Parameters das Zeichen @, gefolgt von einer Kennzeichnung wie @param_name. Mit der folgenden Abfrage werden in einem bestimmten Shakespeare-Korpus alle Wörter gesucht, die mindestens mit der angegebenen Häufigkeit vorkommen:

#standardSQL
SELECT
  word,
  word_count
FROM
  `bigquery-public-data.samples.shakespeare`
WHERE
  corpus = @corpus
  AND word_count >= @min_word_count
ORDER BY
  word_count DESC;

Sie können auch den Platzhalterwert ? verwenden, um einen Positionsparameter anzugeben. Beachten Sie, dass eine Abfrage benannte Parameter oder Positionsparameter, aber nicht beides enthalten darf.

Console

Parametrisierte Abfragen werden von der GCP Console nicht unterstützt.

Web-UI

Parametrisierte Abfragen werden von der BigQuery-Web-UI nicht unterstützt.

Befehlszeile

Verwenden Sie --parameter, um Werte für Parameter der Form "Name:Typ:Wert" bereitzustellen. Wenn der Name weggelassen wird, ergibt sich ein Positionsparameter. Wenn der Typ weggelassen wird, wird vom Typ STRING ausgegangen.

Das Flag --parameter muss in Verbindung mit dem Flag --use_legacy_sql=False verwendet werden, wenn die Standard-SQL-Abfragesyntax angegeben werden soll. Geben Sie Ihren Standort mit dem Flag --location an. Das Flag --location ist optional.

bq --location=US 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

Wenn Sie benannte Parameter verwenden möchten, legen Sie in der Jobkonfiguration den parameterMode auf NAMED fest.

Füllen Sie queryParameters mit der Liste der Parameter in der Jobkonfiguration. Legen Sie den name jedes Parameters mit dem in der Abfrage verwendeten @param_name fest.

Aktivieren Sie die Standard-SQL-Syntax. Legen Sie dazu useLegacySql auf false fest.

{
  "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"
}

Hier können Sie es im Google APIs Explorer ausprobieren.

Wenn Sie Positionsparameter verwenden möchten, legen Sie in der Jobkonfiguration den parameterMode auf POSITIONAL fest.

Go

Folgen Sie der Anleitung zur Einrichtung von Go im BigQuery-Schnellstart zur Verwendung von Clientbibliotheken, bevor Sie dieses Beispiel ausprobieren. Weitere Angaben finden Sie in der Referenzdokumentation zur BigQuery Go API.

So verwenden Sie benannte Parameter:
	// To run this sample, you will need to create (or reuse) a context and
	// an instance of the bigquery client.  For example:
	// import "cloud.google.com/go/bigquery"
	// ctx := context.Background()
	// client, err := bigquery.NewClient(ctx, "your-project-id")
	q := client.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;`)
	q.Parameters = []bigquery.QueryParameter{
		{
			Name:  "corpus",
			Value: "romeoandjuliet",
		},
		{
			Name:  "min_word_count",
			Value: 250,
		},
	}
	job, err := q.Run(ctx)
	if err != nil {
		return err
	}
	status, err := job.Wait(ctx)
	if err != nil {
		return err
	}
	if err := status.Err(); err != nil {
		return err
	}
	it, err := job.Read(ctx)
	for {
		var row []bigquery.Value
		err := it.Next(&row)
		if err == iterator.Done {
			break
		}
		if err != nil {
			return err
		}
		fmt.Println(row)
	}
So verwenden Sie Positionsparameter:
	// To run this sample, you will need to create (or reuse) a context and
	// an instance of the bigquery client.  For example:
	// import "cloud.google.com/go/bigquery"
	// ctx := context.Background()
	// client, err := bigquery.NewClient(ctx, "your-project-id")
	q := client.Query(
		`SELECT word, word_count
        FROM ` + "`bigquery-public-data.samples.shakespeare`" + `
        WHERE corpus = ?
        AND word_count >= ?
        ORDER BY word_count DESC;`)
	q.Parameters = []bigquery.QueryParameter{
		{
			Value: "romeoandjuliet",
		},
		{
			Value: 250,
		},
	}
	job, err := q.Run(ctx)
	if err != nil {
		return err
	}
	status, err := job.Wait(ctx)
	if err != nil {
		return err
	}
	if err := status.Err(); err != nil {
		return err
	}
	it, err := job.Read(ctx)
	for {
		var row []bigquery.Value
		err := it.Next(&row)
		if err == iterator.Done {
			break
		}
		if err != nil {
			return err
		}
		fmt.Println(row)
	}

Java

Folgen Sie der Anleitung zur Einrichtung von Java im BigQuery-Schnellstart zur Verwendung von Clientbibliotheken, bevor Sie dieses Beispiel ausprobieren. Weitere Angaben finden Sie in der Referenzdokumentation zur BigQuery Java API.

// BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();
String corpus = "romeoandjuliet";
long minWordCount = 250;
String query =
    "SELECT word, word_count\n"
        + "FROM `bigquery-public-data.samples.shakespeare`\n"
        + "WHERE corpus = @corpus\n"
        + "AND word_count >= @min_word_count\n"
        + "ORDER BY word_count DESC";
// Note: Standard SQL is required to use query parameters.
QueryJobConfiguration queryConfig =
    QueryJobConfiguration.newBuilder(query)
        .addNamedParameter("corpus", QueryParameterValue.string(corpus))
        .addNamedParameter("min_word_count", QueryParameterValue.int64(minWordCount))
        .build();

// Print the results.
for (FieldValueList row : bigquery.query(queryConfig).iterateAll()) {
  for (FieldValue val : row) {
    System.out.printf("%s,", val.toString());
  }
  System.out.printf("\n");
}

Python

Folgen Sie der Anleitung zur Einrichtung von Python im BigQuery-Schnellstart zur Verwendung von Clientbibliotheken, bevor Sie dieses Beispiel ausprobieren. Weitere Angaben finden Sie in der Referenzdokumentation zur BigQuery Python API.

So verwenden Sie benannte Parameter:
# from google.cloud import bigquery
# client = bigquery.Client()

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;
"""
query_params = [
    bigquery.ScalarQueryParameter("corpus", "STRING", "romeoandjuliet"),
    bigquery.ScalarQueryParameter("min_word_count", "INT64", 250),
]
job_config = bigquery.QueryJobConfig()
job_config.query_parameters = query_params
query_job = client.query(
    query,
    # Location must match that of the dataset(s) referenced in the query.
    location="US",
    job_config=job_config,
)  # API request - starts the query

# Print the results
for row in query_job:
    print("{}: \t{}".format(row.word, row.word_count))

assert query_job.state == "DONE"
So verwenden Sie Positionsparameter:
# from google.cloud import bigquery
# client = bigquery.Client()

query = """
    SELECT word, word_count
    FROM `bigquery-public-data.samples.shakespeare`
    WHERE corpus = ?
    AND word_count >= ?
    ORDER BY word_count DESC;
"""
# Set the name to None to use positional parameters.
# Note that you cannot mix named and positional parameters.
query_params = [
    bigquery.ScalarQueryParameter(None, "STRING", "romeoandjuliet"),
    bigquery.ScalarQueryParameter(None, "INT64", 250),
]
job_config = bigquery.QueryJobConfig()
job_config.query_parameters = query_params
query_job = client.query(
    query,
    # Location must match that of the dataset(s) referenced in the query.
    location="US",
    job_config=job_config,
)  # API request - starts the query

# Print the results
for row in query_job:
    print("{}: \t{}".format(row.word, row.word_count))

assert query_job.state == "DONE"

Node.js

Lesen Sie die Anleitung zur Einrichtung von Node.js unter BigQuery-Schnellstart: Verwendung von Clientbibliotheken, bevor Sie dieses Beispiel ausprobieren. Weitere Angaben finden Sie in der Referenzdokumentation zur BigQuery Node.js API.

So verwenden Sie benannte Parameter:
// Run a query using named query parameters

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

async function queryParamsNamed() {
  // Create a client
  const bigqueryClient = new BigQuery();

  // The SQL query to run
  const sqlQuery = `SELECT word, word_count
        FROM \`bigquery-public-data.samples.shakespeare\`
        WHERE corpus = @corpus
        AND word_count >= @min_word_count
        ORDER BY word_count DESC`;

  const options = {
    query: sqlQuery,
    // Location must match that of the dataset(s) referenced in the query.
    location: 'US',
    params: {corpus: 'romeoandjuliet', min_word_count: 250},
  };

  // Run the query
  const [rows] = await bigqueryClient.query(options);

  console.log('Rows:');
  rows.forEach(row => console.log(row));
}
queryParamsNamed();
So verwenden Sie Positionsparameter:
// Run a query using positional query parameters

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

async function queryParamsPositional() {
  // Create a client
  const bigqueryClient = new BigQuery();

  // The SQL query to run
  const sqlQuery = `SELECT word, word_count
        FROM \`bigquery-public-data.samples.shakespeare\`
        WHERE corpus = ?
        AND word_count >= ?
        ORDER BY word_count DESC`;

  const options = {
    query: sqlQuery,
    // Location must match that of the dataset(s) referenced in the query.
    location: 'US',
    params: ['romeoandjuliet', 250],
  };

  // Run the query
  const [rows] = await bigqueryClient.query(options);

  console.log('Rows:');
  rows.forEach(row => console.log(row));
}
queryParamsPositional();

Arrays in parametrisierten Abfragen verwenden

Wenn Sie in einem Abfrageparameter einen Arraytyp verwenden möchten, setzen Sie den Typ auf ARRAY<T>, wobei T der Typ der Elemente im Array ist. Erstellen Sie den Wert als kommagetrennte Liste von Elementen, die in eckige Klammern eingeschlossen sind, z. B. [1, 2, 3].

Weitere Informationen zum Arraytyp finden Sie in der Datentypreferenz.

Console

Parametrisierte Abfragen werden von der GCP Console nicht unterstützt.

Klassische UI

Parametrisierte Abfragen werden von der BigQuery-Web-UI nicht unterstützt.

Befehlszeile

Durch die folgende Abfrage werden die beliebtesten Jungennamen mit dem Anfangsbuchstaben W für in den USA geborene Kinder ausgewählt. In diesem Beispiel wird das Flag --location=US verwendet, weil Sie ein öffentliches Dataset abfragen. Die öffentlichen BigQuery-Datasets werden am Standort US gespeichert, der mehrere Regionen umfasst. Da die öffentlichen Datasets in den USA gespeichert werden, können Sie Abfrageergebnisse für öffentliche Datasets nicht in Tabellen in einer anderen Region schreiben und Tabellen in öffentlichen Datasets nicht mit Tabellen in einer anderen Region zusammenführen.

bq --location=US query --use_legacy_sql=False \
    --parameter='gender::M' \
    --parameter='states:ARRAY<STRING>:["WA", "WI", "WV", "WY"]' \
    'SELECT name, sum(number) as count
    FROM `bigquery-public-data.usa_names.usa_1910_2013`
    WHERE gender = @gender
    AND state IN UNNEST(@states)
    GROUP BY name
    ORDER BY count DESC
    LIMIT 10;'

Achten Sie darauf, die Array-Typdeklaration in einfache Anführungszeichen zu setzen, damit die Befehlsausgabe nicht versehentlich durch das Zeichen > zu einer Datei weitergeleitet wird.

API

Wenn Sie einen Parameter mit Arraywerten verwenden möchten, legen Sie in der Konfiguration des Abfragejobs den parameterType auf ARRAY fest.

Sollten die Arraywerte Skalare sein, legen Sie den parameterType auf den Typ der Werte fest, z. B. STRING. Sind die Arraywerte Strukturen, legen Sie dafür STRUCT fest und fügen die erforderlichen Felddefinitionen in structTypes ein.

Durch die folgende Abfrage werden z. B. die beliebtesten Jungennamen mit dem Anfangsbuchstaben W für in den USA geborene Kinder ausgewählt:

{
 "query": "SELECT name, sum(number) as count\nFROM `bigquery-public-data.usa_names.usa_1910_2013`\nWHERE gender = @gender\nAND state IN UNNEST(@states)\nGROUP BY name\nORDER BY count DESC\nLIMIT 10;",
 "queryParameters": [
  {
   "parameterType": {
    "type": "STRING"
   },
   "parameterValue": {
    "value": "M"
   },
   "name": "gender"
  },
  {
   "parameterType": {
    "type": "ARRAY",
    "arrayType": {
     "type": "STRING"
    }
   },
   "parameterValue": {
    "arrayValues": [
     {
      "value": "WA"
     },
     {
      "value": "WI"
     },
     {
      "value": "WV"
     },
     {
      "value": "WY"
     }
    ]
   },
   "name": "states"
  }
 ],
 "useLegacySql": false,
 "parameterMode": "NAMED"
}

Hier können Sie es im Google APIs Explorer ausprobieren.

Go

Folgen Sie der Anleitung zur Einrichtung von Go im BigQuery-Schnellstart zur Verwendung von Clientbibliotheken, bevor Sie dieses Beispiel ausprobieren. Weitere Angaben finden Sie in der Referenzdokumentation zur BigQuery Go API.

	// To run this sample, you will need to create (or reuse) a context and
	// an instance of the bigquery client.  For example:
	// import "cloud.google.com/go/bigquery"
	// ctx := context.Background()
	// client, err := bigquery.NewClient(ctx, "your-project-id")
	q := client.Query(
		`SELECT
			name,
			sum(number) as count
        FROM ` + "`bigquery-public-data.usa_names.usa_1910_2013`" + `
		WHERE
			gender = @gender
        	AND state IN UNNEST(@states)
		GROUP BY
			name
		ORDER BY
			count DESC
		LIMIT 10;`)
	q.Parameters = []bigquery.QueryParameter{
		{
			Name:  "gender",
			Value: "M",
		},
		{
			Name:  "states",
			Value: []string{"WA", "WI", "WV", "WY"},
		},
	}
	job, err := q.Run(ctx)
	if err != nil {
		return err
	}
	status, err := job.Wait(ctx)
	if err != nil {
		return err
	}
	if err := status.Err(); err != nil {
		return err
	}
	it, err := job.Read(ctx)
	for {
		var row []bigquery.Value
		err := it.Next(&row)
		if err == iterator.Done {
			break
		}
		if err != nil {
			return err
		}
		fmt.Println(row)
	}

Java

Folgen Sie der Anleitung zur Einrichtung von Java im BigQuery-Schnellstart zur Verwendung von Clientbibliotheken, bevor Sie dieses Beispiel ausprobieren. Weitere Angaben finden Sie in der Referenzdokumentation zur BigQuery Java API.

// BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();
String gender = "M";
String[] states = {"WA", "WI", "WV", "WY"};
String query =
    "SELECT name, sum(number) as count\n"
        + "FROM `bigquery-public-data.usa_names.usa_1910_2013`\n"
        + "WHERE gender = @gender\n"
        + "AND state IN UNNEST(@states)\n"
        + "GROUP BY name\n"
        + "ORDER BY count DESC\n"
        + "LIMIT 10;";
// Note: Standard SQL is required to use query parameters.
QueryJobConfiguration queryConfig =
    QueryJobConfiguration.newBuilder(query)
        .addNamedParameter("gender", QueryParameterValue.string(gender))
        .addNamedParameter("states", QueryParameterValue.array(states, String.class))
        .build();

// Print the results.
for (FieldValueList row : bigquery.query(queryConfig).iterateAll()) {
  for (FieldValue val : row) {
    System.out.printf("%s,", val.toString());
  }
  System.out.printf("\n");
}

Python

Folgen Sie der Anleitung zur Einrichtung von Python im BigQuery-Schnellstart zur Verwendung von Clientbibliotheken, bevor Sie dieses Beispiel ausprobieren. Weitere Informationen finden Sie in der Referenzdokumentation zur BigQuery Python API.

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

query = """
    SELECT name, sum(number) as count
    FROM `bigquery-public-data.usa_names.usa_1910_2013`
    WHERE gender = @gender
    AND state IN UNNEST(@states)
    GROUP BY name
    ORDER BY count DESC
    LIMIT 10;
"""
query_params = [
    bigquery.ScalarQueryParameter("gender", "STRING", "M"),
    bigquery.ArrayQueryParameter("states", "STRING", ["WA", "WI", "WV", "WY"]),
]
job_config = bigquery.QueryJobConfig()
job_config.query_parameters = query_params
query_job = client.query(
    query,
    # Location must match that of the dataset(s) referenced in the query.
    location="US",
    job_config=job_config,
)  # API request - starts the query

# Print the results
for row in query_job:
    print("{}: \t{}".format(row.name, row.count))

assert query_job.state == "DONE"

Node.js

Lesen Sie die Anleitung zur Einrichtung von Node.js unter BigQuery-Schnellstart: Verwendung von Clientbibliotheken, bevor Sie dieses Beispiel ausprobieren. Weitere Angaben finden Sie in der Referenzdokumentation zur BigQuery Node.js API.

// Run a query using array query parameters

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

async function queryParamsArrays() {
  // Create a client
  const bigqueryClient = new BigQuery();

  // The SQL query to run
  const sqlQuery = `SELECT name, sum(number) as count
  FROM \`bigquery-public-data.usa_names.usa_1910_2013\`
  WHERE gender = @gender
  AND state IN UNNEST(@states)
  GROUP BY name
  ORDER BY count DESC
  LIMIT 10;`;

  const options = {
    query: sqlQuery,
    // Location must match that of the dataset(s) referenced in the query.
    location: 'US',
    params: {gender: 'M', states: ['WA', 'WI', 'WV', 'WY']},
  };

  // Run the query
  const [rows] = await bigqueryClient.query(options);

  console.log('Rows:');
  rows.forEach(row => console.log(row));
}
queryParamsArrays();

Zeitstempel in parametrisierten Abfragen verwenden

Wenn Sie in einem Abfrageparameter einen Zeitstempel verwenden möchten, setzen Sie den Typ auf TIMESTAMP. Der Wert sollte im Format YYYY-MM-DD HH:MM:SS.DDDDDD time_zone vorliegen.

Weitere Informationen zum Zeitstempeltyp finden Sie in der Datentypreferenz.

Console

Parametrisierte Abfragen werden von der GCP Console nicht unterstützt.

Klassische UI

Parametrisierte Abfragen werden von der BigQuery-Web-UI nicht unterstützt.

Befehlszeile

Durch die folgende Abfrage wird eine Stunde zum Zeitstempel-Parameterwert hinzugefügt:

bq --location=US query --use_legacy_sql=False \
    --parameter='ts_value:TIMESTAMP:2016-12-07 08:00:00' \
    'SELECT TIMESTAMP_ADD(@ts_value, INTERVAL 1 HOUR);'

API

Wenn Sie einen Zeitstempelparameter verwenden möchten, legen Sie in der Konfiguration des Abfragejobs den parameterType auf TIMESTAMP fest.

Durch die folgende Abfrage wird eine Stunde zum Zeitstempel-Parameterwert hinzugefügt:

{
  "query": "SELECT TIMESTAMP_ADD(@ts_value, INTERVAL 1 HOUR);",
  "queryParameters": [
    {
      "name": "ts_value",
      "parameterType": {
        "type": "TIMESTAMP"
      },
      "parameterValue": {
        "value": "2016-12-07 08:00:00"
      }
    }
  ],
  "useLegacySql": false,
  "parameterMode": "NAMED"
}

Hier können Sie es im Google APIs Explorer ausprobieren.

Go

Folgen Sie der Anleitung zur Einrichtung von Go im BigQuery-Schnellstart zur Verwendung von Clientbibliotheken, bevor Sie dieses Beispiel ausprobieren. Weitere Angaben finden Sie in der Referenzdokumentation zur BigQuery Go API.

// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")
q := client.Query(
	`SELECT TIMESTAMP_ADD(@ts_value, INTERVAL 1 HOUR);`)
q.Parameters = []bigquery.QueryParameter{
	{
		Name:  "ts_value",
		Value: time.Date(2016, 12, 7, 8, 0, 0, 0, time.UTC),
	},
}
job, err := q.Run(ctx)
if err != nil {
	return err
}
status, err := job.Wait(ctx)
if err != nil {
	return err
}
if err := status.Err(); err != nil {
	return err
}
it, err := job.Read(ctx)
for {
	var row []bigquery.Value
	err := it.Next(&row)
	if err == iterator.Done {
		break
	}
	if err != nil {
		return err
	}
	fmt.Println(row)
}

Java

Folgen Sie der Anleitung zur Einrichtung von Java im BigQuery-Schnellstart zur Verwendung von Clientbibliotheken, bevor Sie dieses Beispiel ausprobieren. Weitere Angaben finden Sie in der Referenzdokumentation zur BigQuery Java API.

// BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();
DateTime timestamp = new DateTime(2016, 12, 7, 8, 0, 0, DateTimeZone.UTC);
String query = "SELECT TIMESTAMP_ADD(@ts_value, INTERVAL 1 HOUR);";
// Note: Standard SQL is required to use query parameters.
QueryJobConfiguration queryConfig =
    QueryJobConfiguration.newBuilder(query)
        .addNamedParameter(
            "ts_value",
            QueryParameterValue.timestamp(
                // Timestamp takes microseconds since 1970-01-01T00:00:00 UTC
                timestamp.getMillis() * 1000))
        .build();

// Print the results.
DateTimeFormatter formatter = ISODateTimeFormat.dateTimeNoMillis().withZoneUTC();
for (FieldValueList row : bigquery.query(queryConfig).iterateAll()) {
  System.out.printf(
      "%s\n",
      formatter.print(
          new DateTime(
              // Timestamp values are returned in microseconds since 1970-01-01T00:00:00 UTC,
              // but org.joda.time.DateTime constructor accepts times in milliseconds.
              row.get(0).getTimestampValue() / 1000, DateTimeZone.UTC)));
  System.out.printf("\n");
}

Python

Folgen Sie der Anleitung zur Einrichtung von Python im BigQuery-Schnellstart zur Verwendung von Clientbibliotheken, bevor Sie dieses Beispiel ausprobieren. Weitere Informationen finden Sie in der Referenzdokumentation zur BigQuery Python API.

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

import datetime
import pytz

query = "SELECT TIMESTAMP_ADD(@ts_value, INTERVAL 1 HOUR);"
query_params = [
    bigquery.ScalarQueryParameter(
        "ts_value",
        "TIMESTAMP",
        datetime.datetime(2016, 12, 7, 8, 0, tzinfo=pytz.UTC),
    )
]
job_config = bigquery.QueryJobConfig()
job_config.query_parameters = query_params
query_job = client.query(
    query,
    # Location must match that of the dataset(s) referenced in the query.
    location="US",
    job_config=job_config,
)  # API request - starts the query

# Print the results
for row in query_job:
    print(row)

assert query_job.state == "DONE"

Node.js

Lesen Sie die Anleitung zur Einrichtung von Node.js unter BigQuery-Schnellstart: Verwendung von Clientbibliotheken, bevor Sie dieses Beispiel ausprobieren. Weitere Angaben finden Sie in der Referenzdokumentation zur BigQuery Node.js API.

// Run a query using timestamp parameters

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

async function queryParamsTimestamps() {
  // Create a client
  const bigqueryClient = new BigQuery();

  // The SQL query to run
  const sqlQuery = `SELECT TIMESTAMP_ADD(@ts_value, INTERVAL 1 HOUR);`;

  const options = {
    query: sqlQuery,
    // Location must match that of the dataset(s) referenced in the query.
    location: 'US',
    params: {ts_value: new Date()},
  };

  // Run the query
  const [rows] = await bigqueryClient.query(options);

  console.log('Rows:');
  rows.forEach(row => console.log(row.f0_));
}
queryParamsTimestamps();

Strukturen in parametrisierten Abfragen verwenden

Wenn Sie in einem Abfrageparameter eine Struktur verwenden möchten, setzen Sie den Typ auf STRUCT<T>, wobei durch T die Felder und Typen innerhalb der Struktur definiert werden. Felddefinitionen werden durch Kommas getrennt und haben die Form field_name TF, wobei TF der Typ des Felds ist. Durch STRUCT<x INT64, y STRING> wird z. B. eine Struktur mit einem Feld namens x vom Typ INT64 und ein zweites Feld namens y vom Typ STRING definiert.

Weitere Informationen zum Strukturtyp finden Sie in der Datentypreferenz.

Console

Parametrisierte Abfragen werden von der GCP Console nicht unterstützt.

Klassische UI

Parametrisierte Abfragen werden von der BigQuery-Web-UI nicht unterstützt.

Befehlszeile

Diese einfache Abfrage veranschaulicht die Verwendung strukturierter Typen durch das Zurückgeben des Parameterwerts.

bq --location=US query --use_legacy_sql=False \
    --parameter='struct_value:STRUCT<x INT64, y STRING>:{"x": 1, "y": "foo"}' \
    'SELECT @struct_value AS s;'

API

Wenn Sie einen Strukturparameter verwenden möchten, legen Sie in der Konfiguration des Abfragejobs den parameterType auf STRUCT fest.

Fügen Sie in den queryParameters des Jobs unter structTypes für jedes Feld der Struktur ein Objekt hinzu. Sollten die Strukturwerte Skalare sein, legen Sie den type auf den Typ der Werte fest, z. B. STRING. Sind die Strukturwerte Arrays, legen Sie dafür ARRAY fest und setzen das verschachtelte Feld arrayType auf den entsprechenden Typ. Wenn die Strukturwerte Strukturen sind, setzen Sie type auf STRUCT und fügen Sie die erforderlichen structTypes-Typen hinzu.

Diese einfache Abfrage veranschaulicht die Verwendung strukturierter Typen durch das Zurückgeben des Parameterwerts.

{
  "query": "SELECT @struct_value AS s;",
  "queryParameters": [
    {
      "name": "struct_value",
      "parameterType": {
        "type": "STRUCT",
        "structTypes": [
          {
            "name": "x",
            "type": {
              "type": "INT64"
            }
          },
          {
            "name": "y",
            "type": {
              "type": "STRING"
            }
          }
        ]
      },
      "parameterValue": {
        "structValues": {
          "x": {
            "value": "1"
          },
          "y": {
            "value": "foo"
          }
        }
      }
    }
  ],
  "useLegacySql": false,
  "parameterMode": "NAMED"
}

Hier können Sie es im Google APIs Explorer ausprobieren.

Go

Folgen Sie der Anleitung zur Einrichtung von Go im BigQuery-Schnellstart zur Verwendung von Clientbibliotheken, bevor Sie dieses Beispiel ausprobieren. Weitere Angaben finden Sie in der Referenzdokumentation zur BigQuery Go API.

// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")
type MyStruct struct {
	X int64
	Y string
}
q := client.Query(
	`SELECT @struct_value as s;`)
q.Parameters = []bigquery.QueryParameter{
	{
		Name:  "struct_value",
		Value: MyStruct{X: 1, Y: "foo"},
	},
}
job, err := q.Run(ctx)
if err != nil {
	return err
}
status, err := job.Wait(ctx)
if err != nil {
	return err
}
if err := status.Err(); err != nil {
	return err
}
it, err := job.Read(ctx)
for {
	var row []bigquery.Value
	err := it.Next(&row)
	if err == iterator.Done {
		break
	}
	if err != nil {
		return err
	}
	fmt.Println(row)
}

Python

Folgen Sie der Anleitung zur Einrichtung von Python im BigQuery-Schnellstart zur Verwendung von Clientbibliotheken, bevor Sie dieses Beispiel ausprobieren. Weitere Informationen finden Sie in der Referenzdokumentation zur BigQuery Python API.

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

query = "SELECT @struct_value AS s;"
query_params = [
    bigquery.StructQueryParameter(
        "struct_value",
        bigquery.ScalarQueryParameter("x", "INT64", 1),
        bigquery.ScalarQueryParameter("y", "STRING", "foo"),
    )
]
job_config = bigquery.QueryJobConfig()
job_config.query_parameters = query_params
query_job = client.query(
    query,
    # Location must match that of the dataset(s) referenced in the query.
    location="US",
    job_config=job_config,
)  # API request - starts the query

# Print the results
for row in query_job:
    print(row.s)

assert query_job.state == "DONE"

Node.js

Lesen Sie die Anleitung zur Einrichtung von Node.js unter BigQuery-Schnellstart: Verwendung von Clientbibliotheken, bevor Sie dieses Beispiel ausprobieren. Weitere Angaben finden Sie in der Referenzdokumentation zur BigQuery Node.js API.

// Run a query using struct query parameters

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

async function queryParamsStructs() {
  // Create a client
  const bigqueryClient = new BigQuery();

  // The SQL query to run
  const sqlQuery = `SELECT @struct_value AS struct_obj;`;

  const options = {
    query: sqlQuery,
    // Location must match that of the dataset(s) referenced in the query.
    location: 'US',
    params: {struct_value: {x: 1, y: 'foo'}},
  };

  // Run the query
  const [rows] = await bigqueryClient.query(options);

  console.log('Rows:');
  rows.forEach(row => console.log(row.struct_obj.y));
}
queryParamsStructs();

Hat Ihnen diese Seite weitergeholfen? Teilen Sie uns Ihr Feedback mit:

Feedback geben zu...