Google verwendet KI-Technologie, um Inhalte in Ihre bevorzugte Sprache zu übersetzen. KI-Übersetzungen können Fehler enthalten.

Abfrageoptimierung verwalten

Auf dieser Seite wird beschrieben, wie Sie das Abfrageoptimierungstool in Cloud Spanner für Datenbanken im GoogleSQL-Dialekt und Datenbanken im PostgreSQL-Dialekt verwalten.

Das Cloud Spanner-Abfrageoptimierungstool ermittelt die effizienteste Methode zum Ausführen einer SQL-Abfrage. Der vom Optimierungstool ermittelte Abfrageplan kann sich jedoch geringfügig ändern, wenn sich das Abfrageoptimierungstool weiterentwickelt oder die Datenbankstatistiken aktualisiert werden. Um das Risiko einer Leistungsregression zu minimieren, wenn sich das Abfrageoptimierungstool oder die Statistiken ändern, bietet Cloud Spanner die folgenden Abfrageoptionen.

optimizer_version: Änderungen am Abfrageoptimierungstool werden gebündelt und als Optimierungstoolversionen veröffentlicht. Cloud Spanner verwendet die neueste Version des Optimierungstools mindestens 30 Tage nach der Veröffentlichung dieser Version als Standard. Mit der Option „Version des Abfrageoptimierungstools“ können Sie Abfragen für eine ältere Version des Optimierungstools ausführen.
optimizer_statistics_package: Cloud Spanner aktualisiert die Statistiken des Optimierungstools regelmäßig. Neue Statistiken werden als Paket zur Verfügung gestellt. Mit dieser Abfrageoption wird ein Statistikpaket für das Abfrageoptimierungstool angegeben, das beim Kompilieren einer SQL-Abfrage verwendet werden soll. Für das angegebene Paket muss die automatische Speicherbereinigung deaktiviert sein:
GoogleSQL
```
ALTER STATISTICS <package_name> SET OPTIONS (allow_gc=false)
```
PostgreSQL
```
ALTER STATISTICS spanner."<package_name>" SET OPTIONS (allow_gc = false)
```

In dieser Anleitung wird gezeigt, wie Sie diese einzelnen Optionen in Cloud Spanner in verschiedenen Bereichen festlegen.

Optionen des Abfrageoptimierungstools auflisten

Cloud Spanner speichert Informationen zu den verfügbaren Versionen des Optimierungstools und Statistikpaketen, die Sie auswählen können.

Versionen des Optimierungstools

Die Version des Abfrageoptimierungstools ist ein ganzzahliger Wert, der bei jeder Aktualisierung um 1 erhöht wird. Die neueste Version des Abfrageoptimierungstools ist 9.

Führen Sie die folgende SQL-Anweisung aus, damit eine Liste aller unterstützten Versionen des Optimierungstools zusammen mit den entsprechenden Releasedaten und Informationen dazu zurückgegeben wird, ob diese Version die Standardversion ist. Die größte zurückgegebene Versionsnummer ist die neueste unterstützte Version des Optimierungstools.

SELECT * FROM SPANNER_SYS.SUPPORTED_OPTIMIZER_VERSIONS;

Standardversion

Standardmäßig verwendet Cloud Spanner die neueste Version des Optimierungstools mindestens 30 Tage nach der Veröffentlichung dieser Version. Während des Zeitraums von mehr als 30 Tagen zwischen einer neuen Version und dem Zeitpunkt, an dem diese Version zur Standardversion wird, sollten Sie Abfragen mit der neuen Version testen, um Regressionen zu erkennen.

Führen Sie die folgende SQL-Anweisung aus, um die Standardversion zu ermitteln:

SELECT * FROM SPANNER_SYS.SUPPORTED_OPTIMIZER_VERSIONS;

Die Abfrage gibt eine Liste aller unterstützten Versionen des Optimierungstools zurück. In der Spalte IS_DEFAULT wird angegeben, welche Version die aktuelle Standardversion ist.

Weitere Informationen zu den einzelnen Versionen finden Sie unter Versionsverlauf des Abfrageoptimierungstools.

Statistikpakete des Optimierungstools

Jedes neue Statistikpaket des Optimierungstools, das von Cloud Spanner erstellt wird, erhält einen Paketnamen, der in der jeweiligen Datenbank garantiert eindeutig ist.

Das Format des Paketnamens ist auto_{PACKAGE_TIMESTAMP}UTC. In GoogleSQL löst die ANALYZE Anweisung die Erstellung des Statistikpaketnamens aus. In PostgreSQL führt die ANALYZE Anweisung diese Aufgabe aus. Das Format des Statistikpaketnamens ist analyze_{PACKAGE_TIMESTAMP}UTC. Dabei ist {PACKAGE_TIMESTAMP} der Zeitstempel (in UTC-Zeitzone), zu dem die Erstellung der Statistiken begonnen hat. Führen Sie die folgende SQL-Anweisung aus, um eine Liste aller verfügbaren Statistikpakete des Optimierungstools zurückzugeben.

SELECT * FROM INFORMATION_SCHEMA.SPANNER_STATISTICS;

Standardmäßig verwendet Cloud Spanner das neueste Statistikpaket des Optimierungstools, es sei denn, die Datenbank oder Abfrage ist mit einer der auf dieser Seite beschriebenen Methoden an ein älteres Paket angeheftet.

Rangfolge der Optionsüberschreibung

