Modificare i dati utilizzando la scrittura batch

Questa pagina descrive le richieste di scrittura batch di Spanner e come puoi utilizzarle per modificare i dati di Spanner.

Puoi utilizzare la scrittura batch di Spanner per inserire, aggiornare o eliminare più righe nelle tabelle Spanner. La scrittura batch di Spanner supporta scritture a bassa latenza senza un'operazione di lettura e restituisce risposte man mano che le mutazioni vengono applicate in batch. Per utilizzare la scrittura batch, raggruppa le mutazioni correlate e tutte le mutazioni di un gruppo vengono eseguite in modo atomico. Le mutazioni nei gruppi vengono applicate in un ordine non specificato e sono indipendenti l'una dall'altra (non atomiche). Spanner non deve attendere l'applicazione di tutte le mutazioni prima di inviare una risposta, il che significa che la scrittura batch consente un errore parziale. Puoi anche eseguire più scritture batch contemporaneamente. Per saperne di più, consulta la sezione Come utilizzare la scrittura batch.

Casi d'uso

La scrittura batch di Spanner è particolarmente utile se vuoi eseguire il commit di un gran numero di scritture senza un'operazione di lettura, ma non richiedi una transazione atomica per tutte le mutazioni.

Se vuoi raggruppare le richieste DML, utilizza DML batch per modificare i dati di Spanner. Per saperne di più sulle differenze tra DML e mutazioni, consulta Confronto tra DML e mutazioni.

Per le richieste di singola mutazione, ti consigliamo di utilizzare una transazione di lettura/scrittura con blocco.

Limitazioni

La scrittura batch di Spanner presenta le seguenti limitazioni:

  • La scrittura batch di Spanner non è disponibile utilizzando la consoleGoogle Cloud o Google Cloud CLI. È disponibile solo utilizzando le API REST e RPC e le librerie client di Spanner.

  • La protezione dal replay non è supportata utilizzando la scrittura batch. È possibile che le mutazioni vengano applicate più di una volta e una mutazione applicata più di una volta potrebbe causare un errore. Ad esempio, se una mutazione di inserimento viene riprodotta, potrebbe generare un errore di esistenza o, se utilizzi chiavi basate su timestamp generati o di commit nella mutazione, potrebbe comportare l'aggiunta di righe aggiuntive alla tabella. Ti consigliamo di strutturare le scritture in modo che siano idempotenti per evitare questo problema.

  • Non puoi eseguire il rollback di una richiesta di scrittura batch completata. Puoi annullare una richiesta di scrittura batch in corso. Se annulli una scrittura batch in corso, le mutazioni nei gruppi non completati vengono ripristinate. Le mutazioni nei gruppi completati vengono eseguite nel database.

  • La dimensione massima per una richiesta di scrittura batch è la stessa del limite per una richiesta di commit. Per ulteriori informazioni, consulta Limiti per la creazione, la lettura, l'aggiornamento e l'eliminazione di dati.

Come utilizzare la scrittura batch

Per utilizzare la scrittura batch, devi disporre dell'autorizzazione spanner.databases.write sul database che vuoi modificare. Puoi scrivere mutazioni batch in modo non atomico in una singola chiamata utilizzando una chiamata di richiesta API REST o RPC.

Quando utilizzi la scrittura batch, devi raggruppare i seguenti tipi di mutazione:

  • Inserimento di righe con lo stesso prefisso della chiave primaria sia nella tabella principale sia in quella secondaria.
  • Inserimento di righe nelle tabelle con una relazione di chiave esterna tra le tabelle.
  • Altri tipi di mutazioni correlate a seconda dello schema del database e della logica dell'applicazione.

Puoi anche scrivere in batch utilizzando le librerie client di Spanner. Il seguente esempio di codice aggiorna la tabella Singers con nuove righe.

Librerie client

C++ 

namespace spanner = ::google::cloud::spanner;
// Use upserts as mutation groups are not replay protected.
auto commit_results = client.CommitAtLeastOnce({
    // group #0
    spanner::Mutations{
        spanner::InsertOrUpdateMutationBuilder(
            "Singers", {"SingerId", "FirstName", "LastName"})
            .EmplaceRow(16, "Scarlet", "Terry")
            .Build(),
    },
    // group #1
    spanner::Mutations{
        spanner::InsertOrUpdateMutationBuilder(
            "Singers", {"SingerId", "FirstName", "LastName"})
            .EmplaceRow(17, "Marc", "")
            .EmplaceRow(18, "Catalina", "Smith")
            .Build(),
        spanner::InsertOrUpdateMutationBuilder(
            "Albums", {"SingerId", "AlbumId", "AlbumTitle"})
            .EmplaceRow(17, 1, "Total Junk")
            .EmplaceRow(18, 2, "Go, Go, Go")
            .Build(),
    },
});
for (auto& commit_result : commit_results) {
  if (!commit_result) throw std::move(commit_result).status();
  std::cout << "Mutation group indexes [";
  for (auto index : commit_result->indexes) std::cout << " " << index;
  std::cout << " ]: ";
  if (commit_result->commit_timestamp) {
    auto const& ts = *commit_result->commit_timestamp;
    std::cout << "Committed at " << ts.get<absl::Time>().value();
  } else {
    std::cout << commit_result->commit_timestamp.status();
  }
  std::cout << "\n";
}

C#

// Copyright 2026 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.


using Google.Cloud.Spanner.Data;
using Google.Rpc;
using Google.Cloud.Spanner.V1;
using Google.Protobuf.WellKnownTypes;
using System;
using System.Collections.Generic;
using System.Threading.Tasks;