Wenn Sie eine Datenbank im GoogleSQL-Dialekt verwenden, bietet Cloud Spanner mehrere Möglichkeiten, die Optionen des Optimierungstools zu ändern. Sie können beispielsweise die Option(en) für eine bestimmte Abfrage festlegen oder die Option in der Clientbibliothek auf Prozess- oder Abfrageebene konfigurieren. Wenn eine Option auf mehrere Arten festgelegt wird, gilt die folgende Rangfolge. (Wählen Sie einen Link aus, um zu diesem Abschnitt in diesem Dokument zu springen).

Cloud Spanner-Standardeinstellung ← Datenbankoption ← Client-Anwendung ← Umgebungsvariable ← Client-Abfrage ← Anweisungshinweis

So können Sie beispielsweise die Rangfolge beim Festlegen der Version des Abfrageoptimierungstools interpretieren:

Wenn Sie eine Datenbank erstellen, wird die Standardversion des Optimierungstools von Cloud Spanner verwendet. Das Festlegen der Version des Optimierungstools mit einer der zuvor aufgeführten Methoden hat Vorrang vor allen links daneben stehenden Methoden. Beispielsweise hat das Festlegen des Optimierungstools für eine Anwendung mithilfe einer Umgebungsvariable Vorrang vor allen Werten, die Sie mit der Datenbankoption für die Datenbank festlegen. Das Festlegen der Version des Optimierungstools über einen Anweisungshinweis hat die höchste Priorität für die angegebene Abfrage, wobei der mit einer anderen Methode festgelegte Wert Vorrang hat.

In den folgenden Abschnitten finden Sie weitere Informationen zu den einzelnen Methoden.

Optionen des Optimierungstools festlegen

Sie können die Standardoption des Optimierungstools mit den folgenden Methoden festlegen:

Auf Datenbankebene
Für eine Abfrage mit einem Anweisungshinweis
Mit Clientbibliotheken
Mit dem Cloud Spanner-JDBC-Treiber

In einigen Fällen verwendet Cloud Spanner möglicherweise eine ältere Version des Abfrageoptimierungstools für eine bestimmte Abfrageform, auch wenn Sie eine neuere Version angeheftet haben. Dies ist ein erwartetes internes Verhalten, um die Stabilität und Leistung von Abfragen zu gewährleisten. Sie können die Version des Optimierungstools, die für eine bestimmte Abfrage verwendet wurde, anhand des Abfrageausführungsplans ermitteln.

Optionen des Optimierungstools auf Datenbankebene festlegen

Verwenden Sie den folgenden ALTER DATABASE DDL-Befehl, um die Standardversion des Optimierungstools für eine Datenbank festzulegen. Wenn Sie diese Option festlegen, müssen nicht alle Abfragen mit dieser Version ausgeführt werden. Stattdessen wird eine Obergrenze für die Version des Abfrageoptimierungstools festgelegt, die für Abfragen verwendet wird. Sie soll Regressionen verhindern, die nach der Veröffentlichung einer neuen Version des Optimierungstools auftreten.

GoogleSQL

ALTER DATABASE MyDatabase
SET OPTIONS (optimizer_version =  9);

PostgreSQL

ALTER DATABASE MyDatabase SET spanner.optimizer_version = 5;

Sie können das Statistikpaket ähnlich festlegen, wie im folgenden Beispiel gezeigt.

GoogleSQL

ALTER DATABASE MyDatabase
SET OPTIONS (optimizer_statistics_package = "auto_20191128_14_47_22UTC");

PostgreSQL

ALTER DATABASE MyDatabase
SET spanner.optimizer_statistics_package = "auto_20191128_14_47_22UTC";

Sie können auch mehrere Optionen gleichzeitig festlegen, wie im folgenden DDL-Befehl gezeigt.

GoogleSQL

ALTER DATABASE MyDatabase
SET OPTIONS (optimizer_version = 9,
            optimizer_statistics_package = "auto_20191128_14_47_22UTC");

Sie können ALTER DATABASE in der gcloud CLI mit dem gcloud CLI databases ddl update Befehl wie folgt ausführen.

GoogleSQL

gcloud spanner databases ddl update MyDatabase --instance=test-instance \
    --ddl='ALTER DATABASE MyDatabase SET OPTIONS ( optimizer_version = 9 )'

PostgreSQL

gcloud spanner databases ddl update MyDatabase --instance=test-instance \
  --ddl='ALTER DATABASE MyDatabase SET spanner.optimizer_version = 9'

Wenn Sie eine Datenbankoption auf NULL (in GoogleSQL) oder DEFAULT (in PostgreSQL) setzen, wird sie gelöscht, sodass der Standardwert verwendet wird.

Wenn Sie den aktuellen Wert dieser Optionen für eine Datenbank sehen möchten, fragen Sie die INFORMATION_SCHEMA.DATABASE_OPTIONS Ansicht für GoogleSQL oder die information_schema database_options Tabelle für PostgreSQL wie folgt ab.

GoogleSQL

SELECT
  s.OPTION_NAME,
  s.OPTION_VALUE
FROM
  INFORMATION_SCHEMA.DATABASE_OPTIONS s
WHERE
  s.SCHEMA_NAME=""
  AND s.OPTION_NAME IN ('optimizer_version', 'optimizer_statistics_package')

PostgreSQL

  SELECT
    s.option_name,
    s.option_value
  FROM
    information_schema.database_options s
  WHERE
    s.schema_name='public'
    AND s.option_name IN ('optimizer_version',
      'optimizer_statistics_package')

Optionen des Optimierungstools für eine Abfrage mithilfe eines Anweisungshinweises festlegen

Ein Anweisungshinweis ist ein Hinweis auf eine Abfrageanweisung, durch den die Ausführung der Abfrage vom Standardverhalten abweicht. Wenn Sie den OPTIMIZER_VERSION-Hinweis für eine Anweisung festlegen, wird die Ausführung der Abfrage mit der angegebenen Version des Abfrageoptimierungstools erzwungen.

Der Hinweis OPTIMIZER_VERSION hat die höchste Priorität in Bezug auf die Version des Optimierungstools. Wenn der Hinweis zur Anweisung angegeben ist, wird er unabhängig von allen anderen Einstellungen der Optimierungstoolversion verwendet.

GoogleSQL

@{OPTIMIZER_VERSION=9} SELECT * FROM MyTable;

PostgreSQL

/*@OPTIMIZER_VERSION=9*/ SELECT * FROM MyTable;

Sie können auch das Literal latest_version verwenden, um die Optimierungsversion für eine Abfrage wie hier gezeigt auf die neueste Version festzulegen.

GoogleSQL

@{OPTIMIZER_VERSION=latest_version} SELECT * FROM MyTable;

PostgreSQL

/*@OPTIMIZER_VERSION=latest_version*/ SELECT * FROM MyTable;

Wenn Sie den Hinweis OPTIMIZER_STATISTICS_PACKAGE für eine Anweisung festlegen, wird die Ausführung der Abfrage mit der angegebenen Version des Statistikpakets des Abfrageoptimierungstools erzwungen. Für das angegebene Paket muss die automatische Speicherbereinigung deaktiviert sein:

GoogleSQL

ALTER STATISTICS <package_name> SET OPTIONS (allow_gc=false)

PostgreSQL

ALTER STATISTICS spanner."<package_name>" SET OPTIONS (allow_gc=false)

Der Hinweis OPTIMIZER_STATISTICS_PACKAGE hat die höchste Priorität in Bezug auf die Einstellung des Optimierungspakets. Wenn der Hinweis zur Anweisung angegeben ist, wird er unabhängig von allen anderen Einstellungen der Version des Optimierungspakets verwendet.

@{OPTIMIZER_STATISTICS_PACKAGE=auto_20191128_14_47_22UTC} SELECT * FROM MyTable;

Sie können auch das Literal latest verwenden, um das neueste Statistikpaket zu verwenden.

@{OPTIMIZER_STATISTICS_PACKAGE=latest} SELECT * FROM MyTable;

Beide Hinweise können in einer einzigen Anweisung festgelegt werden, wie im folgenden Beispiel gezeigt.

Das Literal default_version legt die Version des Optimierungstools für eine Abfrage auf die Standardversion fest, die sich von der neuesten Version unterscheiden kann. Weitere Informationen finden Sie unter Standardversion.

GoogleSQL

@{OPTIMIZER_VERSION=default_version, OPTIMIZER_STATISTICS_PACKAGE=auto_20191128_14_47_22UTC} SELECT * FROM MyTable;

PostgreSQL

/*@OPTIMIZER_VERSION=default_version, OPTIMIZER_STATISTICS_PACKAGE=auto_20191128_14_47_22UTC*/ SELECT * FROM KeyValue;

Optionen des Optimierungstools mit Clientbibliotheken festlegen

Wenn Sie programmgesteuert über Clientbibliotheken mit Cloud Spanner interagieren, gibt es mehrere Möglichkeiten, um die Abfrageoptionen für Ihre Client-Anwendung zu ändern.

Sie müssen die neuesten Versionen der Clientbibliotheken verwenden, um Optionen des Optimierungstools festzulegen.

Für einen Datenbankclient

Eine Anwendung kann Optionen des Optimierungstools global für die Clientbibliothek festlegen. Dazu wird die Eigenschaft der Abfrageoptionen wie in den folgenden Code-Snippets konfiguriert. Die Einstellungen des Optimierungstools werden in der Client-Instanz gespeichert und auf alle Abfragen angewendet, die während der Lebensdauer des Clients ausgeführt werden. Auch wenn die Optionen auf Datenbankebene im Back-End gelten, gelten die Optionen auf Client-Ebene für alle Datenbanken, die mit diesem Client verbunden sind.

C++

namespace spanner = ::google::cloud::spanner;
spanner::Client client(
    spanner::MakeConnection(db),
    google::cloud::Options{}
        .set<spanner::QueryOptimizerVersionOption>("1")
        .set<spanner::QueryOptimizerStatisticsPackageOption>(
            "auto_20191128_14_47_22UTC"));

C#


using Google.Cloud.Spanner.Data;
using System.Collections.Generic;
using System.Threading.Tasks;

public class CreateConnectionWithQueryOptionsAsyncSample
{
    public class Album
    {
        public int AlbumId { get; set; }
        public int SingerId { get; set; }
        public string AlbumTitle { get; set; }
    }