public class BatchWriteAtLeastOnceAsyncSample
{
    public async Task BatchWriteAtLeastOnceAsync(string projectId, string instanceId, string databaseId)
    {
        string connectionString = $"Data Source=projects/{projectId}/instances/{instanceId}/databases/{databaseId}";

        using var connection = new SpannerConnection(connectionString);
        await connection.OpenAsync();

        // 1. Create a SpannerBatchWriteCommand.
        var cmd = connection.CreateBatchWriteCommand();

        // 2. Create and add mutation groups.
        // Mutation group 1: Insert or update a singer (16).
        var cmdSinger1 = connection.CreateInsertOrUpdateCommand("Singers", new SpannerParameterCollection
        {
            { "SingerId", SpannerDbType.Int64, 16 },
            { "FirstName", SpannerDbType.String, "Scarlet" },
            { "LastName", SpannerDbType.String, "Terry" }
        });
        cmd.Add(cmdSinger1);

        // Mutation group 2: Insert or update multiple singers and albums together.
        var cmdSinger2 = connection.CreateInsertOrUpdateCommand("Singers", new SpannerParameterCollection
        {
            { "SingerId", SpannerDbType.Int64, 17 },
            { "FirstName", SpannerDbType.String, "Marc" },
            { "LastName", SpannerDbType.String, "Smith" }
        });

        var cmdSinger3 = connection.CreateInsertOrUpdateCommand("Singers", new SpannerParameterCollection
        {
            { "SingerId", SpannerDbType.Int64, 18 },
            { "FirstName", SpannerDbType.String, "Catalina" },
            { "LastName", SpannerDbType.String, "Smith" }
        });

        var cmdAlbum1 = connection.CreateInsertOrUpdateCommand("Albums", new SpannerParameterCollection
        {
            { "SingerId", SpannerDbType.Int64, 17 },
            { "AlbumId", SpannerDbType.Int64, 1 },
            { "AlbumTitle", SpannerDbType.String, "Total Junk" }
        });

        var cmdAlbum2 = connection.CreateInsertOrUpdateCommand("Albums", new SpannerParameterCollection
        {
            { "SingerId", SpannerDbType.Int64, 18 },
            { "AlbumId", SpannerDbType.Int64, 2 },
            { "AlbumTitle", SpannerDbType.String, "Go, Go, Go" }
        });

        // Add multiple commands to the same group.
        cmd.Add(cmdSinger2, cmdSinger3, cmdAlbum1, cmdAlbum2);

        // 3. Execute the batch write request.
        try
        {
            // ExecuteNonQueryAsync returns an IAsyncEnumerable of BatchWriteResponse.
            await foreach (var response in cmd.ExecuteNonQueryAsync())
            {
                if (response.Status?.Code == (int)Code.Ok)
                {
                    Console.WriteLine($"Mutation group indexes {string.Join(", ", response.Indexes)} have been applied with commit timestamp {response.CommitTimestamp}");
                }
                else
                {
                    Console.WriteLine($"Mutation group indexes {string.Join(", ", response.Indexes)} could not be applied with error code {response.Status?.Code}");
                }
            }
        }
        catch (Exception ex)
        {
            Console.WriteLine($"Error executing batch write: {ex.Message}");
            throw;
        }
    }
}

Go 


import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/spanner"
	sppb "cloud.google.com/go/spanner/apiv1/spannerpb"
	"google.golang.org/grpc/status"
)

// batchWrite demonstrates writing mutations to a Spanner database through
// BatchWrite API - https://pkg.go.dev/cloud.google.com/go/spanner#Client.BatchWrite
func batchWrite(w io.Writer, db string) error {
	// db := "projects/my-project/instances/my-instance/databases/my-database"
	ctx := context.Background()
	client, err := spanner.NewClient(ctx, db)
	if err != nil {
		return err
	}
	defer client.Close()

	// Database is assumed to exist - https://cloud.google.com/spanner/docs/getting-started/go#create_a_database
	singerColumns := []string{"SingerId", "FirstName", "LastName"}
	albumColumns := []string{"SingerId", "AlbumId", "AlbumTitle"}
	mutationGroups := make([]*spanner.MutationGroup, 2)

	mutationGroup1 := []*spanner.Mutation{
		spanner.InsertOrUpdate("Singers", singerColumns, []interface{}{16, "Scarlet", "Terry"}),
	}
	mutationGroups[0] = &spanner.MutationGroup{Mutations: mutationGroup1}

	mutationGroup2 := []*spanner.Mutation{
		spanner.InsertOrUpdate("Singers", singerColumns, []interface{}{17, "Marc", ""}),
		spanner.InsertOrUpdate("Singers", singerColumns, []interface{}{18, "Catalina", "Smith"}),
		spanner.InsertOrUpdate("Albums", albumColumns, []interface{}{17, 1, "Total Junk"}),
		spanner.InsertOrUpdate("Albums", albumColumns, []interface{}{18, 2, "Go, Go, Go"}),
	}
	mutationGroups[1] = &spanner.MutationGroup{Mutations: mutationGroup2}
	iter := client.BatchWrite(ctx, mutationGroups)
	// See https://pkg.go.dev/cloud.google.com/go/spanner#BatchWriteResponseIterator.Do
	doFunc := func(response *sppb.BatchWriteResponse) error {
		if err = status.ErrorProto(response.GetStatus()); err == nil {
			fmt.Fprintf(w, "Mutation group indexes %v have been applied with commit timestamp %v",
				response.GetIndexes(), response.GetCommitTimestamp())
		} else {
			fmt.Fprintf(w, "Mutation group indexes %v could not be applied with error %v",
				response.GetIndexes(), err)
		}
		// Return an actual error as needed.
		return nil
	}
	return iter.Do(doFunc)
}

Java 


import com.google.