    public async Task<List<Album>> CreateConnectionWithQueryOptionsAsync(string projectId, string instanceId, string databaseId)
    {
        string connectionString = $"Data Source=projects/{projectId}/instances/{instanceId}/databases/{databaseId}";

        using var connection = new SpannerConnection(connectionString)
        {
            // Set query options on the connection.
            QueryOptions = QueryOptions.Empty
                .WithOptimizerVersion("1")
                // The list of available statistics packages for the database can
                // be found by querying the "INFORMATION_SCHEMA.SPANNER_STATISTICS"
                // table.
                .WithOptimizerStatisticsPackage("latest")
        };

        var albums = new List<Album>();
        var cmd = connection.CreateSelectCommand("SELECT SingerId, AlbumId, AlbumTitle FROM Albums");
        using var reader = await cmd.ExecuteReaderAsync();
        while (await reader.ReadAsync())
        {
            albums.Add(new Album
            {
                SingerId = reader.GetFieldValue<int>("SingerId"),
                AlbumId = reader.GetFieldValue<int>("AlbumId"),
                AlbumTitle = reader.GetFieldValue<string>("AlbumTitle")
            });
        }
        return albums;
    }
}

Go


import (
	"context"
	"fmt"
	"io"
	"time"

	"cloud.google.com/go/spanner"
	sppb "cloud.google.com/go/spanner/apiv1/spannerpb"
	"google.golang.org/api/iterator"
)

func createClientWithQueryOptions(w io.Writer, database string) error {
	ctx := context.Background()
	queryOptions := spanner.QueryOptions{
		Options: &sppb.ExecuteSqlRequest_QueryOptions{
			OptimizerVersion: "1",
			// The list of available statistics packages can be found by
			// querying the "INFORMATION_SCHEMA.SPANNER_STATISTICS" table.
			OptimizerStatisticsPackage: "latest",
		},
	}
	client, err := spanner.NewClientWithConfig(
		ctx, database, spanner.ClientConfig{QueryOptions: queryOptions},
	)
	if err != nil {
		return err
	}
	defer client.Close()

	stmt := spanner.Statement{SQL: `SELECT VenueId, VenueName, LastUpdateTime FROM Venues`}
	iter := client.Single().Query(ctx, stmt)
	defer iter.Stop()
	for {
		row, err := iter.Next()
		if err == iterator.Done {
			return nil
		}
		if err != nil {
			return err
		}
		var venueID int64
		var venueName string
		var lastUpdateTime time.Time
		if err := row.Columns(&venueID, &venueName, &lastUpdateTime); err != nil {
			return err
		}
		fmt.Fprintf(w, "%d %s %s\n", venueID, venueName, lastUpdateTime)
	}
}

Java

static void clientWithQueryOptions(DatabaseId db) {
  SpannerOptions options =
      SpannerOptions.newBuilder()
          .setDefaultQueryOptions(
              db, QueryOptions
                  .newBuilder()
                  .setOptimizerVersion("1")
                  // The list of available statistics packages can be found by querying the
                  // "INFORMATION_SCHEMA.SPANNER_STATISTICS" table.
                  .setOptimizerStatisticsPackage("latest")
                  .build())
          .build();
  Spanner spanner = options.getService();
  DatabaseClient dbClient = spanner.getDatabaseClient(db);
  try (ResultSet resultSet =
      dbClient
          .singleUse()
          .executeQuery(Statement.of("SELECT SingerId, AlbumId, AlbumTitle FROM Albums"))) {
    while (resultSet.next()) {
      System.out.printf(
          "%d %d %s\n", resultSet.getLong(0), resultSet.getLong(1), resultSet.getString(2));
    }
  }
}

Node.js

// Imports the Google Cloud client library
const {Spanner} = require('@google-cloud/spanner');

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// const projectId = 'my-project-id';
// const instanceId = 'my-instance';
// const databaseId = 'my-database';

// Creates a client
const spanner = new Spanner({
  projectId: projectId,
});

// Gets a reference to a Cloud Spanner instance and database
const instance = spanner.instance(instanceId);
const database = instance.database(
  databaseId,
  {},
  {
    optimizerVersion: '1',
    // The list of available statistics packages can be found by querying the
    // "INFORMATION_SCHEMA.SPANNER_STATISTICS" table.
    optimizerStatisticsPackage: 'latest',
  },
);

const query = {
  sql: `SELECT AlbumId, AlbumTitle, MarketingBudget
        FROM Albums
        ORDER BY AlbumTitle`,
};

// Queries rows from the Albums table
try {
  const [rows] = await database.run(query);

  rows.forEach(row => {
    const json = row.toJSON();
    const marketingBudget = json.MarketingBudget
      ? json.MarketingBudget
      : null; // This value is nullable
    console.log(
      `AlbumId: ${json.AlbumId}, AlbumTitle: ${json.AlbumTitle}, MarketingBudget: ${marketingBudget}`,
    );
  });
} catch (err) {
  console.error('ERROR:', err);
} finally {
  // Close the database when finished.
  database.close();
}

PHP

use Google\Cloud\Spanner\SpannerClient;
use Google\Cloud\Spanner\Database;

/**
 * Create a client with query options.
 * Example:
 * ```
 * create_client_with_query_options($instanceId, $databaseId);
 * ```
 *
 * @param string $instanceId The Spanner instance ID.
 * @param string $databaseId The Spanner database ID.
 */
function create_client_with_query_options(string $instanceId, string $databaseId): void
{
    $spanner = new SpannerClient([
        'queryOptions' => [
            'optimizerVersion' => '1',
            // Pin the statistics package used for this client instance to the
            // latest version. The list of available statistics packages can be
            // found by querying the "INFORMATION_SCHEMA.SPANNER_STATISTICS"
            // table.
            'optimizerStatisticsPackage' => 'latest'
        ]
    ]);
    $instance = $spanner->instance($instanceId);
    $database = $instance->database($databaseId);

    $results = $database->execute(
        'SELECT VenueId, VenueName, LastUpdateTime FROM Venues'
    );

    foreach ($results as $row) {
        printf('VenueId: %s, VenueName: %s, LastUpdateTime: %s' . PHP_EOL,
            $row['VenueId'], $row['VenueName'], $row['LastUpdateTime']);
    }
}

Python

# instance_id = "your-spanner-instance"
# database_id = "your-spanner-db-id"
spanner_client = spanner.Client(
    query_options={
        "optimizer_version": "1",
        "optimizer_statistics_package": "latest",
    }
)
instance = spanner_client.instance(instance_id)
database = instance.database(database_id)

with database.snapshot() as snapshot:
    results = snapshot.execute_sql(
        "SELECT VenueId, VenueName, LastUpdateTime FROM Venues"
    )

    for row in results:
        print("VenueId: {}, VenueName: {}, LastUpdateTime: {}".format(*row))

Ruby

# project_id  = "Your Google Cloud project ID"
# instance_id = "Your Spanner instance ID"
# database_id = "Your Spanner database ID"

require "google/cloud/spanner"

query_options = {
  optimizer_version: "1",
  # The list of available statistics packages can be
  # found by querying the "INFORMATION_SCHEMA.SPANNER_STATISTICS"
  # table.
  optimizer_statistics_package: "latest"
}

spanner = Google::Cloud::Spanner.new project: project_id
client  = spanner.client instance_id, database_id, query_options: query_options

sql_query = "SELECT VenueId, VenueName, LastUpdateTime FROM Venues"

client.execute(sql_query).rows.each do |row|
  puts "#{row[:VenueId]} #{row[:VenueName]} #{row[:LastUpdateTime]}"
end

Mit Umgebungsvariablen

Damit Sie verschiedene Einstellungen des Optimierungstools einfacher ausprobieren können, ohne die Anwendung neu kompilieren zu müssen, können Sie die Umgebungsvariablen SPANNER_OPTIMIZER_VERSION und SPANNER_OPTIMIZER_STATISTICS_PACKAGE festlegen und die Anwendung ausführen, wie im folgenden Snippet gezeigt.

Linux / macOS

export SPANNER_OPTIMIZER_VERSION="9"
export SPANNER_OPTIMIZER_STATISTICS_PACKAGE="auto_20191128_14_47_22UTC"

Windows

set SPANNER_OPTIMIZER_VERSION="9"
  set SPANNER_OPTIMIZER_STATISTICS_PACKAGE="auto_20191128_14_47_22UTC"

Die angegebenen Werte für die Optionen des Abfrageoptimierungstools werden zum Zeitpunkt der Client-Initialisierung in der Client-Instanz gelesen und gespeichert und auf alle Abfragen angewendet, die während der Lebensdauer des Clients ausgeführt werden.

Für eine Client-Abfrage

Sie können einen Wert für die Version des Optimierungstools oder des Statistikpakets auf Abfrageebene in Ihrer Client-Anwendung angeben, wenn Sie beim Erstellen der Abfrage eine Eigenschaft für die Abfrageoptionen angeben.

C++

void QueryWithQueryOptions(google::cloud::spanner::Client client) {
  namespace spanner = ::google::cloud::spanner;
  auto sql = spanner::SqlStatement("SELECT SingerId, FirstName FROM Singers");
  auto opts =
      google::cloud::Options{}
          .set<spanner::QueryOptimizerVersionOption>("1")
          .set<spanner::QueryOptimizerStatisticsPackageOption>("latest");
  auto rows = client.ExecuteQuery(std::move(sql), std::move(opts));

  using RowType = std::tuple<std::int64_t, std::string>;
  for (auto& row : spanner::StreamOf<RowType>(rows)) {
    if (!row) throw std::move(row).status();
    std::cout << "SingerId: " << std::get<0>(*row) << "\t";
    std::cout << "FirstName: " << std::get<1>(*row) << "\n";
  }
  std::cout << "Read completed for [spanner_query_with_query_options]\n";
}

C#


using Google.Cloud.Spanner.Data;
using System.Collections.Generic;
using System.Threading.Tasks;

public class RunCommandWithQueryOptionsAsyncSample
{
    public class Album
    {
        public int SingerId { get; set; }
        public int AlbumId { get; set; }
        public string AlbumTitle { get; set; }
    }

    public async Task<List<Album>> RunCommandWithQueryOptionsAsync(string projectId, string instanceId, string databaseId)
    {
        var connectionString = $"Data Source=projects/{projectId}/instances/{instanceId}/databases/{databaseId}";
        using var connection = new SpannerConnection(connectionString);
        using var cmd = connection.CreateSelectCommand("SELECT SingerId, AlbumId, AlbumTitle FROM Albums");

        cmd.QueryOptions = QueryOptions.Empty
            .WithOptimizerVersion("1")
            // The list of available statistics packages for the database can
            // be found by querying the "INFORMATION_SCHEMA.SPANNER_STATISTICS"
            // table.
            .WithOptimizerStatisticsPackage("latest");
        var albums = new List<Album>();
        using var reader = await cmd.ExecuteReaderAsync();
        while (await reader.ReadAsync())
        {
            albums.Add(new Album()
            {
                AlbumId = reader.GetFieldValue<int>("AlbumId"),
                SingerId = reader.GetFieldValue<int>("SingerId"),
                AlbumTitle = reader.GetFieldValue<string>("AlbumTitle")
            });
        }
        return albums;
    }
}

Go


import (
	"context"
	"fmt"
	"io"
	"time"

	"cloud.google.com/go/spanner"
	sppb "cloud.google.com/go/spanner/apiv1/spannerpb"
	"google.golang.org/api/iterator"
)

func queryWithQueryOptions(w io.Writer, db string) error {
	ctx := context.Background()
	client, err := spanner.NewClient(ctx, db)
	if err != nil {
		return err
	}
	defer client.Close()

	stmt := spanner.Statement{SQL: `SELECT VenueId, VenueName, LastUpdateTime FROM Venues`}
	queryOptions := spanner.QueryOptions{
		Options: &sppb.ExecuteSqlRequest_QueryOptions{
			OptimizerVersion: "1",
			// The list of available statistics packages can be found by
			// querying the "INFORMATION_SCHEMA.SPANNER_STATISTICS" table.
			OptimizerStatisticsPackage: "latest",
		},
	}
	iter := client.Single().QueryWithOptions(ctx, stmt, queryOptions)
	defer iter.Stop()
	for {
		row, err := iter.Next()
		if err == iterator.Done {
			return nil
		}
		if err != nil {
			return err
		}
		var venueID int64
		var venueName string
		var lastUpdateTime time.Time
		if err := row.Columns(&venueID, &venueName, &lastUpdateTime); err != nil {
			return err
		}
		fmt.Fprintf(w, "%d %s %s\n", venueID, venueName, lastUpdateTime)
	}
}

Java

static void queryWithQueryOptions(DatabaseClient dbClient) {
  try (ResultSet resultSet =
      dbClient
          .singleUse()
          .executeQuery(
              Statement
                  .newBuilder("SELECT SingerId, AlbumId, AlbumTitle FROM Albums")
                  .withQueryOptions(QueryOptions
                      .newBuilder()
                      .setOptimizerVersion("1")
                      // The list of available statistics packages can be found by querying the
                      // "INFORMATION_SCHEMA.SPANNER_STATISTICS" table.
                      .setOptimizerStatisticsPackage("latest")
                      .build())
                  .build())) {
    while (resultSet.next()) {
      System.out.printf(
          "%d %d %s\n", resultSet.getLong(0), resultSet.getLong(1), resultSet.getString(2));
    }
  }
}

Node.js

// Imports the Google Cloud client library
const {Spanner} = require('@google-cloud/spanner');

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// const projectId = 'my-project-id';
// const instanceId = 'my-instance';
// const databaseId = 'my-database';

// Creates a client
const spanner = new Spanner({
  projectId: projectId,
});

// Gets a reference to a Cloud Spanner instance and database
const instance = spanner.instance(instanceId);
const database = instance.database(databaseId);

const query = {
  sql: `SELECT AlbumId, AlbumTitle, MarketingBudget
        FROM Albums
        ORDER BY AlbumTitle`,
  queryOptions: {
    optimizerVersion: 'latest',
    // The list of available statistics packages can be found by querying the
    // "INFORMATION_SCHEMA.SPANNER_STATISTICS" table.
    optimizerStatisticsPackage: 'latest',
  },
};

// Queries rows from the Albums table
try {
  const [rows] = await database.run(query);

  rows.forEach(row => {
    const json = row.toJSON();
    const marketingBudget = json.MarketingBudget
      ? json.MarketingBudget
      : null; // This value is nullable
    console.log(
      `AlbumId: ${json.AlbumId}, AlbumTitle: ${json.AlbumTitle}, MarketingBudget: ${marketingBudget}`,
    );
  });
} catch (err) {
  console.error('ERROR:', err);
} finally {
  // Close the database when finished.
  database.close();
}

PHP

use Google\Cloud\Spanner\SpannerClient;
use Google\Cloud\Spanner\Database;

/**
 * Queries sample data using SQL with query options.
 * Example:
 * ```
 * query_data_with_query_options($instanceId, $databaseId);
 * ```
 *
 * @param string $instanceId The Spanner instance ID.
 * @param string $databaseId The Spanner database ID.
 */
function query_data_with_query_options(string $instanceId, string $databaseId): void
{
    $spanner = new SpannerClient();
    $instance = $spanner->instance($instanceId);
    $database = $instance->database($databaseId);

    $results = $database->execute(
        'SELECT VenueId, VenueName, LastUpdateTime FROM Venues',
        [
            'queryOptions' => [
                'optimizerVersion' => '1',
                // Pin the statistics package to the latest version just for
                // this query.
                'optimizerStatisticsPackage' => 'latest'
            ]
        ]
    );

    foreach ($results as $row) {
        printf('VenueId: %s, VenueName: %s, LastUpdateTime: %s' . PHP_EOL,
            $row['VenueId'], $row['VenueName'], $row['LastUpdateTime']);
    }
}

Python

# instance_id = "your-spanner-instance"
# database_id = "your-spanner-db-id"
spanner_client = spanner.Client()
instance = spanner_client.instance(instance_id)
database = instance.database(database_id)

with database.snapshot() as snapshot:
    results = snapshot.execute_sql(
        "SELECT VenueId, VenueName, LastUpdateTime FROM Venues",
        query_options={
            "optimizer_version": "1",
            "optimizer_statistics_package": "latest",
        },
    )

    for row in results:
        print("VenueId: {}, VenueName: {}, LastUpdateTime: {}".format(*row))

Ruby

# project_id  = "Your Google Cloud project ID"
# instance_id = "Your Spanner instance ID"
# database_id = "Your Spanner database ID"

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new project: project_id
client  = spanner.client instance_id, database_id

sql_query = "SELECT VenueId, VenueName, LastUpdateTime FROM Venues"
query_options = {
  optimizer_version: "1",
  # The list of available statistics packagebs can be
  # found by querying the "INFORMATION_SCHEMA.SPANNER_STATISTICS"
  # table.
  optimizer_statistics_package: "latest"
}

client.execute(sql_query, query_options: query_options).rows.each do |row|
  puts "#{row[:VenueId]} #{row[:VenueName]} #{row[:LastUpdateTime]}"
end

Optionen des Optimierungstools bei Verwendung des Cloud Spanner-JDBC-Treibers festlegen

Sie können den Standardwert der Version des Optimierungstools und des Statistikpakets überschreiben, wenn Sie wie im folgenden Beispiel gezeigt Optionen im JDBC-Verbindungsstring angeben.

Diese Optionen werden nur in den neuesten Versionen des Cloud Spanner-JDBC-Treibers unterstützt.

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.sql.Statement;

class ConnectionWithQueryOptionsExample {

  static void connectionWithQueryOptions() throws SQLException {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "my-project";
    String instanceId = "my-instance";
    String databaseId = "my-database";
    connectionWithQueryOptions(projectId, instanceId, databaseId);
  }

  static void connectionWithQueryOptions(String projectId, String instanceId, String databaseId)
      throws SQLException {
    String optimizerVersion = "1";
    String connectionUrl =
        String.format(
            "jdbc:cloudspanner:/projects/%s/instances/%s/databases/%s?optimizerVersion=%s",
            projectId, instanceId, databaseId, optimizerVersion);
    try (Connection connection = DriverManager.getConnection(connectionUrl);
        Statement statement = connection.createStatement()) {
      // Execute a query using the optimizer version '1'.
      try (ResultSet rs =
          statement.executeQuery(
              "SELECT SingerId, FirstName, LastName FROM Singers ORDER BY LastName")) {
        while (rs.next()) {
          System.out.printf("%d %s %s%n", rs.getLong(1), rs.getString(2), rs.getString(3));
        }
      }
      try (ResultSet rs = statement.executeQuery("SHOW VARIABLE OPTIMIZER_VERSION")) {
        while (rs.next()) {
          System.out.printf("Optimizer version: %s%n", rs.getString(1));
        }
      }
    }
  }
}

Sie können die Version des Abfrageoptimierungstools auch wie im folgenden Beispiel gezeigt mit der Anweisung SET OPTIMIZER_VERSION festlegen.

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.sql.Statement;

class SetQueryOptionsExample {

  static void setQueryOptions() throws SQLException {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "my-project";
    String instanceId = "my-instance";
    String databaseId = "my-database";
    setQueryOptions(projectId, instanceId, databaseId);
  }

  static void setQueryOptions(String projectId, String instanceId, String databaseId)
      throws SQLException {
    String connectionUrl =
        String.format(
            "jdbc:cloudspanner:/projects/%s/instances/%s/databases/%s",
            projectId, instanceId, databaseId);
    try (Connection connection = DriverManager.getConnection(connectionUrl);
        Statement statement = connection.createStatement()) {
      // Instruct the JDBC connection to use version '1' of the query optimizer.
      // NOTE: Use `SET SPANNER.OPTIMIZER_VERSION='1`` when connected to a PostgreSQL database.
      statement.execute("SET OPTIMIZER_VERSION='1'");
      // Execute a query using the latest optimizer version.
      try (ResultSet rs =
          statement.executeQuery(
              "SELECT SingerId, FirstName, LastName FROM Singers ORDER BY LastName")) {
        while (rs.next()) {
          System.out.printf("%d %s %s%n", rs.getLong(1), rs.getString(2), rs.getString(3));
        }
      }
      // NOTE: Use `SHOW SPANNER.OPTIMIZER_VERSION` when connected to a PostgreSQL database.
      try (ResultSet rs = statement.executeQuery("SHOW VARIABLE OPTIMIZER_VERSION")) {
        while (rs.next()) {
          System.out.printf("Optimizer version: %s%n", rs.getString(1));
        }
      }
    }
  }
}

Weitere Informationen zur Verwendung des Open-Source-Treibers finden Sie unter Open-Source-JDBC-Treiber verwenden.

Umgang mit ungültigen Optimierungstoolversionen

Cloud Spanner unterstützt eine Reihe von Versionen des Optimierungstools. Welche Versionen unterstützt werden, ändert sich von Zeit zu Zeit, wenn das Abfrageoptimierungstool aktualisiert wird. Wenn die von Ihnen angegebene Version außerhalb des zulässigen Bereichs liegt, schlägt die Abfrage fehl. Wenn Sie beispielsweise versuchen, eine Abfrage mit dem Anweisungshinweis @{OPTIMIZER_VERSION=10} auszuführen, die neueste Version des Optimierungstools jedoch nur die Versionsnummer 9 hat, antwortet Cloud Spanner mit der folgenden Fehlermeldung:

Query optimizer version: 10 is not supported

Umgang mit einer ungültigen Einstellung des Statistikpakets des Optimierungstools

Sie können Ihre Datenbank oder Abfrage mit einer der zuvor auf dieser Seite beschriebenen Methoden an ein beliebiges verfügbares Statistikpaket anheften. Eine Abfrage schlägt fehl, wenn ein ungültiger Name für das Statistikpaket angegeben wird. Ein von einer Abfrage angegebenes Statistikpaket muss entweder:

auf Datenbankebene festgelegt sein oder
als ALLOW_GC=false gekennzeichnet sein

Version des Optimierungstools für Abfragen festlegen, die zum Ausführen einer Abfrage verwendet wird

Die für eine Abfrage verwendete Version des Optimierungstools ist über die Google Cloud Console und in der Google Cloud CLI sichtbar.

Google Cloud Console

Führen Sie die Abfrage auf der Spanner Studio Seite der Google Cloud Console aus und wählen Sie dann den Explanation Tab aus, um die für eine Abfrage verwendete Version des Optimierungstools aufzurufen. Sie sollten eine Meldung sehen, die in etwa so aussieht:

Query optimizer version: 9

gcloud CLI

Wenn Sie die Version aufrufen möchten, die beim Ausführen einer Abfrage in der gcloud CLI verwendet wird, setzen Sie das Flag --query-mode wie im folgenden Snippet gezeigt auf PROFILE.

gcloud spanner databases execute-sql MyDatabase --instance=test-instance \
    --query-mode=PROFILE --sql='SELECT * FROM MyTable'

Version der Abfrageoptimierung im Metrics Explorer visualisieren

Cloud Monitoring erfasst Messwerte, um die Leistung Ihrer Anwendungen und Systemdienste besser zu verstehen. Einer der für Cloud Spanner erfassten Messwerte ist die Anzahl der Abfragen. Damit wird die Anzahl der Abfragen in einer Instanz gemessen, die im Laufe der Zeit erfasst wurden. Dieser Messwert ist zwar sehr hilfreich, um Abfragen aufzurufen, die nach Fehlercode gruppiert sind, wir können ihn aber auch verwenden, um zu sehen, welche Version des Optimierungstools zur Ausführung der einzelnen Abfragen verwendet wurde.

Mit dem Metrics Explorer in Google Cloud der Console können Sie die Anzahl der Abfragen für Ihre Datenbank instanz visualisieren. Abbildung 1 zeigt die Anzahl der Abfragen für drei Datenbanken. Sie sehen, welche Version des Optimierungstools in den einzelnen Datenbanken verwendet wird.

Die Tabelle unter dem Diagramm in dieser Abbildung zeigt, dass my-db-1 versucht hat, eine Abfrage mit einer ungültigen Optimierungstoolversion auszuführen, was den Status Falsche Nutzung zurückgibt und zu einer Abfrageanzahl von 0 führt. Die anderen Datenbanken haben Abfragen mit den Versionen 1 und 2 des Optimierungstools ausgeführt.

Grafik: Anzahl der Abfragen im Metrics Explorer nach der Version der Abfrageoptimierung

Abbildung 1. Anzahl der Abfragen, die im Metrics Explorer zusammen mit Abfragen angezeigt werden, die nach der Optimierungsversion gruppiert sind.

So richten Sie ein ähnliches Diagramm für Ihre Instanz ein:

Rufen Sie in der Google Cloud Console den Metrics Explorer auf.
Wählen Sie im Feld Ressourcentyp die Option Cloud Spanner Instance aus.
Wählen Sie im Feld Messwert die Option Count of queries aus.
Wählen Sie im Feld Gruppieren nach die Optionen database, optimizer_version und status aus.

In diesem Beispiel wird nicht der Fall gezeigt, bei dem für verschiedene Abfragen in derselben Datenbank eine andere Optimierungstoolversion verwendet wird. In diesem Fall würde das Diagramm ein Balkendiagramm für jede Kombination aus Datenbank- und Optimierungstoolversion zeigen.

Informationen zum Monitoring Ihrer Cloud Spanner -Instanzen mit Cloud Monitoring finden Sie unter Monitoring mit Cloud Monitoring.

Abfrageoptimierung verwalten Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

GoogleSQL

PostgreSQL

Optionen des Abfrageoptimierungstools auflisten

Versionen des Optimierungstools

Standardversion

Statistikpakete des Optimierungstools

Rangfolge der Optionsüberschreibung

Optionen des Optimierungstools festlegen

Optionen des Optimierungstools auf Datenbankebene festlegen

GoogleSQL

PostgreSQL

GoogleSQL

PostgreSQL

GoogleSQL

GoogleSQL

PostgreSQL

GoogleSQL

PostgreSQL

Optionen des Optimierungstools für eine Abfrage mithilfe eines Anweisungshinweises festlegen

GoogleSQL

PostgreSQL

GoogleSQL

PostgreSQL

GoogleSQL

PostgreSQL

GoogleSQL

PostgreSQL

Optionen des Optimierungstools mit Clientbibliotheken festlegen

Für einen Datenbankclient

C++

C#

Go

Java

Node.js

PHP

Python

Ruby

Mit Umgebungsvariablen

Linux / macOS

Windows

Für eine Client-Abfrage

C++

C#

Go

Java

Node.js

PHP

Python

Ruby

Optionen des Optimierungstools bei Verwendung des Cloud Spanner-JDBC-Treibers festlegen

Umgang mit ungültigen Optimierungstoolversionen

Umgang mit einer ungültigen Einstellung des Statistikpakets des Optimierungstools

Version des Optimierungstools für Abfragen festlegen, die zum Ausführen einer Abfrage verwendet wird

Google Cloud Console

gcloud CLI

Version der Abfrageoptimierung im Metrics Explorer visualisieren

Abfrageoptimierung verwalten